Doc improvements

* initial fixes, links missing

* adding links and resources

* updating headers size and example section

fixes gh-268

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].

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:
 
-<TBD>
+- 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]
+
+
+
+
+

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

docs/src/main/asciidoc/leader-election.adoc

@@ -1,3 +1,3 @@
-= Leader Election
+== Leader Election
 
 <TBD>

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].
+
+

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].

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

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
 <dependency>
     <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-netflix</artifactId>
+    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
     <version>${latest.version}</version>
 </dependency>
 ```

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: