diff --git a/website/content/docs/k8s/connect/ingress-gateways.mdx b/website/content/docs/k8s/connect/ingress-gateways.mdx index abf1da71d5..50e6f288f9 100644 --- a/website/content/docs/k8s/connect/ingress-gateways.mdx +++ b/website/content/docs/k8s/connect/ingress-gateways.mdx @@ -7,7 +7,7 @@ description: Configuring Ingress Gateways on Kubernetes # Ingress Gateways on Kubernetes --> 1.8.0+: This feature is available in Consul versions 1.8.0 and higher +-> 1.9.0+: This feature is available in Consul versions 1.9.0 and higher ~> This topic requires familiarity with [Ingress Gateways](/docs/connect/ingress-gateway). @@ -32,6 +32,8 @@ global: name: consul connectInject: enabled: true +controller: + enabled: true ingressGateways: enabled: true gateways: @@ -40,7 +42,7 @@ ingressGateways: type: LoadBalancer ``` -~> _Note:_ this will create a public unauthenticated LoadBalancer in your cluster, please take appropriate security considerations. +~> **Note:** this will create a public unauthenticated LoadBalancer in your cluster, please take appropriate security considerations. The yaml snippet is the launching point for a valid configuration that must be supplied when installing using the [official consul-helm chart](https://hub.helm.sh/charts/hashicorp/consul). Information on additional options can be found in the [Helm reference](/docs/k8s/helm). Configuration options for ingress gateways reside under the [ingressGateways](/docs/k8s/helm#v-ingressgateways) entry. @@ -51,9 +53,6 @@ Values in this section override the values from the defaults stanza for the give the annotations from the defaults stanza will be _appended_ to any user-defined annotations defined in the gateways stanza rather than being overridden. Please refer to the ingress gateway configuration [documentation](/docs/k8s/helm#v-ingressgateways-defaults) for a detailed explanation of each option. --> _Note_: Make sure any ports that will be used as listeners in the ingress gateway's Consul config entry are included -in the `ports` object for each gateway. By default ports 8080 and 8443 are exposed for traffic. - ## Deploying the helm chart Ensure you have the latest consul-helm chart and install Consul via helm using the following @@ -62,80 +61,99 @@ as previously discussed. ## Configuring the gateway -Now that Consul has been installed with ingress gateways enabled, you must add the corresponding configuration to Consul. This requires you to use the Consul CLI. -Configuring the ingress gateway requires: +Now that Consul has been installed with ingress gateways enabled, you must configure the gateways via the [`IngressGateway`](/docs/connect/config-entries/ingress-gateway) custom resource. -- Accessing the Consul server -- Submitting an Ingress Gateway configuration entry to Consul +Here is an example `IngressGateway` resource: -### Accessing the Consul server +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: IngressGateway +metadata: + name: ingress-gateway +spec: + listeners: + - port: 8080 + protocol: http + services: + - name: static-server +``` -You can access the Consul server directly from your host via `kubectl port-forward`, this is helpful for interacting with the Consul UI locally as well as validating connectivity of the application. +Apply the `IngressGateway` resource with `kubectl apply`: ```shell-session -$ kubectl port-forward consul-server-0 8500 & +$ kubectl apply -f ingress-gateway.yaml +ingressgateway.consul.hashicorp.com/ingress-gateway created ``` -If TLS is enabled use port 8501. +Since we're using `protocol: http`, we also need to set the protocol of our service +`static-server` to http. To do that, we create a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults) custom resource: --> Download the latest Consul binary from [Downloads](/downloads). -[https://releases.hashicorp.com/consul/](https://releases.hashicorp.com/consul/) +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceDefaults +metadata: + name: static-server +spec: + protocol: http +``` -If TLS is enabled set: +Apply the `ServiceDefaults` resource with `kubectl apply`: ```shell-session -$ export CONSUL_HTTP_ADDR=https://localhost:8501 +$ kubectl apply -f service-defaults.yaml +servicedefaults.consul.hashicorp.com/static-server created ``` -If ACLs are enabled set : +Ensure both resources have synced to Consul successfully: ```shell-session -$ export CONSUL_HTTP_TOKEN=$(kubectl get secret consul-bootstrap-acl-token -o jsonpath={.data.token} | base64 -D) -$ export CONSUL_HTTP_SSL_VERIFY=false +$ kubectl get servicedefaults +NAME SYNCED AGE +static-server True 45s + +$ kubectl get ingressgateway +NAME SYNCED AGE +ingress-gateway True 13m ``` -### Submitting an Ingress Gateway configuration entry - -Now that you have access to a Consul server through the forwarded port and you have the Consul CLI configured locally, you are able to submit an ingress gateway configuration entry. -Here is an ingress gateway [configuration](https://www.consul.io/docs/agent/config-entries/ingress-gateway). - -```hcl -Kind = "ingress-gateway" -Name = "ingress-gateway" - -Listeners = [ - { - Port = 8080 - Protocol = "http" - Services = [ - { - Name = "static-server" - } - ] - } -] -``` - -Submit the ingress gateway configuration with the Consul CLI using this command. - -```shell-session -$ consul config write ingress-gateway.hcl -``` +### Viewing the UI You can confirm the ingress gateways have been configured as expected by viewing the ingress-gateway service instances -in the Consul UI: [http://localhost:8500/ui/dc1/services/ingress-gateway/](http://localhost:8500/ui/dc1/services/ingress-gateway/). +in the Consul UI. -If TLS is enabled, use : -[https://localhost:8501/ui/dc1/services/ingress-gateway/](https://localhost:8501/ui/dc1/services/ingress-gateway/). +To view the UI, use the `kubectl port-forward` command. See [Viewing The Consul UI](/docs/k8s/installation/install#viewing-the-consul-ui) +for full instructions. + +Once you've port-forwarded to the UI, navigate to the Ingress Gateway instances: [http://localhost:8500/ui/dc1/services/ingress-gateway/instances](http://localhost:8500/ui/dc1/services/ingress-gateway/instances) + +If TLS is enabled, use [https://localhost:8501/ui/dc1/services/ingress-gateway/instances](https://localhost:8501/ui/dc1/services/ingress-gateway/instances). ## Defining an Intention -If ACLs are enabled, you must define an [intention](/docs/connect/intentions) to allow the ingress gateway to access the upstream services defined in the config entry. +If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/docs/connect/intentions) +to allow the ingress gateway to route to the upstream services defined in the `IngressGateway` resource (in the example above the upstream service is `static-server`). -To create an intention that allows the ingress gateway to route to the service `static-server`, run: +To create an intention that allows the ingress gateway to route to the service `static-server`, create a [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) +resource: + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +metadata: + name: static-server +spec: + destination: + name: static-server + sources: + - name: ingress-gateway + action: allow +``` + +Apply the `ServiceIntentions` resource with `kubectl apply`: ```shell-session -$ consul intention create ingress-gateway static-server +$ kubectl apply -f service-intentions.yaml +serviceintentions.consul.hashicorp.com/ingress-gateway created ``` For detailed instructions on how to configure zero-trust networking with intentions please refer to this [guide](https://learn.hashicorp.com/tutorials/consul/service-mesh-zero-trust-network). @@ -186,7 +204,9 @@ You can also validate the connectivity of the application from the ingress gatew ```shell-session $ EXTERNAL_IP=$(kubectl get services | grep ingress-gateway | awk ‘{print $4}’) -$ curl -H "Host: static-server.ingress.consul" $EXTERNAL_IP:8080 +$ echo "Connecting to \"$EXTERNAL_IP\"" +$ curl -H "Host: static-server.ingress.consul" "http://$EXTERNAL_IP:8080" +"hello world" ``` ~> **Security Warning:** Please be sure to delete the application and services created here as they represent a security risk through @@ -199,6 +219,8 @@ global: name: consul connectInject: enabled: true +controller: + enabled: true ingressGateways: enabled: false # Set to false gateways: diff --git a/website/content/docs/k8s/connect/terminating-gateways.mdx b/website/content/docs/k8s/connect/terminating-gateways.mdx index fa52023eb3..56ec14f750 100644 --- a/website/content/docs/k8s/connect/terminating-gateways.mdx +++ b/website/content/docs/k8s/connect/terminating-gateways.mdx @@ -7,23 +7,15 @@ description: Configuring Terminating Gateways on Kubernetes # Terminating Gateways on Kubernetes --> 1.8.0+: This feature is available in Consul versions 1.8.0 and higher - --> 0.16.0+: This feature is available in consul-k8s versions 0.16.0 and higher +-> 1.9.0+: This feature is available in Consul versions 1.9.0 and higher ~> This topic requires familiarity with [Terminating Gateways](/docs/connect/terminating-gateway). -Terminating gateways are a new feature included in Consul 1.8. The correlating consul-k8s binary version is -[0.16.0](https://github.com/hashicorp/consul-k8s/blob/master/CHANGELOG.md#0160-june-17-2020), and is required to enable -terminating gateways. If you are using the latest official [consul-helm chart](https://github.com/hashicorp/consul-helm), -and have not customized the [imageK8S](/docs/k8s/helm#v-global-imagek8s) configuration for any of -your components, you should be running a compatible version by default. - Adding a terminating gateway is a multi-step process: - Update the helm chart with terminating gateway config options -- Deploying the helm chart -- Accessing the Consul agent +- Deploy the helm chart +- Access the Consul agent - Register external services with Consul ## Update the helm chart with terminating gateway config options @@ -35,6 +27,8 @@ global: name: consul connectInject: enabled: true +controller: + enabled: true terminatingGateways: enabled: true ``` @@ -50,13 +44,13 @@ as previously discussed. 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. ```shell-session -$ kubectl port-foward consul-server-0 8500 & +$ kubectl port-forward consul-server-0 8500 & ``` If TLS is enabled use port 8501: ```shell-session -$ kubectl port-foward consul-server-0 8501 & +$ kubectl port-forward consul-server-0 8501 & ``` -> Be sure the latest consul binary is installed locally on your host. @@ -85,8 +79,8 @@ 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 the configuration entry for the terminating gateway -- Create intentions to allow access from services in the mesh to external service +- Create a [`TerminatingGateway`](/docs/connect/config-entries/terminating-gateway) resource to configure the terminating gateway +- Create a [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) 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 @@ -113,12 +107,14 @@ Register the external service with Consul: ```shell-session $ curl --request PUT --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register +true ``` If ACLs and TLS are enabled : ```shell-session $ curl --request PUT --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register +true ``` ### Update terminating gateway ACL token if ACLs are enabled @@ -140,18 +136,36 @@ service "example-https" { ```shell-session $ consul acl policy create -name "example-https-write-policy" -rules @write-policy.hcl +ID: xxxxxxxxxxxxxxx +Name: example-https-write-policy +Description: +Datacenters: +Rules: +service "example-https" { + policy = "write" +} ``` Now fetch the id of the terminating gateway token ```shell-session -$ consul acl token list | grep terminating-gateway-terminating-gateway-token +consul acl token list | grep -B 6 -- "- terminating-gateway-terminating-gateway-token" | grep AccessorID + +AccessorID: ``` Update the terminating gateway acl token with the new policy ```shell-session $ consul acl token update -id -policy-name example-https-write-policy -merge-policies -merge-roles -merge-service-identities +AccessorID: +SecretID: +Description: terminating-gateway-terminating-gateway-token Token +Local: true +Create Time: 2021-01-08 21:18:47.957450486 +0000 UTC +Policies: + 63bf1d9b-a87d-8672-ddcb-d25e2d88adb8 - terminating-gateway-terminating-gateway-token + f63d1ae6-ffe7-44bd-bf7a-704a86939a63 - example-https-write-policy ``` ### Create the configuration entry for the terminating gateway @@ -160,29 +174,44 @@ Once the tokens have been updated, create the [TerminatingGateway](/docs/connect resource to configure the terminating gateway: ```hcl -Kind = "terminating-gateway" -Name = "terminating-gateway" -Services = [ - { - Name = "example-https" - CAFile = "/etc/ssl/cert.pem" - } -] +apiVersion: consul.hashicorp.com/v1alpha1 +kind: TerminatingGateway +metadata: + name: terminating-gateway +spec: + services: + - name: example-https + 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. +~> 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`). -Submit the terminating gateway entry with the Consul CLI using this command. +Apply the `TerminatingGateway` resource with `kubectl apply`: ```shell-session -$ consul config write terminating-gateway.hcl +$ kubectl apply -f terminating-gateway.yaml ``` -If using ACLs and TLS, create intentions to allow access from services in the mesh to the external service +If using ACLs and TLS, create a [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) resource to allow access from services in the mesh to the external service + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +metadata: + name: example-https +spec: + destination: + name: example-https + sources: + - name: static-client + action: allow +``` + +Apply the `ServiceIntentions` resource with `kubectl apply`: ```shell-session -$ consul intention create -allow static-client example-https +$ kubectl apply -f service-intentions.yaml ``` ### Define the external services as upstreams for services in the mesh @@ -230,6 +259,13 @@ Run the service via `kubectl apply`: $ kubectl apply -f static-client.yaml ``` +Wait for the service to be ready: + +```shell-session +$ kubectl rollout status deploy static-client --watch +deployment "static-client" successfully rolled out +``` + You can verify connectivity of the static-client and terminating gateway via a curl command: ```shell-session