From d2f0ddf8f61572a1c2bcca983f9bbcbf9582ea6f Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 14 Jun 2022 17:14:34 -0500 Subject: [PATCH 1/4] Nav.json updates --- website/data/docs-nav-data.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 139508de95..1fe87cf30d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -331,6 +331,10 @@ { "title": "Create and Manage Peering Connections", "path": "connect/cluster-peering/create-manage-peering" + }, + { + "title": "Cluster Peering on Kubernetes", + "path": "connect/cluster-peering/k8s" } ] }, From 3141469ef754088ca30a5413a2619470ad687859 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 14 Jun 2022 17:15:14 -0500 Subject: [PATCH 2/4] Cluster Peering on Kubernetes page creation --- .../docs/connect/cluster-peering/k8s.mdx | 211 ++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 website/content/docs/connect/cluster-peering/k8s.mdx diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx new file mode 100644 index 0000000000..2796cda8b1 --- /dev/null +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -0,0 +1,211 @@ +--- +layout: docs +page_title: Cluster Peering on Kubernetes +description: >- + This page describes how to create peering connections, deploy services, export cluster services, and end peering connections for Consul cluster peering using Kubernetes (K8s). +--- + +# Cluster Peering on Kubernetes + +~> This page covers features that are currently in _technical preview_. Features and functionality are subject to change. You should never use the technical preview release in secure environments or production scenarios. Features in technical preview may face performance and scaling issues, with limited support options available. + +To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions for each side of the peering. + +The following Custom Resource Definitions (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. + +## Prerequisites + +To create and use cluster peering connections with Kubernetes, you need at least two Kubernetes clusters running in a flat network with Consul on Kubernetes v. 0.45 or later. + +### Helm chart configuration +To establish cluster peering through Kubernetes, deploy clusters with the following Helm values. + +```yaml +global: + peering: + enabled: true +connectInject: + enabled: true +meshGateway: + enabled: true + replicas: 1 +``` + +## Create a peering connection + +To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. + +1. In “cluster-01,” create the `PeeringAcceptor` custom resource. + + + + ```yaml + apiVersion: consul.hashicorp.com/v1alpha1 + kind: PeeringAcceptor + metadata: + name: cluster-02 ## The name of the peer you want to connect to + spec: + peer: + secret: + name: "peering-token" + key: "data" + backend: "kubernetes" + ``` + + + +1. Apply the `PeeringAcceptor` resource to the first cluster. + + ```shell-session + $ kubectl apply -f acceptor.yml + ```` + +1. Save your peering token so that you can export it to the other cluster. + + ```shell-session + $ kubectl get secret peering-token -o yaml > peering-token.yml + ``` + +1. Apply the peering token to the second cluster. + + ```shell-session + $ kubectl apply -f peering-token.yml + ``` + +1. In “cluster-02,” create the `PeeringDialer` custom resource. + + + + ```yaml + apiVersion: consul.hashicorp.com/v1alpha1 + kind: PeeringDialer + metadata: + name: cluster-01 ## The name of the peer you want to connect to + spec: + peer: + secret: + name: "peering-token" + key: "data" + backend: "kubernetes" + ``` + + + +1. Apply the `PeeringDialer` resource to the second cluster. + + ```shell-session + $ kubectl apply -f dialer.yml + ``` + +## Deploy and export cluster services + +1. For the service in “cluster-02” that you want to export, add the following [annotations to your service files](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams). + + + + ```yaml + ##… + annotations: + "consul.hashicorp.com/connect-inject": "true" + "consul.hashicorp.com/transparent-proxy": "false" + ##… + ``` + + + +1. In “cluster-02,” create an `ExportedServices` custom resource. + + + + ```yaml + apiVersion: consul.hashicorp.com/v1alpha1 + kind: ExportedServices + metadata: + name: default ## The name of the partition containing the service + spec: + services: + name: backend-service ## The name of the service you want to export + consumers: + peerName: cluster-01 ## The name of the peer that receives the service + ``` + + + +1. Create service intentions for the second cluster. + + + + ```yaml + apiVersion: consul.hashicorp.com/v1alpha1 + kind: ServiceIntentions + metadata: + name: backend-deny + spec: + destination: + name: backend-service + sources: + - name: "*" + action: deny + - name: frontend-service + action: allow + ``` + + + +1. Apply the service file, the `ExportedServices` resource, and the intentions to the second cluster. + + ```shell-session + $ kubectl apply -f backend-service.yml; kubectl apply -f exportedsvc.yml; kubectl apply -f intention.yml + ``` + +1. To confirm that you peered your clusters, in “cluster-01,” query the `/health` HTTP endpoint. + + ```shell-session + $ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02" + ``` + +1. For the services in “cluster-01” that you want to access the “backend-service,” add the following annotations to the service file. + + + + ```yaml + ##… + annotations: + "consul.hashicorp.com/connect-inject": "true" + "consul.hashicorp.com/transparent-proxy": "false" + "consul.hashicorp.com/connect-service-upstreams": "backend-service.svc.cluster-02.peer:1234" + ##… + ``` + + + +1. Apply the service file to the first cluster. + + ```shell-session + $ kubectl apply -f frontend-service.yml + ``` + +1. Run the following command and check the output to confirm that you peered your clusters successfully. + + ```shell-session + $ curl localhost:1234 + { + “name”: “backend-service”, + ##… + “body”: “Response from backend”, + “code”: 200 + } + ``` + +## End a peering connection + +To end a peering connection, delete both the `PeeringAcceptor` and `PeeringDialer` resources. + +To confirm that you deleted your peering connection, in “cluster-01,” query the `/health` HTTP endpoint. The peered services should no longer appear. + +```shell-session +$ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02" +``` From b9917285ea07019001b3d256afbbf6d3d545f825 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Wed, 15 Jun 2022 16:15:03 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Nitya Dhanushkodi Co-authored-by: Blake Covarrubias --- .../content/docs/connect/cluster-peering/k8s.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 2796cda8b1..8943ebb258 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -18,7 +18,7 @@ The following Custom Resource Definitions (CRDs) are used to create and manage a ## Prerequisites -To create and use cluster peering connections with Kubernetes, you need at least two Kubernetes clusters running in a flat network with Consul on Kubernetes v. 0.45 or later. +To create and use cluster peering connections with Kubernetes, you need at least two Kubernetes clusters running in a flat network with Consul on Kubernetes v.0.45 or later. ### Helm chart configuration To establish cluster peering through Kubernetes, deploy clusters with the following Helm values. @@ -60,19 +60,19 @@ 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 -f acceptor.yml + $ kubectl apply --filename acceptor.yml ```` 1. Save your peering token so that you can export it to the other cluster. ```shell-session - $ kubectl get secret peering-token -o yaml > peering-token.yml + $ kubectl get secret peering-token --output yaml > peering-token.yml ``` 1. Apply the peering token to the second cluster. ```shell-session - $ kubectl apply -f peering-token.yml + $ kubectl apply --filename peering-token.yml ``` 1. In “cluster-02,” create the `PeeringDialer` custom resource. @@ -97,12 +97,12 @@ 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 -f dialer.yml + $ kubectl apply --filename dialer.yml ``` ## Deploy and export cluster services -1. For the service in “cluster-02” that you want to export, add the following [annotations to your service files](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams). +1. For the service in “cluster-02” that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) to your service's pods. This service is referred to as "backend-service" in the following steps. @@ -158,7 +158,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a 1. Apply the service file, the `ExportedServices` resource, and the intentions to the second cluster. ```shell-session - $ kubectl apply -f backend-service.yml; kubectl apply -f exportedsvc.yml; kubectl apply -f intention.yml + $ kubectl apply --filename backend-service.yml --filename exportedsvc.yml --filename intention.yml ``` 1. To confirm that you peered your clusters, in “cluster-01,” query the `/health` HTTP endpoint. @@ -185,7 +185,7 @@ 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 -f frontend-service.yml + $ kubectl apply --filename frontend-service.yml ``` 1. Run the following command and check the output to confirm that you peered your clusters successfully. From da72911ba7773e42732f53e3ae789e167603102e Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Wed, 15 Jun 2022 16:25:57 -0500 Subject: [PATCH 4/4] Additional consistency edits --- website/content/docs/connect/cluster-peering/k8s.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 8943ebb258..7b32d17432 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -7,7 +7,10 @@ description: >- # Cluster Peering on Kubernetes -~> This page covers features that are currently in _technical preview_. Features and functionality are subject to change. You should never use the technical preview release in secure environments or production scenarios. Features in technical preview may face performance and scaling issues, with limited support options available. +~> **Cluster peering is currently in technical preview:** Functionality associated +with cluster peering is subject to change. You should never use the technical +preview release in secure environments or production scenarios. Features in +technical preview may have performance issues, scaling issues, and limited support. To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions for each side of the peering. @@ -21,6 +24,7 @@ The following Custom Resource Definitions (CRDs) are used to create and manage a To create and use cluster peering connections with Kubernetes, you need at least two Kubernetes clusters running in a flat network with Consul on Kubernetes v.0.45 or later. ### Helm chart configuration + To establish cluster peering through Kubernetes, deploy clusters with the following Helm values. ```yaml