mirror of
https://github.com/status-im/consul.git
synced 2025-01-09 21:35:52 +00:00
166d7a39e8
Remove outdated usage of "Consul Connect" instead of Consul service mesh. The connect subsystem in Consul provides Consul's service mesh capabilities. However, the term "Consul Connect" should not be used as an alternative to the name "Consul service mesh".
167 lines
6.1 KiB
Plaintext
167 lines
6.1 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`.
|
|
|
|
<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>
|