luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

docs: Cluster peering with Transparent Proxy updates (#14369) 

* Update Cluster Peering docs to show example with Transparent Proxy 
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
David Yu 2022-08-29 13:07:08 -07:00 committed by GitHub
parent 91be64887e
commit f5139f0c17
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 215 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

269
website/content/docs/connect/cluster-peering/k8s.mdx
View File

@ -25,50 +25,82 @@ You must implement the following requirements to create and use cluster peering
- At least two Kubernetes clusters
- The installation must be running on Consul on Kubernetes version 0.47.1 or later
### Helm chart configuration
### Prepare for install
To establish cluster peering through Kubernetes, deploy clusters with the following Helm values.
1. After provisioning a Kubernetes cluster and setting up your kubeconfig file to manage access to multiple Kubernetes clusters, export the Kubernetes context names for future use with `kubectl`. For more information on how to use kubeconfig and contexts, refer to [Configure access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) on the Kubernetes documentation website.
<CodeBlockConfig filename="values.yaml">
You can use the following methods to get the context names for your clusters:
```yaml
global:
image: "hashicorp/consul:1.13.1"
peering:
* Issue the `kubectl config current-context` command to get the context for the cluster you are currently in.
* Issue the `kubectl config get-contexts` command to get all configured contexts in your kubeconfig file.
```shell-session
$ export CLUSTER1_CONTEXT=<CONTEXT for first Kubernetes cluster>
$ export CLUSTER2_CONTEXT=<CONTEXT for second Kubernetes cluster>
```
1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values.
With these values,
the servers in each cluster will be exposed over a Kubernetes Load balancer service. This service can be customized
using [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice).
When generating a peering token from one of the clusters, Consul uses the address(es) of the load balancer in the peering token so that the peering stream goes through the load balancer in front of the servers. For customizing the addresses used in the peering token, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration).
<CodeBlockConfig filename="values.yaml">
```yaml
global:
image: "hashicorp/consul:1.13.1"
peering:
enabled: true
connectInject:
enabled: true
connectInject:
enabled: true
controller:
enabled: true
meshGateway:
enabled: true
replicas: 1
```
dns:
enabled: true
enableRedirection: true
server:
exposeService:
enabeld: true
controller:
enabled: true
meshGateway:
enabled: true
replicas: 1
```
</CodeBlockConfig>
</CodeBlockConfig>
Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. With these values,
the servers in each cluster will be exposed over a Kubernetes Load balancer service. This service can be customized
using [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). When generating a peering token from one of the
clusters, the address(es) of the load balancer will be used in the peering token, so the peering stream will go through
the load balancer in front of the servers. For customizing the addresses used in the peering token, see
[`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration).
### Install Consul on Kubernetes
```shell-session
$ export HELM_RELEASE_NAME=cluster-name
```
1. Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI.
```shell-session
$ helm install ${HELM_RELEASE_NAME} hashicorp/consul --version "0.47.1" --values values.yaml
```
1. Install Consul on Kubernetes on `cluster-01`
```shell-session
$ export HELM_RELEASE_NAME=cluster-01
```
```shell-session
$ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER1_CONTEXT
```
1. Install Consul on Kubernetes on `cluster-02`
```shell-session
$ export HELM_RELEASE_NAME=cluster-02
```
```shell-session
$ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER2_CONTEXT
```
## Create a peering token
To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster.
To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. As part of the peering process, the peer names for each respective cluster within the peering are established by using the `metadata.name` values for the `PeeringAcceptor` and `PeeringDialer` CRDs.
1. In `cluster-01`, create the `PeeringAcceptor` custom resource.
<CodeBlockConfig filename="acceptor.yml">
<CodeBlockConfig filename="acceptor.yaml">
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
@ -88,13 +120,13 @@ 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 --filename acceptor.yml
$ kubectl --context $CLUSTER1_CONTEXT apply --filename acceptor.yaml
````
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
$ kubectl --context $CLUSTER1_CONTEXT get secret peering-token --output yaml > peering-token.yaml
```
## Establish a peering connection between clusters
@ -102,12 +134,12 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
1. Apply the peering token to the second cluster.
```shell-session
$ kubectl apply --filename peering-token.yml
$ kubectl --context $CLUSTER2_CONTEXT apply --filename peering-token.yaml
```
1. In `cluster-02`, create the `PeeringDialer` custom resource.
<CodeBlockConfig filename="dialer.yml">
<CodeBlockConfig filename="dialer.yaml">
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
@ -127,27 +159,74 @@ 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 --filename dialer.yml
$ kubectl --context $CLUSTER2_CONTEXT apply --filename dialer.yaml
```
## Export services between clusters
1. For the service in "cluster-02" that you want to export, add the following [annotation](/docs/k8s/annotations-and-labels) to your service's pods.
<CodeBlockConfig filename="backend-service.yml">
<CodeBlockConfig filename="backend-service.yaml">
```yaml
##…
annotations:
"consul.hashicorp.com/connect-inject": "true"
##…
# Service to expose backend
apiVersion: v1
kind: Service
metadata:
name: backend-service
spec:
selector:
app: backend
ports:
- name: http
protocol: TCP
port: 80
targetPort: 9090
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: backend
---
# deployment for backend
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
labels:
app: backend
spec:
replicas: 1
selector:
matchLabels:
app: backend
template:
metadata:
labels:
app: backend
annotations:
"consul.hashicorp.com/connect-inject": "true"
spec:
serviceAccountName: backend
containers:
- name: backend
image: nicholasjackson/fake-service:v0.22.4
ports:
- containerPort: 9090
env:
- name: "LISTEN_ADDR"
value: "0.0.0.0:9090"
- name: "NAME"
value: "backend"
- name: "MESSAGE"
value: "Response from backend"
```
</CodeBlockConfig>
1. In `cluster-02`, create an `ExportedServices` custom resource.
<CodeBlockConfig filename="exportedsvc.yml">
<CodeBlockConfig filename="exportedsvc.yaml">
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
@ -166,7 +245,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
1. Apply the service file and the `ExportedServices` resource for the second cluster.
```shell-session
$ kubectl apply --filename backend-service.yml --filename exportedsvc.yml
$ kubectl apply --context $CLUSTER2_CONTEXT --filename backend-service.yaml --filename exportedsvc.yaml
```
## Authorize services for peers
@ -195,18 +274,71 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
1. Apply the intentions to the second cluster.
```shell-session
$ kubectl apply --filename intention.yml
$ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yml
```
1. For the services in `cluster-01` that you want to access the "backend-service," add the following annotations to the service file.
1. For the services in `cluster-01` that you want to access the "backend-service," add the following annotations to the service file. To dial the upstream service from an application, ensure that the requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups).
<CodeBlockConfig filename="frontend-service.yml">
<CodeBlockConfig filename="frontend-service.yaml">
```yaml
##…
annotations:
"consul.hashicorp.com/connect-inject": "true"
##…
# Service to expose frontend
apiVersion: v1
kind: Service
metadata:
name: frontend-service
spec:
selector:
app: frontend
ports:
- name: http
protocol: TCP
port: 9090
targetPort: 9090
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: frontend
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: frontend
labels:
app: frontend
spec:
replicas: 1
selector:
matchLabels:
app: frontend
template:
metadata:
labels:
app: frontend
annotations:
"consul.hashicorp.com/connect-inject": "true"
spec:
serviceAccountName: frontend
containers:
- name: frontend
image: nicholasjackson/fake-service:v0.22.4
securityContext:
capabilities:
add: ["NET_ADMIN"]
ports:
- containerPort: 9090
env:
- name: "LISTEN_ADDR"
value: "0.0.0.0:9090"
- name: "UPSTREAM_URIS"
value: "http://backend-service.virtual.cluster-02.consul"
- name: "NAME"
value: "frontend"
- name: "MESSAGE"
value: "Hello World"
- name: "HTTP_CLIENT_KEEP_ALIVES"
value: "false"
```
</CodeBlockConfig>
@ -214,18 +346,45 @@ 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 --filename frontend-service.yml
$ kubectl --context $CLUSTER1_CONTEXT apply --filename frontend-service.yaml
```
1. Run the following command in `frontend-service` and check the output to confirm that you peered your clusters successfully.
```shell-session
$ kubectl exec -it $(kubectl get pod -l app=frontend -o name) -- curl localhost:1234
$ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090
{
"name": "backend-service",
##…
"body": "Response from backend",
"code": 200
"name": "frontend",
"uri": "/",
"type": "HTTP",
"ip_addresses": [
"10.16.2.11"
],
"start_time": "2022-08-26T23:40:01.167199",
"end_time": "2022-08-26T23:40:01.226951",
"duration": "59.752279ms",
"body": "Hello World",
"upstream_calls": {
"http://backend-service.virtual.cluster-02.consul": {
"name": "backend",
"uri": "http://backend-service.virtual.cluster-02.consul",
"type": "HTTP",
"ip_addresses": [
"10.32.2.10"
],
"start_time": "2022-08-26T23:40:01.223503",
"end_time": "2022-08-26T23:40:01.224653",
"duration": "1.149666ms",
"headers": {
"Content-Length": "266",
"Content-Type": "text/plain; charset=utf-8",
"Date": "Fri, 26 Aug 2022 23:40:01 GMT"
},
"body": "Response from backend",
"code": 200
}
},
"code": 200
}
```