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 000000000..7b32d1743 --- /dev/null +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -0,0 +1,215 @@ +--- +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 + +~> **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. + +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 --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 --output yaml > peering-token.yml + ``` + +1. Apply the peering token to the second cluster. + + ```shell-session + $ kubectl apply --filename 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 --filename dialer.yml + ``` + +## Deploy and export cluster services + +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. + + + + ```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 --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. + + ```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 --filename 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" +``` diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b5d441515..855a532c8 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" } ] },