diff --git a/README.adoc b/README.adoc index fcd8a345..ee7640f4 100644 --- a/README.adoc +++ b/README.adoc @@ -18,17 +18,16 @@ to fetch the list of the endpoints defined for an application to be load balance This is something that you get for free just by adding the following dependency inside your project: -```xml +[source,xml] org.springframework.cloud spring-cloud-starter-kubernetes ${latest.version} -``` To enable loading of the `DiscoveryClient`, add `@EnableDiscoveryClient` to the according configuration or application class like this: -```java +[source,java] @SpringBootApplication @EnableDiscoveryClient public class Application { @@ -36,20 +35,18 @@ public class Application { SpringApplication.run(Application.class, args); } } -``` Then you can inject the client in your code simply by: -```java +[source,java] @Autowired private DiscoveryClient discoveryClient; -``` 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 to obtain info about the local service instance. For this to work you need to align the Kubernetes service name with the `spring.application.name` property. @@ -77,7 +74,7 @@ However, more advanced configuration are possible where multiple ConfigMaps can This is made possible by the `spring.cloud.kubernetes.config.sources` list. For example one could define the following ConfigMaps -```yaml +[source,yaml] spring: application: name: cloud-k8s-app @@ -94,7 +91,6 @@ spring: # Spring Cloud Kubernetes will lookup a ConfigMap named c3 in namespace n3 - namespace: n3 name: c3 -``` In the example above, it `spring.cloud.kubernetes.config.namespace` had not been set, then the ConfigMap named `c1` would be looked up in the namespace that the application runs @@ -122,7 +118,7 @@ configuration. This can be externalized to config map in `yaml` format: -```yaml +[source,yaml] kind: ConfigMap apiVersion: v1 metadata: @@ -130,12 +126,11 @@ metadata: data: pool.size.core: 1 pool.size.max: 16 -``` 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 +[source,yaml] kind: ConfigMap apiVersion: v1 metadata: @@ -146,11 +141,10 @@ data: size: core: 1 max:16 -``` The following also works: - ```yaml +[source,yaml] kind: ConfigMap apiVersion: v1 metadata: @@ -161,14 +155,13 @@ data: size: core: 1 max:16 -``` Spring Boot applications can also be configured differently depending on active profiles which will be merged together when the ConfigMap is read. 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 +[source,yaml] kind: ConfigMap apiVersion: v1 metadata: @@ -191,22 +184,20 @@ data: profiles: production greeting: message: Say Hello to the Ops -``` In the above case, the configuration loaded into your Spring Application with the `development` profile will be: -```yaml +[source,yaml] greeting: message: Say Hello to the Developers farewell: message: Say Goodbye to the Developers -``` + whereas if the `production` profile is active, the configuration will be: -```yaml +[source,yaml] greeting: message: Say Hello to the Ops farewell: message: Say Goodbye -``` If both profiles are active, the property which appears last within the configmap will overwrite preceding values. @@ -215,7 +206,7 @@ To tell to Spring Boot which `profile` should be enabled at bootstrap, a system 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 +[source,yaml] apiVersion: v1 kind: DeploymentConfig spec: @@ -228,7 +219,6 @@ spec: value: /deployments - name: JAVA_OPTIONS value: -Dspring.profiles.active=developer -``` **Notes:** - check the security configuration section, to access config maps from inside a pod you need to have the correct @@ -266,13 +256,13 @@ If the secrets are found their data is made available to the application. Let's assume that we have a spring boot application named ``demo`` that uses properties to read its database configuration. We can create a Kubernetes secret using the following command: -``` +---- oc create secret generic db-secret --from-literal=username=user --from-literal=password=p455w0rd -``` +---- This would create the following secret (shown using `oc get secrets db-secret -o yaml`): -```yaml +[source,yaml] apiVersion: v1 data: password: cDQ1NXcwcmQ= @@ -286,14 +276,12 @@ metadata: selfLink: /api/v1/namespaces/default/secrets/db-secret uid: 63c89263-6099-11e7-b3da-76d6186905a8 type: Opaque -``` - Note that the data contains Base64-encoded versions of the literal provided by the create command. This secret can then be used by your application for example by exporting the secret's value as environment variables: -```yaml +[source,yaml] apiVersion: v1 kind: Deployment metadata: @@ -313,7 +301,6 @@ spec: secretKeyRef: name: db-secret key: password -``` You can select the Secrets to consume in a number of ways: @@ -381,7 +368,8 @@ Example: Assuming that the reload feature is enabled with default settings (*`refresh`* mode), the following bean will be refreshed when the config map changes: -```java +[source,java] +---- @Configuration @ConfigurationProperties(prefix = "bean") public class MyConfig { @@ -391,11 +379,12 @@ public class MyConfig { // getter and setters } -``` +---- A way to see that changes effectively happen is creating another bean that prints the message periodically. -```java +[source,java] +---- @Component public class MyBean { @@ -407,11 +396,12 @@ public class MyBean { System.out.println("The message is: " + config.getMessage()); } } -``` +---- The message printed by the application can be changed using a `ConfigMap` as follows: -```yaml +[source,java] +---- apiVersion: v1 kind: ConfigMap metadata: @@ -419,7 +409,7 @@ metadata: data: application.properties: |- bean.message=Hello World! -``` +---- Any change to the property named `bean.message` in the `ConfigMap` associated to the pod will be reflected in the output. More generally speaking, changes associated to properties prefixed with the value defined by the `prefix` @@ -465,20 +455,18 @@ about such endpoints. The implementation is part of the following starter that you can use by adding its dependency to your pom file: -```xml +[source,xml] org.springframework.cloud spring-cloud-starter-kubernetes-netflix ${latest.version} -``` When the list of the endpoints is populated, the Kubernetes client will search the registered endpoints living in the current namespace/project matching the service name defined using the Ribbon Client annotation: -```java +[source,java] @RibbonClient(name = "name-service") -``` You can configure Ribbon's behavior by providing properties in your `application.properties` (via your application's dedicated `ConfigMap`) using the following format: `.ribbon.` where: @@ -542,7 +530,7 @@ The Kubernetes health indicator which is part of the core module exposes the fol ## Namespace Most of the components provided in this project need to know the namespace. For Kubernetes (1.3+) the namespace is made available to pod as part of the service account secret and automatically detected by the client. For earlier version it needs to be specified as an env var to the pod. A quick way to do this is: - +[source,yaml] env: - name: "KUBERNETES_NAMESPACE" valueFrom: