diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 35f17959c..b18633f09 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -25,50 +25,82 @@ You must implement the following requirements to create and use cluster peering - At least two Kubernetes clusters - The installation must be running on Consul on Kubernetes version 0.47.1 or later -### Helm chart configuration +### Prepare for install -To establish cluster peering through Kubernetes, deploy clusters with the following Helm values. +1. After provisioning a Kubernetes cluster and setting up your kubeconfig file to manage access to multiple Kubernetes clusters, export the Kubernetes context names for future use with `kubectl`. For more information on how to use kubeconfig and contexts, refer to [Configure access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) on the Kubernetes documentation website. - + You can use the following methods to get the context names for your clusters: + + * Issue the `kubectl config current-context` command to get the context for the cluster you are currently in. + * Issue the `kubectl config get-contexts` command to get all configured contexts in your kubeconfig file. + + ```shell-session + $ export CLUSTER1_CONTEXT= + $ export CLUSTER2_CONTEXT= + ``` - ```yaml - global: - image: "hashicorp/consul:1.13.1" - peering: +1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values. + + With these values, + the servers in each cluster will be exposed over a Kubernetes Load balancer service. This service can be customized + using [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). + + When generating a peering token from one of the clusters, Consul uses the address(es) of the load balancer in the peering token so that the peering stream goes through the load balancer in front of the servers. For customizing the addresses used in the peering token, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration). + + + + ```yaml + global: + image: "hashicorp/consul:1.13.1" + peering: + enabled: true + connectInject: enabled: true - connectInject: - enabled: true - controller: - enabled: true - meshGateway: - enabled: true - replicas: 1 - ``` + dns: + enabled: true + enableRedirection: true + server: + exposeService: + enabeld: true + controller: + enabled: true + meshGateway: + enabled: true + replicas: 1 + ``` - + + +### Install Consul on Kubernetes -Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. With these values, -the servers in each cluster will be exposed over a Kubernetes Load balancer service. This service can be customized -using [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). When generating a peering token from one of the -clusters, the address(es) of the load balancer will be used in the peering token, so the peering stream will go through -the load balancer in front of the servers. For customizing the addresses used in the peering token, see -[`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration). +1. Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. + + 1. Install Consul on Kubernetes on `cluster-01` + + ```shell-session + $ export HELM_RELEASE_NAME=cluster-01 + ``` -```shell-session -$ export HELM_RELEASE_NAME=cluster-name -``` + ```shell-session + $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER1_CONTEXT + ``` + 1. Install Consul on Kubernetes on `cluster-02` + + ```shell-session + $ export HELM_RELEASE_NAME=cluster-02 + ``` -```shell-session -$ helm install ${HELM_RELEASE_NAME} hashicorp/consul --version "0.47.1" --values values.yaml -``` + ```shell-session + $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER2_CONTEXT + ``` ## Create a peering token -To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. +To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. As part of the peering process, the peer names for each respective cluster within the peering are established by using the `metadata.name` values for the `PeeringAcceptor` and `PeeringDialer` CRDs. 1. In `cluster-01`, create the `PeeringAcceptor` custom resource. - + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -88,13 +120,13 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the `PeeringAcceptor` resource to the first cluster. ```shell-session - $ kubectl apply --filename acceptor.yml + $ kubectl --context $CLUSTER1_CONTEXT apply --filename acceptor.yaml ```` 1. Save your peering token so that you can export it to the other cluster. ```shell-session - $ kubectl get secret peering-token --output yaml > peering-token.yml + $ kubectl --context $CLUSTER1_CONTEXT get secret peering-token --output yaml > peering-token.yaml ``` ## Establish a peering connection between clusters @@ -102,12 +134,12 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the peering token to the second cluster. ```shell-session - $ kubectl apply --filename peering-token.yml + $ kubectl --context $CLUSTER2_CONTEXT apply --filename peering-token.yaml ``` -1. In `cluster-02`, create the `PeeringDialer` custom resource. +1. In `cluster-02`, create the `PeeringDialer` custom resource. - + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -127,27 +159,74 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the `PeeringDialer` resource to the second cluster. ```shell-session - $ kubectl apply --filename dialer.yml + $ kubectl --context $CLUSTER2_CONTEXT apply --filename dialer.yaml ``` ## Export services between clusters 1. For the service in "cluster-02" that you want to export, add the following [annotation](/docs/k8s/annotations-and-labels) to your service's pods. - + ```yaml - ##… - annotations: - "consul.hashicorp.com/connect-inject": "true" - ##… + # Service to expose backend + apiVersion: v1 + kind: Service + metadata: + name: backend-service + spec: + selector: + app: backend + ports: + - name: http + protocol: TCP + port: 80 + targetPort: 9090 + --- + apiVersion: v1 + kind: ServiceAccount + metadata: + name: backend + --- + # deployment for backend + apiVersion: apps/v1 + kind: Deployment + metadata: + name: backend + labels: + app: backend + spec: + replicas: 1 + selector: + matchLabels: + app: backend + template: + metadata: + labels: + app: backend + annotations: + "consul.hashicorp.com/connect-inject": "true" + spec: + serviceAccountName: backend + containers: + - name: backend + image: nicholasjackson/fake-service:v0.22.4 + ports: + - containerPort: 9090 + env: + - name: "LISTEN_ADDR" + value: "0.0.0.0:9090" + - name: "NAME" + value: "backend" + - name: "MESSAGE" + value: "Response from backend" ``` 1. In `cluster-02`, create an `ExportedServices` custom resource. - + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -166,7 +245,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the service file and the `ExportedServices` resource for the second cluster. ```shell-session - $ kubectl apply --filename backend-service.yml --filename exportedsvc.yml + $ kubectl apply --context $CLUSTER2_CONTEXT --filename backend-service.yaml --filename exportedsvc.yaml ``` ## Authorize services for peers @@ -195,18 +274,71 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the intentions to the second cluster. ```shell-session - $ kubectl apply --filename intention.yml + $ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yml ``` -1. For the services in `cluster-01` that you want to access the "backend-service," add the following annotations to the service file. +1. For the services in `cluster-01` that you want to access the "backend-service," add the following annotations to the service file. To dial the upstream service from an application, ensure that the requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). - + ```yaml - ##… - annotations: - "consul.hashicorp.com/connect-inject": "true" - ##… + # Service to expose frontend + apiVersion: v1 + kind: Service + metadata: + name: frontend-service + spec: + selector: + app: frontend + ports: + - name: http + protocol: TCP + port: 9090 + targetPort: 9090 + --- + apiVersion: v1 + kind: ServiceAccount + metadata: + name: frontend + --- + apiVersion: apps/v1 + kind: Deployment + metadata: + name: frontend + labels: + app: frontend + spec: + replicas: 1 + selector: + matchLabels: + app: frontend + template: + metadata: + labels: + app: frontend + annotations: + "consul.hashicorp.com/connect-inject": "true" + spec: + serviceAccountName: frontend + containers: + - name: frontend + image: nicholasjackson/fake-service:v0.22.4 + securityContext: + capabilities: + add: ["NET_ADMIN"] + ports: + - containerPort: 9090 + env: + - name: "LISTEN_ADDR" + value: "0.0.0.0:9090" + - name: "UPSTREAM_URIS" + value: "http://backend-service.virtual.cluster-02.consul" + - name: "NAME" + value: "frontend" + - name: "MESSAGE" + value: "Hello World" + - name: "HTTP_CLIENT_KEEP_ALIVES" + value: "false" ``` @@ -214,18 +346,45 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the service file to the first cluster. ```shell-session - $ kubectl apply --filename frontend-service.yml + $ kubectl --context $CLUSTER1_CONTEXT apply --filename frontend-service.yaml ``` 1. Run the following command in `frontend-service` and check the output to confirm that you peered your clusters successfully. ```shell-session - $ kubectl exec -it $(kubectl get pod -l app=frontend -o name) -- curl localhost:1234 + $ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090 { - "name": "backend-service", - ##… - "body": "Response from backend", - "code": 200 + "name": "frontend", + "uri": "/", + "type": "HTTP", + "ip_addresses": [ + "10.16.2.11" + ], + "start_time": "2022-08-26T23:40:01.167199", + "end_time": "2022-08-26T23:40:01.226951", + "duration": "59.752279ms", + "body": "Hello World", + "upstream_calls": { + "http://backend-service.virtual.cluster-02.consul": { + "name": "backend", + "uri": "http://backend-service.virtual.cluster-02.consul", + "type": "HTTP", + "ip_addresses": [ + "10.32.2.10" + ], + "start_time": "2022-08-26T23:40:01.223503", + "end_time": "2022-08-26T23:40:01.224653", + "duration": "1.149666ms", + "headers": { + "Content-Length": "266", + "Content-Type": "text/plain; charset=utf-8", + "Date": "Fri, 26 Aug 2022 23:40:01 GMT" + }, + "body": "Response from backend", + "code": 200 + } + }, + "code": 200 } ```