spring-cloud-kubernetes

This project has moved to the Spring Cloud Incubator.

Spring Cloud Kubernetes

Spring Cloud integration with Kubernetes

Features

• DiscoveryClient for Kubernetes
• KubernetesClient autoconfiguration
• PropertySource
• ConfigMap PropertySource
• Secrets PropertySource
• PropertySource Reload
• Pod Health Indicator
• Transparency (its transparent wether the code runs in or outside of Kubernetes)
• Kubernetes Profile Autoconfiguration
• Ribbon discovery in Kubernetes
• Zipkin discovery in Kubernetes
• ConfigMap Archaius Bridge

DiscoveryClient for Kubernetes

This project provides an implementation of Discovery Client for Kubernetes. This allows you to query Kubernetes endpoints (see services) by name. This is something that you get for free just by adding the following dependency inside your project:

    io.fabric8
    spring-cloud-starter-kubernetes
    ${latest.version}

Then you can inject the client in your cloud simply by:

@Autowire
private DiscoveryClient discoveryClient;

If for any reason you need to disable the DiscoveryClient you can simply set the following property:

spring.cloud.kubernetes.discovery.enabled=false

Some spring cloud components use the DiscoveryClient in order obtain info about the local service instance. For this to work you need to align the service name with spring.application.name.

Kubernetes PropertySource

The most common approach to configure your spring boot application is to edit the application.yaml file. Often the user may override properties by specifying system properties or env variables.

ConfigMap PropertySource

Kubernetes has the notion of ConfigMap for passing configuration to the application. This project provides integration with ConfigMap to make config maps accessible by spring boot.

The ConfigMap PropertySource when enabled will lookup Kubernetes for a ConfigMap named after the application (see spring.application.name). If the map is found it will read its data and do the following:

• apply individual configuration properties.
• apply as yaml the content of any property named application.yaml
• apply as properties file the content of any property named application.properties

Example:

Let's assume that we have a spring boot application named demo that uses properties to read its thread pool configuration.

• pool.size.core
• pool.size.maximum

This can be externalized to config map in yaml format:

kind: ConfigMap
apiVersion: v1
metadata:
  name: demo
data:
  pool.size.core: 1
  pool.size.max: 16

Individual properties work fine for most cases but sometimes we yaml is more convinient. In this case we will use a single property named application.yaml and embed our yaml inside it:

kind: ConfigMap
apiVersion: v1
metadata:
 name: demo
data:
 application.yaml: |-
   pool:
     size:
       core: 1
       max:16

Notes:

• To access ConfigMaps on OpenShift the service account needs at least view permissions i.e.:

  oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)

Secrets PropertySource

Kubernetes has the notion of Secrets for storing sensitive data such as password, OAuth tokens, etc. This project provides integration with Secrets to make secrets accessible by spring boot.

The Secrets PropertySource when enabled will lookup Kubernetes for Secrets from the following sources:

1. reading recursively from secrets mounts
2. named after the application (see spring.application.name)
3. matching some labels

Please note that by default, consuming Secrets via API (points 2 and 3 above) is not enabled.

If the secrets are found theirs data is made available to the application.

Example:

Let's assume that we have a spring boot application named demo that uses properties to read its ActiveMQ and PostreSQL configuration.

• amq.username
• amq.password
• pg.username
• pg.password

This can be externalized to Secrets in yaml format:

• ActiveMQ

  yaml复制

  apiVersion: v1
  kind: Secret
  metadata:
    name: activemq-secrets
    labels:
      broker: activemq
  type: Opaque
  data:
    amq.username: bXl1c2VyCg==
    amq.password: MWYyZDFlMmU2N2Rm

• PostreSQL

  yaml复制

  apiVersion: v1
  kind: Secret
  metadata:
    name: postgres-secrets
    labels:
      db: postgres
  type: Opaque
  data:
    amq.username: dXNlcgo=
    amq.password: cGdhZG1pbgo=

You can select the Secrets to consume in a number of ways:

1. By listing the directories were secrets are mapped:

   复制

   -Dspring.cloud.kubernetes.secrets.paths=/etc/secrets/activemq,etc/secrets/postgres

   If you have all the secrets mapped to a common root, you can set them like:

   复制

   -Dspring.cloud.kubernetes.secrets.paths=/etc/secrets

2. By setting a named secret:

   复制

   -Dspring.cloud.kubernetes.secrets.name=postgres-secrets

3. By defining a list of labels:

   复制

   -Dspring.cloud.kubernetes.secrets.labels.broker=activemq
   -Dspring.cloud.kubernetes.secrets.labels.db=postgres

Properties:

Notes:

• The property spring.cloud.kubernetes.secrets.labels behave as defined by Map-based binding.
• The property spring.cloud.kubernetes.secrets.paths behave as defined by Collection-based binding.
• Access to secrets via API may be restricted for security reasons, the preferred way is to mount secret to the POD.

PropertySource Reload

Some applications may need to detect changes on external property sources and update their internal status to reflect the new configuration. The reload feature of Spring Cloud Kubernetes is able to trigger an application reload when a related ConfigMap or Secret change.

This feature is disabled by default and can be enabled using the configuration property spring.cloud.kubernetes.reload.enabled=true (eg. in the application.properties file).

The following levels of reload are supported (property spring.cloud.kubernetes.reload.strategy):

• refresh (default): only configuration beans annotated with @ConfigurationProperties or @RefreshScope are reloaded. This reload level leverages the refresh feature of Spring Cloud Context.
• restart_context: the whole Spring ApplicationContext is gracefully restarted. Beans are recreated with the new configuration.
• shutdown: the Spring ApplicationContext is shut down to activate a restart of the container. When using this level, make sure that the lifecycle of all non-daemon threads is bound to the ApplicationContext and that a replication controller or replica set is configured to restart the pod.

Example:

Assuming that the reload feature is enabled with default settings (refresh mode), the following bean will be refreshed when the config map changes:

@Configuration
@ConfigurationProperties(prefix = "bean")
public class MyConfig {

    private String message = "a message that can be changed live";

    // getter and setters

}

A way to see that changes effectively happen is creating another bean that prints the message periodically.

@Component
public class MyBean {

    @Autowired
    private MyConfig config;

    @Scheduled(fixedDelay = 5000)
    public void hello() {
        System.out.println("The message is: " + config.getMessage());
    }
}

The message printed by the application can be changed using a config map like the following one:

apiVersion: v1
kind: ConfigMap
metadata:
  name: reload-example
data:
  application.properties: |-
    bean.message=Hello World!

Any change to the property named bean.message in the Config Map associated to the pod will be reflected in the output of the program (more details here about how to associate a Config Map to a pod).

The full example is available in spring-cloud-kubernetes-reload-example.

The reload feature supports two operating modes:

• event (default): watches for changes in config maps or secrets using the Kubernetes API (web socket). Any event will produce a re-check on the configuration and a reload in case of changes. The view role on the service account is required in order to listen for config map changes. A higher level role (eg. edit) is required for secrets (secrets are not monitored by default).
• polling: re-creates the configuration periodically from config maps and secrets to see if it has changed. The polling period can be configured using the property spring.cloud.kubernetes.reload.period and defaults to 15 seconds. It requires the same role as the monitored property source. This means, for example, that using polling on file mounted secret sources does not require particular privileges.

Properties: