status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update k8s gateway docs for CRDs

This commit is contained in:
Luke Kysow 2021-01-08 13:41:27 -08:00
parent a73111ba82
commit e7496e01f0
2 changed files with 142 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
website/content/docs/k8s/connect/ingress-gateways.mdx
View File

@ -7,7 +7,7 @@ description: Configuring Ingress Gateways on Kubernetes
# 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). ~> This topic requires familiarity with [Ingress Gateways](/docs/connect/ingress-gateway).
@ -32,6 +32,8 @@ global:
name: consul name: consul
connectInject: connectInject:
enabled: true enabled: true
controller:
enabled: true
ingressGateways: ingressGateways:
enabled: true enabled: true
gateways: gateways:
@ -40,7 +42,7 @@ ingressGateways:
type: LoadBalancer 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). 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. 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. 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. 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 ## Deploying the helm chart
Ensure you have the latest consul-helm chart and install Consul via helm using the following 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 ## 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. 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.
Configuring the ingress gateway requires:
- Accessing the Consul server Here is an example `IngressGateway` resource:
- Submitting an Ingress Gateway configuration entry to Consul
### 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 ```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). ```yaml
[https://releases.hashicorp.com/consul/](https://releases.hashicorp.com/consul/) 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 ```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 ```shell-session
$ export CONSUL_HTTP_TOKEN=$(kubectl get secret consul-bootstrap-acl-token -o jsonpath={.data.token} | base64 -D) $ kubectl get servicedefaults
$ export CONSUL_HTTP_SSL_VERIFY=false NAME SYNCED AGE
static-server True 45s
$ kubectl get ingressgateway
NAME SYNCED AGE
ingress-gateway True 13m
``` ```
### Submitting an Ingress Gateway configuration entry ### Viewing the UI
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
```
You can confirm the ingress gateways have been configured as expected by viewing the ingress-gateway service instances 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 : To view the UI, use the `kubectl port-forward` command. See [Viewing The Consul UI](/docs/k8s/installation/install#viewing-the-consul-ui)
[https://localhost:8501/ui/dc1/services/ingress-gateway/](https://localhost:8501/ui/dc1/services/ingress-gateway/). 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 ## 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 ```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). 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 ```shell-session
$ EXTERNAL_IP=$(kubectl get services | grep ingress-gateway | awk ‘{print $4}’) $ 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 ~> **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 name: consul
connectInject: connectInject:
enabled: true enabled: true
controller:
enabled: true
ingressGateways: ingressGateways:
enabled: false # Set to false enabled: false # Set to false
gateways: gateways:

96
website/content/docs/k8s/connect/terminating-gateways.mdx
View File

@ -7,23 +7,15 @@ description: Configuring Terminating Gateways on Kubernetes
# Terminating Gateways on Kubernetes # Terminating 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
-> 0.16.0+: This feature is available in consul-k8s versions 0.16.0 and higher
~> This topic requires familiarity with [Terminating Gateways](/docs/connect/terminating-gateway). ~> 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: Adding a terminating gateway is a multi-step process:
- Update the helm chart with terminating gateway config options - Update the helm chart with terminating gateway config options
- Deploying the helm chart - Deploy the helm chart
- Accessing the Consul agent - Access the Consul agent
- Register external services with Consul - Register external services with Consul
## Update the helm chart with terminating gateway config options ## Update the helm chart with terminating gateway config options
@ -35,6 +27,8 @@ global:
name: consul name: consul
connectInject: connectInject:
enabled: true enabled: true
controller:
enabled: true
terminatingGateways: terminatingGateways:
enabled: true 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. 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 ```shell-session
$ kubectl port-foward consul-server-0 8500 & $ kubectl port-forward consul-server-0 8500 &
``` ```
If TLS is enabled use port 8501: If TLS is enabled use port 8501:
```shell-session ```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. -> 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 - Register external services with Consul
- Update the terminating gateway ACL token if ACLs are enabled - Update the terminating gateway ACL token if ACLs are enabled
- Create the configuration entry for the terminating gateway - Create a [`TerminatingGateway`](/docs/connect/config-entries/terminating-gateway) resource to configure the terminating gateway
- Create intentions to allow access from services in the mesh to external service - 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 - Define upstream annotations for any services that need to talk to the external services
### Register external services with Consul ### Register external services with Consul
@ -113,12 +107,14 @@ Register the external service with Consul:
```shell-session ```shell-session
$ curl --request PUT --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register $ curl --request PUT --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register
true
``` ```
If ACLs and TLS are enabled : If ACLs and TLS are enabled :
```shell-session ```shell-session
$ curl --request PUT --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" --data @external.json -k $CONSUL_HTTP_ADDR/v1/catalog/register $ 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 ### Update terminating gateway ACL token if ACLs are enabled
@ -140,18 +136,36 @@ service "example-https" {
```shell-session ```shell-session
$ consul acl policy create -name "example-https-write-policy" -rules @write-policy.hcl $ 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 Now fetch the id of the terminating gateway token
```shell-session ```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 Update the terminating gateway acl token with the new policy
```shell-session ```shell-session
$ consul acl token update -id <token-id> -policy-name example-https-write-policy -merge-policies -merge-roles -merge-service-identities $ 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 ### 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: resource to configure the terminating gateway:
```hcl ```hcl
Kind = "terminating-gateway" apiVersion: consul.hashicorp.com/v1alpha1
Name = "terminating-gateway" kind: TerminatingGateway
Services = [ metadata:
{ name: terminating-gateway
Name = "example-https" spec:
CAFile = "/etc/ssl/cert.pem" 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 ~> If TLS is enabled a `caFile` must be provided, it must point to the system trust store of the terminating gateway
container. 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 ```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 ```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 ### 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 $ 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: You can verify connectivity of the static-client and terminating gateway via a curl command:
```shell-session ```shell-session