Update k8s gateway docs for CRDs (#9538)
This commit is contained in:
Luke Kysow
GitHub
parent
70d2da7582
commit
a89461cc95
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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,49 +136,82 @@ 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: <token id>
|
||||
```
|
||||
|
||||
Update the terminating gateway acl token with the new policy
|
||||
|
||||
```shell-session
|
||||
$ consul acl token update -id <token-id> -policy-name example-https-write-policy -merge-policies -merge-roles -merge-service-identities
|
||||
AccessorID: <token id>
|
||||
SecretID: <secret id>
|
||||
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
|
||||
|
||||
Once the tokens have been updated, next write the Consul [config](/docs/agent/config-entries/terminating-gateway)
|
||||
entry for the terminating gateway:
|
||||
Once the tokens have been updated, create the [TerminatingGateway](/docs/agent/config-entries/terminating-gateway)
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue