diff --git a/README.adoc b/README.adoc index 6a33b61b..60120e74 100644 --- a/README.adoc +++ b/README.adoc @@ -5,6 +5,22 @@ Edit the files in the src/main/asciidoc/ directory instead. //// = Spring Cloud Kubernetes +: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} This reference guide covers how to use Spring Cloud Kubernetes. @@ -133,6 +149,8 @@ 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. In order to enable this functionality you need to add `@EnableScheduling` on a configuration class in your application. @@ -453,10 +471,13 @@ When enabled, the `SecretsPropertySource` looks up Kubernetes for `Secrets` from . Named after the application (as defined by `spring.application.name`) . Matching some labels -Note that, by default, consuming Secrets through the API (points 2 and 3 above) *is not enabled* for security reasons. +*Note:* + +By default, consuming Secrets through the API (points 2 and 3 above) *is not enabled* for security reasons. The permission 'list' on secrets allows clients to inspect secrets values in the specified namespace. Further, we recommend that containers share secrets through mounted volumes. -If you enable consuming Secrets through the API, we recommend that you limit access to Secrets by using an -[authorization policy, such as RBAC](https://kubernetes.io/docs/concepts/configuration/secret/#best-practices). + +If you enable consuming Secrets through the API, we recommend that you limit access to Secrets by using an authorization policy, such as RBAC. +For more information about risks and best practices when consuming Secrets through the API refer to https://kubernetes.io/docs/concepts/configuration/secret/#best-practices[this doc]. If the secrets are found, their data is made available to the application. @@ -602,6 +623,7 @@ the `Secret` named `s1` would be looked up in the namespace that the application |=== Notes: + * The `spring.cloud.kubernetes.secrets.labels` property behaves as defined by https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-Configuration-Binding#map-based-binding[Map-based binding]. * The `spring.cloud.kubernetes.secrets.paths` property behaves as defined by @@ -941,6 +963,10 @@ This section lists other resources, such as presentations (slides) and videos ab Please feel free to submit other resources through pull requests to https://github.com/spring-cloud/spring-cloud-kubernetes[this repository]. +== Configuration properties + +To see the list of all Sleuth related configuration properties please check link:appendix.html[the Appendix page]. + == Building :jdkversion: 1.7 diff --git a/docs/pom.xml b/docs/pom.xml index eded83fe..fd766684 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -17,7 +17,26 @@ spring-cloud-kubernetes ${basedir}/.. 1.2.x,1.3.x,2.0.x + spring.cloud.kubernetes.* + + + ${project.groupId} + spring-cloud-starter-kubernetes + + + ${project.groupId} + spring-cloud-starter-kubernetes-all + + + ${project.groupId} + spring-cloud-starter-kubernetes-config + + + ${project.groupId} + spring-cloud-starter-kubernetes-ribbon + + @@ -34,6 +53,14 @@ docs + + pl.project13.maven + git-commit-id-plugin + + + org.codehaus.mojo + exec-maven-plugin + org.apache.maven.plugins maven-dependency-plugin diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/src/main/asciidoc/_attributes.adoc new file mode 100644 index 00000000..31424366 --- /dev/null +++ b/docs/src/main/asciidoc/_attributes.adoc @@ -0,0 +1,16 @@ +: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} diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/src/main/asciidoc/_configprops.adoc new file mode 100644 index 00000000..a574ef12 --- /dev/null +++ b/docs/src/main/asciidoc/_configprops.adoc @@ -0,0 +1,70 @@ +|=== +|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.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.trust-certs | | +|spring.cloud.kubernetes.client.trustCerts | false | Kubernetes API Trust Certificates +|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.name | | +|spring.cloud.kubernetes.config.namespace | | +|spring.cloud.kubernetes.config.paths | | +|spring.cloud.kubernetes.config.sources | | +|spring.cloud.kubernetes.reload.enabled | false | Enables the Kubernetes configuration reload on change. +|spring.cloud.kubernetes.reload.max-wait-for-restart | 2s | If Restart or Shutdown strategies are used, Spring Cloud Kubernetes waits a random amount of time before restarting. This is done in order to avoid having all instances of the same application restart at the same time. This property configures the maximum of amount of wait time from the moment the signal is received that a restart is needed until the moment the restart is actually triggered +|spring.cloud.kubernetes.reload.mode | | Sets the detection mode for Kubernetes configuration reload. +|spring.cloud.kubernetes.reload.monitoring-config-maps | true | Enables monitoring on config maps to detect changes. +|spring.cloud.kubernetes.reload.monitoring-secrets | false | Enables monitoring on secrets to detect changes. +|spring.cloud.kubernetes.reload.period | 15000ms | Sets the polling period to use when the detection mode is POLLING. +|spring.cloud.kubernetes.reload.strategy | | Sets the reload strategy for Kubernetes configuration reload on change. +|spring.cloud.kubernetes.ribbon.cluster-domain | cluster.local | cluster domain. +|spring.cloud.kubernetes.ribbon.enabled | true | Ribbon enabled,default true. +|spring.cloud.kubernetes.ribbon.mode | | {@link KubernetesRibbonMode} setting ribbon server list with ip of pod or service name. default value is POD. +|spring.cloud.kubernetes.secrets.enable-api | false | +|spring.cloud.kubernetes.secrets.enabled | true | Enable the Secrets property source locator. +|spring.cloud.kubernetes.secrets.labels | | +|spring.cloud.kubernetes.secrets.name | | +|spring.cloud.kubernetes.secrets.namespace | | +|spring.cloud.kubernetes.secrets.paths | | +|spring.cloud.kubernetes.secrets.sources | | + +|=== diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/src/main/asciidoc/appendix.adoc new file mode 100644 index 00000000..39eb1593 --- /dev/null +++ b/docs/src/main/asciidoc/appendix.adoc @@ -0,0 +1,14 @@ +: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[] diff --git a/docs/src/main/asciidoc/spring-cloud-kubernetes.adoc b/docs/src/main/asciidoc/spring-cloud-kubernetes.adoc index 283aed78..3ad907fa 100644 --- a/docs/src/main/asciidoc/spring-cloud-kubernetes.adoc +++ b/docs/src/main/asciidoc/spring-cloud-kubernetes.adoc @@ -1,4 +1,5 @@ = Spring Cloud Kubernetes +include::_attributes.adoc[] This reference guide covers how to use Spring Cloud Kubernetes. @@ -31,6 +32,10 @@ include::examples.adoc[] include::other-resources.adoc[] +== Configuration properties + +To see the list of all Sleuth related configuration properties please check link:appendix.html[the Appendix page]. + == Building include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building.adoc[]