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

docs(peering): update k8s docs for GA (#15417) 

* docs(peering): update k8s docs for GA

* fix code formatting and typo
This commit is contained in:
Dan Stough 2022-11-17 11:25:32 -05:00 committed by GitHub
parent 2dea269a25
commit 9f90e80795
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 34 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
website/content/api-docs/peering.mdx
View File

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

4
website/content/docs/connect/cluster-peering/create-manage-peering.mdx
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. 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 ```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. 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 ```json
{ {
"PeerName": "cluster-01", "Peer": "cluster-01",
"PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8" "PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8"
} }
``` ```

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

@ -7,13 +7,18 @@ description: >-
# Cluster Peering on Kubernetes # 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: The following CRDs are used to create and manage a peering connection:
- `PeeringAcceptor`: Generates a peering token and accepts an incoming 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. - `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. 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). > 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" image: "hashicorp/consul:1.14.0"
peering: peering:
enabled: true enabled: true
tls:
enabled: true
connectInject: connectInject:
enabled: true enabled: true
dns: dns:
enabled: true enabled: true
enableRedirection: true enableRedirection: true
server:
exposeService:
enabled: true
controller: controller:
enabled: true enabled: true
meshGateway: meshGateway:
@ -68,10 +72,6 @@ Complete the following procedure after you have provisioned a Kubernetes cluster
``` ```
</CodeBlockConfig> </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
@ -94,7 +94,7 @@ Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each clu
``` ```
```shell-session ```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 ## 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. 1. Apply the intentions to the second cluster.
<CodeBlockConfig>
```shell-session ```shell-session
$ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yaml $ 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"> <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. 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 ```shell-session
$ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090 $ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090

22
website/content/docs/connect/config-entries/exported-services.mdx
View File

@ -62,7 +62,7 @@ spec:
services: services:
- name: <name of service to export> - name: <name of service to export>
consumers: consumers:
- peerName: <name of the peered cluster that dials the exported service> - peer: <name of the peered cluster that dials the exported service>
``` ```
```json ```json
@ -113,7 +113,7 @@ spec:
- name: <name of service to export> - name: <name of service to export>
namespace: <namespace in the partition containing the service to export> namespace: <namespace in the partition containing the service to export>
consumers: consumers:
- peerName: <name of the peered cluster that dials the exported service> - peer: <name of the peered cluster that dials the exported service>
``` ```
```json ```json
@ -266,10 +266,10 @@ spec:
services: services:
- name: payments - name: payments
consumers: consumers:
- peerName: web-shop - peer: web-shop
- name: refunds - name: refunds
consumers: consumers:
- peerName: web-shop - peer: web-shop
``` ```
```json ```json
@ -341,11 +341,11 @@ spec:
- name: payments - name: payments
namespace: billing namespace: billing
consumers: consumers:
- peerName: web-shop - peer: web-shop
- name: refunds - name: refunds
namespace: billing namespace: billing
consumers: consumers:
- peerName: web-shop - peer: web-shop
``` ```
```json ```json
@ -494,8 +494,8 @@ spec:
services: services:
- name: * - name: *
consumers: consumers:
- peerName: monitoring - peer: monitoring
- peerName: platform - peer: platform
``` ```
```json ```json
@ -557,8 +557,8 @@ spec:
- name: * - name: *
namespace: * namespace: *
consumers: consumers:
- peerName: monitoring - peer: monitoring
- peerName: platform - peer: platform
``` ```
```json ```json
@ -677,4 +677,4 @@ An ACL token with `service:write` permissions is required for the cluster the qu
Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports. Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports.
For additional information, refer to [Health HTTP Endpoint](/api-docs/health). For additional information, refer to [Health HTTP Endpoint](/api-docs/health).