github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update k8s fed docs to clarify role of acl token (#10233)

release/1.10.0-beta3
Luke Kysow 2021-05-13 10:20:12 -07:00 committed by hc-github-team-consul-core
parent 1fe17b720a
commit 832560b610
1 changed files with 111 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx
View File

@ -20,70 +20,81 @@ must be the [primary](/docs/k8s/installation/multi-cluster/kubernetes#primary-da
If your primary datacenter is running on Kubernetes, use the Helm config from the If your primary datacenter is running on Kubernetes, use the Helm config from the
[Primary Datacenter](/docs/k8s/installation/multi-cluster/kubernetes#primary-datacenter) section to install Consul. [Primary Datacenter](/docs/k8s/installation/multi-cluster/kubernetes#primary-datacenter) section to install Consul.
Once installed, and with the `ProxyDefaults` [resource created](/docs/k8s/installation/multi-cluster/kubernetes#proxydefaults), Once installed on Kubernetes, and with the `ProxyDefaults` [resource created](/docs/k8s/installation/multi-cluster/kubernetes#proxydefaults),
you'll need to export the following information from the primary Kubernetes cluster: you'll need to export the following information from the primary Kubernetes cluster:
* The certificate authority cert: - Certificate authority cert and key (in order to create SSL certs for VMs)
- External addresses of Kubernetes mesh gateways
- Replication ACL token
- Gossip encryption key
```sh The following sections detail how to export this data.
kubectl get secrets/consul-ca-cert --template='{{index .data "tls.crt" }}' |
base64 -D > consul-agent-ca.pem
```
* The certificate authority signing key: ### Certificates
```sh 1. Retrieve the certificate authority cert:
kubectl get secrets/consul-ca-key --template='{{index .data "tls.key" }}' |
base64 -D > consul-agent-ca-key.pem
```
With the `consul-agent-ca.pem` and `consul-agent-ca-key.pem` files you can ```sh
create certificates for your servers and clients running on VMs that share the kubectl get secrets/consul-ca-cert --template='{{index .data "tls.crt" }}' |
same certificate authority as your Kubernetes servers. base64 -D > consul-agent-ca.pem
```
You can use the `consul tls` commands to generate those certificates: 1. And the certificate authority signing key:
```sh ```sh
# NOTE: consul-agent-ca.pem and consul-agent-ca-key.pem must be in the current kubectl get secrets/consul-ca-key --template='{{index .data "tls.key" }}' |
# directory. base64 -D > consul-agent-ca-key.pem
$ consul tls cert create -server -dc=vm-dc -node <node_name> ```
==> WARNING: Server Certificates grants authority to become a
server and access all state in the cluster including root keys
and all ACL tokens. Do not distribute them to production hosts
that are not server nodes. Store them as securely as CA keys.
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved vm-dc-server-consul-0.pem
==> Saved vm-dc-server-consul-0-key.pem
```
-> Note the `-node` option in the above command. This should be same as the node name of the [Consul Agent](https://www.consul.io/docs/agent#running-an-agent). This is a [requirement](https://www.consul.io/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways#tls) for Consul Federation to work. Alternatively, if you plan to use the same certificate and key pair on all your Consul server nodes, or you don't know the nodename in advance, use `-node "*"` instead. 1. With the `consul-agent-ca.pem` and `consul-agent-ca-key.pem` files you can
Not satisfying this requirement would result in the following error in the Consul Server logs: create certificates for your servers and clients running on VMs that share the
`[ERROR] agent.server.rpc: TLS handshake failed: conn=from= error="remote error: tls: bad certificate"` same certificate authority as your Kubernetes servers.
See the help for output of `consul tls cert create -h` to see more options You can use the `consul tls` commands to generate those certificates:
for generating server certificates.
These certificates can be used in your server config file: ```sh
# NOTE: consul-agent-ca.pem and consul-agent-ca-key.pem must be in the current
# directory.
$ consul tls cert create -server -dc=vm-dc -node <node_name>
==> WARNING: Server Certificates grants authority to become a
server and access all state in the cluster including root keys
and all ACL tokens. Do not distribute them to production hosts
that are not server nodes. Store them as securely as CA keys.
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved vm-dc-server-consul-0.pem
==> Saved vm-dc-server-consul-0-key.pem
```
```hcl -> Note the `-node` option in the above command. This should be same as the node name of the [Consul Agent](https://www.consul.io/docs/agent#running-an-agent). This is a [requirement](https://www.consul.io/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways#tls) for Consul Federation to work. Alternatively, if you plan to use the same certificate and key pair on all your Consul server nodes, or you don't know the nodename in advance, use `-node "*"` instead.
# server.hcl Not satisfying this requirement would result in the following error in the Consul Server logs:
cert_file = "vm-dc-server-consul-0.pem" `[ERROR] agent.server.rpc: TLS handshake failed: conn=from= error="remote error: tls: bad certificate"`
key_file = "vm-dc-server-consul-0-key.pem"
ca_file = "consul-agent-ca.pem"
```
For clients, you can generate TLS certs with: See the help for output of `consul tls cert create -h` to see more options
for generating server certificates.
```shell-session 1. These certificates can be used in your server config file:
$ consul tls cert create -client
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved dc1-client-consul-0.pem
==> Saved dc1-client-consul-0-key.pem
```
Or use the [auto_encrypt](/docs/agent/options#auto_encrypt) feature. ```hcl
# server.hcl
cert_file = "vm-dc-server-consul-0.pem"
key_file = "vm-dc-server-consul-0-key.pem"
ca_file = "consul-agent-ca.pem"
```
1. The WAN addresses of the mesh gateways: 1. For clients, you can generate TLS certs with:
```shell-session
$ consul tls cert create -client
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved dc1-client-consul-0.pem
==> Saved dc1-client-consul-0-key.pem
```
Or use the [auto_encrypt](/docs/agent/options#auto_encrypt) feature.
### Mesh Gateway Addresses
Retrieve the WAN addresses of the mesh gateways:
```shell-session ```shell-session
$ kubectl exec statefulset/consul-server -- sh -c \ $ kubectl exec statefulset/consul-server -- sh -c \
@ -108,7 +119,9 @@ setting:
primary_gateways = ["1.2.3.4:443"] primary_gateways = ["1.2.3.4:443"]
``` ```
1. If ACLs are enabled, you'll also need the replication ACL token: ### Replication ACL Token
If ACLs are enabled, you'll also need the replication ACL token:
```shell-session ```shell-session
$ kubectl get secrets/consul-acl-replication-acl-token --template='{{.data.token}}' $ kubectl get secrets/consul-acl-replication-acl-token --template='{{.data.token}}'
@ -116,25 +129,31 @@ e7924dd1-dc3f-f644-da54-81a73ba0a178
``` ```
This token will be used in the server config for the replication token. This token will be used in the server config for the replication token.
You must also create your own agent policy and token.
```hcl ```hcl
acls { acls {
tokens { tokens {
agent = "<your agent token>"
replication = "e7924dd1-dc3f-f644-da54-81a73ba0a178" replication = "e7924dd1-dc3f-f644-da54-81a73ba0a178"
} }
} }
``` ```
1. If gossip encryption is enabled, you'll need the key as well. The command -> **NOTE:** You'll also need to set up additional ACL tokens as needed by the
to retrieve the key will depend on which Kubernetes secret you've stored it in. ACL system. See tutorial [Secure Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#apply-individual-tokens-to-agents)
for more information.
This key will be used in server and client configs for the `encrypt` setting: ### Gossip Encryption Key
```hcl If gossip encryption is enabled, you'll need the key as well. The command
encrypt = "uF+GsbI66cuWU21kiXLze5JLEX5j4iDFlDTb0ZWNpDI=" to retrieve the key will depend on which Kubernetes secret you've stored it in.
```
This key will be used in server and client configs for the `encrypt` setting:
```hcl
encrypt = "uF+GsbI66cuWU21kiXLze5JLEX5j4iDFlDTb0ZWNpDI="
```
### Final Configuration
A final example server config file might look like: A final example server config file might look like:
@ -192,41 +211,41 @@ You'll need:
be routable from the Kubernetes cluster. be routable from the Kubernetes cluster.
1. If ACLs are enabled you must create an ACL replication token with the following rules: 1. If ACLs are enabled you must create an ACL replication token with the following rules:
```hcl ```hcl
acl = "write" acl = "write"
operator = "write" operator = "write"
agent_prefix "" { agent_prefix "" {
policy = "read" policy = "read"
} }
node_prefix "" { node_prefix "" {
policy = "write" policy = "write"
} }
service_prefix "" { service_prefix "" {
policy = "read" policy = "read"
intentions = "read" intentions = "read"
} }
``` ```
This token is used for ACL replication and for automatic ACL management in Kubernetes. This token is used for ACL replication and for automatic ACL management in Kubernetes.
If you're running Consul Enterprise you'll need the rules: If you're running Consul Enterprise you'll need the rules:
```hcl ```hcl
acl = "write" acl = "write"
operator = "write" operator = "write"
agent_prefix "" { agent_prefix "" {
policy = "read" policy = "read"
} }
node_prefix "" { node_prefix "" {
policy = "write" policy = "write"
} }
namespace_prefix "" { namespace_prefix "" {
service_prefix "" { service_prefix "" {
policy = "read" policy = "read"
intentions = "read" intentions = "read"
} }
} }
``` ```
1. If gossip encryption is enabled, you'll need the key. 1. If gossip encryption is enabled, you'll need the key.
@ -293,11 +312,11 @@ gateways running on VMs.
With your config file ready to go, follow our [Installation Guide](/docs/k8s/installation/install) With your config file ready to go, follow our [Installation Guide](/docs/k8s/installation/install)
to install Consul on your secondary cluster(s). to install Consul on your secondary cluster(s).
## Next Steps
After installation, if you're using consul-helm 0.30.0+, [create the After installation, if you're using consul-helm 0.30.0+, [create the
`ProxyDefaults` resource](/docs/k8s/installation/multi-cluster/kubernetes#proxydefaults) `ProxyDefaults` resource](/docs/k8s/installation/multi-cluster/kubernetes#proxydefaults)
to allow traffic between datacenters. to allow traffic between datacenters.
Follow the [Verifying Federation](/docs/k8s/installation/multi-cluster/kubernetes#verifying-federation) ## Next Steps
In both cases (Kubernetes as primary or secondary), after installation, follow the [Verifying Federation](/docs/k8s/installation/multi-cluster/kubernetes#verifying-federation)
section to verify that federation is working as expected. section to verify that federation is working as expected.