Introduction to Spring Cloud CLI

1. Introduction

In this article, we take a look at Spring Boot Cloud CLI (or Cloud CLI for short). The tool provides a set of command line enhancements to the Spring Boot CLI that helps in further abstracting and simplifying Spring Cloud deployments.

The CLI was introduced in late 2016 and allows quick auto-configuration and deployment of standard Spring Cloud services using a command line, .yml configuration files, and Groovy scripts.

2. Set Up

Spring Boot Cloud CLI 1.3.x requires Spring Boot CLI 1.5.x, so make sure to grab the latest version of Spring Boot CLI from Maven Central (installation instructions) and the most recent version of the Cloud CLI from Maven Repository (the official Spring repository)!

To make sure the CLI is installed and ready to use, simply run:

$ spring --version

After verifying your Spring Boot CLI installation, install the latest stable version of Cloud CLI:

$ spring install org.springframework.cloud:spring-cloud-cli:1.3.2.RELEASE

Then verify the Cloud CLI:

$ spring cloud --version

Advanced installation features can be found on the official Cloud CLI page!

3. Default Services and Configuration

The CLI provides seven core services that can be run and deployed with single line commands.

To launch a Cloud Config server on http://localhost:8888:

$ spring cloud configserver

To start a Eureka server on http://localhost:8761:

$ spring cloud eureka

To initiate an H2 server on http://localhost:9095:

$ spring cloud h2

To launch a Kafka server on http://localhost:9091:

$ spring cloud kafka

To start a Zipkin server on http://localhost:9411:

$ spring cloud zipkin

To launch a Dataflow server on http://localhost:9393:

$ spring cloud dataflow

To start a Hystrix dashboard on http://localhost:7979:

$ spring cloud hystrixdashboard

List currently running cloud services:

$ spring cloud --list

The handy help command:

$ spring help cloud

For more details about these commands, please check out the official blog.

4. Customizing Cloud Services with YML

Each of the services that are deployable through the Cloud CLI can also be configured using correspondingly-named .yml files:

spring:
  profiles:
    active: git
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo

This constitutes a simple configuration file that we can use for launching the Cloud Config Server.

We can, for example, specify a Git repository as the URI source that will be automatically cloned and deployed when we issue the ‘spring cloud configserver’ command.

Cloud CLI uses the Spring Cloud Launcher under the hood. That means that Cloud CLI supports most of the Spring Boot configuration mechanisms. Here’s the official list of Spring Boot properties.

Spring Cloud configuration conforms to the ‘spring.cloud…‘ convention. Settings for Spring Cloud and Spring Config Server can be found at this link.

We can also specify several different modules and services directly into the cloud.yml:

spring:
  cloud:
    launcher:
      deployables:
        - name: configserver
          coordinates: maven://...:spring-cloud-launcher-configserver:1.3.2.RELEASE
          port: 8888
          waitUntilStarted: true
          order: -10
        - name: eureka
          coordinates: maven:/...:spring-cloud-launcher-eureka:1.3.2.RELEASE
          port: 8761

The cloud.yml allows custom services or modules to be added and the use of Maven and Git repositories to be used.

5. Running Custom Groovy Scripts

Custom components can be written in Groovy and deployed efficiently since Cloud CLI can compile and deploy Groovy code.

Here’s an example minimal REST API implementation:

@RestController
@RequestMapping('/api')
class api {
 
    @GetMapping('/get')
    def get() { [message: 'Hello'] }
}

Assuming that the script is saved as rest.groovy, we can launch our minimal server like this:

$ spring run rest.groovy

Pinging http://localhost:8080/api/get should reveal:

{"message":"Hello"}

6. Encrypt/Decrypt

Cloud CLI also provides a tool for encryption and decryption (found in the package org.springframework.cloud.cli.command.*) that can be used directly through the command line or indirectly by passing a value to a Cloud Config Server endpoint.

Let’s set it up and see how to use it.

6.1. Setup

Both Cloud CLI as well as Spring Cloud Config Server use org.springframework.security.crypto.encrypt.* for handling encrypt and decrypt commands.

As such, both require the JCE Unlimited Strength Extension provided by Oracle here.

6.2. Encrypt and Decrypt By Command

To encrypt ‘my_value‘ via the terminal, invoke:

$ spring encrypt my_value --key my_key

File paths can be substituted for the key name (e.g. ‘my_key‘ above) by using ‘@’ followed by the path (commonly used for RSA public keys):

$ spring encrypt my_value --key @${WORKSPACE}/foos/foo.pub

‘my_value‘ will now be encrypted to something like:

c93cb36ce1d09d7d62dffd156ef742faaa56f97f135ebd05e90355f80290ce6b

Furthermore, it will be stored in memory under key ‘my_key‘. This allows us to decrypt ‘my_key‘ back into’my_value‘ via command line:

$ spring decrypt --key my_key

We can also now use the encrypted value in a configuration YAML or properties file, where it will be automatically decrypted by the Cloud Config Server when loaded:

encrypted_credential: "{cipher}c93cb36ce1d09d7d62dffd156ef742faaa56f97f135ebd05e90355f80290ce6b"

6.3. Encrypt and Decrypt with Config Server

Spring Cloud Config Server exposes RESTful endpoints where keys and encrypted value pairs can be stored in the Java Security Store or memory.

For more information on how to correctly set up and configure your Cloud Config Server to accept symmetric or asymmetric encryption, please check out our article or the official docs.

Once Spring Cloud Config Server is configured and up running using the ‘spring cloud configserver‘ command, you’ll be able to call its API:

$ curl localhost:8888/encrypt -d mysecret
//682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
$ curl localhost:8888/decrypt -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
//mysecret

7. Conclusion

We’ve focused here on an introduction to Spring Boot Cloud CLI. For more information, please check out the official docs.

The configuration and bash examples used in this article are available over on GitHub.