From bbe62e599885efbf9bcae6d078cd76cd6797ae86 Mon Sep 17 00:00:00 2001 From: hc-github-team-consul-core Date: Thu, 17 Nov 2022 11:26:05 -0500 Subject: [PATCH] Backport of docs(peering): update k8s docs for GA into release/1.14.x (#15425) This pull request was automerged via backport-assistant --- website/content/api-docs/peering.mdx | 12 ++++----- .../cluster-peering/create-manage-peering.mdx | 4 +-- .../docs/connect/cluster-peering/k8s.mdx | 26 +++++++++++-------- .../config-entries/exported-services.mdx | 22 ++++++++-------- 4 files changed, 34 insertions(+), 30 deletions(-) diff --git a/website/content/api-docs/peering.mdx b/website/content/api-docs/peering.mdx index d68716f82f..86c74e0a40 100644 --- a/website/content/api-docs/peering.mdx +++ b/website/content/api-docs/peering.mdx @@ -34,8 +34,8 @@ The table below shows this endpoint's support for ### JSON Request Body Schema -- `PeerName` `(string: )` - The name assigned to the peer cluster. - The `PeerName` is used to reference the peer cluster in service discovery queries +- `Peer` `(string: )` - The name assigned to the peer cluster. + The `Peer` is used to reference the peer cluster in service discovery queries and configuration entries such as `service-intentions`. This field must be a valid DNS hostname label. @@ -54,7 +54,7 @@ You can specify one or more load balancers or external IPs that route external t ```json { - "PeerName": "cluster-02", + "Peer": "cluster-02", "Meta": { "env": "production" } @@ -101,8 +101,8 @@ The table below shows this endpoint's support for ### JSON Request Body Schema -- `PeerName` `(string: )` - The name assigned to the peer cluster. - The `PeerName` is used to reference the peer cluster in service discovery queries +- `Peer` `(string: )` - The name assigned to the peer cluster. + The `Peer` is used to reference the peer cluster in service discovery queries and configuration entries such as `service-intentions`. This field must be a valid DNS hostname label. @@ -121,7 +121,7 @@ The table below shows this endpoint's support for ```json { - "PeerName": "cluster-01", + "Peer": "cluster-01", "PeeringToken": "eyJDQSI6bnVsbCwiU2V...", "Meta": { "env": "production" diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 651826c04d..166770bbaf 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -37,7 +37,7 @@ Every time you generate a peering token, a single-use establishment secret is em In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to issue a request for a peering token. ```shell-session -$ curl --request POST --data '{"PeerName":"cluster-02"}' --url http://localhost:8500/v1/peering/token +$ curl --request POST --data '{"Peer":"cluster-02"}' --url http://localhost:8500/v1/peering/token ``` The CLI outputs the peering token, which is a base64-encoded string containing the token details. @@ -48,7 +48,7 @@ Create a JSON file that contains the first cluster's name and the peering token. ```json { - "PeerName": "cluster-01", + "Peer": "cluster-01", "PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8" } ``` diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 1922a86406..88d3a4aff9 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -7,13 +7,18 @@ description: >- # Cluster Peering on Kubernetes -To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions (CRDs) for each side of the peering. +To establish a cluster peering connection on Kubernetes, you need to enable several pre-requisite values in the Helm chart and create custom resource definitions (CRDs) for each side of the peering. + +The following Helm values are mandatory for cluster peering: +- [`global.tls.enabled = true`](/docs/k8s/helm#v-global-tls-enabled) +- [`meshGateway.enabled = true`](/docs/k8s/helm#v-meshgateway-enabled) The following CRDs are used to create and manage a peering connection: - `PeeringAcceptor`: Generates a peering token and accepts an incoming peering connection. - `PeeringDialer`: Uses a peering token to make an outbound peering connection with the cluster that generated the token. +Peering connections, including both data-plane and control-plane traffic, will be routed over mesh gateways. As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers. > To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs). @@ -52,14 +57,13 @@ Complete the following procedure after you have provisioned a Kubernetes cluster image: "hashicorp/consul:1.14.0" peering: enabled: true + tls: + enabled: true connectInject: enabled: true dns: enabled: true enableRedirection: true - server: - exposeService: - enabled: true controller: enabled: true meshGateway: @@ -68,10 +72,6 @@ Complete the following procedure after you have provisioned a Kubernetes cluster ``` - - These Helm values configure the servers in each cluster so that they expose ports over a Kubernetes load balancer service. For additional configuration options, refer to [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). - - When generating a peering token from one of the clusters, Consul includes a load balancer address in the token so that the peering stream goes through the load balancer in front of the servers. For additional configuration options, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration). ### Install Consul on Kubernetes @@ -94,7 +94,7 @@ Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each clu ``` ```shell-session - $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "1.0.0" --values values.yaml --kube-context $CLUSTER2_CONTEXT + $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "1.0.0" --values values.yaml --set global.datacenter=dc2 --kube-context $CLUSTER2_CONTEXT ``` ## Create a peering connection for Consul on Kubernetes @@ -288,11 +288,15 @@ The examples described in this section demonstrate how to export a service named 1. Apply the intentions to the second cluster. + + ```shell-session $ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yaml ``` -1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. + + +1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces. @@ -366,7 +370,7 @@ The examples described in this section demonstrate how to export a service named 1. Run the following command in `frontend` and then check the output to confirm that you peered your clusters successfully. - + ```shell-session $ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090 diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index 5c6dd2a09d..ed08cf39b4 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -62,7 +62,7 @@ spec: services: - name: consumers: - - peerName: + - peer: ``` ```json @@ -113,7 +113,7 @@ spec: - name: namespace: consumers: - - peerName: + - peer: ``` ```json @@ -266,10 +266,10 @@ spec: services: - name: payments consumers: - - peerName: web-shop + - peer: web-shop - name: refunds consumers: - - peerName: web-shop + - peer: web-shop ``` ```json @@ -341,11 +341,11 @@ spec: - name: payments namespace: billing consumers: - - peerName: web-shop + - peer: web-shop - name: refunds namespace: billing consumers: - - peerName: web-shop + - peer: web-shop ``` ```json @@ -494,8 +494,8 @@ spec: services: - name: * consumers: - - peerName: monitoring - - peerName: platform + - peer: monitoring + - peer: platform ``` ```json @@ -557,8 +557,8 @@ spec: - name: * namespace: * consumers: - - peerName: monitoring - - peerName: platform + - peer: monitoring + - peer: platform ``` ```json @@ -677,4 +677,4 @@ An ACL token with `service:write` permissions is required for the cluster the qu Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports. -For additional information, refer to [Health HTTP Endpoint](/api-docs/health). \ No newline at end of file +For additional information, refer to [Health HTTP Endpoint](/api-docs/health).