Antora migration (#1446)
* Migrate Structure * Insert explicit ids for headers * Remove unnecessary asciidoc attributes * Copy default antora files * Fix indentation for all pages * Split files * Generate a default navigation * Remove includes * Fix cross references * Enable Section Summary TOC for small pages * Antora migration
This commit is contained in:
Spencer Gibb
20
docs/src/main/antora/resources/antora-resources/antora.yml
Normal file
20
docs/src/main/antora/resources/antora-resources/antora.yml
Normal file
@@ -0,0 +1,20 @@
|
||||
version: @antora-component.version@
|
||||
prerelease: @antora-component.prerelease@
|
||||
|
||||
asciidoc:
|
||||
attributes:
|
||||
attribute-missing: 'warn'
|
||||
chomp: 'all'
|
||||
project-root: @maven.multiModuleProjectDirectory@
|
||||
github-repo: @docs.main@
|
||||
github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
|
||||
github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@
|
||||
github-issues: https://github.com/spring-cloud/@docs.main@/issues/
|
||||
github-wiki: https://github.com/spring-cloud/@docs.main@/wiki
|
||||
spring-cloud-version: @project.version@
|
||||
github-tag: @github-tag@
|
||||
version-type: @version-type@
|
||||
docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@
|
||||
raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
|
||||
project-version: @project.version@
|
||||
project-name: @docs.main@
|
||||
@@ -1 +0,0 @@
|
||||
include::spring-cloud-kubernetes.adoc[]
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
:doctype: book
|
||||
:idprefix:
|
||||
:idseparator: -
|
||||
:toc: left
|
||||
:toclevels: 4
|
||||
:tabsize: 4
|
||||
:numbered:
|
||||
:sectanchors:
|
||||
:sectnums:
|
||||
:icons: font
|
||||
:hide-uri-scheme:
|
||||
:docinfo: shared,private
|
||||
|
||||
:sc-ext: java
|
||||
:project-full-name: Spring Cloud Kubernetes
|
||||
:all: {asterisk}{asterisk}
|
||||
@@ -1,116 +0,0 @@
|
||||
|===
|
||||
|Name | Default | Description
|
||||
|
||||
|spring.cloud.kubernetes.client.api-version | |
|
||||
|spring.cloud.kubernetes.client.apiVersion | `+++v1+++` | Kubernetes API Version
|
||||
|spring.cloud.kubernetes.client.ca-cert-data | |
|
||||
|spring.cloud.kubernetes.client.ca-cert-file | |
|
||||
|spring.cloud.kubernetes.client.caCertData | | Kubernetes API CACertData
|
||||
|spring.cloud.kubernetes.client.caCertFile | | Kubernetes API CACertFile
|
||||
|spring.cloud.kubernetes.client.client-cert-data | |
|
||||
|spring.cloud.kubernetes.client.client-cert-file | |
|
||||
|spring.cloud.kubernetes.client.client-key-algo | |
|
||||
|spring.cloud.kubernetes.client.client-key-data | |
|
||||
|spring.cloud.kubernetes.client.client-key-file | |
|
||||
|spring.cloud.kubernetes.client.client-key-passphrase | |
|
||||
|spring.cloud.kubernetes.client.clientCertData | | Kubernetes API ClientCertData
|
||||
|spring.cloud.kubernetes.client.clientCertFile | | Kubernetes API ClientCertFile
|
||||
|spring.cloud.kubernetes.client.clientKeyAlgo | `+++RSA+++` | Kubernetes API ClientKeyAlgo
|
||||
|spring.cloud.kubernetes.client.clientKeyData | | Kubernetes API ClientKeyData
|
||||
|spring.cloud.kubernetes.client.clientKeyFile | | Kubernetes API ClientKeyFile
|
||||
|spring.cloud.kubernetes.client.clientKeyPassphrase | `+++changeit+++` | Kubernetes API ClientKeyPassphrase
|
||||
|spring.cloud.kubernetes.client.connection-timeout | |
|
||||
|spring.cloud.kubernetes.client.connectionTimeout | `+++10s+++` | Connection timeout
|
||||
|spring.cloud.kubernetes.client.http-proxy | |
|
||||
|spring.cloud.kubernetes.client.https-proxy | |
|
||||
|spring.cloud.kubernetes.client.logging-interval | |
|
||||
|spring.cloud.kubernetes.client.loggingInterval | `+++20s+++` | Logging interval
|
||||
|spring.cloud.kubernetes.client.master-url | |
|
||||
|spring.cloud.kubernetes.client.masterUrl | `+++https://kubernetes.default.svc+++` | Kubernetes API Master Node URL
|
||||
|spring.cloud.kubernetes.client.namespace | `+++true+++` | Kubernetes Namespace
|
||||
|spring.cloud.kubernetes.client.no-proxy | |
|
||||
|spring.cloud.kubernetes.client.oauth-token | |
|
||||
|spring.cloud.kubernetes.client.oauthToken | | Kubernetes API Oauth Token
|
||||
|spring.cloud.kubernetes.client.password | | Kubernetes API Password
|
||||
|spring.cloud.kubernetes.client.proxy-password | |
|
||||
|spring.cloud.kubernetes.client.proxy-username | |
|
||||
|spring.cloud.kubernetes.client.request-timeout | |
|
||||
|spring.cloud.kubernetes.client.requestTimeout | `+++10s+++` | Request timeout
|
||||
|spring.cloud.kubernetes.client.rolling-timeout | |
|
||||
|spring.cloud.kubernetes.client.rollingTimeout | `+++900s+++` | Rolling timeout
|
||||
|spring.cloud.kubernetes.client.service-account-namespace-path | `+++/var/run/secrets/kubernetes.io/serviceaccount/namespace+++` |
|
||||
|spring.cloud.kubernetes.client.trust-certs | |
|
||||
|spring.cloud.kubernetes.client.trustCerts | `+++false+++` | Kubernetes API Trust Certificates
|
||||
|spring.cloud.kubernetes.client.user-agent | `+++Spring-Cloud-Kubernetes-Application+++` |
|
||||
|spring.cloud.kubernetes.client.username | | Kubernetes API Username
|
||||
|spring.cloud.kubernetes.client.watch-reconnect-interval | |
|
||||
|spring.cloud.kubernetes.client.watch-reconnect-limit | |
|
||||
|spring.cloud.kubernetes.client.watchReconnectInterval | `+++1s+++` | Reconnect Interval
|
||||
|spring.cloud.kubernetes.client.watchReconnectLimit | `+++-1+++` | Reconnect Interval limit retries
|
||||
|spring.cloud.kubernetes.config.enable-api | `+++true+++` |
|
||||
|spring.cloud.kubernetes.config.enabled | `+++true+++` | Enable the ConfigMap property source locator.
|
||||
|spring.cloud.kubernetes.config.fail-fast | `+++false+++` |
|
||||
|spring.cloud.kubernetes.config.include-profile-specific-sources | `+++true+++` |
|
||||
|spring.cloud.kubernetes.config.labels | |
|
||||
|spring.cloud.kubernetes.config.name | |
|
||||
|spring.cloud.kubernetes.config.namespace | |
|
||||
|spring.cloud.kubernetes.config.paths | |
|
||||
|spring.cloud.kubernetes.config.retry | |
|
||||
|spring.cloud.kubernetes.config.sources | |
|
||||
|spring.cloud.kubernetes.config.use-name-as-prefix | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.all-namespaces | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.cache-loading-timeout-seconds | `+++60+++` |
|
||||
|spring.cloud.kubernetes.discovery.enabled | `+++true+++` |
|
||||
|spring.cloud.kubernetes.discovery.filter | |
|
||||
|spring.cloud.kubernetes.discovery.include-external-name-services | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.include-not-ready-addresses | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.known-secure-ports | `+++[443, 8443]+++` |
|
||||
|spring.cloud.kubernetes.discovery.metadata.add-annotations | `+++true+++` |
|
||||
|spring.cloud.kubernetes.discovery.metadata.add-labels | `+++true+++` |
|
||||
|spring.cloud.kubernetes.discovery.metadata.add-pod-annotations | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.metadata.add-pod-labels | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.metadata.add-ports | `+++true+++` |
|
||||
|spring.cloud.kubernetes.discovery.metadata.annotations-prefix | |
|
||||
|spring.cloud.kubernetes.discovery.metadata.labels-prefix | |
|
||||
|spring.cloud.kubernetes.discovery.metadata.ports-prefix | `+++port.+++` |
|
||||
|spring.cloud.kubernetes.discovery.namespaces | |
|
||||
|spring.cloud.kubernetes.discovery.order | `+++0+++` |
|
||||
|spring.cloud.kubernetes.discovery.primary-port-name | |
|
||||
|spring.cloud.kubernetes.discovery.service-labels | |
|
||||
|spring.cloud.kubernetes.discovery.use-endpoint-slices | `+++false+++` |
|
||||
|spring.cloud.kubernetes.discovery.wait-cache-ready | `+++true+++` |
|
||||
|spring.cloud.kubernetes.leader.auto-startup | `+++true+++` | Should leader election be started automatically on startup. Default: true
|
||||
|spring.cloud.kubernetes.leader.config-map-name | `+++leaders+++` | Kubernetes ConfigMap where leaders information will be stored. Default: leaders
|
||||
|spring.cloud.kubernetes.leader.create-config-map | `+++true+++` | Enable/disable creating ConfigMap if it does not exist. Default: true
|
||||
|spring.cloud.kubernetes.leader.enabled | `+++true+++` | Should leader election be enabled. Default: true
|
||||
|spring.cloud.kubernetes.leader.leader-id-prefix | `+++leader.id.+++` | Leader id property prefix for the ConfigMap. Default: leader.id.
|
||||
|spring.cloud.kubernetes.leader.namespace | | Kubernetes namespace where the leaders ConfigMap and candidates are located.
|
||||
|spring.cloud.kubernetes.leader.publish-failed-events | `+++false+++` | Enable/disable publishing events in case leadership acquisition fails. Default: false
|
||||
|spring.cloud.kubernetes.leader.role | | Role for which leadership this candidate will compete.
|
||||
|spring.cloud.kubernetes.leader.update-period | `+++60000ms+++` | Leadership status check period. Default: 60s
|
||||
|spring.cloud.kubernetes.loadbalancer.cluster-domain | `+++cluster.local+++` | cluster domain.
|
||||
|spring.cloud.kubernetes.loadbalancer.enabled | `+++true+++` | Load balancer enabled,default true.
|
||||
|spring.cloud.kubernetes.loadbalancer.mode | | {@link KubernetesLoadBalancerMode} setting load balancer server list with ip of pod or service name. default value is POD.
|
||||
|spring.cloud.kubernetes.loadbalancer.port-name | `+++http+++` | service port name.
|
||||
|spring.cloud.kubernetes.reload.enable-reload-filtering | `+++false+++` |
|
||||
|spring.cloud.kubernetes.reload.enabled | `+++false+++` |
|
||||
|spring.cloud.kubernetes.reload.max-wait-for-restart | `+++2s+++` |
|
||||
|spring.cloud.kubernetes.reload.mode | `+++EVENT+++` |
|
||||
|spring.cloud.kubernetes.reload.monitoring-config-maps | `+++true+++` |
|
||||
|spring.cloud.kubernetes.reload.monitoring-secrets | `+++false+++` |
|
||||
|spring.cloud.kubernetes.reload.namespaces | |
|
||||
|spring.cloud.kubernetes.reload.period | `+++15000ms+++` |
|
||||
|spring.cloud.kubernetes.reload.strategy | `+++REFRESH+++` |
|
||||
|spring.cloud.kubernetes.secrets.enable-api | `+++false+++` |
|
||||
|spring.cloud.kubernetes.secrets.enabled | `+++true+++` | Enable the Secrets property source locator.
|
||||
|spring.cloud.kubernetes.secrets.fail-fast | `+++false+++` |
|
||||
|spring.cloud.kubernetes.secrets.include-profile-specific-sources | `+++true+++` |
|
||||
|spring.cloud.kubernetes.secrets.labels | |
|
||||
|spring.cloud.kubernetes.secrets.name | |
|
||||
|spring.cloud.kubernetes.secrets.namespace | |
|
||||
|spring.cloud.kubernetes.secrets.paths | |
|
||||
|spring.cloud.kubernetes.secrets.retry | |
|
||||
|spring.cloud.kubernetes.secrets.sources | |
|
||||
|spring.cloud.kubernetes.secrets.use-name-as-prefix | `+++false+++` |
|
||||
|
||||
|===
|
||||
@@ -1,14 +0,0 @@
|
||||
:numbered!:
|
||||
[appendix]
|
||||
[[common-application-properties]]
|
||||
== Common application properties
|
||||
|
||||
include::_attributes.adoc[]
|
||||
|
||||
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
|
||||
This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them.
|
||||
|
||||
NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
|
||||
Also, you can define your own properties.
|
||||
|
||||
include::_configprops.adoc[]
|
||||
@@ -1,175 +0,0 @@
|
||||
== DiscoveryClient for Kubernetes
|
||||
|
||||
This project provides an implementation of https://github.com/spring-cloud/spring-cloud-commons/blob/master/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java[Discovery Client]
|
||||
for https://kubernetes.io[Kubernetes].
|
||||
This client lets you query Kubernetes endpoints (see https://kubernetes.io/docs/user-guide/services/[services]) by name.
|
||||
A service is typically exposed by the Kubernetes API server as a collection of endpoints that represent `http` and `https` addresses and that a client can
|
||||
access from a Spring Boot application running as a pod.
|
||||
|
||||
DiscoveryClient can also find services of type `ExternalName` (see https://kubernetes.io/docs/concepts/services-networking/service/#externalname[ExternalName services]). At the moment, external name support type of services is only available if the following property `spring.cloud.kubernetes.discovery.include-external-name-services` is set to `true` and only in the `fabric8` implementation. In a later release, support will be added for the kubernetes native client also.
|
||||
|
||||
This is something that you get for free by adding the following dependency inside your project:
|
||||
|
||||
====
|
||||
HTTP Based `DiscoveryClient`
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-discoveryclient</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
NOTE: `spring-cloud-starter-kubernetes-discoveryclient` is designed to be used with the
|
||||
<<spring-cloud-kubernetes-discoveryserver, Spring Cloud Kubernetes DiscoveryServer>>.
|
||||
|
||||
====
|
||||
Fabric8 Kubernetes Client
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-fabric8</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
====
|
||||
Kubernetes Java Client
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-client</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
To enable loading of the `DiscoveryClient`, add `@EnableDiscoveryClient` to the according configuration or application class, as the following example shows:
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@SpringBootApplication
|
||||
@EnableDiscoveryClient
|
||||
public class Application {
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(Application.class, args);
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Then you can inject the client in your code simply by autowiring it, as the following example shows:
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Autowired
|
||||
private DiscoveryClient discoveryClient;
|
||||
----
|
||||
====
|
||||
|
||||
You can choose to enable `DiscoveryClient` from all namespaces by setting the following property in `application.properties`:
|
||||
|
||||
====
|
||||
[source]
|
||||
----
|
||||
spring.cloud.kubernetes.discovery.all-namespaces=true
|
||||
----
|
||||
====
|
||||
|
||||
To discover services and endpoints only from specified namespaces you should set property `all-namespaces` to `false` and set the following property in `application.properties` (in this example namespaces are: `ns1` and `ns2`).
|
||||
|
||||
====
|
||||
[source]
|
||||
----
|
||||
spring.cloud.kubernetes.discovery.namespaces[0]=ns1
|
||||
spring.cloud.kubernetes.discovery.namespaces[1]=ns2
|
||||
----
|
||||
====
|
||||
|
||||
To discover service endpoint addresses that are not marked as "ready" by the kubernetes api server, you can set the following property in `application.properties` (default: false):
|
||||
|
||||
====
|
||||
[source]
|
||||
----
|
||||
spring.cloud.kubernetes.discovery.include-not-ready-addresses=true
|
||||
----
|
||||
NOTE: This might be useful when discovering services for monitoring purposes, and would enable inspecting the `/health` endpoint of not-ready service instances.
|
||||
====
|
||||
|
||||
If your service exposes multiple ports, you will need to specify which port the `DiscoveryClient` should use.
|
||||
The `DiscoveryClient` will choose the port using the following logic.
|
||||
|
||||
1. If the service has a label `primary-port-name` it will use the port with the name specified in the label's value.
|
||||
2. If no label is present, then the port name specified in `spring.cloud.kubernetes.discovery.primary-port-name` will be used.
|
||||
3. If neither of the above are specified it will use the port named `https`.
|
||||
4. If none of the above conditions are met it will use the port named `http`.
|
||||
5. As a last resort it wil pick the first port in the list of ports.
|
||||
|
||||
WARNING: The last option may result in non-deterministic behaviour.
|
||||
Please make sure to configure your service and/or application accordingly.
|
||||
|
||||
By default all of the ports and their names will be added to the metadata of the `ServiceInstance`.
|
||||
|
||||
As said before, if you want to get the list of `ServiceInstance` to also include the `ExternalName` type services, you need to enable that support via: `spring.cloud.kubernetes.discovery.include-external-name-services=true`. As such, when calling `DiscoveryClient::getInstances` those will be returned also. You can distinguish between `ExternalName` and any other types by inspecting `ServiceInstance::getMetadata` and lookup for a field called `type`. This will be the type of the service returned : `ExternalName`/`ClusterIP`, etc.
|
||||
|
||||
`ServiceInstance` can include the labels and annotations of specific pods from the underlying service instance. To obtain such information, you need to also enable:
|
||||
|
||||
`spring.cloud.kubernetes.discovery.metadata.add-pod-labels=true` and/or `spring.cloud.kubernetes.discovery.metadata.add-pod-annotations=true`. At the moment, such functionality is present only in the fabric8 client implementation, but will be added to the kubernetes native client in a later release.
|
||||
|
||||
If, for any reason, you need to disable the `DiscoveryClient`, you can set the following property in `application.properties`:
|
||||
|
||||
====
|
||||
[source]
|
||||
----
|
||||
spring.cloud.kubernetes.discovery.enabled=false
|
||||
----
|
||||
====
|
||||
|
||||
Some Spring Cloud components use the `DiscoveryClient` in order to obtain information about the local service instance. For
|
||||
this to work, you need to align the Kubernetes service name with the `spring.application.name` property.
|
||||
|
||||
NOTE: `spring.application.name` has no effect as far as the name registered for the application within Kubernetes
|
||||
|
||||
Spring Cloud Kubernetes can also watch the Kubernetes service catalog for changes and update the
|
||||
`DiscoveryClient` implementation accordingly. By "watch" we mean that we will publish a heartbeat event every `spring.cloud.kubernetes.discovery.catalog-services-watch-delay`
|
||||
milliseconds (by default it is `30000`). The heartbeat event will contain the target references (and their namespaces of the addresses of all endpoints
|
||||
(for the exact details of what will get returned you can take a look inside `KubernetesCatalogWatch`). This is an implementation detail, and listeners of the heartbeat event
|
||||
should not rely on the details. Instead, they should see if there are differences between two subsequent heartbeats via `equals` method. We will take care to return a correct implementation that adheres to the equals contract.
|
||||
The endpoints will be queried in either :
|
||||
|
||||
- all namespaces (enabled via `spring.cloud.kubernetes.discovery.all-namespaces=true`)
|
||||
|
||||
- specific namespaces (enabled via `spring.cloud.kubernetes.discovery.namespaces`), for example:
|
||||
|
||||
```
|
||||
spring:
|
||||
cloud:
|
||||
kubernetes:
|
||||
discovery:
|
||||
namespaces:
|
||||
- namespace-a
|
||||
- namespace-b
|
||||
```
|
||||
|
||||
- we will use: xref:property-source-config.adoc#namespace-resolution[Namespace Resolution] if the above two paths are not taken.
|
||||
|
||||
In order to enable this functionality you need to add
|
||||
`@EnableScheduling` on a configuration class in your application.
|
||||
|
||||
By default, we use the `Endpoints`(see https://kubernetes.io/docs/concepts/services-networking/service/#endpoints) API to find out the current state of services. There is another way though, via `EndpointSlices` (https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/). Such support can be enabled via a property: `spring.cloud.kubernetes.discovery.use-endpoint-slices=true` (by default it is `false`). Of course, your cluster has to support it also. As a matter of fact, if you enable this property, but your cluster does not support it, we will fail starting the application. If you decide to enable such support, you also need proper Role/ClusterRole set-up. For example:
|
||||
|
||||
```
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
namespace: default
|
||||
name: namespace-reader
|
||||
rules:
|
||||
- apiGroups: ["discovery.k8s.io"]
|
||||
resources: ["endpointslices"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
```
|
||||
@@ -1,11 +0,0 @@
|
||||
== Kubernetes native service discovery
|
||||
|
||||
Kubernetes itself is capable of (server side) service discovery (see: https://kubernetes.io/docs/concepts/services-networking/service/#discovering-services).
|
||||
Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (https://istio.io), a service mesh that is capable of load balancing, circuit breaker, failover, and much more.
|
||||
|
||||
The caller service then need only refer to names resolvable in a particular Kubernetes cluster. A simple implementation might use a spring `RestTemplate` that refers to a fully qualified domain name (FQDN), such as `https://{service-name}.{namespace}.svc.{cluster}.local:{service-port}`.
|
||||
|
||||
Additionally, you can use Hystrix for:
|
||||
|
||||
* Circuit breaker implementation on the caller side, by annotating the spring boot application class with `@EnableCircuitBreaker`
|
||||
* Fallback functionality, by annotating the respective method with `@HystrixCommand(fallbackMethod=`
|
||||
@@ -1,17 +0,0 @@
|
||||
== Examples
|
||||
|
||||
Spring Cloud Kubernetes tries to make it transparent for your applications to consume Kubernetes Native Services by
|
||||
following the Spring Cloud interfaces.
|
||||
|
||||
In your applications, you need to add the `spring-cloud-kubernetes-discovery` dependency to your classpath and remove any other dependency that contains a `DiscoveryClient` implementation (that is, a Eureka discovery client).
|
||||
The same applies for `PropertySourceLocator`, where you need to add to the classpath the `spring-cloud-kubernetes-config` and remove any other dependency that contains a `PropertySourceLocator` implementation (that is, a configuration server client).
|
||||
|
||||
The following projects highlight the usage of these dependencies and demonstrate how you can use these libraries from any Spring Boot application:
|
||||
|
||||
* https://github.com/spring-cloud/spring-cloud-kubernetes/tree/master/spring-cloud-kubernetes-examples[Spring Cloud Kubernetes Examples]: the ones located inside this repository.
|
||||
* Spring Cloud Kubernetes Full Example: Minions and Boss
|
||||
** https://github.com/salaboy/spring-cloud-k8s-minion[Minion]
|
||||
** https://github.com/salaboy/spring-cloud-k8s-boss[Boss]
|
||||
* Spring Cloud Kubernetes Full Example: https://github.com/salaboy/s1p_docs[SpringOne Platform Tickets Service]
|
||||
* https://github.com/salaboy/s1p_gateway[Spring Cloud Gateway with Spring Cloud Kubernetes Discovery and Config]
|
||||
* https://github.com/salaboy/showcase-admin-tool[Spring Boot Admin with Spring Cloud Kubernetes Discovery and Config]
|
||||
@@ -1,74 +0,0 @@
|
||||
== Starters
|
||||
|
||||
Starters are convenient dependency descriptors you can include in your
|
||||
application. Include a starter to get the dependencies and Spring Boot
|
||||
auto-configuration for a feature set. Starters that begin with `spring-cloud-starter-kubernetes-fabric8`
|
||||
provide implementations using the https://github.com/fabric8io/kubernetes-client[Fabric8 Kubernetes Java Client].
|
||||
Starters that begin with
|
||||
`spring-cloud-starter-kubernetes-client` provide implementations using the https://github.com/kubernetes-client/java[Kubernetes Java Client].
|
||||
|
||||
[cols="a,d"]
|
||||
|===
|
||||
| Starter | Features
|
||||
|
||||
| [source,xml]
|
||||
.Fabric8 Dependency
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-fabric8</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
[source,xml]
|
||||
.Kubernetes Client Dependency
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-client</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
| <<DiscoveryClient for Kubernetes,Discovery Client>> implementation that
|
||||
resolves service names to Kubernetes Services.
|
||||
|
||||
| [source,xml]
|
||||
.Fabric8 Dependency
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-fabric8-config</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
[source,xml]
|
||||
.Kubernetes Client Dependency
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-client-config</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
| Load application properties from Kubernetes
|
||||
<<configmap-propertysource,ConfigMaps>> and <<Secrets PropertySource,Secrets>>.
|
||||
<<propertysource-reload,Reload>> application properties when a ConfigMap or
|
||||
Secret changes.
|
||||
|
||||
| [source,xml]
|
||||
.Fabric8 Dependency
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-fabric8-all</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
[source,xml]
|
||||
.Kubernetes Client Dependency
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-client-all</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
| All Spring Cloud Kubernetes features.
|
||||
|===
|
||||
@@ -1 +0,0 @@
|
||||
include::spring-cloud-kubernetes.adoc[]
|
||||
@@ -1,7 +0,0 @@
|
||||
== Info Contributor
|
||||
|
||||
Spring Cloud Kubernetes includes an `InfoContributor` which adds Pod information to
|
||||
Spring Boot's `/info` Acturator endpoint.
|
||||
|
||||
You can disable this `InfoContributor` by setting `management.info.kubernetes.enabled`
|
||||
to `false` in `application.[properties | yaml]`.
|
||||
@@ -1,42 +0,0 @@
|
||||
== Kubernetes Ecosystem Awareness
|
||||
|
||||
All features described earlier in this guide work equally well, regardless of whether your application is running inside
|
||||
Kubernetes. This is really helpful for development and troubleshooting.
|
||||
From a development point of view, this lets you start your Spring Boot application and debug one
|
||||
of the modules that is part of this project. You need not deploy it in Kubernetes,
|
||||
as the code of the project relies on the
|
||||
https://github.com/fabric8io/kubernetes-client[Fabric8 Kubernetes Java client], which is a fluent DSL that can
|
||||
communicate by using `http` protocol to the REST API of the Kubernetes Server.
|
||||
|
||||
Kubernetes awareness is based on Spring Boot API, specifically on https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/condition/ConditionalOnCloudPlatform.html[ConditionalOnCloudPlatform].
|
||||
That property will auto-detect if your application is currently deployed in kubernetes or not. It is possible to override
|
||||
that setting via `spring.main.cloud-platform`.
|
||||
|
||||
For example, if you need to test some features, but do not want to deploy to a cluster, it is enough to set the:
|
||||
`spring.main.cloud-platform=KUBERNETES`. This will make `spring-cloud-kubernetes` act as-if it is deployed in a real cluster.
|
||||
|
||||
NOTE: If you have `spring-cloud-starter-bootstrap` on your classpath or are setting `spring.cloud.bootstrap.enabled=true` then
|
||||
you will have to set `spring.main.cloud-platform` should be set in `bootstrap.{properties|yml}`
|
||||
(or the profile specific one). Also note that these properties: `spring.cloud.kubernetes.config.enabled` and `spring.cloud.kubernetes.secrets.enabled`
|
||||
will only take effect when set in `bootstrap.{properties|yml}` when you have `spring-cloud-starter-bootstrap` on your classpath or are setting `spring.cloud.bootstrap.enabled=true`.
|
||||
|
||||
=== Breaking Changes In 3.0.x
|
||||
|
||||
In versions of Spring Cloud Kubernetes prior to `3.0.x`, Kubernetes awareness was implemented using `spring.cloud.kubernetes.enabled` property. This
|
||||
property was removed and is un-supported. Instead, we use Spring Boot API: https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/condition/ConditionalOnCloudPlatform.html[ConditionalOnCloudPlatform].
|
||||
If it is needed to explicitly enable or disable this awareness, use `spring.main.cloud-platform=NONE/KUBERNETES`.
|
||||
|
||||
=== Kubernetes Profile Autoconfiguration
|
||||
|
||||
When the application runs as a pod inside Kubernetes, a Spring profile named `kubernetes` automatically gets activated.
|
||||
This lets you customize the configuration, to define beans that are applied when the Spring Boot application is deployed
|
||||
within the Kubernetes platform (for example, different development and production configuration).
|
||||
|
||||
=== Istio Awareness
|
||||
|
||||
When you include the `spring-cloud-kubernetes-fabric8-istio` module in the application classpath, a new profile is added to the application,
|
||||
provided the application is running inside a Kubernetes Cluster with https://istio.io[Istio] installed. You can then use
|
||||
spring `@Profile("istio")` annotations in your Beans and `@Configuration` classes.
|
||||
|
||||
The Istio awareness module uses `me.snowdrop:istio-client` to interact with Istio APIs, letting us discover traffic rules, circuit breakers, and so on,
|
||||
making it easy for our Spring Boot applications to consume this data to dynamically configure themselves according to the environment.
|
||||
@@ -1,29 +0,0 @@
|
||||
== Leader Election
|
||||
The Spring Cloud Kubernetes leader election mechanism implements the leader election API of Spring Integration using a Kubernetes ConfigMap.
|
||||
|
||||
Multiple application instances compete for leadership, but leadership will only be granted to one.
|
||||
When granted leadership, a leader application receives an `OnGrantedEvent` application event with leadership `Context`.
|
||||
Applications periodically attempt to gain leadership, with leadership granted to the first caller.
|
||||
A leader will remain a leader until either it is removed from the cluster, or it yields its leadership.
|
||||
When leadership removal occurs, the previous leader receives `OnRevokedEvent` application event.
|
||||
After removal, any instances in the cluster may become the new leader, including the old leader.
|
||||
|
||||
To include it in your project, add the following dependency.
|
||||
====
|
||||
Fabric8 Leader Implementation
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-kubernetes-fabric8-leader</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
To specify the name of the configmap used for leader election use the following property.
|
||||
====
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.kubernetes.leader.config-map-name=leader
|
||||
----
|
||||
====
|
||||
@@ -1,42 +0,0 @@
|
||||
== LoadBalancer for Kubernetes
|
||||
This project includes Spring Cloud Load Balancer for load balancing based on Kubernetes Endpoints and provides implementation of load balancer based on Kubernetes Service.
|
||||
To include it to your project add the following dependency.
|
||||
====
|
||||
Fabric8 Implementation
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-fabric8-loadbalancer</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
====
|
||||
Kubernetes Java Client Implementation
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-kubernetes-client-loadbalancer</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
To enable load balancing based on Kubernetes Service name use the following property. Then load balancer would try to call application using address, for example `service-a.default.svc.cluster.local`
|
||||
====
|
||||
[source]
|
||||
----
|
||||
spring.cloud.kubernetes.loadbalancer.mode=SERVICE
|
||||
----
|
||||
====
|
||||
|
||||
To enabled load balancing across all namespaces use the following property. Property from `spring-cloud-kubernetes-discovery` module is respected.
|
||||
====
|
||||
[source]
|
||||
----
|
||||
spring.cloud.kubernetes.discovery.all-namespaces=true
|
||||
----
|
||||
====
|
||||
|
||||
If a service needs to be accessed over HTTPS you need to add a label or annotation to your service definition with the name `secured` and the value `true` and the load balancer will then use HTTPS to make requests to the service.
|
||||
@@ -1,9 +0,0 @@
|
||||
== Other Resources
|
||||
|
||||
This section lists other resources, such as presentations (slides) and videos about Spring Cloud Kubernetes.
|
||||
|
||||
* https://salaboy.com/2018/09/27/the-s1p-experience/[S1P Spring Cloud on PKS]
|
||||
* https://salaboy.com/2018/07/18/ljc-july-18-spring-cloud-docker-k8s/[Spring Cloud, Docker, Kubernetes -> London Java Community July 2018]
|
||||
|
||||
|
||||
Please feel free to submit other resources through pull requests to https://github.com/spring-cloud/spring-cloud-kubernetes[this repository].
|
||||
@@ -1,12 +0,0 @@
|
||||
== Pod Health Indicator
|
||||
|
||||
Spring Boot uses https://github.com/spring-projects/spring-boot/blob/master/spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/health/HealthEndpoint.java[`HealthIndicator`] to expose info about the health of an application.
|
||||
That makes it really useful for exposing health-related information to the user and makes it a good fit for use as https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/[readiness probes].
|
||||
|
||||
The Kubernetes health indicator (which is part of the core module) exposes the following info:
|
||||
|
||||
* Pod name, IP address, namespace, service account, node name, and its IP address
|
||||
* A flag that indicates whether the Spring Boot application is internal or external to Kubernetes
|
||||
|
||||
You can disable this `HealthContributor` by setting `management.health.kubernetes.enabled`
|
||||
to `false` in `application.[properties | yaml]`.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,12 +0,0 @@
|
||||
Spring Cloud Kubernetes provide Spring Cloud common interface implementations that consume Kubernetes native services.
|
||||
The main objective of the projects provided in this repository is to facilitate the integration of Spring Cloud and Spring Boot applications running inside Kubernetes.
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
* Kubernetes awareness
|
||||
* `DiscoveryClient` implementation
|
||||
* `PropertySource` objects configured via ConfigMaps
|
||||
|
||||
## Getting Started
|
||||
The easiest way to get started is by including the Spring Cloud BOM and then adding `spring-cloud-starter-kubernetes-client-all` to your application's classpath. If you don't want to include all of the Spring Cloud Kubernetes features you can add individual starters for the features you would like. By default Spring Cloud Kubernetes will enable the `kubernetes` profile when it detects it is running inside a Kubernetes cluster. You can take advantage of this by creating a `kubernetes-application` configuration properties for anything specific to Kubernetes you might want to configure. Once the starter is on the classpath the application should behave as any other Spring Cloud application.
|
||||
@@ -1,78 +0,0 @@
|
||||
== Security Configurations Inside Kubernetes
|
||||
|
||||
|
||||
=== Namespace
|
||||
|
||||
Most of the components provided in this project need to know the namespace. For Kubernetes (1.3+), the namespace is made available to the pod as part of the service account secret and is automatically detected by the client.
|
||||
For earlier versions, it needs to be specified as an environment variable to the pod. A quick way to do this is as follows:
|
||||
|
||||
====
|
||||
[source]
|
||||
----
|
||||
env:
|
||||
- name: "KUBERNETES_NAMESPACE"
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: "metadata.namespace"
|
||||
----
|
||||
====
|
||||
|
||||
=== Service Account
|
||||
|
||||
For distributions 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 any service accounts you assign to a deployment or pod, you need to make sure they have the correct roles.
|
||||
|
||||
Depending on the requirements, you'll need `get`, `list` and `watch` permission on the following resources:
|
||||
|
||||
.Kubernetes Resource Permissions
|
||||
|===
|
||||
|Dependency | Resources
|
||||
|
||||
|
||||
|spring-cloud-starter-kubernetes-fabric8
|
||||
|pods, services, endpoints
|
||||
|
||||
|spring-cloud-starter-kubernetes-fabric8-config
|
||||
|configmaps, secrets
|
||||
|
||||
|spring-cloud-starter-kubernetes-client
|
||||
|pods, services, endpoints
|
||||
|
||||
|spring-cloud-starter-kubernetes-client-config
|
||||
|configmaps, secrets
|
||||
|===
|
||||
|
||||
For development purposes, you can add `cluster-reader` permissions to your `default` service account. On a production system you'll likely want to provide more granular permissions.
|
||||
|
||||
The following Role and RoleBinding are an example for namespaced permissions for the `default` account:
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
kind: Role
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
metadata:
|
||||
namespace: YOUR-NAME-SPACE
|
||||
name: namespace-reader
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["configmaps", "pods", "services", "endpoints", "secrets"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
|
||||
---
|
||||
|
||||
kind: RoleBinding
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
metadata:
|
||||
name: namespace-reader-binding
|
||||
namespace: YOUR-NAME-SPACE
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: default
|
||||
apiGroup: ""
|
||||
roleRef:
|
||||
kind: Role
|
||||
name: namespace-reader
|
||||
apiGroup: ""
|
||||
----
|
||||
====
|
||||
@@ -1,5 +0,0 @@
|
||||
== Service Registry Implementation
|
||||
|
||||
In Kubernetes service registration is controlled by the platform, the application itself does not control
|
||||
registration as it may do in other platforms. For this reason using `spring.cloud.service-registry.auto-registration.enabled`
|
||||
or setting `@EnableDiscoveryClient(autoRegister=false)` will have no effect in Spring Cloud Kubernetes.
|
||||
@@ -1,122 +0,0 @@
|
||||
[#spring-cloud-kubernetes-configserver]
|
||||
## Spring Cloud Kubernetes Config Server
|
||||
|
||||
The Spring Cloud Kubernetes Config Server, is based on https://spring.io/projects/spring-cloud-config[Spring Cloud Config Server] and adds an https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_environment_repository[environment repository] for Kubernetes
|
||||
https://kubernetes.io/docs/concepts/configuration/configmap/[Config Maps] and https://kubernetes.io/docs/concepts/configuration/secret/[Secrets].
|
||||
|
||||
This is component is completely optional. However, it allows you to continue to leverage configuration
|
||||
you may have stored in existing environment repositories (Git, SVN, Vault, etc) with applications that you are running on Kubernetes.
|
||||
|
||||
A default image is located on https://hub.docker.com/r/springcloud/spring-cloud-kubernetes-configserver[Docker Hub] which will allow you to easily get a Config Server deployed on Kubernetes without building
|
||||
the code and image yourself. However, if you need to customize the config server behavior or prefer to build the image yourself you can easily build your own
|
||||
image from the https://github.com/spring-cloud/spring-cloud-kubernetes/tree/main/spring-cloud-kubernetes-controllers/spring-cloud-kubernetes-configserver[source code on GitHub] and use that.
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Enabling The Kubernetes Environment Repository
|
||||
To enable the Kubernetes environment repository the `kubernetes` profile must be included in the list of active profiles.
|
||||
You may activate other profiles as well to use other environment repository implementations.
|
||||
|
||||
#### Config Map and Secret PropertySources
|
||||
By default, only Config Map data will be fetched. To enable Secrets as well you will need to set `spring.cloud.kubernetes.secrets.enableApi=true`.
|
||||
You can disable the Config Map `PropertySource` by setting `spring.cloud.kubernetes.config.enableApi=false`.
|
||||
|
||||
#### Fetching Config Map and Secret Data From Additional Namespaces
|
||||
By default, the Kubernetes environment repository will only fetch Config Map and Secrets from the namespace in which it is deployed.
|
||||
If you want to include data from other namespaces you can set `spring.cloud.kubernetes.configserver.config-map-namespaces` and/or `spring.cloud.kubernetes.configserver.secrets-namespaces` to a comma separated
|
||||
list of namespace values.
|
||||
|
||||
NOTE: If you set `spring.cloud.kubernetes.configserver.config-map-namespaces` and/or `spring.cloud.kubernetes.configserver.secrets-namespaces`
|
||||
you will need to include the namespace in which the Config Server is deployed in order to continue to fetch Config Map and Secret data from that namespace.
|
||||
|
||||
#### Kubernetes Access Controls
|
||||
The Kubernetes Config Server uses the Kubernetes API server to fetch Config Map and Secret data. In order for it to do that
|
||||
it needs ability to `get` and `list` Config Map and Secrets (depending on what you enable/disable).
|
||||
|
||||
### Deployment Yaml
|
||||
|
||||
Below is a sample deployment, service and permissions configuration you can use to deploy a basic Config Server to Kubernetes.
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: List
|
||||
items:
|
||||
- apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configserver
|
||||
name: spring-cloud-kubernetes-configserver
|
||||
spec:
|
||||
ports:
|
||||
- name: http
|
||||
port: 8888
|
||||
targetPort: 8888
|
||||
selector:
|
||||
app: spring-cloud-kubernetes-configserver
|
||||
type: ClusterIP
|
||||
- apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configserver
|
||||
name: spring-cloud-kubernetes-configserver
|
||||
- apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configserver
|
||||
name: spring-cloud-kubernetes-configserver:view
|
||||
roleRef:
|
||||
kind: Role
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
name: namespace-reader
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: spring-cloud-kubernetes-configserver
|
||||
- apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
namespace: default
|
||||
name: namespace-reader
|
||||
rules:
|
||||
- apiGroups: ["", "extensions", "apps"]
|
||||
resources: ["configmaps", "secrets"]
|
||||
verbs: ["get", "list"]
|
||||
- apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: spring-cloud-kubernetes-configserver-deployment
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: spring-cloud-kubernetes-configserver
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configserver
|
||||
spec:
|
||||
serviceAccount: spring-cloud-kubernetes-configserver
|
||||
containers:
|
||||
- name: spring-cloud-kubernetes-configserver
|
||||
image: springcloud/spring-cloud-kubernetes-configserver
|
||||
imagePullPolicy: IfNotPresent
|
||||
env:
|
||||
- name: SPRING_PROFILES_INCLUDE
|
||||
value: "kubernetes"
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
port: 8888
|
||||
path: /actuator/health/readiness
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
port: 8888
|
||||
path: /actuator/health/liveness
|
||||
ports:
|
||||
- containerPort: 8888
|
||||
|
||||
----
|
||||
====
|
||||
@@ -1,216 +0,0 @@
|
||||
[#spring-cloud-kubernetes-configuration-watcher]
|
||||
## Spring Cloud Kubernetes Configuration Watcher
|
||||
|
||||
Kubernetes provides the ability to https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#add-configmap-data-to-a-volume[mount a ConfigMap or Secret as a volume]
|
||||
in the container of your application. When the contents of the ConfigMap or Secret changes, the https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#mounted-configmaps-are-updated-automatically[mounted volume will be updated with those changes].
|
||||
|
||||
However, Spring Boot will not automatically update those changes unless you restart the application. Spring Cloud
|
||||
provides the ability refresh the application context without restarting the application by either hitting the
|
||||
actuator endpoint `/refresh` or via publishing a `RefreshRemoteApplicationEvent` using Spring Cloud Bus.
|
||||
|
||||
To achieve this configuration refresh of a Spring Cloud app running on Kubernetes, you can deploy the Spring Cloud
|
||||
Kubernetes Configuration Watcher controller into your Kubernetes cluster.
|
||||
|
||||
The application is published as a container and is available on https://hub.docker.com/r/springcloud/spring-cloud-kubernetes-configuration-watcher[Docker Hub].
|
||||
However, if you need to customize the config watcher behavior or prefer to build the image yourself you can easily build your own
|
||||
image from the https://github.com/spring-cloud/spring-cloud-kubernetes/tree/main/spring-cloud-kubernetes-controllers/spring-cloud-kubernetes-configuration-watcher[source code on GitHub] and use that.
|
||||
|
||||
Spring Cloud Kubernetes Configuration Watcher can send refresh notifications to applications in two ways.
|
||||
|
||||
1. Over HTTP in which case the application being notified must of the `/refresh` actuator endpoint exposed and accessible from within the cluster
|
||||
2. Using Spring Cloud Bus, in which case you will need a message broker deployed to your custer for the application to use.
|
||||
|
||||
### Deployment YAML
|
||||
|
||||
Below is a sample deployment YAML you can use to deploy the Kubernetes Configuration Watcher to Kubernetes.
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: List
|
||||
items:
|
||||
- apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configuration-watcher
|
||||
name: spring-cloud-kubernetes-configuration-watcher
|
||||
spec:
|
||||
ports:
|
||||
- name: http
|
||||
port: 8888
|
||||
targetPort: 8888
|
||||
selector:
|
||||
app: spring-cloud-kubernetes-configuration-watcher
|
||||
type: ClusterIP
|
||||
- apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configuration-watcher
|
||||
name: spring-cloud-kubernetes-configuration-watcher
|
||||
- apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configuration-watcher
|
||||
name: spring-cloud-kubernetes-configuration-watcher:view
|
||||
roleRef:
|
||||
kind: Role
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
name: namespace-reader
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: spring-cloud-kubernetes-configuration-watcher
|
||||
- apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
namespace: default
|
||||
name: namespace-reader
|
||||
rules:
|
||||
- apiGroups: ["", "extensions", "apps"]
|
||||
resources: ["configmaps", "pods", "services", "endpoints", "secrets"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
- apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: spring-cloud-kubernetes-configuration-watcher-deployment
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: spring-cloud-kubernetes-configuration-watcher
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-configuration-watcher
|
||||
spec:
|
||||
serviceAccount: spring-cloud-kubernetes-configuration-watcher
|
||||
containers:
|
||||
- name: spring-cloud-kubernetes-configuration-watcher
|
||||
image: springcloud/spring-cloud-kubernetes-configuration-watcher:2.0.1-SNAPSHOT
|
||||
imagePullPolicy: IfNotPresent
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
port: 8888
|
||||
path: /actuator/health/readiness
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
port: 8888
|
||||
path: /actuator/health/liveness
|
||||
ports:
|
||||
- containerPort: 8888
|
||||
|
||||
----
|
||||
====
|
||||
|
||||
The Service Account and associated Role Binding is important for Spring Cloud Kubernetes Configuration to work properly.
|
||||
The controller needs access to read data about ConfigMaps, Pods, Services, Endpoints and Secrets in the Kubernetes cluster.
|
||||
|
||||
### Monitoring ConfigMaps and Secrets
|
||||
|
||||
Spring Cloud Kubernetes Configuration Watcher will react to changes in ConfigMaps with a label of `spring.cloud.kubernetes.config` with the value `true`
|
||||
or any Secret with a label of `spring.cloud.kubernetes.secret` with the value `true`. If the ConfigMap or Secret does not have either of those labels
|
||||
or the values of those labels is not `true` then any changes will be ignored.
|
||||
|
||||
If a change is made to a ConfigMap or Secret with valid labels then Spring Cloud Kubernetes Configuration Watcher will take the name of the ConfigMap or Secret
|
||||
and send a notification to the application with that name. This might not be enough for your use-case though, you could for example what to:
|
||||
|
||||
- bind a config-map to multiple applications, so that a change inside a single configmap triggers a refresh for many services
|
||||
- have profile based sources trigger events for your application
|
||||
|
||||
For that reasons there is an addition annotation you could specify:
|
||||
|
||||
`spring.cloud.kubernetes.configmap.apps` or `spring.cloud.kubernetes.secret.apps`. It takes a String of apps separated by comma,
|
||||
that specifies the names of applications that will receive a notification when changes happen in this secret/configmap.
|
||||
|
||||
For example:
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
kind: ConfigMap
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: example-configmap
|
||||
labels:
|
||||
spring.cloud.kubernetes.config: "true"
|
||||
annotations:
|
||||
spring.cloud.kubernetes.configmap.apps: "app-a, app-b"
|
||||
----
|
||||
====
|
||||
|
||||
### HTTP Implementation
|
||||
|
||||
The HTTP implementation is what is used by default. When this implementation is used Spring Cloud Kubernetes Configuration Watcher and a
|
||||
change to a ConfigMap or Secret occurs then the HTTP implementation will use the Spring Cloud Kubernetes Discovery Client to fetch all
|
||||
instances of the application which match the name of the ConfigMap or Secret and send an HTTP POST request to the application's actuator
|
||||
`/refresh` endpoint. By default it will send the post request to `/actuator/refresh` using the port registered in the discovery client.
|
||||
|
||||
#### Non-Default Management Port and Actuator Path
|
||||
|
||||
If the application is using a non-default actuator path and/or using a different port for the management endpoints, the Kubernetes service for the application
|
||||
can add an annotation called `boot.spring.io/actuator` and set its value to the path and port used by the application. For example
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app: config-map-demo
|
||||
name: config-map-demo
|
||||
annotations:
|
||||
boot.spring.io/actuator: http://:9090/myactuator/home
|
||||
spec:
|
||||
ports:
|
||||
- name: http
|
||||
port: 8080
|
||||
targetPort: 8080
|
||||
selector:
|
||||
app: config-map-demo
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
Another way you can choose to configure the actuator path and/or management port is by setting
|
||||
`spring.cloud.kubernetes.configuration.watcher.actuatorPath` and `spring.cloud.kubernetes.configuration.watcher.actuatorPort`.
|
||||
|
||||
### Messaging Implementation
|
||||
|
||||
The messaging implementation can be enabled by setting profile to either `bus-amqp` (RabbitMQ) or `bus-kafka` (Kafka) when the Spring Cloud Kubernetes Configuration Watcher
|
||||
application is deployed to Kubernetes.
|
||||
|
||||
### Configuring RabbitMQ
|
||||
|
||||
When the `bus-amqp` profile is enabled you will need to configure Spring RabbitMQ to point it to the location of the RabbitMQ
|
||||
instance you would like to use as well as any credentials necessary to authenticate. This can be done
|
||||
by setting the standard Spring RabbitMQ properties, for example
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
username: user
|
||||
password: password
|
||||
host: rabbitmq
|
||||
----
|
||||
====
|
||||
|
||||
### Configuring Kafka
|
||||
|
||||
When the `bus-kafka` profile is enabled you will need to configure Spring Kafka to point it to the location of the Kafka Broker
|
||||
instance you would like to use. This can be done by setting the standard Spring Kafka properties, for example
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
producer:
|
||||
bootstrap-servers: localhost:9092
|
||||
----
|
||||
====
|
||||
@@ -1,214 +0,0 @@
|
||||
[#spring-cloud-kubernetes-discoveryserver]
|
||||
## Spring Cloud Kubernetes Discovery Server
|
||||
|
||||
The Spring Cloud Kubernetes Discovery Server provides HTTP endpoints apps can use to gather information
|
||||
about services available within a Kubernetes cluster. The Spring Cloud Kubernetes Discovery Server
|
||||
can be used by apps using the `spring-cloud-starter-kubernetes-discoveryclient` to provide data to
|
||||
the `DiscoveryClient` implementation provided by that starter.
|
||||
|
||||
### Permissions
|
||||
The Spring Cloud Discovery server uses
|
||||
the Kubernetes API server to get data about Service and Endpoint resrouces so it needs list, watch, and
|
||||
get permissions to use those endpoints. See the below sample Kubernetes deployment YAML for an
|
||||
examlpe of how to configure the Service Account on Kubernetes.
|
||||
|
||||
|
||||
### Endpoints
|
||||
There are three endpoints exposed by the server.
|
||||
|
||||
#### `/apps`
|
||||
|
||||
A `GET` request sent to `/apps` will return a JSON array of available services. Each item contains
|
||||
the name of the Kubernetes service and service instance information. Below is a sample response.
|
||||
|
||||
====
|
||||
[source,json]
|
||||
----
|
||||
[
|
||||
{
|
||||
"name":"spring-cloud-kubernetes-discoveryserver",
|
||||
"serviceInstances":[
|
||||
{
|
||||
"instanceId":"836a2f25-daee-4af2-a1be-aab9ce2b938f",
|
||||
"serviceId":"spring-cloud-kubernetes-discoveryserver",
|
||||
"host":"10.244.1.6",
|
||||
"port":8761,
|
||||
"uri":"http://10.244.1.6:8761",
|
||||
"secure":false,
|
||||
"metadata":{
|
||||
"app":"spring-cloud-kubernetes-discoveryserver",
|
||||
"kubectl.kubernetes.io/last-applied-configuration":"{\"apiVersion\":\"v1\",\"kind\":\"Service\",\"metadata\":{\"annotations\":{},\"labels\":{\"app\":\"spring-cloud-kubernetes-discoveryserver\"},\"name\":\"spring-cloud-kubernetes-discoveryserver\",\"namespace\":\"default\"},\"spec\":{\"ports\":[{\"name\":\"http\",\"port\":80,\"targetPort\":8761}],\"selector\":{\"app\":\"spring-cloud-kubernetes-discoveryserver\"},\"type\":\"ClusterIP\"}}\n",
|
||||
"http":"8761"
|
||||
},
|
||||
"namespace":"default",
|
||||
"scheme":"http"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name":"kubernetes",
|
||||
"serviceInstances":[
|
||||
{
|
||||
"instanceId":"1234",
|
||||
"serviceId":"kubernetes",
|
||||
"host":"172.18.0.3",
|
||||
"port":6443,
|
||||
"uri":"http://172.18.0.3:6443",
|
||||
"secure":false,
|
||||
"metadata":{
|
||||
"provider":"kubernetes",
|
||||
"component":"apiserver",
|
||||
"https":"6443"
|
||||
},
|
||||
"namespace":"default",
|
||||
"scheme":"http"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
----
|
||||
====
|
||||
|
||||
#### `/apps/{name}`
|
||||
|
||||
A `GET` request to `/apps/{name}` can be used to get instance data for all instances of a given
|
||||
service. Below is a sample response when a `GET` request is made to `/apps/kubernetes`.
|
||||
|
||||
====
|
||||
[source,json]
|
||||
----
|
||||
[
|
||||
{
|
||||
"instanceId":"1234",
|
||||
"serviceId":"kubernetes",
|
||||
"host":"172.18.0.3",
|
||||
"port":6443,
|
||||
"uri":"http://172.18.0.3:6443",
|
||||
"secure":false,
|
||||
"metadata":{
|
||||
"provider":"kubernetes",
|
||||
"component":"apiserver",
|
||||
"https":"6443"
|
||||
},
|
||||
"namespace":"default",
|
||||
"scheme":"http"
|
||||
}
|
||||
]
|
||||
----
|
||||
====
|
||||
|
||||
#### `/app/{name}/{instanceid}`
|
||||
|
||||
A `GET` request made to `/app/{name}/{instanceid}` will return the instance data for a specific
|
||||
instance of a given service. Below is a sample response when a `GET` request is made to `/app/kubernetes/1234`.
|
||||
|
||||
====
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"instanceId":"1234",
|
||||
"serviceId":"kubernetes",
|
||||
"host":"172.18.0.3",
|
||||
"port":6443,
|
||||
"uri":"http://172.18.0.3:6443",
|
||||
"secure":false,
|
||||
"metadata":{
|
||||
"provider":"kubernetes",
|
||||
"component":"apiserver",
|
||||
"https":"6443"
|
||||
},
|
||||
"namespace":"default",
|
||||
"scheme":"http"
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
### Deployment YAML
|
||||
|
||||
An image of the Spring Cloud Discovery Server is hosted on https://hub.docker.com/r/springcloud/spring-cloud-kubernetes-discoveryserver[Docker Hub].
|
||||
However, if you need to customize the discovery server behavior or prefer to build the image yourself you can easily build your own
|
||||
image from the https://github.com/spring-cloud/spring-cloud-kubernetes/tree/main/spring-cloud-kubernetes-controllers/spring-cloud-kubernetes-discoveryserver[source code on GitHub] and use that.
|
||||
|
||||
Below is a sample deployment YAML you can use to deploy the Kubernetes Configuration Watcher to Kubernetes.
|
||||
|
||||
====
|
||||
[source,yaml]
|
||||
----
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: List
|
||||
items:
|
||||
- apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-discoveryserver
|
||||
name: spring-cloud-kubernetes-discoveryserver
|
||||
spec:
|
||||
ports:
|
||||
- name: http
|
||||
port: 80
|
||||
targetPort: 8761
|
||||
selector:
|
||||
app: spring-cloud-kubernetes-discoveryserver
|
||||
type: ClusterIP
|
||||
- apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-discoveryserver
|
||||
name: spring-cloud-kubernetes-discoveryserver
|
||||
- apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-discoveryserver
|
||||
name: spring-cloud-kubernetes-discoveryserver:view
|
||||
roleRef:
|
||||
kind: Role
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
name: namespace-reader
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: spring-cloud-kubernetes-discoveryserver
|
||||
- apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
namespace: default
|
||||
name: namespace-reader
|
||||
rules:
|
||||
- apiGroups: ["", "extensions", "apps"]
|
||||
resources: ["services", "endpoints"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
- apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: spring-cloud-kubernetes-discoveryserver-deployment
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: spring-cloud-kubernetes-discoveryserver
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: spring-cloud-kubernetes-discoveryserver
|
||||
spec:
|
||||
serviceAccount: spring-cloud-kubernetes-discoveryserver
|
||||
containers:
|
||||
- name: spring-cloud-kubernetes-discoveryserver
|
||||
image: springcloud/spring-cloud-kubernetes-discoveryserver:3.0.0-SNAPSHOT
|
||||
imagePullPolicy: IfNotPresent
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
port: 8761
|
||||
path: /actuator/health/readiness
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
port: 8761
|
||||
path: /actuator/health/liveness
|
||||
ports:
|
||||
- containerPort: 8761
|
||||
|
||||
|
||||
----
|
||||
====
|
||||
@@ -1,69 +0,0 @@
|
||||
= Spring Cloud Kubernetes
|
||||
include::_attributes.adoc[]
|
||||
|
||||
This reference guide covers how to use Spring Cloud Kubernetes.
|
||||
|
||||
== Why do you need Spring Cloud Kubernetes?
|
||||
|
||||
Spring Cloud Kubernetes provides implementations of well known Spring Cloud interfaces allowing developers to build and run Spring Cloud applications on Kubernetes. While this project may be useful to you when building a cloud native application, it is also not a requirement in order to deploy a Spring Boot app on Kubernetes. If you are just getting started in your journey to running your Spring Boot app on Kubernetes you can accomplish a lot with nothing more than a basic Spring Boot app and Kubernetes itself. To learn more, you can get started by reading the https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#cloud-deployment-kubernetes[Spring Boot reference documentation for deploying to Kubernetes ] and also working through the workshop material https://hackmd.io/@ryanjbaxter/spring-on-k8s-workshop[Spring and Kubernetes].
|
||||
|
||||
include::getting-started.adoc[]
|
||||
|
||||
include::discovery-client.adoc[]
|
||||
|
||||
include::discovery-kubernetes-native.adoc[]
|
||||
|
||||
include::property-source-config.adoc[]
|
||||
|
||||
include::kubernetes-awareness.adoc[]
|
||||
|
||||
include::pod-health-indicator.adoc[]
|
||||
|
||||
include::info-contributor.adoc[]
|
||||
|
||||
include::leader-election.adoc[]
|
||||
|
||||
include::load-balancer.adoc[]
|
||||
|
||||
include::security-service-accounts.adoc[]
|
||||
|
||||
include::service-registry.adoc[]
|
||||
|
||||
include::spring-cloud-kubernetes-configuration-watcher.adoc[]
|
||||
|
||||
include::spring-cloud-kubernetes-configserver.adoc[]
|
||||
|
||||
include::spring-cloud-kubernetes-discoveryserver.adoc[]
|
||||
|
||||
include::examples.adoc[]
|
||||
|
||||
include::other-resources.adoc[]
|
||||
|
||||
== Configuration properties
|
||||
|
||||
To see the list of all Kubernetes related configuration properties please check link:appendix.html[the Appendix page].
|
||||
|
||||
== Building
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/modules/ROOT/partials/building.adoc[]
|
||||
|
||||
=== Building Docker Images On ARM64
|
||||
|
||||
If you run the Spring Cloud Kuberentes build on an ARM64 machine the docker images
|
||||
used for the integration tests will fail to run due to using the wrong architecture.
|
||||
This is because the Paketo build pack does not yet support ARM64. To work around this you
|
||||
can run the build by passing `-Dspring-boot.build-image.builder=dashaun/builder:tiny` to Maven.
|
||||
|
||||
For example:
|
||||
```
|
||||
./mvnw clean install -Dspring-boot.build-image.builder=dashaun/builder:tiny
|
||||
```
|
||||
|
||||
|
||||
== Contributing
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/modules/ROOT/partials/contributing.adoc[]
|
||||
|
||||
== AOT and native image support
|
||||
|
||||
At this point, Spring Cloud Kubernetes does not support Spring Boot AOT transformations or native images. Partial support might be added in future releases.
|
||||
Reference in New Issue
Block a user