status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

k8s page updates

This commit is contained in:
boruszak 2022-09-28 15:42:21 -05:00
parent 6fd154ec73
commit 3e2a650e5f
1 changed files with 62 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -18,34 +18,31 @@ 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.
As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers.
## Prerequisites
You must implement the following requirements to create and use cluster peering connections with Kubernetes:
- Consul version 1.13.1 or later
- Consul v1.13.1 or later
- At least two Kubernetes clusters
- The installation must be running on Consul on Kubernetes version 0.47.1 or later
### Prepare for install
### Prepare for installation
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.
1. After you provision a Kubernetes cluster and set up your kubeconfig file to manage access to multiple Kubernetes clusters, use the `kubectl` command to export the Kubernetes context names and then set them to variables for future use. For more information on how to use kubeconfig and contexts, refer to the [Kubernetes docs on configuring access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
You can use the following methods to get the context names for your clusters:
* 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.
- Use the `kubectl config current-context` command to get the context for the cluster you are currently in.
- Use 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).
1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values.
<CodeBlockConfig filename="values.yaml">
@ -71,12 +68,16 @@ You must implement the following requirements to create and use cluster peering
```
</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
1. Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI.
Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each cluster.
1. Install Consul on Kubernetes on `cluster-01`
1. In `cluster-01`, run the following commands:
```shell-session
$ export HELM_RELEASE_NAME=cluster-01
@ -85,7 +86,8 @@ You must implement the following requirements to create and use cluster peering
```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`
1. In `cluster-02`, run the following commands:
```shell-session
$ export HELM_RELEASE_NAME=cluster-02
@ -95,9 +97,11 @@ You must implement the following requirements to create and use cluster peering
$ 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
## Create a peering connection for Consul on Kubernetes
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.
### Create a peering token
To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. Peers identify each other using the `metadata.name` values you establish when creating the `PeeringAcceptor` and `PeeringDialer` CRDs.
1. In `cluster-01`, create the `PeeringAcceptor` custom resource.
@ -130,7 +134,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
$ kubectl --context $CLUSTER1_CONTEXT get secret peering-token --output yaml > peering-token.yaml
```
## Establish a peering connection between clusters
### Establish a peering connection between clusters
1. Apply the peering token to the second cluster.
@ -138,7 +142,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
$ kubectl --context $CLUSTER2_CONTEXT apply --filename peering-token.yaml
```
1. In `cluster-02`, create the `PeeringDialer` custom resource.
1. In `cluster-02`, create the `PeeringDialer` custom resource.
<CodeBlockConfig filename="dialer.yaml">
@ -163,9 +167,11 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
$ kubectl --context $CLUSTER2_CONTEXT apply --filename dialer.yaml
```
## Export services between clusters
### 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.
~> **Tip**: The examples in this section demonstrate how to export a service named `backend`. You should change instances of `backend` in the example code to the name of the service you want to export.
1. For the service in `cluster-02` that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels) to your service's pods.
<CodeBlockConfig filename="backend.yaml">
@ -189,7 +195,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
metadata:
name: backend
---
# deployment for backend
# Deployment for backend
apiVersion: apps/v1
kind: Deployment
metadata:
@ -243,13 +249,13 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
</CodeBlockConfig>
1. Apply the service file and the `ExportedServices` resource for the second cluster.
1. Apply the service file and the `ExportedServices` resource to the second cluster.
```shell-session
$ kubectl apply --context $CLUSTER2_CONTEXT --filename backend.yaml --filename exportedsvc.yaml
```
## Authorize services for peers
### Authorize services for peers
1. Create service intentions for the second cluster.
@ -278,7 +284,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
$ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yml
```
1. For the services in `cluster-01` that you want to access the "backend," 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).
1. For the services in `cluster-01` that you want to access `backend`, 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.yaml">
@ -350,10 +356,11 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
$ kubectl --context $CLUSTER1_CONTEXT apply --filename frontend.yaml
```
1. Run the following command in `frontend` and check the output to confirm that you peered your clusters successfully.
1. Run the following command in `frontend` and then check the output to confirm that you peered your clusters successfully.
```shell-session
$ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090
{
"name": "frontend",
"uri": "/",
@ -401,9 +408,9 @@ $ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02"
## Recreate or reset a peering connection
To recreate or reset the peering connection, you need to generate a new peering token on the cluster where you created the `PeeringAcceptor` (in this example, `cluster-01`).
To recreate or reset the peering connection, you need to generate a new peering token from the cluster where you created the `PeeringAcceptor`.
1. You can do this by creating or updating the annotation `consul.hashicorp.com/peering-version` on the `PeeringAcceptor`. If the annotation already exists, update its value to a version that is higher.
1. In the `PeeringAcceptor` CRD, add the annotation `consul.hashicorp.com/peering-version`. If the annotation already exists, update its value to a higher version.
<CodeBlockConfig filename="acceptor.yml" highlight="6" hideClipboard>
@ -424,6 +431,31 @@ To recreate or reset the peering connection, you need to generate a new peering
</CodeBlockConfig>
1. Once you have done this, repeat the steps in the peering process. This includes saving your peering token so that you can export it to the other cluster. This will re-establish peering with the updated token.
2. After you update `PeeringAcceptor`, repeat the steps to create a peering connection, including saving a new peering token and exporting it to the other cluster. Your peering connection is re-established with the updated token.
~> **Note:** A new peering token is only generated upon manually setting and updating the value of the annotation `consul.hashicorp.com/peering-version`. Creating a new token will cause the previous token to expire.
~> **Note:** The only way to create or set a new peering token is to manually adjust the value of the annotation `consul.hashicorp.com/peering-version`. Creating a new token causes the previous token to expire.
## Traffic management between peers
As of Consul v1.14, you can use dynamic traffic management features to configure your service mesh so that services automatically failover and redirect between peers.
To configure automatic service failovers and redirect, edit the `ServiceResolver` CRD so that traffic resolves to a backup service instance on a peer. The following example updates the `ServiceResolver` CRD in `cluster-02` so that Consul redirects traffic intended for the `backend` service to a backup instance in `cluster-01` when it detects multiple connection failures to the primary instance.
<CodeBlockConfig filename="service-resolver.yaml" hideClipboard>
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
name: backend
spec:
connectTimeout: 15s
failover:
'*':
targets:
- peer: 'cluster-01'
service: 'backup'
namespace: 'default'
```
</CodeBlockConfig>