Generate config props for docs. Fixes #463

2019-09-10 11:26:26 -04:00
parent e9776cdeba
commit e3cda1c678
6 changed files with 161 additions and 3 deletions
--- 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
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -17,7 +17,26 @@
 		<docs.main>spring-cloud-kubernetes</docs.main>
 		<main.basedir>${basedir}/..</main.basedir>
 		<docs.whitelisted.branches>1.2.x,1.3.x,2.0.x</docs.whitelisted.branches>
+		<configprops.inclusionPattern>spring.cloud.kubernetes.*</configprops.inclusionPattern>
 	</properties>
+	<dependencies>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-cloud-starter-kubernetes</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-cloud-starter-kubernetes-all</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-cloud-starter-kubernetes-config</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
+		</dependency>
+	</dependencies>
 	<build>
 		<plugins>
 			<plugin>
@@ -34,6 +53,14 @@
 			<id>docs</id>
 			<build>
 				<plugins>
+					<plugin>
+						<groupId>pl.project13.maven</groupId>
+						<artifactId>git-commit-id-plugin</artifactId>
+					</plugin>
+					<plugin>
+						<groupId>org.codehaus.mojo</groupId>
+						<artifactId>exec-maven-plugin</artifactId>
+					</plugin>
 					<plugin>
 						<groupId>org.apache.maven.plugins</groupId>
 						<artifactId>maven-dependency-plugin</artifactId>
--- a/docs/src/main/asciidoc/_attributes.adoc
+++ 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}
--- a/docs/src/main/asciidoc/_configprops.adoc
+++ 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 |  | 
+
+|===
--- a/docs/src/main/asciidoc/appendix.adoc
+++ 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[]
--- 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[]