From 076281794b2da3c0c3c05b6614e72de39d2c1c29 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Wed, 20 May 2020 16:41:17 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- reference/html/README.html | 276 ++++-------------- reference/html/discovery-client.html | 3 +- .../html/discovery-kubernetes-native.html | 2 +- reference/html/getting-started.html | 12 - reference/html/index.html | 276 ++++-------------- reference/html/sagan-index.html | 3 - reference/html/security-service-accounts.html | 4 - reference/html/spring-cloud-kubernetes.html | 276 ++++-------------- 8 files changed, 167 insertions(+), 685 deletions(-) diff --git a/reference/html/README.html b/reference/html/README.html index 72c25e88..5074a785 100644 --- a/reference/html/README.html +++ b/reference/html/README.html @@ -126,50 +126,49 @@ $(globalSwitch);
  • 5.3. PropertySource Reload
    • -
  • 6. Ribbon Discovery in Kubernetes
    • -
  • 7. Kubernetes Ecosystem Awareness +
  • 6. Kubernetes Ecosystem Awareness
    • -
  • 8. Pod Health Indicator
    • -
  • 9. Leader Election
    • -
  • 10. Security Configurations Inside Kubernetes +
  • 7. Pod Health Indicator
    • +
  • 8. Leader Election
    • +
  • 9. Security Configurations Inside Kubernetes
    • -
  • 11. Service Registry Implementation
    • -
  • 12. Examples
    • -
  • 13. Other Resources
    • -
  • 14. Configuration properties
    • -
  • 15. Building +
  • 10. Service Registry Implementation
    • +
  • 11. Examples
    • +
  • 12. Other Resources
    • +
  • 13. Configuration properties
    • +
  • 14. Building
    • -
  • 16. Contributing +
  • 15. Contributing @@ -243,18 +242,6 @@ Secret changes.

    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-</dependency>
    -
    -
    -

    Ribbon client-side load balancer with -server list obtained from Kubernetes Endpoints.

    - - -
    -
    <dependency>
     <groupId>org.springframework.cloud</groupId>
     <artifactId>spring-cloud-starter-kubernetes-all</artifactId>
@@ -275,8 +262,7 @@ server list obtained from Kubernetes Endpoints.
    
 for Kubernetes.
 This client lets you query Kubernetes endpoints (see 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. This discovery feature is also used by the Spring Cloud Kubernetes Ribbon project
-to fetch the list of the endpoints defined for an application to be load balanced.
    
+access from a Spring Boot application running as a pod.

    This is something that you get for free by adding the following dependency inside your project:

    @@ -376,7 +362,7 @@ this to work, you need to align the Kubernetes service name with the sprin

    Kubernetes itself is capable of (server side) service discovery (see: kubernetes.io/docs/concepts/services-networking/service/#discovering-services). -Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (istio.io), a service mesh that is capable of load balancing, ribbon, circuit breaker, failover, and much more.

    +Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (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 {service-name}.{namespace}.svc.{cluster}.local:{service-port}.

    @@ -1249,155 +1235,7 @@ This means, for example, that using polling on file-mounted secret sources does
    -

    6. Ribbon Discovery in Kubernetes

    -
    -
    -

    Spring Cloud client applications that call a microservice should be interested on relying on a client load-balancing -feature in order to automatically discover at which endpoint(s) it can reach a given service. This mechanism has been -implemented within the spring-cloud-kubernetes-ribbon project, where a -Kubernetes client populates a Ribbon ServerList that contains information -about such endpoints.

    -
    -
    -

    The implementation is part of the following starter that you can use by adding its dependency to your pom file:

    -
    -
    -
    -
    -
    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-    <version>${latest.version}</version>
-</dependency>
    -
    -
    -
    -
    -
    -

    When the list of the endpoints is populated, the Kubernetes client searches the registered endpoints that live in -the current namespace or project by matching the service name defined in the Ribbon Client annotation, as follows:

    -
    -
    -
    -
    -
    -
    @RibbonClient(name = "name-service")
    -
    -
    -
    -
    -
    -

    You can configure Ribbon’s behavior by providing properties in your application.properties (through your application’s -dedicated ConfigMap) by using the following format: <name of your service>.ribbon.<Ribbon configuration key>, where:

    -
    -
    -
      -
    • -

      <name of your service> corresponds to the service name you access over Ribbon, as configured by using the -@RibbonClient annotation (such as name-service in the preceding example).

      -
      • -
    • -

      <Ribbon configuration key> is one of the Ribbon configuration keys defined by -Ribbon’s CommonClientConfigKey class.

      -
      • -
    -
    -
    -

    Additionally, the spring-cloud-kubernetes-ribbon project defines two additional configuration keys to further -control how Ribbon interacts with Kubernetes. In particular, if an endpoint defines multiple ports, the default -behavior is to use the first one found. To select more specifically which port to use in a multi-port service, you can use -the PortName key. If you want to specify in which Kubernetes namespace the target service should be looked up, you can use -the KubernetesNamespace key, remembering in both instances to prefix these keys with your service name and -ribbon prefix, as specified earlier.

    -
    - - ----- - - - - - - - - - - - - - - - - - - - - - - - - -
    Table 4. Spring Cloud Kubernetes Ribbon Configuration
    Property KeyTypeDefault Value

    spring.cloud.kubernetes.ribbon.enabled

    boolean

    true

    spring.cloud.kubernetes.ribbon.mode

    KubernetesRibbonMode

    POD

    spring.cloud.kubernetes.ribbon.cluster-domain

    string

    cluster.local

    -
    -
      -
    • -

      spring.cloud.kubernetes.ribbon.mode supports POD and SERVICE modes.

      -
      -
        -
      • -

        The POD mode is to achieve load balancing by obtaining the Pod IP address of Kubernetes and using Ribbon. -POD mode uses the load balancing of the Ribbon Does not support Kubernetes load balancing, The traffic policy of Istio is not supported.

        -
        • -
      • -

        the SERVICE mode is directly based on the service name of the Ribbon. Get -The Kubernetes service is concatenated into service-name.{namespace}.svc.{cluster.domain}:{port} such as: demo1.default.svc.cluster.local:8080. -the SERVICE mode uses load balancing of the Kubernetes service to support Istio’s traffic policy.

        -
        • -
      -
      -
      • -
    • -

      spring.cloud.kubernetes.ribbon.cluster-domain Set the custom Kubernetes cluster domain suffix. The default value is: 'cluster.local'

      -
      • -
    -
    -
    -

    The following examples use this module for ribbon discovery:

    -
    -
    - -
    -
    - - - - - -
    - - -You can disable the Ribbon discovery client by setting the spring.cloud.kubernetes.ribbon.enabled=false key within the application properties file. -
    -
    -
    -
    -
    -

    7. Kubernetes Ecosystem Awareness

    +

    6. Kubernetes Ecosystem Awareness

    All of the features described earlier in this guide work equally well, regardless of whether your application is running inside @@ -1414,7 +1252,7 @@ communicate by using http protocol to the REST API of the Kubernete Also note that these properties: spring.cloud.kubernetes.config.enabled and spring.cloud.kubernetes.secrets.enabled only take effect when set in bootstrap.{properties|yml}

    -

    7.1. Kubernetes Profile Autoconfiguration

    +

    6.1. 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 @@ -1422,7 +1260,7 @@ within the Kubernetes platform (for example, different development and productio

    -

    7.2. Istio Awareness

    +

    6.2. Istio Awareness

    When you include the spring-cloud-kubernetes-istio module in the application classpath, a new profile is added to the application, provided the application is running inside a Kubernetes Cluster with Istio installed. You can then use @@ -1436,7 +1274,7 @@ making it easy for our Spring Boot applications to consume this data to dynamica

    -

    8. Pod Health Indicator

    +

    7. Pod Health Indicator

    Spring Boot uses HealthIndicator to expose info about the health of an application. @@ -1458,7 +1296,7 @@ That makes it really useful for exposing health-related information to the user

    -

    9. Leader Election

    +

    8. Leader Election

    <TBD>

    @@ -1466,10 +1304,10 @@ That makes it really useful for exposing health-related information to the user
    -

    10. Security Configurations Inside Kubernetes

    +

    9. Security Configurations Inside Kubernetes

    -

    10.1. Namespace

    +

    9.1. 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:

    @@ -1489,7 +1327,7 @@ For earlier versions, it needs to be specified as an environment variable to the
    -

    10.2. Service Account

    +

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

    @@ -1498,7 +1336,7 @@ For any service accounts you assign to a deployment or pod, you need to make sur

    Depending on the requirements, you’ll need get, list and watch permission on the following resources:

    - +@@ -1518,10 +1356,6 @@ For any service accounts you assign to a deployment or pod, you need to make sur - - - -
    Table 5. Kubernetes Resource PermissionsTable 4. Kubernetes Resource Permissions

    spring-cloud-starter-kubernetes-config

    configmaps, secrets

    spring-cloud-starter-kubernetes-ribbon

    pods, services, endpoints
    @@ -1567,7 +1401,7 @@ roleRef:
    -

    11. Service Registry Implementation

    +

    10. Service Registry Implementation

    In Kubernetes service registration is controlled by the platform, the application itself does not control @@ -1577,7 +1411,7 @@ or setting @EnableDiscoveryClient(autoRegister=false) will have no

    -

    12. Examples

    +

    11. Examples

    Spring Cloud Kubernetes tries to make it transparent for your applications to consume Kubernetes Native Services by @@ -1622,7 +1456,7 @@ The same applies for PropertySourceLocator, where you need to add t

    -

    13. Other Resources

    +

    12. Other Resources

    This section lists other resources, such as presentations (slides) and videos about Spring Cloud Kubernetes.

    @@ -1643,7 +1477,7 @@ The same applies for PropertySourceLocator, where you need to add t
    -

    14. Configuration properties

    +

    13. Configuration properties

    To see the list of all Sleuth related configuration properties please check the Appendix page.

    @@ -1651,10 +1485,10 @@ The same applies for PropertySourceLocator, where you need to add t
    -

    15. Building

    +

    14. Building

    -

    15.1. Basic Compile and Test

    +

    14.1. Basic Compile and Test

    To build the source you will need to install JDK 1.7.

    @@ -1732,7 +1566,7 @@ If all else fails, build with the command from .travis.yml (usually
    -

    15.2. Documentation

    +

    14.2. Documentation

    The spring-cloud-build module has a "docs" profile, and if you switch that on it will try to build asciidoc sources from @@ -1745,7 +1579,7 @@ a modified file in the correct place. Just commit it and push the change.

    -

    15.3. Working with the code

    +

    14.3. Working with the code

    If you don’t have an IDE preference we would recommend that you use Spring Tools Suite or @@ -1754,7 +1588,7 @@ a modified file in the correct place. Just commit it and push the change.

    should also work without issue as long as they use Maven 3.3.3 or better.

    -

    15.3.1. Importing into eclipse with m2eclipse

    +

    14.3.1. Importing into eclipse with m2eclipse

    We recommend the m2eclipse eclipse plugin when working with eclipse. If you don’t already have m2eclipse installed it is available from the "eclipse @@ -1781,7 +1615,7 @@ pom into your settings.xml.

    -

    15.3.2. Importing into eclipse without m2eclipse

    +

    14.3.2. Importing into eclipse without m2eclipse

    If you prefer not to use m2eclipse you can generate eclipse project metadata using the following command:

    @@ -1800,7 +1634,7 @@ from the file menu.

    -

    16. Contributing

    +

    15. Contributing

    Spring Cloud is released under the non-restrictive Apache 2.0 license, @@ -1810,7 +1644,7 @@ to contribute even something trivial please do not hesitate, but follow the guidelines below.

    -

    16.1. Sign the Contributor License Agreement

    +

    15.1. Sign the Contributor License Agreement

    Before we accept a non-trivial patch or pull request we will need you to sign the Contributor License Agreement. @@ -1821,7 +1655,7 @@ given the ability to merge pull requests.

    -

    16.2. Code of Conduct

    +

    15.2. Code of Conduct

    This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report @@ -1829,7 +1663,7 @@ unacceptable behavior to spri

    -

    16.3. Code Conventions and Housekeeping

    +

    15.3. Code Conventions and Housekeeping

    None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.

    @@ -1877,7 +1711,7 @@ message (where XXXX is the issue number).

    -

    16.4. Checkstyle

    +

    15.4. Checkstyle

    Spring Cloud Build comes with a set of checkstyle rules. You can find them in the spring-cloud-build-tools module. The most notable files under the module are:

    @@ -1910,7 +1744,7 @@ message (where XXXX is the issue number).

    -

    16.4.1. Checkstyle configuration

    +

    15.4.1. Checkstyle configuration

    Checkstyle rules are disabled by default. To add checkstyle to your project just define the following properties and plugins.

    @@ -2000,9 +1834,9 @@ $ touch .springformat
    -

    16.5. IDE setup

    +

    15.5. IDE setup

    -

    16.5.1. Intellij IDEA

    +

    15.5.1. Intellij IDEA

    In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. The following files can be found in the Spring Cloud Build project.

    diff --git a/reference/html/discovery-client.html b/reference/html/discovery-client.html index 2056fa41..f466e87e 100644 --- a/reference/html/discovery-client.html +++ b/reference/html/discovery-client.html @@ -127,8 +127,7 @@ $(globalSwitch); for Kubernetes. This client lets you query Kubernetes endpoints (see 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. This discovery feature is also used by the Spring Cloud Kubernetes Ribbon project -to fetch the list of the endpoints defined for an application to be load balanced.

    +access from a Spring Boot application running as a pod.

    This is something that you get for free by adding the following dependency inside your project:

    diff --git a/reference/html/discovery-kubernetes-native.html b/reference/html/discovery-kubernetes-native.html index a41f29d0..72f8ec3d 100644 --- a/reference/html/discovery-kubernetes-native.html +++ b/reference/html/discovery-kubernetes-native.html @@ -124,7 +124,7 @@ $(globalSwitch);

    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, ribbon, circuit breaker, failover, and much more.

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

    diff --git a/reference/html/getting-started.html b/reference/html/getting-started.html index 0beb8e6c..c83e0f01 100644 --- a/reference/html/getting-started.html +++ b/reference/html/getting-started.html @@ -168,18 +168,6 @@ Secret changes.

    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-</dependency>
    -
    -
    -

    Ribbon client-side load balancer with -server list obtained from Kubernetes Endpoints.

    - - -
    -
    <dependency>
     <groupId>org.springframework.cloud</groupId>
     <artifactId>spring-cloud-starter-kubernetes-all</artifactId>
diff --git a/reference/html/index.html b/reference/html/index.html
index 72c25e88..5074a785 100644
--- a/reference/html/index.html
+++ b/reference/html/index.html
@@ -126,50 +126,49 @@ $(globalSwitch);
 
  • 5.3. PropertySource Reload
    •
    • -
  • 6. Ribbon Discovery in Kubernetes
    • -
  • 7. Kubernetes Ecosystem Awareness +
  • 6. Kubernetes Ecosystem Awareness
    • -
  • 8. Pod Health Indicator
    • -
  • 9. Leader Election
    • -
  • 10. Security Configurations Inside Kubernetes +
  • 7. Pod Health Indicator
    • +
  • 8. Leader Election
    • +
  • 9. Security Configurations Inside Kubernetes
    • -
  • 11. Service Registry Implementation
    • -
  • 12. Examples
    • -
  • 13. Other Resources
    • -
  • 14. Configuration properties
    • -
  • 15. Building +
  • 10. Service Registry Implementation
    • +
  • 11. Examples
    • +
  • 12. Other Resources
    • +
  • 13. Configuration properties
    • +
  • 14. Building
    • -
  • 16. Contributing +
  • 15. Contributing @@ -243,18 +242,6 @@ Secret changes.

    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-</dependency>
    -
    -
    -

    Ribbon client-side load balancer with -server list obtained from Kubernetes Endpoints.

    - - -
    -
    <dependency>
     <groupId>org.springframework.cloud</groupId>
     <artifactId>spring-cloud-starter-kubernetes-all</artifactId>
@@ -275,8 +262,7 @@ server list obtained from Kubernetes Endpoints.
    
 for Kubernetes.
 This client lets you query Kubernetes endpoints (see 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. This discovery feature is also used by the Spring Cloud Kubernetes Ribbon project
-to fetch the list of the endpoints defined for an application to be load balanced.
    
+access from a Spring Boot application running as a pod.

    This is something that you get for free by adding the following dependency inside your project:

    @@ -376,7 +362,7 @@ this to work, you need to align the Kubernetes service name with the sprin

    Kubernetes itself is capable of (server side) service discovery (see: kubernetes.io/docs/concepts/services-networking/service/#discovering-services). -Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (istio.io), a service mesh that is capable of load balancing, ribbon, circuit breaker, failover, and much more.

    +Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (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 {service-name}.{namespace}.svc.{cluster}.local:{service-port}.

    @@ -1249,155 +1235,7 @@ This means, for example, that using polling on file-mounted secret sources does
    -

    6. Ribbon Discovery in Kubernetes

    -
    -
    -

    Spring Cloud client applications that call a microservice should be interested on relying on a client load-balancing -feature in order to automatically discover at which endpoint(s) it can reach a given service. This mechanism has been -implemented within the spring-cloud-kubernetes-ribbon project, where a -Kubernetes client populates a Ribbon ServerList that contains information -about such endpoints.

    -
    -
    -

    The implementation is part of the following starter that you can use by adding its dependency to your pom file:

    -
    -
    -
    -
    -
    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-    <version>${latest.version}</version>
-</dependency>
    -
    -
    -
    -
    -
    -

    When the list of the endpoints is populated, the Kubernetes client searches the registered endpoints that live in -the current namespace or project by matching the service name defined in the Ribbon Client annotation, as follows:

    -
    -
    -
    -
    -
    -
    @RibbonClient(name = "name-service")
    -
    -
    -
    -
    -
    -

    You can configure Ribbon’s behavior by providing properties in your application.properties (through your application’s -dedicated ConfigMap) by using the following format: <name of your service>.ribbon.<Ribbon configuration key>, where:

    -
    -
    -
      -
    • -

      <name of your service> corresponds to the service name you access over Ribbon, as configured by using the -@RibbonClient annotation (such as name-service in the preceding example).

      -
      • -
    • -

      <Ribbon configuration key> is one of the Ribbon configuration keys defined by -Ribbon’s CommonClientConfigKey class.

      -
      • -
    -
    -
    -

    Additionally, the spring-cloud-kubernetes-ribbon project defines two additional configuration keys to further -control how Ribbon interacts with Kubernetes. In particular, if an endpoint defines multiple ports, the default -behavior is to use the first one found. To select more specifically which port to use in a multi-port service, you can use -the PortName key. If you want to specify in which Kubernetes namespace the target service should be looked up, you can use -the KubernetesNamespace key, remembering in both instances to prefix these keys with your service name and -ribbon prefix, as specified earlier.

    -
    - - ----- - - - - - - - - - - - - - - - - - - - - - - - - -
    Table 4. Spring Cloud Kubernetes Ribbon Configuration
    Property KeyTypeDefault Value

    spring.cloud.kubernetes.ribbon.enabled

    boolean

    true

    spring.cloud.kubernetes.ribbon.mode

    KubernetesRibbonMode

    POD

    spring.cloud.kubernetes.ribbon.cluster-domain

    string

    cluster.local

    -
    -
      -
    • -

      spring.cloud.kubernetes.ribbon.mode supports POD and SERVICE modes.

      -
      -
        -
      • -

        The POD mode is to achieve load balancing by obtaining the Pod IP address of Kubernetes and using Ribbon. -POD mode uses the load balancing of the Ribbon Does not support Kubernetes load balancing, The traffic policy of Istio is not supported.

        -
        • -
      • -

        the SERVICE mode is directly based on the service name of the Ribbon. Get -The Kubernetes service is concatenated into service-name.{namespace}.svc.{cluster.domain}:{port} such as: demo1.default.svc.cluster.local:8080. -the SERVICE mode uses load balancing of the Kubernetes service to support Istio’s traffic policy.

        -
        • -
      -
      -
      • -
    • -

      spring.cloud.kubernetes.ribbon.cluster-domain Set the custom Kubernetes cluster domain suffix. The default value is: 'cluster.local'

      -
      • -
    -
    -
    -

    The following examples use this module for ribbon discovery:

    -
    -
    - -
    -
    - - - - - -
    - - -You can disable the Ribbon discovery client by setting the spring.cloud.kubernetes.ribbon.enabled=false key within the application properties file. -
    -
    -
    -
    -
    -

    7. Kubernetes Ecosystem Awareness

    +

    6. Kubernetes Ecosystem Awareness

    All of the features described earlier in this guide work equally well, regardless of whether your application is running inside @@ -1414,7 +1252,7 @@ communicate by using http protocol to the REST API of the Kubernete Also note that these properties: spring.cloud.kubernetes.config.enabled and spring.cloud.kubernetes.secrets.enabled only take effect when set in bootstrap.{properties|yml}

    -

    7.1. Kubernetes Profile Autoconfiguration

    +

    6.1. 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 @@ -1422,7 +1260,7 @@ within the Kubernetes platform (for example, different development and productio

    -

    7.2. Istio Awareness

    +

    6.2. Istio Awareness

    When you include the spring-cloud-kubernetes-istio module in the application classpath, a new profile is added to the application, provided the application is running inside a Kubernetes Cluster with Istio installed. You can then use @@ -1436,7 +1274,7 @@ making it easy for our Spring Boot applications to consume this data to dynamica

    -

    8. Pod Health Indicator

    +

    7. Pod Health Indicator

    Spring Boot uses HealthIndicator to expose info about the health of an application. @@ -1458,7 +1296,7 @@ That makes it really useful for exposing health-related information to the user

    -

    9. Leader Election

    +

    8. Leader Election

    <TBD>

    @@ -1466,10 +1304,10 @@ That makes it really useful for exposing health-related information to the user
    -

    10. Security Configurations Inside Kubernetes

    +

    9. Security Configurations Inside Kubernetes

    -

    10.1. Namespace

    +

    9.1. 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:

    @@ -1489,7 +1327,7 @@ For earlier versions, it needs to be specified as an environment variable to the
    -

    10.2. Service Account

    +

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

    @@ -1498,7 +1336,7 @@ For any service accounts you assign to a deployment or pod, you need to make sur

    Depending on the requirements, you’ll need get, list and watch permission on the following resources:

    - +@@ -1518,10 +1356,6 @@ For any service accounts you assign to a deployment or pod, you need to make sur - - - -
    Table 5. Kubernetes Resource PermissionsTable 4. Kubernetes Resource Permissions

    spring-cloud-starter-kubernetes-config

    configmaps, secrets

    spring-cloud-starter-kubernetes-ribbon

    pods, services, endpoints
    @@ -1567,7 +1401,7 @@ roleRef:
    -

    11. Service Registry Implementation

    +

    10. Service Registry Implementation

    In Kubernetes service registration is controlled by the platform, the application itself does not control @@ -1577,7 +1411,7 @@ or setting @EnableDiscoveryClient(autoRegister=false) will have no

    -

    12. Examples

    +

    11. Examples

    Spring Cloud Kubernetes tries to make it transparent for your applications to consume Kubernetes Native Services by @@ -1622,7 +1456,7 @@ The same applies for PropertySourceLocator, where you need to add t

    -

    13. Other Resources

    +

    12. Other Resources

    This section lists other resources, such as presentations (slides) and videos about Spring Cloud Kubernetes.

    @@ -1643,7 +1477,7 @@ The same applies for PropertySourceLocator, where you need to add t
    -

    14. Configuration properties

    +

    13. Configuration properties

    To see the list of all Sleuth related configuration properties please check the Appendix page.

    @@ -1651,10 +1485,10 @@ The same applies for PropertySourceLocator, where you need to add t
    -

    15. Building

    +

    14. Building

    -

    15.1. Basic Compile and Test

    +

    14.1. Basic Compile and Test

    To build the source you will need to install JDK 1.7.

    @@ -1732,7 +1566,7 @@ If all else fails, build with the command from .travis.yml (usually
    -

    15.2. Documentation

    +

    14.2. Documentation

    The spring-cloud-build module has a "docs" profile, and if you switch that on it will try to build asciidoc sources from @@ -1745,7 +1579,7 @@ a modified file in the correct place. Just commit it and push the change.

    -

    15.3. Working with the code

    +

    14.3. Working with the code

    If you don’t have an IDE preference we would recommend that you use Spring Tools Suite or @@ -1754,7 +1588,7 @@ a modified file in the correct place. Just commit it and push the change.

    should also work without issue as long as they use Maven 3.3.3 or better.

    -

    15.3.1. Importing into eclipse with m2eclipse

    +

    14.3.1. Importing into eclipse with m2eclipse

    We recommend the m2eclipse eclipse plugin when working with eclipse. If you don’t already have m2eclipse installed it is available from the "eclipse @@ -1781,7 +1615,7 @@ pom into your settings.xml.

    -

    15.3.2. Importing into eclipse without m2eclipse

    +

    14.3.2. Importing into eclipse without m2eclipse

    If you prefer not to use m2eclipse you can generate eclipse project metadata using the following command:

    @@ -1800,7 +1634,7 @@ from the file menu.

    -

    16. Contributing

    +

    15. Contributing

    Spring Cloud is released under the non-restrictive Apache 2.0 license, @@ -1810,7 +1644,7 @@ to contribute even something trivial please do not hesitate, but follow the guidelines below.

    -

    16.1. Sign the Contributor License Agreement

    +

    15.1. Sign the Contributor License Agreement

    Before we accept a non-trivial patch or pull request we will need you to sign the Contributor License Agreement. @@ -1821,7 +1655,7 @@ given the ability to merge pull requests.

    -

    16.2. Code of Conduct

    +

    15.2. Code of Conduct

    This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report @@ -1829,7 +1663,7 @@ unacceptable behavior to spri

    -

    16.3. Code Conventions and Housekeeping

    +

    15.3. Code Conventions and Housekeeping

    None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.

    @@ -1877,7 +1711,7 @@ message (where XXXX is the issue number).

    -

    16.4. Checkstyle

    +

    15.4. Checkstyle

    Spring Cloud Build comes with a set of checkstyle rules. You can find them in the spring-cloud-build-tools module. The most notable files under the module are:

    @@ -1910,7 +1744,7 @@ message (where XXXX is the issue number).

    -

    16.4.1. Checkstyle configuration

    +

    15.4.1. Checkstyle configuration

    Checkstyle rules are disabled by default. To add checkstyle to your project just define the following properties and plugins.

    @@ -2000,9 +1834,9 @@ $ touch .springformat
    -

    16.5. IDE setup

    +

    15.5. IDE setup

    -

    16.5.1. Intellij IDEA

    +

    15.5.1. Intellij IDEA

    In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. The following files can be found in the Spring Cloud Build project.

    diff --git a/reference/html/sagan-index.html b/reference/html/sagan-index.html index eaf01568..60d9eccc 100644 --- a/reference/html/sagan-index.html +++ b/reference/html/sagan-index.html @@ -142,9 +142,6 @@ The main objective of the projects provided in this repository is to facilitate

  • PropertySource objects configured via ConfigMaps

    • -
  • -

    Client side loadbalancing via Netflix Ribbon

    -
    • diff --git a/reference/html/security-service-accounts.html b/reference/html/security-service-accounts.html index eebeb85b..0ccd76ab 100644 --- a/reference/html/security-service-accounts.html +++ b/reference/html/security-service-accounts.html @@ -177,10 +177,6 @@ For any service accounts you assign to a deployment or pod, you need to make sur

    spring-cloud-starter-kubernetes-config

    configmaps, secrets

    - -

    spring-cloud-starter-kubernetes-ribbon

    -

    pods, services, endpoints

    -
    diff --git a/reference/html/spring-cloud-kubernetes.html b/reference/html/spring-cloud-kubernetes.html index 72c25e88..5074a785 100644 --- a/reference/html/spring-cloud-kubernetes.html +++ b/reference/html/spring-cloud-kubernetes.html @@ -126,50 +126,49 @@ $(globalSwitch);
  • 5.3. PropertySource Reload
    • -
  • 6. Ribbon Discovery in Kubernetes
    • -
  • 7. Kubernetes Ecosystem Awareness +
  • 6. Kubernetes Ecosystem Awareness
    • -
  • 8. Pod Health Indicator
    • -
  • 9. Leader Election
    • -
  • 10. Security Configurations Inside Kubernetes +
  • 7. Pod Health Indicator
    • +
  • 8. Leader Election
    • +
  • 9. Security Configurations Inside Kubernetes
    • -
  • 11. Service Registry Implementation
    • -
  • 12. Examples
    • -
  • 13. Other Resources
    • -
  • 14. Configuration properties
    • -
  • 15. Building +
  • 10. Service Registry Implementation
    • +
  • 11. Examples
    • +
  • 12. Other Resources
    • +
  • 13. Configuration properties
    • +
  • 14. Building
    • -
  • 16. Contributing +
  • 15. Contributing @@ -243,18 +242,6 @@ Secret changes.

    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-</dependency>
    -
    -
    -

    Ribbon client-side load balancer with -server list obtained from Kubernetes Endpoints.

    - - -
    -
    <dependency>
     <groupId>org.springframework.cloud</groupId>
     <artifactId>spring-cloud-starter-kubernetes-all</artifactId>
@@ -275,8 +262,7 @@ server list obtained from Kubernetes Endpoints.
    
 for Kubernetes.
 This client lets you query Kubernetes endpoints (see 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. This discovery feature is also used by the Spring Cloud Kubernetes Ribbon project
-to fetch the list of the endpoints defined for an application to be load balanced.
    
+access from a Spring Boot application running as a pod.

    This is something that you get for free by adding the following dependency inside your project:

    @@ -376,7 +362,7 @@ this to work, you need to align the Kubernetes service name with the sprin

    Kubernetes itself is capable of (server side) service discovery (see: kubernetes.io/docs/concepts/services-networking/service/#discovering-services). -Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (istio.io), a service mesh that is capable of load balancing, ribbon, circuit breaker, failover, and much more.

    +Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (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 {service-name}.{namespace}.svc.{cluster}.local:{service-port}.

    @@ -1249,155 +1235,7 @@ This means, for example, that using polling on file-mounted secret sources does
    -

    6. Ribbon Discovery in Kubernetes

    -
    -
    -

    Spring Cloud client applications that call a microservice should be interested on relying on a client load-balancing -feature in order to automatically discover at which endpoint(s) it can reach a given service. This mechanism has been -implemented within the spring-cloud-kubernetes-ribbon project, where a -Kubernetes client populates a Ribbon ServerList that contains information -about such endpoints.

    -
    -
    -

    The implementation is part of the following starter that you can use by adding its dependency to your pom file:

    -
    -
    -
    -
    -
    -
    <dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
-    <version>${latest.version}</version>
-</dependency>
    -
    -
    -
    -
    -
    -

    When the list of the endpoints is populated, the Kubernetes client searches the registered endpoints that live in -the current namespace or project by matching the service name defined in the Ribbon Client annotation, as follows:

    -
    -
    -
    -
    -
    -
    @RibbonClient(name = "name-service")
    -
    -
    -
    -
    -
    -

    You can configure Ribbon’s behavior by providing properties in your application.properties (through your application’s -dedicated ConfigMap) by using the following format: <name of your service>.ribbon.<Ribbon configuration key>, where:

    -
    -
    -
      -
    • -

      <name of your service> corresponds to the service name you access over Ribbon, as configured by using the -@RibbonClient annotation (such as name-service in the preceding example).

      -
      • -
    • -

      <Ribbon configuration key> is one of the Ribbon configuration keys defined by -Ribbon’s CommonClientConfigKey class.

      -
      • -
    -
    -
    -

    Additionally, the spring-cloud-kubernetes-ribbon project defines two additional configuration keys to further -control how Ribbon interacts with Kubernetes. In particular, if an endpoint defines multiple ports, the default -behavior is to use the first one found. To select more specifically which port to use in a multi-port service, you can use -the PortName key. If you want to specify in which Kubernetes namespace the target service should be looked up, you can use -the KubernetesNamespace key, remembering in both instances to prefix these keys with your service name and -ribbon prefix, as specified earlier.

    -
    - - ----- - - - - - - - - - - - - - - - - - - - - - - - - -
    Table 4. Spring Cloud Kubernetes Ribbon Configuration
    Property KeyTypeDefault Value

    spring.cloud.kubernetes.ribbon.enabled

    boolean

    true

    spring.cloud.kubernetes.ribbon.mode

    KubernetesRibbonMode

    POD

    spring.cloud.kubernetes.ribbon.cluster-domain

    string

    cluster.local

    -
    -
      -
    • -

      spring.cloud.kubernetes.ribbon.mode supports POD and SERVICE modes.

      -
      -
        -
      • -

        The POD mode is to achieve load balancing by obtaining the Pod IP address of Kubernetes and using Ribbon. -POD mode uses the load balancing of the Ribbon Does not support Kubernetes load balancing, The traffic policy of Istio is not supported.

        -
        • -
      • -

        the SERVICE mode is directly based on the service name of the Ribbon. Get -The Kubernetes service is concatenated into service-name.{namespace}.svc.{cluster.domain}:{port} such as: demo1.default.svc.cluster.local:8080. -the SERVICE mode uses load balancing of the Kubernetes service to support Istio’s traffic policy.

        -
        • -
      -
      -
      • -
    • -

      spring.cloud.kubernetes.ribbon.cluster-domain Set the custom Kubernetes cluster domain suffix. The default value is: 'cluster.local'

      -
      • -
    -
    -
    -

    The following examples use this module for ribbon discovery:

    -
    -
    - -
    -
    - - - - - -
    - - -You can disable the Ribbon discovery client by setting the spring.cloud.kubernetes.ribbon.enabled=false key within the application properties file. -
    -
    -
    -
    -
    -

    7. Kubernetes Ecosystem Awareness

    +

    6. Kubernetes Ecosystem Awareness

    All of the features described earlier in this guide work equally well, regardless of whether your application is running inside @@ -1414,7 +1252,7 @@ communicate by using http protocol to the REST API of the Kubernete Also note that these properties: spring.cloud.kubernetes.config.enabled and spring.cloud.kubernetes.secrets.enabled only take effect when set in bootstrap.{properties|yml}

    -

    7.1. Kubernetes Profile Autoconfiguration

    +

    6.1. 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 @@ -1422,7 +1260,7 @@ within the Kubernetes platform (for example, different development and productio

    -

    7.2. Istio Awareness

    +

    6.2. Istio Awareness

    When you include the spring-cloud-kubernetes-istio module in the application classpath, a new profile is added to the application, provided the application is running inside a Kubernetes Cluster with Istio installed. You can then use @@ -1436,7 +1274,7 @@ making it easy for our Spring Boot applications to consume this data to dynamica

    -

    8. Pod Health Indicator

    +

    7. Pod Health Indicator

    Spring Boot uses HealthIndicator to expose info about the health of an application. @@ -1458,7 +1296,7 @@ That makes it really useful for exposing health-related information to the user

    -

    9. Leader Election

    +

    8. Leader Election

    <TBD>

    @@ -1466,10 +1304,10 @@ That makes it really useful for exposing health-related information to the user
    -

    10. Security Configurations Inside Kubernetes

    +

    9. Security Configurations Inside Kubernetes

    -

    10.1. Namespace

    +

    9.1. 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:

    @@ -1489,7 +1327,7 @@ For earlier versions, it needs to be specified as an environment variable to the
    -

    10.2. Service Account

    +

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

    @@ -1498,7 +1336,7 @@ For any service accounts you assign to a deployment or pod, you need to make sur

    Depending on the requirements, you’ll need get, list and watch permission on the following resources:

    - +@@ -1518,10 +1356,6 @@ For any service accounts you assign to a deployment or pod, you need to make sur - - - -
    Table 5. Kubernetes Resource PermissionsTable 4. Kubernetes Resource Permissions

    spring-cloud-starter-kubernetes-config

    configmaps, secrets

    spring-cloud-starter-kubernetes-ribbon

    pods, services, endpoints
    @@ -1567,7 +1401,7 @@ roleRef:
    -

    11. Service Registry Implementation

    +

    10. Service Registry Implementation

    In Kubernetes service registration is controlled by the platform, the application itself does not control @@ -1577,7 +1411,7 @@ or setting @EnableDiscoveryClient(autoRegister=false) will have no

    -

    12. Examples

    +

    11. Examples

    Spring Cloud Kubernetes tries to make it transparent for your applications to consume Kubernetes Native Services by @@ -1622,7 +1456,7 @@ The same applies for PropertySourceLocator, where you need to add t

    -

    13. Other Resources

    +

    12. Other Resources

    This section lists other resources, such as presentations (slides) and videos about Spring Cloud Kubernetes.

    @@ -1643,7 +1477,7 @@ The same applies for PropertySourceLocator, where you need to add t
    -

    14. Configuration properties

    +

    13. Configuration properties

    To see the list of all Sleuth related configuration properties please check the Appendix page.

    @@ -1651,10 +1485,10 @@ The same applies for PropertySourceLocator, where you need to add t
    -

    15. Building

    +

    14. Building

    -

    15.1. Basic Compile and Test

    +

    14.1. Basic Compile and Test

    To build the source you will need to install JDK 1.7.

    @@ -1732,7 +1566,7 @@ If all else fails, build with the command from .travis.yml (usually
    -

    15.2. Documentation

    +

    14.2. Documentation

    The spring-cloud-build module has a "docs" profile, and if you switch that on it will try to build asciidoc sources from @@ -1745,7 +1579,7 @@ a modified file in the correct place. Just commit it and push the change.

    -

    15.3. Working with the code

    +

    14.3. Working with the code

    If you don’t have an IDE preference we would recommend that you use Spring Tools Suite or @@ -1754,7 +1588,7 @@ a modified file in the correct place. Just commit it and push the change.

    should also work without issue as long as they use Maven 3.3.3 or better.

    -

    15.3.1. Importing into eclipse with m2eclipse

    +

    14.3.1. Importing into eclipse with m2eclipse

    We recommend the m2eclipse eclipse plugin when working with eclipse. If you don’t already have m2eclipse installed it is available from the "eclipse @@ -1781,7 +1615,7 @@ pom into your settings.xml.

    -

    15.3.2. Importing into eclipse without m2eclipse

    +

    14.3.2. Importing into eclipse without m2eclipse

    If you prefer not to use m2eclipse you can generate eclipse project metadata using the following command:

    @@ -1800,7 +1634,7 @@ from the file menu.

    -

    16. Contributing

    +

    15. Contributing

    Spring Cloud is released under the non-restrictive Apache 2.0 license, @@ -1810,7 +1644,7 @@ to contribute even something trivial please do not hesitate, but follow the guidelines below.

    -

    16.1. Sign the Contributor License Agreement

    +

    15.1. Sign the Contributor License Agreement

    Before we accept a non-trivial patch or pull request we will need you to sign the Contributor License Agreement. @@ -1821,7 +1655,7 @@ given the ability to merge pull requests.

    -

    16.2. Code of Conduct

    +

    15.2. Code of Conduct

    This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report @@ -1829,7 +1663,7 @@ unacceptable behavior to spri

    -

    16.3. Code Conventions and Housekeeping

    +

    15.3. Code Conventions and Housekeeping

    None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.

    @@ -1877,7 +1711,7 @@ message (where XXXX is the issue number).

    -

    16.4. Checkstyle

    +

    15.4. Checkstyle

    Spring Cloud Build comes with a set of checkstyle rules. You can find them in the spring-cloud-build-tools module. The most notable files under the module are:

    @@ -1910,7 +1744,7 @@ message (where XXXX is the issue number).

    -

    16.4.1. Checkstyle configuration

    +

    15.4.1. Checkstyle configuration

    Checkstyle rules are disabled by default. To add checkstyle to your project just define the following properties and plugins.

    @@ -2000,9 +1834,9 @@ $ touch .springformat
    -

    16.5. IDE setup

    +

    15.5. IDE setup

    -

    16.5.1. Intellij IDEA

    +

    15.5.1. Intellij IDEA

    In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. The following files can be found in the Spring Cloud Build project.