docs: Update Admin Partitions with more explicit commands by using shell variables (#12966)

* docs: Update Admin Partitions with more explicit commands by using shell variables Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
2022-05-11 09:27:58 -07:00 · 2022-05-11 09:27:58 -07:00 · 4a2b61a1f4
parent 1bac1544d0
commit 4a2b61a1f4
1 changed files with 88 additions and 23 deletions
--- a/website/content/docs/enterprise/admin-partitions.mdx
+++ b/website/content/docs/enterprise/admin-partitions.mdx
@ -68,6 +68,17 @@ Your Consul configuration must meet the following requirements to use admin part

 - Consul 1.11.1 and newer

+### General Networking Requirements
+
+All Consul clients must be able to communicate with the Consul servers in the `default` partition. All servers must also be able to communicate with the clients.
+
+For Consul on Kubernetes, a dedicated `partition` Kubernetes `LoadBalancer` service is deployed to allow communication from clients to servers for admin partitions support (refer to [Kubernetes Requirements](#kubernetes-requirements) for additional information). 
+
+For other runtimes, refer to the documentation for your infrastructure environment for instructions on how to allow communication on the following ports:
+- 8300 (RPC)  
+- 8301 (gossip)
+- 443 (HTTPS API requests)  
+
 ### Security Configurations

 - The agent token used by the client agent must allow `node:write` in the admin partition.
@ -95,7 +106,12 @@ One of the primary use cases for admin partitions is for enabling a service mesh
 - A Consul Enterprise license must be installed on each Kubernetes cluster.
 - The helm chart for consul-k8s v0.39.0 or greater.
 - Consul 1.11.1-ent or greater.
- All Consul clients must be able to communicate with the Consul servers in the `default` partition, and all servers must be able to communicate with the clients.
+- A designated Kubernetes `LoadBalancer` service must be exposed on the Consul server cluster. This enable the following communication channels to the Consul servers and the `default` partition:
+  - RPC on port 8300 
+  - Gossip on port 8301
+  - HTTPS API requests on port 443 API requests 
+- Mesh gateways must be deployed as a Kubernetes `LoadBalancer` service on port 443 across all Kubernetes clusters.
+- Cross-partition networking must be implemented as described in [Cross-Partition Networking](#cross-partition-networking). 

 ## Usage

@ -107,16 +123,51 @@ The expected use case is to create admin partitions on Kubernetes clusters. This

 The following procedure will result in an admin partition in each Kubernetes cluster. The Consul clients running in the cluster with servers will be in the `default` partition. Another partition called `clients` will also be created.

+#### Prepare to install Consul across multiple Kubernetes clusters
+
 Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernetes-requirements) before proceeding.

 1. Verify that your VPC is configured to enable connectivity between the pods running Consul clients and servers. Refer to your virtual cloud provider's documentation for instructions on configuring network connectivity.
-1. Create the license secret in each cluster, e.g.:
+1. Set environment variables to use with shell commands. 

  ```shell-session
-  $ kubectl create secret generic license --from-file=key=[license file path i.e. ./license.hclic]
+  $ export HELM_RELEASE_SERVER=server
+  $ export HELM_RELEASE_CLIENT=client
+  $ export SERVER_CONTEXT=<context for server, run `kubectl config current-context` for cluster provisioned for servers>
+  $ export CLIENT_CONTEXT=<context for workload partition, run `kubectl config current-context` for cluster provisioned for workload partition>
+  ```
+1. Set your context to the server cluster. 
+
+  ```shell-session
+  $ kubectl config use-context ${SERVER_CONTEXT}
+  ```
+  
+1. Create the license secret in server cluster.
+
+  ```shell-session
+  $ kubectl create secret --namespace consul generic license --from-file=key=./path/to/license.hclic
+  ```
+  
+1. Set your context to the workload client cluster. 
+
+  ```shell-session
+  $ kubectl config use-context ${CLIENT_CONTEXT}
  ```

-  This step must also be completed for every cluster.
+1. Create the license secret in the workload client cluster. This step must be repeated for every additional workload client cluster. 
+
+  ```shell-session
+  $ kubectl create ns consul 
+  $ kubectl create secret --namespace consul generic license --from-file=key=./path/to/license.hclic
+  ```
+  
+#### Install the Consul server cluster
+
+1. Set your context to the server cluster. 
+
+  ```shell-session
+  $ kubectl config use-context ${SERVER_CONTEXT}
+  ```

 1. Create a server configuration values file to override the default Consul Helm chart settings:

@ -129,7 +180,7 @@ Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernet
    enableConsulNamespaces: true
    tls:
      enabled: true
-    image: hashicorp/consul-enterprise:1.11.2-ent
+    image: hashicorp/consul-enterprise:1.12.0-ent
    adminPartitions:
      enabled: true
    acls:
@ -161,20 +212,20 @@ Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernet
 1. Install the Consul server(s) using the values file created in the previous step:

  ```shell-session
-  $ helm install server hashicorp/consul --values server.yaml --version "0.40.0"
+  $ helm install ${HELM_RELEASE_SERVER} hashicorp/consul --version "0.43.0" --create-namespace --namespace consul --values server.yaml
  ```

 1. After the server starts, get the external IP address for partition service so that it can be added to the client configuration. The IP address is used to bootstrap connectivity between servers and clients. <a name="get-external-ip-address"/>

  ```shell-session
-  $ kubectl get services --selector="app=consul,component=server" --output jsonpath="{range .items[*]}{@.status.loadBalancer.ingress[*].ip}{end}"
+  $ kubectl get services --selector="app=consul,component=server" --namespace consul --output jsonpath="{range .items[*]}{@.status.loadBalancer.ingress[*].ip}{end}"
  34.135.103.67
  ```

 1. Get the Kubernetes authentication method URL for the workload cluster:

  ```shell-session
-  $ kubectl config view --output "jsonpath={.clusters[?(@.name=='<workload-cluster-name>')].cluster.server}"
+  $ kubectl config view --output "jsonpath={.clusters[?(@.name=='${CLIENT_CONTEXT}')].cluster.server}"
  ```

  Use the IP address printed to the console to configure the `k8sAuthMethodHost` parameter in the workload configuration file for your client nodes.
@ -182,19 +233,27 @@ Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernet
 1. Copy the server certificate to the workload cluster.

  ```shell-session
-  $ kubectl get secret server-consul-ca-cert --context <server-context> --output yaml | kubectl apply --context <client-context> --filename -
+  $ kubectl get secret ${HELM_RELEASE_SERVER}-consul-ca-cert --context ${SERVER_CONTEXT} -n consul --output yaml | kubectl apply --namespace consul --context ${CLIENT_CONTEXT} --filename -
  ```

 1. Copy the server key to the workload cluster.

  ```shell-session
-  $ kubectl get secret server-consul-ca-key --context <server-context> --output yaml | kubectl apply --context <client-context> --filename -
+  $ kubectl get secret ${HELM_RELEASE_SERVER}-consul-ca-key --context ${SERVER_CONTEXT} --namespace consul --output yaml | kubectl apply --namespace consul --context ${CLIENT_CONTEXT} --filename -
  ```

 1. If ACLs were enabled in the server configuration values file, copy the token to the workload cluster.

  ```shell-session
-  $ kubectl get secret server-consul-partitions-acl-token --context <server-context> --output yaml | kubectl apply --context <client-context> --filename -
+  $ kubectl get secret ${HELM_RELEASE_SERVER}-consul-partitions-acl-token --context ${SERVER_CONTEXT} --namespace consul --output yaml | kubectl apply --namespace consul --context ${CLIENT_CONTEXT} --filename -
+  ```
+  
+#### Install the workload client cluster 
+  
+1. Switch to the workload client clusters:
+
+  ```shell-session
+  $ kubectl config use-context ${CLIENT_CONTEXT}  
  ```

 1. Create the workload configuration for client nodes in your cluster. Create a configuration for each admin partition.
@ -202,42 +261,42 @@ Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernet

  <CodeTabs heading="client.yaml">

-  <CodeBlockConfig lineNumbers highlight="2,27,29,33">
+  <CodeBlockConfig lineNumbers highlight="2,12,15,20,27,29,33">

  ```yaml
  global:
    name: client
    enabled: false
    enableConsulNamespaces: true
-    image: hashicorp/consul-enterprise:1.11.2-ent
+    image: hashicorp/consul-enterprise:1.12.0-ent
    adminPartitions:
      enabled: true
      name: clients
    tls:
      enabled: true
      caCert:
-        secretName: server-consul-ca-cert
+        secretName: server-consul-ca-cert # See step 6 from `Install Consul server cluster`
        secretKey: tls.crt
      caKey:
-        secretName: server-consul-ca-key
+        secretName: server-consul-ca-key # See step 7 from `Install Consul server cluster`
        secretKey: tls.key
    acls:
      manageSystemACLs: true
      bootstrapToken:
-        secretName: server-consul-partitions-acl-token
+        secretName: server-consul-partitions-acl-token # See step 8 from `Install Consul server cluster`
        secretKey: token
    enterpriseLicense:
      secretName: license
      secretKey: key
  externalServers:
    enabled: true
-    hosts: [34.135.103.67] # See step 5
+    hosts: [34.135.103.67] # See step 4 from `Install Consul server cluster`
    tlsServerName: server.dc1.consul
-    k8sAuthMethodHost: https://104.154.156.146 # See step 6
+    k8sAuthMethodHost: https://104.154.156.146 # See step 5 from `Install Consul server cluster`
  client:
    enabled: true
    exposeGossipPorts: true
-    join: [34.135.103.67] # See step 5
+    join: [34.135.103.67] # See step 4 from `Install Consul server cluster`
  connectInject:
    enabled: true
    consulNamespaces:
@ -257,18 +316,24 @@ Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernet

 1. Install the workload client clusters:

-```shell-session
-$ helm install clients hashicorp/consul --values client.yaml --version "0.40.0"
-```
+  ```shell-session
+  $ helm install ${HELM_RELEASE_CLIENT} hashicorp/consul --version "0.43.0" --create-namespace --namespace consul --values client.yaml 
+  ```

 ### Verifying the Deployment

 You can log into the Consul UI to verify that the partitions appear as expected.

+1. Set your context to the server cluster. 
+
+  ```shell-session
+  $ kubectl config use-context ${SERVER_CONTEXT} 
+  ```
+  
 1. If ACLs are enabled, you will need the partitions ACL token, which can be read from the Kubernetes secret. The token is an encoded string that must be decoded in base64, e.g.:

  ```shell-session
-  $ kubectl get secret server-consul-bootstrap-acl-token --template "{{ .data.token | base64decode }}"
+  $ kubectl get secret --namespace consul ${HELM_RELEASE_SERVER}-consul-bootstrap-acl-token --template "{{ .data.token | base64decode }}"
  ```

  The example command gets the token using the secret name configured in the values file (`bootstrap.secretName`), decodes the secret, and prints the usable token to the console in JSON format.