mirror of https://github.com/hashicorp/consul
180 lines
6.6 KiB
Markdown
180 lines
6.6 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Cluster Peering on Kubernetes Technical Specifications
|
|
description: >-
|
|
In Kubernetes deployments, cluster peering connections interact with mesh gateways, sidecar proxies, exported services, and ACLs. Learn about requirements specific to k8s, including required Helm values and CRDs.
|
|
---
|
|
|
|
# Cluster peering on Kubernetes technical specifications
|
|
|
|
This reference topic describes the technical specifications associated with using cluster peering in your Kubernetes deployments. These specifications include [required Helm values](#helm-requirements) and [required custom resource definitions (CRDs)](#crd-requirements), as well as required Consul components and their configurations.
|
|
|
|
For cluster peering requirements in non-Kubernetes deployments, refer to [cluster peering technical specifications](/consul/docs/connect/cluster-peering/tech-specs).
|
|
|
|
## General Requirements
|
|
|
|
To use cluster peering features, make sure your Consul environment meets the following prerequisites:
|
|
|
|
- Consul v1.14 or higher
|
|
- Consul on Kubernetes v1.0.0 or higher
|
|
- At least two Kubernetes clusters
|
|
|
|
In addition, the following service mesh components are required in order to establish cluster peering connections:
|
|
|
|
- [Helm](#helm-requirements)
|
|
- [Custom resource definitions (CRD)](#crd-requirements)
|
|
- [Mesh gateways](#mesh-gateway-requirements)
|
|
- [Exported services](#exported-service-requirements)
|
|
- [ACLs](#acl-requirements)
|
|
|
|
## Helm requirements
|
|
|
|
Mesh gateways are required when establishing cluster peering connections. The following values must be set in the Helm chart to enable mesh gateways:
|
|
|
|
- [`global.tls.enabled = true`](/consul/docs/k8s/helm#v-global-tls-enabled)
|
|
- [`meshGateway.enabled = true`](/consul/docs/k8s/helm#v-meshgateway-enabled)
|
|
|
|
Refer to the following example Helm configuration:
|
|
|
|
<CodeBlockConfig filename="values.yaml">
|
|
|
|
```yaml
|
|
global:
|
|
name: consul
|
|
image: "hashicorp/consul:1.14.1"
|
|
peering:
|
|
enabled: true
|
|
tls:
|
|
enabled: true
|
|
meshGateway:
|
|
enabled: true
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
After mesh gateways are enabled in the Helm chart, you can separately [configure Mesh CRDs](#mesh-gateway-configuration-for-kubernetes).
|
|
|
|
## CRD requirements
|
|
|
|
You must create the following CRDs in order to establish 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.
|
|
|
|
Refer to the following example CRDs:
|
|
|
|
<CodeTabs tabs={[ "PeeringAcceptor", "PeeringDialer" ]}>
|
|
|
|
<CodeBlockConfig filename="acceptor.yaml">
|
|
|
|
```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"
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
<CodeBlockConfig filename="dialer.yaml">
|
|
|
|
```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"
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
</CodeTabs>
|
|
|
|
## Mesh gateway requirements
|
|
|
|
Mesh gateways are required for routing service mesh traffic between partitions with cluster peering connections. Consider the following general requirements for mesh gateways when using cluster peering:
|
|
|
|
- A cluster requires a registered mesh gateway in order to export services to peers.
|
|
- For Enterprise, this mesh gateway must also be registered in the same partition as the exported services and their `exported-services` configuration entry.
|
|
- To use the `local` mesh gateway mode, you must register a mesh gateway in the importing cluster.
|
|
|
|
In addition, you must define the `Proxy.Config` settings using opaque parameters compatible with your proxy. Refer to the [Gateway options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional Envoy proxy configuration information.
|
|
|
|
### Mesh gateway modes
|
|
|
|
By default, all cluster peering connections use mesh gateways in [remote mode](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#remote). Be aware of these additional requirements when changing a mesh gateway's mode.
|
|
|
|
- For mesh gateways that connect peered clusters, you can set the `mode` as either `remote` or `local`.
|
|
- The `none` mode is invalid for mesh gateways with cluster peering connections.
|
|
|
|
Refer to [mesh gateway modes](/consul/docs/connect/gateways/mesh-gateway#modes) for more information.
|
|
|
|
### Mesh gateway configuration for Kubernetes
|
|
|
|
Mesh gateways are required for cluster peering connections. Complete the following steps to add mesh gateways to your deployment so that you can establish cluster peering connections:
|
|
|
|
1. In `cluster-01` create the `Mesh` custom resource with `peeringThroughMeshGateways` set to `true`.
|
|
|
|
<CodeBlockConfig filename="mesh.yaml">
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
spec:
|
|
peering:
|
|
peerThroughMeshGateways: true
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
1. Apply the mesh gateway to `cluster-01`. Replace `CLUSTER1_CONTEXT` to target the first Consul cluster.
|
|
|
|
```shell-session
|
|
$ kubectl --context $CLUSTER1_CONTEXT apply -f mesh.yaml
|
|
```
|
|
|
|
1. Repeat the process to create and apply a mesh gateway with cluster peering enabled to `cluster-02`. Replace `CLUSTER2_CONTEXT` to target the second Consul cluster.
|
|
|
|
<CodeBlockConfig filename="mesh.yaml">
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
spec:
|
|
peering:
|
|
peerThroughMeshGateways: true
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
```shell-session
|
|
$ kubectl --context $CLUSTER2_CONTEXT apply -f mesh.yaml
|
|
```
|
|
|
|
## Exported service requirements
|
|
|
|
The `exported-services` CRD is required in order for services to communicate across partitions with cluster peering connections.
|
|
|
|
Refer to the [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services) reference for more information.
|
|
|
|
## ACL requirements
|
|
|
|
If ACLs are enabled, you must add tokens to grant the following permissions:
|
|
|
|
- Grant `service:write` permissions to services that define mesh gateways in their server definition.
|
|
- Grant `service:read` permissions for all services on the partition.
|
|
- Grant `mesh:write` permissions to the mesh gateways that participate in cluster peering connections. This permission allows a leaf certificate to be issued for mesh gateways to terminate TLS sessions for HTTP requests. |