mirror of https://github.com/status-im/consul.git
171 lines
6.4 KiB
Plaintext
171 lines
6.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Join Kubernetes Clusters to external Consul Servers
|
|
description: >-
|
|
Kubernetes clusters can be joined to existing Consul clusters in a much simpler way with the introduction of Consul Dataplane. Learn how to add Kubernetes Clusters into an existing Consul cluster and bootstrap ACLs by configuring the Helm chart.
|
|
---
|
|
|
|
# Join Kubernetes Clusters to external Consul Servers
|
|
|
|
If you have a Consul cluster already running, you can configure your
|
|
Consul on Kubernetes installation to join this existing cluster.
|
|
|
|
The below `values.yaml` file shows how to configure the Helm chart to install
|
|
Consul so that it joins an existing Consul server cluster.
|
|
|
|
The `global.enabled` value first disables all chart components by default
|
|
so that each component is opt-in.
|
|
|
|
Next, configure `externalServers` to point it to Consul servers.
|
|
The `externalServers.hosts` value must be provided and should be set to a DNS, an IP,
|
|
or an `exec=` string with a command returning Consul IPs. Please see [this documentation](https://github.com/hashicorp/go-netaddrs)
|
|
on how the `exec=` string works.
|
|
Other values in the `externalServers` section are optional. Please refer to
|
|
[Helm Chart configuration](/consul/docs/k8s/helm#h-externalservers) for more details.
|
|
|
|
<CodeBlockConfig filename="values.yaml">
|
|
|
|
```yaml
|
|
global:
|
|
enabled: false
|
|
|
|
externalServers:
|
|
hosts: [<consul server DNS, IP or exec= string>]
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
With the introduction of [Consul Dataplane](/consul/docs/connect/dataplane#what-is-consul-dataplane), Consul installation on Kubernetes is simplified by removing the Consul Client agents.
|
|
This requires the Helm installation and rest of the consul-k8s components installed on Kubernetes to talk to Consul Servers directly on various ports.
|
|
Before starting the installation, ensure that the Consul Servers are configured to have the gRPC port enabled `8502/tcp` using the [`ports.grpc = 8502`](/consul/docs/agent/config/config-files#grpc) configuration option.
|
|
|
|
|
|
## Configuring TLS
|
|
|
|
-> **Note:** Consul on Kubernetes currently does not support external servers that require mutual authentication
|
|
for the HTTPS clients of the Consul servers, that is when servers have either
|
|
`tls.defaults.verify_incoming` or `tls.https.verify_incoming` set to `true`.
|
|
As noted in the [Security Model](/consul/docs/security#secure-configuration),
|
|
that setting isn't strictly necessary to support Consul's threat model as it is recommended that
|
|
all requests contain a valid ACL token.
|
|
|
|
If the Consul server has TLS enabled, you need to provide the CA certificate so that Consul on Kubernetes can communicate with the server. Save the certificate in a Kubernetes secret and then provide it in your Helm values, as demonstrated in the following example:
|
|
|
|
<CodeBlockConfig filename="values.yaml" highlight="2-8">
|
|
|
|
```yaml
|
|
global:
|
|
tls:
|
|
enabled: true
|
|
caCert:
|
|
secretName: <CA certificate secret name>
|
|
secretKey: <CA Certificate secret key>
|
|
externalServers:
|
|
enabled: true
|
|
hosts: [<consul server DNS, IP or exec= string>]
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
If your HTTPS port is different from Consul's default `8501`, you must also set
|
|
`externalServers.httpsPort`. If the Consul servers are not running TLS enabled, use this config to set the HTTP port the servers are configured with (default `8500`).
|
|
|
|
## Configuring ACLs
|
|
|
|
If you are running external servers with ACLs enabled, there are a couple of ways to configure the Helm chart
|
|
to help initialize ACL tokens for Consul clients and consul-k8s components for you.
|
|
|
|
### Manually Bootstrapping ACLs
|
|
|
|
If you would like to call the [ACL bootstrapping API](/consul/api-docs/acl#bootstrap-acls) yourself or if your cluster has already been bootstrapped with ACLs,
|
|
you can provide the bootstrap token to the Helm chart. The Helm chart will then use this token to configure ACLs
|
|
for Consul clients and any consul-k8s components you are enabling.
|
|
|
|
First, create a Kubernetes secret containing your bootstrap token:
|
|
|
|
```shell
|
|
kubectl create secret generic bootstrap-token --from-literal='token=<your bootstrap token>'
|
|
```
|
|
|
|
Then provide that secret to the Helm chart:
|
|
|
|
<CodeBlockConfig filename="values.yaml" highlight="4-6">
|
|
|
|
```yaml
|
|
global:
|
|
acls:
|
|
manageSystemACLs: true
|
|
bootstrapToken:
|
|
secretName: bootstrap-token
|
|
secretKey: token
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
The bootstrap token requires the following minimal permissions:
|
|
|
|
- `acl:write`
|
|
- `operator:write` if enabling Consul namespaces
|
|
- `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 service mesh](/consul/docs/k8s/connect),
|
|
`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](/consul/docs/security/acl/auth-methods/kubernetes)
|
|
with `consul login`.
|
|
|
|
-> **Note:** If `externalServers.k8sAuthMethodHost` is set and you are also using WAN federation
|
|
(`global.federation.enabled` is set to `true`), ensure that `global.federation.k8sAuthMethodHost` is set to the same
|
|
value as `externalServers.k8sAuthMethodHost`.
|
|
|
|
<CodeBlockConfig filename="values.yaml">
|
|
|
|
```yaml
|
|
externalServers:
|
|
enabled: true
|
|
hosts: [<consul server DNS, IP or exec= string>]
|
|
k8sAuthMethodHost: 'https://kubernetes.example.com:443'
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
Your resulting Helm configuration will end up looking similar to this:
|
|
|
|
<CodeBlockConfig filename="values.yaml">
|
|
|
|
```yaml
|
|
global:
|
|
enabled: false
|
|
acls:
|
|
manageSystemACLs: true
|
|
bootstrapToken:
|
|
secretName: bootstrap-token
|
|
secretKey: token
|
|
externalServers:
|
|
enabled: true
|
|
hosts: [<consul server DNS, IP or exec= string>]
|
|
k8sAuthMethodHost: 'https://kubernetes.example.com:443'
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
### Bootstrapping ACLs via the Helm chart
|
|
|
|
If you would like the Helm chart to call the bootstrapping API and set the server tokens for you, then the steps are similar.
|
|
The only difference is that you don't need to set the bootstrap token. The Helm chart will save the bootstrap token as a Kubernetes secret.
|
|
|
|
<CodeBlockConfig filename="values.yaml">
|
|
|
|
```yaml
|
|
global:
|
|
enabled: false
|
|
acls:
|
|
manageSystemACLs: true
|
|
externalServers:
|
|
enabled: true
|
|
hosts: [<consul server DNS, IP or exec= string>]
|
|
k8sAuthMethodHost: 'https://kubernetes.example.com:443'
|
|
```
|
|
|
|
</CodeBlockConfig>
|