mirror of https://github.com/status-im/consul.git
Merge pull request #8140 from hashicorp/k8s/gateway-setup-docs
K8s ingress and terminating gateway setup docs
This commit is contained in:
Rebecca Zanzig
GitHub
commit
a93bc5cd18
|
|
@ -36,6 +36,7 @@
|
|||
/docs/connect/mesh_gateway.html /docs/connect/mesh-gateway 301!
|
||||
/docs/connect/ingress_gateway.html /docs/connect/ingress-gateway 301!
|
||||
/docs/connect/terminating_gateway.html /docs/connect/terminating-gateway 301!
|
||||
/docs/k8s/connect /docs/k8s/connect/overview 301!
|
||||
|
||||
# CLI renames
|
||||
|
||||
|
|
|
|||
|
|
@ -231,7 +231,14 @@ export default [
|
|||
name: 'Operations',
|
||||
content: ['upgrading', 'tls-on-existing-cluster', 'uninstalling'],
|
||||
},
|
||||
'connect',
|
||||
{
|
||||
category: 'connect',
|
||||
name: 'Connect Service Mesh',
|
||||
content: [
|
||||
'overview',
|
||||
'ingress-gateways',
|
||||
],
|
||||
},
|
||||
'service-sync',
|
||||
'dns',
|
||||
'ambassador',
|
||||
|
|
|
|||
|
|
@ -101,4 +101,4 @@ The Consul Helm chart can automate much of Consul Connect's configuration, and
|
|||
makes it easy to automatically inject Envoy sidecars into new pods when they are
|
||||
deployed. Learn about the [Helm chart](/docs/platform/k8s/helm) in general,
|
||||
or if you are already familiar with it, check out it's
|
||||
[connect specific configurations](/docs/platform/k8s/connect).
|
||||
[connect specific configurations](/docs/platform/k8s/connect/overview).
|
||||
|
|
|
|||
|
|
@ -439,4 +439,4 @@ environment.
|
|||
[services-nomad]: https://www.nomadproject.io/docs/job-specification/service.html
|
||||
[sidecar]: https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar
|
||||
[sidecar_service]: https://www.consul.io/docs/connect/registration/sidecar-service.html
|
||||
[services-k8s]: https://www.consul.io/docs/platform/k8s/connect.html#installation-and-configuration
|
||||
[services-k8s]: https://www.consul.io/docs/platform/k8s/connect/overview.html#installation-and-configuration
|
||||
|
|
|
|||
|
|
@ -286,7 +286,7 @@ If you have tried the above troubleshooting steps and are still stuck, DataWire
|
|||
[ingress controller]: https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d
|
||||
[proxies]: /docs/connect/proxies
|
||||
[service sync]: /docs/k8s/service-sync
|
||||
[connect sidecar]: /docs/k8s/connect
|
||||
[connect sidecar]: /docs/k8s/connect/overview
|
||||
[install]: https://www.getambassador.io/user-guide/consul-connect-ambassador/
|
||||
[ambassador-service.yaml]: https://www.getambassador.io/yaml/ambassador/ambassador-service.yaml
|
||||
[request access]: https://d6e.co/slack
|
||||
|
|
|
|||
|
|
@ -0,0 +1,208 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Ingress Gateways - Kubernetes
|
||||
sidebar_title: Ingress Gateways
|
||||
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
|
||||
|
||||
~> 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 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.
|
||||
|
||||
|
||||
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
|
||||
```
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Connect Service Mesh - Kubernetes
|
||||
sidebar_title: Connect - Service Mesh
|
||||
sidebar_title: Overview
|
||||
description: >-
|
||||
Connect is a feature built into to Consul that enables automatic
|
||||
service-to-service authorization and connection encryption across your Consul
|
||||
|
|
@ -26,7 +26,7 @@ automatically installed and configured using the
|
|||
## Usage
|
||||
|
||||
When the
|
||||
[Connect injector is installed](/docs/k8s/connect#installation-and-configuration),
|
||||
[Connect injector is installed](/docs/k8s/connect/overview#installation-and-configuration),
|
||||
the Connect sidecar can be automatically added to all pods. This sidecar can both
|
||||
accept and establish connections using Connect, enabling the pod to communicate
|
||||
to clients and dependencies exclusively over authorized and encrypted
|
||||
|
|
@ -78,7 +78,7 @@ spec:
|
|||
The only change for Connect is the addition of the
|
||||
`consul.hashicorp.com/connect-inject` annotation. This enables injection
|
||||
for this pod. The injector can also be
|
||||
[configured](/docs/k8s/connect#installation-and-configuration)
|
||||
[configured](/docs/k8s/connect/overview#installation-and-configuration)
|
||||
to automatically inject unless explicitly disabled, but the default
|
||||
installation requires opt-in using the annotation shown above.
|
||||
|
||||
|
|
@ -131,7 +131,7 @@ spec:
|
|||
```
|
||||
|
||||
Pods must specify upstream dependencies with the
|
||||
[`consul.hashicorp.com/connect-service-upstreams` annotation](/docs/k8s/connect#consul-hashicorp-com-connect-service-upstreams).
|
||||
[`consul.hashicorp.com/connect-service-upstreams` annotation](/docs/k8s/connect/overview#consul-hashicorp-com-connect-service-upstreams).
|
||||
This annotation declares the names of any upstream dependencies and a
|
||||
local port for the proxy to listen on. When a connection is established to that local
|
||||
port, the proxy establishes a connection to the target service
|
||||
|
|
@ -503,7 +503,7 @@ See [consul.hashicorp.com/connect-service-upstreams](#consul-hashicorp-com-conne
|
|||
### Verifying the Installation
|
||||
|
||||
To verify the installation, run the
|
||||
["Accepting Inbound Connections"](/docs/k8s/connect#accepting-inbound-connections)
|
||||
["Accepting Inbound Connections"](/docs/k8s/connect/overview#accepting-inbound-connections)
|
||||
example from the "Usage" section above. After running this example, run
|
||||
`kubectl get pod static-server -o yaml`. In the raw YAML output, you should
|
||||
see injected Connect containers and an annotation
|
||||
|
|
@ -400,7 +400,7 @@ and consider if they're appropriate for your deployment.
|
|||
|
||||
- `grpc` ((#v-client-grpc)) (`boolean: true`) - If true, agents will enable their GRPC listener on
|
||||
port 8502 and expose it to the host. This will use slightly more resources, but is
|
||||
required for [Connect](/docs/k8s/connect).
|
||||
required for [Connect](/docs/k8s/connect/overview).
|
||||
|
||||
- `exposeGossipPorts` ((#v-client-exposegossipports)) (`boolean: false`) - If true, the Helm chart
|
||||
will expose the clients' gossip ports as hostPorts. This is only necessary if pod IPs in the k8s cluster are not directly routable and the Consul servers are outside of the k8s cluster.
|
||||
|
|
@ -643,7 +643,7 @@ and consider if they're appropriate for your deployment.
|
|||
- `additionalSpec` ((#v-ui-service-additionalspec)) (`string: null`) - Additional Service spec
|
||||
values. This should be a multi-line string mapping directly to a Kubernetes `Service` object.
|
||||
|
||||
- `connectInject` ((#v-connectinject)) - Values that configure running the [Connect injector](/docs/k8s/connect).
|
||||
- `connectInject` ((#v-connectinject)) - Values that configure running the [Connect injector](/docs/k8s/connect/overview).
|
||||
|
||||
- `enabled` ((#v-connectinject-enabled)) (`boolean: false`) - If true, the chart will install all the
|
||||
resources necessary for the Connect injector process to run. This will enable the injector but will
|
||||
|
|
@ -653,7 +653,7 @@ and consider if they're appropriate for your deployment.
|
|||
(including any tag) for the [consul-k8s](https://github.com/hashicorp/consul-k8s) binary.
|
||||
|
||||
- `default` ((#v-connectinject-default)) (`boolean: false`) - If true, the injector will inject the
|
||||
Connect sidecar into all pods by default. Otherwise, pods must specify the. [injection annotation](/docs/k8s/connect#consul-hashicorp-com-connect-inject)
|
||||
Connect sidecar into all pods by default. Otherwise, pods must specify the. [injection annotation](/docs/k8s/connect/overview#consul-hashicorp-com-connect-inject)
|
||||
to opt-in to Connect injection. If this is true, pods can use the same annotation
|
||||
to explicitly opt-out of injection.
|
||||
|
||||
|
|
@ -754,7 +754,7 @@ and consider if they're appropriate for your deployment.
|
|||
configuration feature. Pods that have a Connect proxy injected will have their service automatically registered in this central configuration.
|
||||
|
||||
- `defaultProtocol` ((#v-connectinject-centralconfig-defaultprotocol)) (`string: null`) - If
|
||||
defined, this value will be used as the default protocol type for all services registered with the central configuration. This can be overridden by using the [protocol annotation](/docs/k8s/connect#consul-hashicorp-com-connect-service-protocol) directly on any pod spec.
|
||||
defined, this value will be used as the default protocol type for all services registered with the central configuration. This can be overridden by using the [protocol annotation](/docs/k8s/connect/overview#consul-hashicorp-com-connect-service-protocol) directly on any pod spec.
|
||||
|
||||
- `proxyDefaults` ((#v-connectinject-centralconfig-proxydefaults)) (`string: "{}"`) - This value is
|
||||
a raw json string that will be applied to all Connect proxy sidecar pods. It can include any valid configuration for the configured proxy.
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ The bootstrap token requires the following minimal permissions:
|
|||
- `agent:read` if using WAN federation over mesh gateways
|
||||
|
||||
Next, configure external servers. The Helm chart will use this configuration to talk to the Consul server's API
|
||||
to create policies, tokens, and an auth method. If you are [enabling Consul Connect](/docs/k8s/connect.html),
|
||||
to create policies, tokens, and an auth method. If you are [enabling Consul Connect](/docs/k8s/connect/overview),
|
||||
`k8sAuthMethodHost` should be set to the address of your Kubernetes API server
|
||||
so that the Consul servers can validate a Kubernetes service account token when using the [Kubernetes auth method](https://www.consul.io/docs/acl/auth-methods/kubernetes.html)
|
||||
with `consul login`.
|
||||
|
|
|
|||
|
|
@ -391,4 +391,4 @@ in the top left:
|
|||
With your Kubernetes clusters federated, try out using Consul service mesh to
|
||||
route between services deployed on each cluster by following our Learn Guide: [Secure and Route Service Mesh Communication Across Kubernetes](https://learn.hashicorp.com/consul/kubernetes/mesh-gateways#deploy-microservices).
|
||||
|
||||
You can also read our in-depth documentation on [Consul Service Mesh In Kubernetes](/docs/k8s/connect).
|
||||
You can also read our in-depth documentation on [Consul Service Mesh In Kubernetes](/docs/k8s/connect/overview).
|
||||
|
|
|
|||
|
|
@ -98,7 +98,7 @@ create a `config.yaml` file to override the default settings.
|
|||
You can learn what settings are available by running `helm inspect values hashicorp/consul`
|
||||
or by reading the [Helm Chart Reference](/docs/k8s/helm).
|
||||
|
||||
For example, if you want to enable the [Consul Connect](/docs/k8s/connect) feature,
|
||||
For example, if you want to enable the [Consul Connect](/docs/k8s/connect/overview) feature,
|
||||
use the following config file:
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
Loading…
Reference in New Issue