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.
To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster.
In cluster-01, create the PeeringAcceptor custom resource.
apiVersion: consul.hashicorp.com/v1alpha1
kind: PeeringAcceptor
metadata:name: cluster-02## The name of the peer you want to connect tospec:peer:secret:name:"peering-token"key:"data"backend:"kubernetes"
acceptor.yml
apiVersion: consul.hashicorp.com/v1alpha1
kind: PeeringAcceptor
metadata:name: cluster-02## The name of the peer you want to connect tospec:peer:secret:name:"peering-token"key:"data"backend:"kubernetes"
Apply the PeeringAcceptor resource to the first cluster.
$kubectl apply --filename acceptor.yml
$kubectl apply --filename acceptor.yml
Save your peering token so that you can export it to the other cluster.
$kubectl get secret peering-token --output yaml > peering-token.yml
$kubectl get secret peering-token --output yaml > peering-token.yml
Apply the peering token to the second cluster.
$kubectl apply --filename peering-token.yml
$kubectl apply --filename peering-token.yml
In “cluster-02,” create the PeeringDialer custom resource.
apiVersion: consul.hashicorp.com/v1alpha1
kind: PeeringDialer
metadata:name: cluster-01## The name of the peer you want to connect tospec:peer:secret:name:"peering-token"key:"data"backend:"kubernetes"
dialer.yml
apiVersion: consul.hashicorp.com/v1alpha1
kind: PeeringDialer
metadata:name: cluster-01## The name of the peer you want to connect tospec:peer:secret:name:"peering-token"key:"data"backend:"kubernetes"
Apply the PeeringDialer resource to the second cluster.
For the service in “cluster-02” that you want to export, add the following annotations to your service's pods. This service is referred to as "backend-service" in the following steps.
In “cluster-02,” create an ExportedServices custom resource.
apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:name: default ## The name of the partition containing the servicespec:services:name: backend-service ## The name of the service you want to exportconsumers:peerName: cluster-01## The name of the peer that receives the service
exportedsvc.yml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:name: default ## The name of the partition containing the servicespec:services:name: backend-service ## The name of the service you want to exportconsumers:peerName: cluster-01## The name of the peer that receives the service