Backport of docs(peering): update k8s docs for GA into release/1.14.x (#15425)

This pull request was automerged via backport-assistant
pull/15431/head
hc-github-team-consul-core 2022-11-17 11:26:05 -05:00 committed by GitHub
parent 1853ac8669
commit bbe62e5998
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 34 additions and 30 deletions

View File

@ -34,8 +34,8 @@ The table below shows this endpoint's support for
### JSON Request Body Schema
- `PeerName` `(string: <required>)` - The name assigned to the peer cluster.
The `PeerName` is used to reference the peer cluster in service discovery queries
- `Peer` `(string: <required>)` - The name assigned to the peer cluster.
The `Peer` is used to reference the peer cluster in service discovery queries
and configuration entries such as `service-intentions`. This field must be a
valid DNS hostname label.
@ -54,7 +54,7 @@ You can specify one or more load balancers or external IPs that route external t
```json
{
"PeerName": "cluster-02",
"Peer": "cluster-02",
"Meta": {
"env": "production"
}
@ -101,8 +101,8 @@ The table below shows this endpoint's support for
### JSON Request Body Schema
- `PeerName` `(string: <required>)` - The name assigned to the peer cluster.
The `PeerName` is used to reference the peer cluster in service discovery queries
- `Peer` `(string: <required>)` - The name assigned to the peer cluster.
The `Peer` is used to reference the peer cluster in service discovery queries
and configuration entries such as `service-intentions`. This field must be a
valid DNS hostname label.
@ -121,7 +121,7 @@ The table below shows this endpoint's support for
```json
{
"PeerName": "cluster-01",
"Peer": "cluster-01",
"PeeringToken": "eyJDQSI6bnVsbCwiU2V...",
"Meta": {
"env": "production"

View File

@ -37,7 +37,7 @@ Every time you generate a peering token, a single-use establishment secret is em
In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to issue a request for a peering token.
```shell-session
$ curl --request POST --data '{"PeerName":"cluster-02"}' --url http://localhost:8500/v1/peering/token
$ curl --request POST --data '{"Peer":"cluster-02"}' --url http://localhost:8500/v1/peering/token
```
The CLI outputs the peering token, which is a base64-encoded string containing the token details.
@ -48,7 +48,7 @@ Create a JSON file that contains the first cluster's name and the peering token.
```json
{
"PeerName": "cluster-01",
"Peer": "cluster-01",
"PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8"
}
```

View File

@ -7,13 +7,18 @@ description: >-
# Cluster Peering on Kubernetes
To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions (CRDs) for each side of the peering.
To establish a cluster peering connection on Kubernetes, you need to enable several pre-requisite values in the Helm chart and create custom resource definitions (CRDs) for each side of the peering.
The following Helm values are mandatory for cluster peering:
- [`global.tls.enabled = true`](/docs/k8s/helm#v-global-tls-enabled)
- [`meshGateway.enabled = true`](/docs/k8s/helm#v-meshgateway-enabled)
The following 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.
Peering connections, including both data-plane and control-plane traffic, will be routed over mesh gateways.
As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers.
> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs).
@ -52,14 +57,13 @@ Complete the following procedure after you have provisioned a Kubernetes cluster
image: "hashicorp/consul:1.14.0"
peering:
enabled: true
tls:
enabled: true
connectInject:
enabled: true
dns:
enabled: true
enableRedirection: true
server:
exposeService:
enabled: true
controller:
enabled: true
meshGateway:
@ -69,10 +73,6 @@ Complete the following procedure after you have provisioned a Kubernetes cluster
</CodeBlockConfig>
These Helm values configure the servers in each cluster so that they expose ports over a Kubernetes load balancer service. For additional configuration options, refer to [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice).
When generating a peering token from one of the clusters, Consul includes a load balancer address in the token so that the peering stream goes through the load balancer in front of the servers. For additional configuration options, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration).
### Install Consul on Kubernetes
Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each cluster.
@ -94,7 +94,7 @@ Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each clu
```
```shell-session
$ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "1.0.0" --values values.yaml --kube-context $CLUSTER2_CONTEXT
$ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "1.0.0" --values values.yaml --set global.datacenter=dc2 --kube-context $CLUSTER2_CONTEXT
```
## Create a peering connection for Consul on Kubernetes
@ -288,11 +288,15 @@ The examples described in this section demonstrate how to export a service named
1. Apply the intentions to the second cluster.
<CodeBlockConfig>
```shell-session
$ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yaml
```
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted.
</CodeBlockConfig>
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces.
<CodeBlockConfig filename="frontend.yaml" highlight="36,51">
@ -366,7 +370,7 @@ The examples described in this section demonstrate how to export a service named
1. Run the following command in `frontend` and then check the output to confirm that you peered your clusters successfully.
<CodeBlockConfig filename="frontend.yaml" highlight="31">
<CodeBlockConfig highlight="31">
```shell-session
$ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090

View File

@ -62,7 +62,7 @@ spec:
services:
- name: <name of service to export>
consumers:
- peerName: <name of the peered cluster that dials the exported service>
- peer: <name of the peered cluster that dials the exported service>
```
```json
@ -113,7 +113,7 @@ spec:
- name: <name of service to export>
namespace: <namespace in the partition containing the service to export>
consumers:
- peerName: <name of the peered cluster that dials the exported service>
- peer: <name of the peered cluster that dials the exported service>
```
```json
@ -266,10 +266,10 @@ spec:
services:
- name: payments
consumers:
- peerName: web-shop
- peer: web-shop
- name: refunds
consumers:
- peerName: web-shop
- peer: web-shop
```
```json
@ -341,11 +341,11 @@ spec:
- name: payments
namespace: billing
consumers:
- peerName: web-shop
- peer: web-shop
- name: refunds
namespace: billing
consumers:
- peerName: web-shop
- peer: web-shop
```
```json
@ -494,8 +494,8 @@ spec:
services:
- name: *
consumers:
- peerName: monitoring
- peerName: platform
- peer: monitoring
- peer: platform
```
```json
@ -557,8 +557,8 @@ spec:
- name: *
namespace: *
consumers:
- peerName: monitoring
- peerName: platform
- peer: monitoring
- peer: platform
```
```json