diff --git a/docs/src/main/asciidoc/discovery-client.adoc b/docs/src/main/asciidoc/discovery-client.adoc index 3b75c27b..fc214f91 100644 --- a/docs/src/main/asciidoc/discovery-client.adoc +++ b/docs/src/main/asciidoc/discovery-client.adoc @@ -1,4 +1,4 @@ -= DiscoveryClient for Kubernetes +== 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 http://kubernetes.io[Kubernetes]. diff --git a/docs/src/main/asciidoc/examples.adoc b/docs/src/main/asciidoc/examples.adoc index ead86361..a33fbf9c 100644 --- a/docs/src/main/asciidoc/examples.adoc +++ b/docs/src/main/asciidoc/examples.adoc @@ -1,5 +1,24 @@ -= Examples +== Examples + +Spring Cloud Kubernetes tries to make it transparent for your applications to consume Kubernetes Native Services +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 (ie. 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 (ie. Config Server Client). + +The following projects highlight the usage of these dependencies and demonstrate how these libraries can be used from any Spring Boot application. List of examples using these projects: - +- 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] + + + + + diff --git a/docs/src/main/asciidoc/kubernetes-awareness.adoc b/docs/src/main/asciidoc/kubernetes-awareness.adoc index 2f3bbfd0..27c3a075 100644 --- a/docs/src/main/asciidoc/kubernetes-awareness.adoc +++ b/docs/src/main/asciidoc/kubernetes-awareness.adoc @@ -1,4 +1,4 @@ -= Kubernetes Awareness +== Kubernetes Awareness All of the features described above will work equally well regardless of whether your application is running inside Kubernetes or not. This is really helpful for development and troubleshooting. @@ -8,7 +8,7 @@ as the code of the project relies on the [Fabric8 Kubernetes Java client](https://github.com/fabric8io/kubernetes-client) which is a fluent DSL able to communicate using `http` protocol to the REST API of Kubernetes Server. -== Kubernetes Profile Autoconfiguration +=== Kubernetes Profile Autoconfiguration When the application runs as a pod inside Kubernetes a Spring profile named `kubernetes` will automatically get activated. This allows the developer to customize the configuration, to define beans that will be applied when the Spring Boot application is deployed diff --git a/docs/src/main/asciidoc/leader-election.adoc b/docs/src/main/asciidoc/leader-election.adoc index 394b18be..aee32932 100644 --- a/docs/src/main/asciidoc/leader-election.adoc +++ b/docs/src/main/asciidoc/leader-election.adoc @@ -1,3 +1,3 @@ -= Leader Election +== Leader Election diff --git a/docs/src/main/asciidoc/other-resources.adoc b/docs/src/main/asciidoc/other-resources.adoc index 9782ea96..49afe06a 100644 --- a/docs/src/main/asciidoc/other-resources.adoc +++ b/docs/src/main/asciidoc/other-resources.adoc @@ -1 +1,11 @@ -= Other Resources +== Other Resources + +Here you can find 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 via PR to http://github.com/spring-cloud/spring-cloud-kubernetes[this repository]. + + diff --git a/docs/src/main/asciidoc/pod-health-indicator.adoc b/docs/src/main/asciidoc/pod-health-indicator.adoc index 21ee8159..b2f21cbd 100644 --- a/docs/src/main/asciidoc/pod-health-indicator.adoc +++ b/docs/src/main/asciidoc/pod-health-indicator.adoc @@ -1,4 +1,4 @@ -= Pod Health Indicator +== 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 are also a good fit for use as https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/[readiness probes]. diff --git a/docs/src/main/asciidoc/property-source-config.adoc b/docs/src/main/asciidoc/property-source-config.adoc index ef51291e..0e8b3ad3 100644 --- a/docs/src/main/asciidoc/property-source-config.adoc +++ b/docs/src/main/asciidoc/property-source-config.adoc @@ -1,11 +1,11 @@ -= Kubernetes PropertySource implementations +== Kubernetes PropertySource implementations The most common approach to configure your Spring Boot application is to create an `application.properties|yaml` or an `application-profile.properties|yaml` file containing key-value pairs providing customization values to your application or Spring Boot starters. Users may override these properties by specifying system properties or environment variables. -== ConfigMap PropertySource +=== ConfigMap PropertySource Kubernetes provides a resource named http://kubernetes.io/docs/user-guide/configmap/[ConfigMap] to externalize the parameters to pass to your application in the form of key-value pairs or embedded `application.properties|yaml` files. @@ -189,7 +189,7 @@ Kubernetes service accounts, roles and role bindings. | spring.cloud.kubernetes.config.enableApi | Boolean | true | Enable/Disable consuming ConfigMaps via APIs |=== -== Secrets PropertySource +=== Secrets PropertySource Kubernetes has the notion of [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) for storing sensitive data such as password, OAuth tokens, etc. This project provides integration with `Secrets` to make secrets @@ -201,7 +201,8 @@ The `SecretsPropertySource` when enabled will lookup Kubernetes for `Secrets` fr 3. matching some labels Please note that by default, consuming Secrets via API (points 2 and 3 above) **is not enabled** for security reasons - and it is recommend that containers share secrets via mounted volumes. + and it is recommend that containers share secrets via mounted volumes. Otherwise proper RBAC security configurations must be provided + to make sure that unauthorized access to Secrets occurs. If the secrets are found their data is made available to the application. @@ -304,7 +305,7 @@ https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-Configuration-Bi Example of application using secrets (though it hasn't been updated to use the new `spring-cloud-kubernetes` project): https://github.com/fabric8-quickstarts/spring-boot-camel-config[spring-boot-camel-config] -== PropertySource Reload +=== PropertySource Reload Some applications may need to detect changes on external property sources and update their internal status to reflect the new configuration. The reload feature of Spring Cloud Kubernetes is able to trigger an application reload when a related `ConfigMap` or diff --git a/docs/src/main/asciidoc/ribbon-integration.adoc b/docs/src/main/asciidoc/ribbon-integration.adoc index 031f4358..0df2d732 100644 --- a/docs/src/main/asciidoc/ribbon-integration.adoc +++ b/docs/src/main/asciidoc/ribbon-integration.adoc @@ -1,4 +1,4 @@ -# Ribbon discovery in Kubernetes +== Ribbon discovery in Kubernetes Spring Cloud client applications calling a microservice should be interested on relying on a client load-balancing @@ -12,7 +12,7 @@ The implementation is part of the following starter that you can use by adding i ```xml org.springframework.cloud - spring-cloud-starter-kubernetes-netflix + spring-cloud-starter-kubernetes-ribbon ${latest.version} ``` diff --git a/docs/src/main/asciidoc/security-service-accounts.adoc b/docs/src/main/asciidoc/security-service-accounts.adoc index ab80a7e8..87056aa7 100644 --- a/docs/src/main/asciidoc/security-service-accounts.adoc +++ b/docs/src/main/asciidoc/security-service-accounts.adoc @@ -1,7 +1,7 @@ -# Security Configurations inside Kubernetes +== Security Configurations inside Kubernetes -## Namespace +=== 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: @@ -12,6 +12,6 @@ For earlier version it needs to be specified as an env var to the pod. A quick w fieldPath: "metadata.namespace" -## Service Account +=== Service Account For distros 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/pod, you need to make sure it has the correct roles. For example, you can add `cluster-reader` permissions to your `default` service account depending on the project you're in: