diff --git a/README.md b/README.md index 24aaf597..0dd068b7 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,10 @@ This project provides an implementation of [Discovery Client](https://github.com/spring-cloud/spring-cloud-commons/blob/master/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java) for [Kubernetes](http://kubernetes.io). This allows you to query Kubernetes endpoints *(see [services](http://kubernetes.io/docs/user-guide/services/))* by name. +A service is typically exposed by the Kubernetes API server as a collection of endpoints which represent `http`, `https` addresses that a client can +access from a Spring Boot application running as a pod. This discovery feature is also used by the Spring Cloud Kubernetes Ribbon or Zipkin projects +to fetch respectively the list of the endpoints defined for an application to be load balanced or the Zipkin servers available to send the traces or spans. + This is something that you get for free just by adding the following dependency inside your project: ```xml @@ -38,43 +42,58 @@ This is something that you get for free just by adding the following dependency ``` -Then you can inject the client in your cloud simply by: +Then you can inject the client in your code simply by: ```java @Autowire private DiscoveryClient discoveryClient; ``` -If for any reason you need to disable the `DiscoveryClient` you can simply set the following property: +If for any reason you need to disable the `DiscoveryClient` you can simply set the following property in `application +.properties`: ``` 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`. +// TODO: make clearer with an example and details on how to align service and application name +Some Spring Cloud components use the `DiscoveryClient` in order to obtain info about the local service instance. For +this to work you need to align the service name with the `spring.application.name` property. ### 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. +The most common approach to configure your Spring Boot application is to create an `application.properties|yaml` or +an `application-profile.properties|yaml` file containing key-value pairs providing customization values to your +application or Spring Boot starters. Users may override these properties by specifying system properties or environment +variables. #### ConfigMap PropertySource -Kubernetes has the notion of [ConfigMap](http://kubernetes.io/docs/user-guide/configmap/) for passing configuration to the application. This project provides integration with `ConfigMap` to make config maps accessible by spring boot. +Kubernetes provides a resource named [ConfigMap](http://kubernetes.io/docs/user-guide/configmap/) to externalize the +parameters to pass to your application in the form of key-value pairs or embedded `application.properties|yaml` files. +The [Spring Cloud Kubernetes Config](./spring-cloud-kubernetes-config) project makes Kubernetes `ConfigMap`s available +during application bootstrapping and triggers hot reloading of beans or Spring context when changes are detected on +observed `ConfigMap`s. -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: +`ConfigMapPropertySource` will search for a Kubernetes `ConfigMap` which `metadata.name` is either the name of +your Spring application (as defined by its `spring.application.name` property) or a custom name defined within the +`bootstrap.properties` file under the following key `spring.cloud.kubernetes.config.name`. + +If such a `ConfigMap` is found, it will be processed as follows: - apply individual configuration properties. -- apply as yaml the content of any property named `application.yaml` +- 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. +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: +This can be externalized to config map in `yaml` format: ```yaml kind: ConfigMap @@ -86,7 +105,8 @@ data: pool.size.max: 16 ``` -Individual properties work fine for most cases but sometimes yaml is more convinient. In this case we will use a single property named `application.yaml` and embed our yaml inside it: +Individual properties work fine for most cases but sometimes embedded `yaml` is more convenient. In this case we will +use a single property named `application.yaml` to embed our `yaml`: ```yaml kind: ConfigMap @@ -101,10 +121,63 @@ data: max:16 ``` +Spring Boot applications can also be configured differently depending on active profiles and it is possible to +provide different property values for different profiles using an `application.properties|yaml` property, specifying +profile-specific values each in their own document (indicated by the `---` sequence) as follows: + +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: demo +data: + application.yml: |- + greeting: + message: Say Hello to the World + --- + spring: + profiles: development + greeting: + message: Say Hello to the Developers + --- + spring: + profiles: production + greeting: + message: Say Hello to the Ops +``` + +To tell to Spring Boot which `profile` should be enabled at bootstrap, a system property can be passed to the Java +command launching your Spring Boot application using an env variable that you will define with the OpenShift +`DeploymentConfig` or Kubernetes `ReplicationConfig` resource file as follows: + +```yaml +apiVersion: v1 +kind: DeploymentConfig +spec: + replicas: 1 + ... + spec: + containers: + - env: + - name: JAVA_APP_DIR + value: /deployments + - name: JAVA_OPTIONS + value: -Dspring.profile.active=developer +``` + **Notes:** -- To access ConfigMaps on OpenShift the service account needs at least view permissions i.e.: +- To access `ConfigMap`s 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)``` + +**Properties:** + +| Name | Type | Default | Description +| --- | --- | --- | --- +| spring.cloud.kubernetes.config.enabled | Boolean | true | Enable Secrets PropertySource +| spring.cloud.kubernetes.config.name | String | ${spring.application.name} | Sets the name of ConfigMap to lookup +| spring.cloud.kubernetes.config.namespace | String | Client namespace | Sets the Kubernetes namespace where to lookup + #### Secrets PropertySource @@ -121,7 +194,7 @@ 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. +Let's assume that we have a spring boot application named ``demo`` that uses properties to read its ActiveMQ Message broker and PosgreSQL Database configuration. - `amq.username` - `amq.password` @@ -144,25 +217,27 @@ This can be externalized to Secrets in yaml format: amq.password: MWYyZDFlMmU2N2Rm ``` -- **PostgreSQL** +- **PosgreSQL** ```yaml apiVersion: v1 kind: Secret metadata: - name: postgres-secrets + name: posgresql-secrets labels: - db: postgres + db: posgresql type: Opaque data: - pg.username: dXNlcgo= - pg.password: cGdhZG1pbgo= + amq.username: dXNlcgo= + amq.password: cGdhZG1pbgo= ``` +**NOTE** +The data are converted from clear text format to base64 when a secret is created. 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 + -Dspring.cloud.kubernetes.secrets.paths=/etc/secrets/activemq,etc/secrets/posgresql ``` If you have all the secrets mapped to a common root, you can set them like: @@ -173,13 +248,13 @@ You can select the Secrets to consume in a number of ways: 2. By setting a named secret: ``` - -Dspring.cloud.kubernetes.secrets.name=postgres-secrets + -Dspring.cloud.kubernetes.secrets.name=posgresql-secrets ``` 3. By defining a list of labels: ``` -Dspring.cloud.kubernetes.secrets.labels.broker=activemq - -Dspring.cloud.kubernetes.secrets.labels.db=postgres + -Dspring.cloud.kubernetes.secrets.labels.db=posgresql ``` **Properties:** @@ -188,6 +263,7 @@ You can select the Secrets to consume in a number of ways: | --- | --- | --- | --- | spring.cloud.kubernetes.secrets.enabled | Boolean | true | Enable Secrets PropertySource | spring.cloud.kubernetes.secrets.name | String | ${spring.application.name} | Sets the name of the secret to lookup +| spring.cloud.kubernetes.secrets.namespace | String | Client namespace | Sets the kubernetes namespace where to lookup | spring.cloud.kubernetes.secrets.labels | Map | null | Sets the labels used to lookup secrets | spring.cloud.kubernetes.secrets.paths | List | null | Sets the paths were secrets are mounted /example 1) | spring.cloud.kubernetes.secrets.enableApi | Boolean | false | Enable/Disable consuming secrets via APIs (examples 2 and 3) @@ -293,20 +369,22 @@ Notes: Spring Boot uses [HealthIndicator](https://github.com/spring-projects/spring-boot/blob/master/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/health/HealthIndicator.java) to expose info about the health of an application. That makes it really useful for exposing health related information to the user and are also a good fit for use as [readiness probes](http://kubernetes.io/docs/user-guide/production-pods/#liveness-and-readiness-probes-aka-health-checks). -The Kubernetes health indicator which is part of the core modules exposes the following info: +The Kubernetes health indicator which is part of the core module exposes the following info: -- pod name -- visible services -- flag that indicates if app is internal or external to Kubernetes +- pod name, ip address, namespace, service account, node name amd its ip address +- flag that indicates if the Spring Boot application is internal or external to Kubernetes ### Transparency -All of the features described above will work equally fine regardless of wether our application is inside Kubernetes or not. This is really helpful for development and troubleshooting. +All of the features described above will work equally fine regardless of whether our application is running inside Kubernetes or not. This is really helpful for development and troubleshooting. +From a development point of view, this is really helpful as you can start your Spring Boot application and debug one of the modules part of this project. It is not required to deploy it in Kubernetes +as the code of the project relies on the [Fabric8 Kubernetes Java client](https://github.com/fabric8io/kubernetes-client) which is a fluent DSL able to communicate using `http` protocol to the REST Api of Kubernetes Server. ### Kubernetes Profile Autoconfiguration -When the application is run inside Kubernetes a profile named `kubernetes` will automatically get activated. -This allows the user to customize the configuration that will be applied in and out of kubernetes *(e.g. different dev and prod configuration)*. +When the application runs as a pod inside Kubernetes a Spring profile named `kubernetes` will automatically get activated. +This allows the developer to customize the configuration, to define beans that will be applied when the Spring Boot application is deployed +within the kubernetes platform *(e.g. different dev and prod configuration)*. ### Ribbon discovery in Kubernetes @@ -314,7 +392,11 @@ This allows the user to customize the configuration that will be applied in and [![Javadocs](http://www.javadoc.io/badge/org.springframework.cloud/spring-cloud-starter-kubernetes-netflix.svg?color=blue)](http://www.javadoc.io/doc/org.springframework.cloud/spring-cloud-starter-kubernetes-netflix) [![Dependency Status](https://www.versioneye.com/java/org.springframework.cloud:spring-cloud-starter-kubernetes-netflix/badge?style=flat)](https://www.versioneye.com/java/org.springframework.cloud:spring-cloud-starter-kubernetes-netflix/) -A Kubernetes based `ServerList` for Ribbon has been implemented. The implementation is part of the [spring-cloud-kubernetes-ribbon](spring-cloud-kubernetes-ribbon/pom.xml) module and you can use it by adding: +A Spring Cloud application which is a client calling a microservice will be interested to rely on a client loadbalanceing feature in order to discover for a service, the endpoints that it could +reach. This mechanism has been implemented within the [spring-cloud-kubernetes-ribbon](spring-cloud-kubernetes-ribbon/pom.xml) project where a kubernetes client will populate a `ServerList` about +such endpoints available. + +The implementation is part of the following starter that you can use by adding its dependency to your pom file: ```xml @@ -324,19 +406,26 @@ A Kubernetes based `ServerList` for Ribbon has been implemented. The implementat ``` -The ribbon discovery client can be disabled by setting `spring.cloud.kubernetes.ribbon.enabled=false`. +When the list of the endpoints will be populated, the Kubernetes client will search the registered endpoints that lives in the current namespace/project and where the name to search has been defined +using the Ribbon Client annotation -By default the client will detect all endpoints with the configured *client name* that lives in the current namespace. -If the endpoint contains multiple ports, the first port will be used. To fine tune the name of the desired port (if the service is a multiport service) or fine tune the namespace you can use one of the following properties. +```java +@RibbonClient(name = "name-service") +``` + +If a endpoint contains multiple ports, the first port will be used. To fine tune the name of the desired port (if the service is a multiport service) or fine tune the namespace you can use one of the following properties. - `KubernetesNamespace` - `PortName` Examples that are using this module for ribbon discovery are: +- [Sprinng Cloud Circuitbreaker and Ribbon](kubernetes-circuitbreaker-ribbon-example) - [fabric8-quickstarts - Spring Boot - Ribbon](https://github.com/fabric8-quickstarts/spring-boot-ribbon) - [Kubeflix - LoanBroker - Bank](https://github.com/fabric8io/kubeflix/tree/master/examples/loanbroker/bank) +Remark : The ribbon discovery client can be disabled by setting this key within the application properties file `spring.cloud.kubernetes.ribbon.enabled=false`. + ### Zipkin discovery in Kubernetes @@ -344,9 +433,11 @@ Examples that are using this module for ribbon discovery are: [![Javadocs](http://www.javadoc.io/badge/org.springframework.cloud/spring-cloud-starter-kubernetes-zipkin.svg?color=blue)](http://www.javadoc.io/doc/org.springframework.cloud/spring-cloud-starter-kubernetes-zipkin) [![Dependency Status](https://www.versioneye.com/java/org.springframework.cloud:spring-cloud-starter-kubernetes-zipkin/badge?style=flat)](https://www.versioneye.com/java/org.springframework.cloud:spring-cloud-starter-kubernetes-zipkin/) -[Zipkin](https://github.com/openzipkin/zipkin) is a distributed tracing system and it is also supported by [Sleuth](https://github.com/spring-cloud/spring-cloud-sleuth). +[Zipkin](https://github.com/openzipkin/zipkin) is a distributed tracing system which is supported by the project [Spring Cloud Sleuth](https://github.com/spring-cloud/spring-cloud-sleuth) which allows +to collect traces or spans from microservice applications. -Discovery of the services required by Zipkin (e.g. `zipkin-query`) is provided by [spring-cloud-kubernetes-zipkin](spring-cloud-kubernetes-zipkin/pom.xml) module and you can use it by adding: +A Discovery client has been implemented top of Kubernetes in order to fetch the service Zipkin (e.g. `zipkin`). This client is provided by the [spring-cloud-kubernetes-zipkin](spring-cloud-kubernetes-zipkin/pom.xml) project that you can use it by adding +this starter to your maven pom file: ```xml @@ -356,10 +447,19 @@ Discovery of the services required by Zipkin (e.g. `zipkin-query`) is provided b ``` -This works as an extension of [spring-cloud-sleuth-zipkin](https://github.com/spring-cloud/spring-cloud-sleuth/tree/master/spring-cloud-sleuth-zipkin). +This works as an extension of the [spring-cloud-sleuth-zipkin](https://github.com/spring-cloud/spring-cloud-sleuth/tree/master/spring-cloud-sleuth-zipkin) project. +the name of the Zipkin service to find like also the kubernetes namespace/project where it runs can be changed using these keys: + +```bash +spring.cloud.kubernetes.zipkin.discovery.serviceName=my-zipkin +spring.cloud.kubernetes.zipkin.discovery.serviceNamespace=tracing +``` + +By default, the discovery client will look about the service `zipkin` within the current namespace. Examples of application that are using Zipkin discovery in Kubernetes: +- [Spring Cloud Kubernetes and Zipkin](kubernetes-zipkin) - [fabric8-quickstarts - Spring Boot - Ribbon](https://github.com/fabric8-quickstarts/spring-boot-ribbon) - [Kubeflix - LoanBroker - Bank](https://github.com/fabric8io/kubeflix/tree/master/examples/loanbroker/bank) @@ -369,11 +469,14 @@ Examples of application that are using Zipkin discovery in Kubernetes: [![Javadocs](http://www.javadoc.io/badge/org.springframework.cloud/spring-cloud-kubernetes-archaius.svg?color=blue)](http://www.javadoc.io/doc/org.springframework.cloud/spring-cloud-kubernetes-archaius) [![Dependency Status](https://www.versioneye.com/java/org.springframework.cloud:spring-cloud-kubernetes-archaius/badge?style=flat)](https://www.versioneye.com/java/org.springframework.cloud:spring-cloud-kubernetes-archaius/) -Section [ConfigMap PropertySource](#configmap-propertysource) provides a brief explanation on how to configure spring boot application via ConfigMap. -This approach will aid in creating the configuration properties objects that will be passed in our application. If our application is using Archaius it will indirectly benefit by it. -An alternative approach that provides more direct Archaius support without getting in the way of spring configuration properties by using [spring-cloud-kubernetes-archaius](spring-cloud-kubernetes-archaius/pom.xml) that is part of the Netflix starter. +The section [ConfigMap PropertySource](#configmap-propertysource) introduced how to configure a spring boot application via `Kubernetes ConfigMap` containing your configuration properties file. -This module allows you to annotate your application with the `@ArchaiusConfigMapSource` and archaius will automatically use the configmap as a watched source *(get notification on changes)*. +If you prefer to use the configuration management library [NetFlix Archaius](https://github.com/Netflix/archaius/wiki) instead of using the Spring application.properties|"yaml file, +then you can also leverage the `ConfigMap feature` by using the [spring-cloud-kubernetes-archaius](spring-cloud-kubernetes-archaius/pom.xml) project. + +To use it, add the following starter `spring-cloud-starter-kubernetes-all` to yiur pom file definition. + +This module allows you to annotate your application with the `@ArchaiusConfigMapSource` and archaius will automatically use the `Kubernetes configmap` as a watched source *(get notification on changes)*. --- ### Troubleshooting @@ -396,7 +499,9 @@ For earlier version it needs to be specified as an env var to the pod. A quick w #### Service Account -For distros of Kubernetes that support more fine-grained role-based access within the cluster, you need to make sure a pod that runs with spring-cloud-kubernetes has access to the Kubernetes API. For example, OpenShift has very comprehensive security measures that are on by default (typically) in a shared cluster. For any service accounts you assign to a deployment/pod, you need to make sure it has the correct roles. For example, you can add `cluster-reader` permissions to your `default` service account depending on the project you're in: +For distros of Kubernetes that support more fine-grained role-based access within the cluster, you need to make sure a pod that runs with spring-cloud-kubernetes has access to the Kubernetes API. +For example, OpenShift has very comprehensive security measures that are on by default (typically) in a shared cluster. +For any service accounts you assign to a deployment/pod, you need to make sure it has the correct roles. For example, you can add `cluster-reader` permissions to your `default` service account depending on the project you're in: ``` oc policy add-role-to-user cluster-reader system:serviceaccount::default