mirror of
https://github.com/status-im/consul.git
synced 2025-01-11 06:16:08 +00:00
ingress gw docs for k8s (#8291)
Co-authored-by: Derek Strickland Co-authored-by: Luke Kysow <1034429+lkysow@users.noreply.github.com>
This commit is contained in:
Kyle Schochenmaier
GitHub
parent
8c7a4c8063
commit
1227974f43
@ -5,4 +5,203 @@ sidebar_title: Ingress Gateways
|
||||
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
|
||||
|
||||
~> This topic requires familiarity with [Ingress Gateways](/docs/connect/ingress-gateway).
|
||||
|
||||
This page describes how to enable external access to Connect service mesh services running inside Kubernetes using Consul ingress gateways.
|
||||
See [Ingress Gateways](/docs/connect/ingress-gateway) for more information on use-cases and how it works.
|
||||
|
||||
Adding an ingress gateway is a multi-step process that consists of the following steps:
|
||||
|
||||
* Setting the helm chart configuration
|
||||
* Deploying the helm chart
|
||||
* Configuring the gateway
|
||||
* Defining an Intention (if ACLs are enabled)
|
||||
* Deploying your application to Kubernetes
|
||||
* Connecting to your application
|
||||
|
||||
## Setting the helm chart configuration
|
||||
When deploying the helm chart you must provide helm with a custom yaml file that contains your environment configuration.
|
||||
|
||||
```yaml
|
||||
global:
|
||||
name: consul
|
||||
connectInject:
|
||||
enabled: true
|
||||
ingressGateways:
|
||||
enabled: true
|
||||
gateways:
|
||||
- name: ingress-gateway
|
||||
service:
|
||||
type: LoadBalancer
|
||||
```
|
||||
~> *Note:* this will create a public unathenticated 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.
|
||||
|
||||
|
||||
The gateways stanza is where you will define and configure the set of ingress gateways you want deployed to your environment.
|
||||
The only required field for each entry is `name`, though entries may contain any of the fields found in the `defaults` stanza.
|
||||
Values in this section override the values from the defaults stanza for the given ingress gateway with one exception:
|
||||
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
|
||||
[guide](/docs/k8s/installation/overview#installing-consul) while being sure to provide the yaml configuration
|
||||
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:
|
||||
|
||||
* Accessing the Consul server
|
||||
* Submitting an Ingress Gateway configuration entry to Consul
|
||||
|
||||
### Accessing the Consul 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.
|
||||
|
||||
```shell-session
|
||||
$ kubectl port-forward consul-server-0 8500 &
|
||||
```
|
||||
-> If TLS is enabled use port 8501
|
||||
|
||||
-> Download the latest Consul binary from [Downloads](/downloads.html).
|
||||
[https://releases.hashicorp.com/consul/](https://releases.hashicorp.com/consul/)
|
||||
|
||||
-> If TLS is enabled set:
|
||||
```shell-session
|
||||
$ export CONSUL_HTTP_ADDR=https://localhost:8501
|
||||
```
|
||||
|
||||
-> If ACLs are enabled set :
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
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/).
|
||||
|
||||
If TLS is enabled, use [https://localhost:8501/ui/dc1/services/ingress-gateway/](https://localhost:8501/ui/dc1/services/ingress-gateway/).
|
||||
|
||||
## 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.
|
||||
|
||||
To create an intention that allows the ingress gateway to route to the service `static-server`, run:
|
||||
```shell-session
|
||||
$ consul intention create ingress-gateway static-server
|
||||
```
|
||||
|
||||
For detailed instructions on how to configure zero-trust networking with intentions please refer to this [guide](https://learn.hashicorp.com/consul/gs-consul-service-mesh/network-security-with-consul-service-mesh).
|
||||
|
||||
## Deploying your application to Kubernetes
|
||||
Now you will deploy a sample application which echoes “hello world”
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: static-server
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: static-server
|
||||
annotations:
|
||||
'consul.hashicorp.com/connect-inject': 'true'
|
||||
spec:
|
||||
containers:
|
||||
# This name will be the service name in Consul.
|
||||
- name: static-server
|
||||
image: hashicorp/http-echo:latest
|
||||
args:
|
||||
- -text="hello world"
|
||||
- -listen=:8080
|
||||
ports:
|
||||
- containerPort: 8080
|
||||
name: http
|
||||
# If ACLs are enabled, the serviceAccountName must match the Consul service name.
|
||||
serviceAccountName: static-server
|
||||
```
|
||||
|
||||
```shell-session
|
||||
$ kubectl apply -f static-server.yaml
|
||||
```
|
||||
|
||||
## Connecting to your application
|
||||
|
||||
You can validate the service is running and registered in the Consul UI by navigating to
|
||||
[http://localhost:8500/ui/dc1/services/static-server/instances](http://localhost:8500/ui/dc1/services/static-server/instances)
|
||||
|
||||
-> If TLS is enabled, use [https://localhost:8501/ui/dc1/services/static-server/instances](https://localhost:8501/ui/dc1/services/static-server/instances)
|
||||
|
||||
You can also validate the connectivity of the application from the ingress gateway using `curl`:
|
||||
|
||||
```shell-session
|
||||
$ EXTERNAL_IP=$(kubectl get services | grep ingress-gateway | awk ‘{print $4}’)
|
||||
$ curl -H "Host: static-server.ingress.consul" $EXTERNAL_IP:8080
|
||||
```
|
||||
|
||||
~> **Security Warning:** Please be sure to delete the application and services created here as they represent a security risk through
|
||||
leaving an open and unauthenticated load balancer alive in your cluster.
|
||||
|
||||
To delete the ingress gateway, set enabled to false in your Helm configuration:
|
||||
|
||||
```yaml
|
||||
global:
|
||||
name: consul
|
||||
connectInject:
|
||||
enabled: true
|
||||
ingressGateways:
|
||||
enabled: false # Set to false
|
||||
gateways:
|
||||
- name: ingress-gateway
|
||||
service:
|
||||
type: LoadBalancer
|
||||
```
|
||||
|
||||
And run Helm upgrade:
|
||||
|
||||
```shell-session
|
||||
$ helm upgrade consul hashicorp/consul -f config.yaml
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user