update docs yaml examples, and consistently document code in asciidoc (#280)
This commit is contained in:
Julio Cesar Villalta III
committed by
Ryan Baxter
Ryan Baxter
parent
df1d4424d4
commit
bd872515c4
72
README.adoc
72
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]
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes</artifactId>
|
||||
<version>${latest.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
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]
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-netflix</artifactId>
|
||||
<version>${latest.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
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: `<name of your service>.ribbon.<Ribbon configuration key>` 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:
|
||||
|
||||
Reference in New Issue
Block a user