Terminating Gateways on Kubernetes

1.9.0+: This feature is available in Consul versions 1.9.0 and higher

This topic requires familiarity with Terminating Gateways.

Adding a terminating gateway is a multi-step process:

  • Update the helm chart with terminating gateway config options
  • Deploy the helm chart
  • Access the Consul agent
  • Register external services with Consul

Update the helm chart with terminating gateway config options

Minimum required Helm options:

  1. global:
  2.   name: consul
  3. connectInject:
  4.   enabled: true
  5. controller:
  6.   enabled: true
  7. terminatingGateways:
  8.   enabled: true

Deploying the helm chart

Ensure you have the latest consul-helm chart and install Consul via helm using the following guide while being sure to provide the yaml configuration as previously discussed.

Accessing the Consul agent

You can access the Consul server directly from your host via kubectl port-forward. This is helpful for interacting with your Consul UI locally as well as to validate connectivity of the application.

  1. $ kubectl port-forward consul-server-0 8500 &

If TLS is enabled use port 8501:

  1. $ kubectl port-forward consul-server-0 8501 &

Be sure the latest consul binary is installed locally on your host. https://releases.hashicorp.com/consul/

  1. $ export CONSUL_HTTP_ADDR=http://localhost:8500

If TLS is enabled set:

  1. $ export CONSUL_HTTP_ADDR=https://localhost:8501
  2. $ export CONSUL_HTTP_SSL_VERIFY=false

If ACLs are enabled also set:

  1. $ export CONSUL_HTTP_TOKEN=$(kubectl get secret consul-bootstrap-acl-token -o jsonpath={.data.token} | base64 -D)

Register external services with Consul

Registering the external services with Consul is a multi-step process:

  • Register external services with Consul
  • Update the terminating gateway ACL token if ACLs are enabled
  • Create a TerminatingGateway resource to configure the terminating gateway
  • Create a ServiceIntentions resource to allow access from services in the mesh to external service
  • Define upstream annotations for any services that need to talk to the external services

Register external services with Consul

Create a sample external service and register it with Consul.

  1. {
  2.   "Node": "legacy_node",
  3.   "Address": "example.com",
  4.   "NodeMeta": {
  5.     "external-node": "true",
  6.     "external-probe": "true"
  7.   },
  8.   "Service": {
  9.     "ID": "example-https",
  10.     "Service": "example-https",
  11.     "Port": 443
  12.   }
  13. }

Register the external service with Consul:

  1. $ curl --request PUT --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register
  2. true

If ACLs and TLS are enabled :

  1. $ curl --request PUT --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register
  2. true

Update terminating gateway ACL token if ACLs are enabled

If ACLs are enabled, update the terminating gateway acl token to have service: write permissions on all of the services being represented by the gateway:

  • Create a new policy that includes these permissions
  • Update the existing token to include the new policy

The CLI command should be run with the -merge-policies, -merge-roles and -merge-service-identities so nothing is removed from the terminating gateway token

  1. service "example-https" {
  2.   policy = "write"
  3. }
  1. $ consul acl policy create -name "example-https-write-policy" -rules @write-policy.hcl
  2. ID:           xxxxxxxxxxxxxxx
  3. Name:         example-https-write-policy
  4. Description:
  5. Datacenters:
  6. Rules:
  7. service "example-https" {
  8.   policy = "write"
  9. }

Now fetch the id of the terminating gateway token

  1. consul acl token list | grep -B 6 -- "- terminating-gateway-terminating-gateway-token" | grep AccessorID
  3. AccessorID:       <token id>

Update the terminating gateway acl token with the new policy

  1. $ consul acl token update -id <token-id> -policy-name example-https-write-policy -merge-policies -merge-roles -merge-service-identities
  2. AccessorID:       <token id>
  3. SecretID:         <secret id>
  4. Description:      terminating-gateway-terminating-gateway-token Token
  5. Local:            true
  6. Create Time:      2021-01-08 21:18:47.957450486 +0000 UTC
  7. Policies:
  8.    63bf1d9b-a87d-8672-ddcb-d25e2d88adb8 - terminating-gateway-terminating-gateway-token
  9.    f63d1ae6-ffe7-44bd-bf7a-704a86939a63 - example-https-write-policy

Create the configuration entry for the terminating gateway

Once the tokens have been updated, create the TerminatingGateway resource to configure the terminating gateway:

  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: TerminatingGateway
  3. metadata:
  4.   name: terminating-gateway
  5. spec:
  6.   services:
  7.     - name: example-https
  8.       caFile: /etc/ssl/cert.pem

If TLS is enabled a caFile must be provided, it must point to the system trust store of the terminating gateway container (/etc/ssl/cert.pem).

Apply the TerminatingGateway resource with kubectl apply:

  1. $ kubectl apply -f terminating-gateway.yaml

If using ACLs and TLS, create a ServiceIntentions resource to allow access from services in the mesh to the external service

  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: ServiceIntentions
  3. metadata:
  4.   name: example-https
  5. spec:
  6.   destination:
  7.     name: example-https
  8.   sources:
  9.     - name: static-client
  10.       action: allow

Apply the ServiceIntentions resource with kubectl apply:

  1. $ kubectl apply -f service-intentions.yaml

Define the external services as upstreams for services in the mesh

Finally define and deploy the external services as upstreams for the internal mesh services that wish to talk to them. An example deployment is provided which will serve as a static client for the terminating gateway service.

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   name: static-client
  5. ---
  6. apiVersion: apps/v1
  7. kind: Deployment
  8. metadata:
  9.   name: static-client
  10. spec:
  11.   replicas: 1
  12.   selector:
  13.     matchLabels:
  14.       app: static-client
  15.   template:
  16.     metadata:
  17.       name: static-client
  18.       labels:
  19.         app: static-client
  20.       annotations:
  21.         'consul.hashicorp.com/connect-inject': 'true'
  22.         'consul.hashicorp.com/connect-service-upstreams': 'example-https:1234'
  23.     spec:
  24.       containers:
  25.         # This name will be the service name in Consul.
  26.         - name: static-client
  27.           image: tutum/curl:latest
  28.           command: ['/bin/sh', '-c', '--']
  29.           args: ['while true; do sleep 30; done;']
  30.         # If ACLs are enabled, the serviceAccountName must match the Consul service name.
  31.       serviceAccountName: static-client

Run the service via kubectl apply:

  1. $ kubectl apply -f static-client.yaml

Wait for the service to be ready:

  1. $ kubectl rollout status deploy static-client --watch
  2. deployment "static-client" successfully rolled out

You can verify connectivity of the static-client and terminating gateway via a curl command:

  1. $ kubectl exec deploy/static-client -- curl -vvvs -H "Host: example-https.com" http://localhost:1234/