19. Configuration Reference

The following pieces of configuration must be provided. These are Spring Boot @ConfigurationProperties so you can set them as environment variables or by any other means that Spring Boot supports. Here is a listing in environment variable format as that is an easy way to get started configuring Boot applications in Cloud Foundry.

# Default values cited after the equal sign.
# Example values, typical for Pivotal Web Services, cited as a comment

# url of the CF API (used when using cf login -a for example), e.g. https://api.run.pivotal.io
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_URL)
spring.cloud.deployer.cloudfoundry.url=

# name of the organization that owns the space above, e.g. youruser-org
# (For Setting Env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_ORG)
spring.cloud.deployer.cloudfoundry.org=

# name of the space into which modules will be deployed, e.g. development
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SPACE)
spring.cloud.deployer.cloudfoundry.space=

# the root domain to use when mapping routes, e.g. cfapps.io
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_DOMAIN)
spring.cloud.deployer.cloudfoundry.domain=

# username and password of the user to use to create apps
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_USERNAME and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_PASSWORD)
spring.cloud.deployer.cloudfoundry.username=
spring.cloud.deployer.cloudfoundry.password=

# Whether to allow self-signed certificates during SSL validation
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SKIP_SSL_VALIDATION)
spring.cloud.deployer.cloudfoundry.skipSslValidation=false

# Comma separated set of service instance names to bind to every stream app deployed.
# Amongst other things, this should include a service that will be used
# for Spring Cloud Stream binding, e.g. rabbit
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_SERVICES)
spring.cloud.deployer.cloudfoundry.stream.services=

# Health check type to use for stream apps. Accepts 'none' and 'port'
spring.cloud.deployer.cloudfoundry.stream.health-check=


# Comma separated set of service instance names to bind to every task app deployed.
# Amongst other things, this should include an RDBMS service that will be used
# for Spring Cloud Task execution reporting, e.g. my_mysql
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_SERVICES)
spring.cloud.deployer.cloudfoundry.task.services=

# Timeout to use, in seconds, when doing blocking API calls to Cloud Foundry.
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_API_TIMEOUT
# and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_API_TIMEOUT)
spring.cloud.deployer.cloudfoundry.stream.apiTimeout=360
spring.cloud.deployer.cloudfoundry.task.apiTimeout=360

# Timeout to use, in milliseconds, when querying the Cloud Foundry API to compute app status.
# (for setting env var use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_STATUS_TIMEOUT
# and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_STATUS_TIMEOUT)
spring.cloud.deployer.cloudfoundry.stream.statusTimeout=5000
spring.cloud.deployer.cloudfoundry.task.statusTimeout=5000

Note that you can set the following properties spring.cloud.deployer.cloudfoundry.services, spring.cloud.deployer.cloudfoundry.buildpack or the Spring Cloud Deployer standard spring.cloud.deployer.memory and spring.cloud.deployer.disk as part of an individual deployment request by using the deployer.<app-name> shortcut. For example

>stream create --name ticktock --definition "time | log"
>stream deploy --name ticktock --properties "deployer.time.memory=2g"

will deploy the time source with 2048MB of memory, while the log sink will use the default 1024MB.

19.1 Understanding what’s going on

If you want to get better insights into what is happening when your streams and tasks are being deployed, you may want to turn on the following features:

  • Reactor "stacktraces", showing which operators were involved before an error occurred. This is helpful as the deployer relies on project reactor and regular stacktraces may not always allow understanding the flow before an error happened. Note that this comes with a performance penalty, so is disabled by default.

    spring.cloud.dataflow.server.cloudfoundry.debugReactor = true
  • Deployer and Cloud Foundry client library request/response logs. This allows seeing detailed conversation between the Data Flow server and the Cloud Foundry Cloud Controller.

    logging.level.cloudfoundry-client = DEBUG

19.2 Using Spring Cloud Config Server

Spring Cloud Config Server can be used to centralize configuration properties for Spring Boot applications. Likewise, both Spring Cloud Data Flow and the applications orchestrated using Spring Cloud Data Flow can be integrated with config-server to leverage the same capabilities.

19.2.1 Stream, Task, and Spring Cloud Config Server

Similar to Spring Cloud Data Flow server, it is also possible to configure both the stream and task applications to resolve the centralized properties from config-server. Setting the property spring.cloud.config.uri for the deployed applications is a common way to bind to the Config Server. See the Spring Cloud Config Client reference guide for more information. Since this property is likely to be used across all applications deployed by the Data Flow server, the Data Flow Server’s property spring.cloud.dataflow.applicationProperties.stream for stream apps and spring.cloud.dataflow.applicationProperties.task for task apps can be used to pass the uri of the Config Server to each deployed stream or task application. Refer to the section on Common application properties for more information.

If you’re using applications from the App Starters project, note that these applications already embed the spring-cloud-services-starter-config-client dependency. If you’re building your application from scratch and want to add the client side support for config server, simply add a reference dependency reference to the config server client library. A maven example snippet follows:

...
<dependency>
  <groupId>io.pivotal.spring.cloud</groupId>
  <artifactId>spring-cloud-services-starter-config-client</artifactId>
  <version>CONFIG_CLIENT_VERSION</version>
</dependency>
...

Where, CONFIG_CLIENT_VERSION can be the latest release of Spring Cloud Config Server client for Pivotal Cloud Foundry.

[Note]Note

You will observe a WARN logging message if the application that uses this library can not connect to the config server when the applicaiton starts and whenever the /health endpoint is accessed. You can disable the client library if you know that you are not using config server functionality by setting the environment variable SPRING_CLOUD_CONFIG_ENABLED=false. Another, more drastic option, is to disable the platform health check with the environment variable SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_HEALTH_CHECK=none

19.2.2 Sample Manifest Template

Following manifest.yml template includes the required env-var’s for the Spring Cloud Data Flow server and deployed apps/tasks to successfully run on Cloud Foundry and automatically resolve centralized properties from my-config-server at the runtime.

---
applications:
- name: data-flow-server
  host: data-flow-server
  memory: 2G
  disk_quota: 2G
  instances: 1
  path: {PATH TO SERVER UBER-JAR}
  env:
    SPRING_APPLICATION_NAME: data-flow-server
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_URL: https://api.local.pcfdev.io
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_ORG: pcfdev-org
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SPACE: pcfdev-space
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_DOMAIN: local.pcfdev.io
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_USERNAME: admin
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_PASSWORD: admin
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_SERVICES: rabbit,my-config-server
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_SERVICES: mysql,my-config-server
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SKIP_SSL_VALIDATION: true
    SPRING_APPLICATION_JSON {"maven": { "remote-repositories": { "repo1": { "url": "https://repo.spring.io/libs-release"} } } }
services:
- mysql
- my-config-server

Where, my-config-server is the name of the Spring Cloud Config Service instance running on Cloud Foundry. By binding the service to both Spring Cloud Data Flow server as well as all the Spring Cloud Stream and Spring Cloud Task applications respectively, we can now resolve centralized properties backed by this service.

19.2.3 Self-signed SSL Certificate and Spring Cloud Config Server

Often, in a development environment, we may not have a valid certificate to enable SSL communication between clients and the backend services. However, the config-server for Pivotal Cloud Foundry uses HTTPS for all client-to-service communication, so it is necessary to add a self-signed SSL certificate in environments with no valid certificates.

Using the same manifest.yml template listed in the previous section, for the server, we can provide the self-signed SSL certificate via: TRUST_CERTS: <API_ENDPOINT>.

However, the deployed applications also require TRUST_CERTS as a flat env-var (as opposed to being wrapped inside SPRING_APPLICATION_JSON), so we will have to instruct the server with yet another set of tokens SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_USE_SPRING_APPLICATION_JSON: false and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_USE_SPRING_APPLICATION_JSON: false for stream and task applications respectively. With this setup, the applications will receive their application properties as regular environment variables

Let’s review the updated manifest.yml with the required changes. Both the Data Flow server and deployed applications would get their config from the my-config-server Cloud Config server (deployed as a Cloud Foundry service)

---
applications:
- name: test-server
  host: test-server
  memory: 1G
  disk_quota: 1G
  instances: 1
  path: spring-cloud-dataflow-server-cloudfoundry-VERSION.jar
  env:
    SPRING_APPLICATION_NAME: test-server
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_URL: <URL>
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_ORG: <ORG>
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SPACE: <SPACE>
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_DOMAIN: <DOMAIN>
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_USERNAME: <USER>
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_PASSWORD: <PASSWORD>
    MAVEN_REMOTE_REPOSITORIES_REPO1_URL: https://repo.spring.io/libs-release
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_SERVICES: my-config-server #this is so all stream applications bind to my-config-server
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_SERVICES: config-server      #this for so all task applications bind to my-config-server
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_USE_SPRING_APPLICATION_JSON: false #this is for all the stream applications
    SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_USE_SPRING_APPLICATION_JSON: false #this is for all the task applications
    TRUST_CERTS: <API_ENDPOINT> #this is for the server
    spring.cloud.dataflow.applicationProperties.stream.TRUST_CERTS: <API_ENDPOINT> #this propagates to all streams
    spring.cloud.dataflow.applicationProperties.task.TRUST_CERTS: <API_ENDPOINT>   #this propagates to all tasks
services:
- mysql
- my-config-server #this is for the server