open-consul/website/content/docs/security/acl/auth-methods/kubernetes.mdx
Jeff Boruszak 3c30b64220
Apply suggestions from code review
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Luke Kysow <1034429+lkysow@users.noreply.github.com>
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
2022-10-11 09:34:17 -05:00

159 lines
6.5 KiB
Plaintext

---
layout: docs
page_title: Kubernetes Auth Method
description: >-
Use the Kubernetes auth method type to authenticate to Consul with a Kubernetes service account token and receive an ACL token with privileges based on JWT identity attributes. Learn how to configure auth method parameters using this reference page and example configuration.
---
# Kubernetes Auth Method
-> **1.5.0+:** This feature is available in Consul versions 1.5.0 and newer.
The `kubernetes` auth method type allows for a Kubernetes service account token
to be used to authenticate to Consul. This method of authentication makes it
easy to introduce a Consul token into a Kubernetes pod.
This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and
the concepts described in the main [auth method
documentation](/docs/security/acl/auth-methods).
## Config Parameters
The following auth method [`Config`](/api-docs/acl/auth-methods#config)
parameters are required to properly configure an auth method of type
`kubernetes`:
- `Host` `(string: <required>)` - Must be a host string, a host:port pair, or a
URL to the base of the Kubernetes API server.
- `CACert` `(string: <required>)` - PEM encoded CA cert for use by the TLS
client used to talk with the Kubernetes API. NOTE: Every line must end with a
newline (`\n`). If not set, system certificates are used.
- `ServiceAccountJWT` `(string: <required>)` - A Service Account Token
([JWT](https://jwt.io/ 'JSON Web Token')) used by the Consul leader to
validate application JWTs during login.
- `MapNamespaces` `(bool: <false>)` <EnterpriseAlert inline /> -
**Deprecated in Consul 1.8.0 in favor of [namespace rules](/api-docs/acl/auth-methods#namespacerules).**
Indicates whether the auth method should attempt to map the Kubernetes namespace to a Consul
namespace instead of creating tokens in the auth methods own namespace. Note
that mapping namespaces requires the auth method to reside within the
`default` namespace.
Deprecated in Consul 1.8.0 in favor of [namespace rules](/api-docs/acl/auth-methods#namespacerules).
- `ConsulNamespacePrefix` `(string: <optional>)` <EnterpriseAlert inline /> -
**Deprecated in Consul 1.8.0 in favor of [namespace rules](/api-docs/acl/auth-methods#namespacerules).**
When `MapNamespaces` is enabled, this value will be prefixed to the Kubernetes
namespace to determine the Consul namespace to create the new token within.
Deprecated in Consul 1.8.0 in favor of [namespace rules](/api-docs/acl/auth-methods#namespacerules).
- `ConsulNamespaceOverrides` `(map: <string:string>)` <EnterpriseAlert inline /> -
**Deprecated in Consul 1.8.0 in favor of [namespace rules](/api-docs/acl/auth-methods#namespacerules).**
This field is a mapping of Kubernetes namespace names to Consul namespace
names. If a Kubernetes namespace is present within this map, the value will
be used without adding the `ConsulNamespacePrefix`. If the value in the map
is `""` then the auth methods namespace will be used instead of attempting
to determine an alternate namespace.
Deprecated in Consul 1.8.0 in favor of [namespace rules](/api-docs/acl/auth-methods#namespacerules).
### Sample Config
```json
{
...other fields...
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}
}
```
## RBAC
The Kubernetes service account corresponding to the configured
[`ServiceAccountJWT`](/docs/security/acl/auth-methods/kubernetes#serviceaccountjwt)
needs to have access to two Kubernetes APIs:
- [**TokenReview**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#create-tokenreview-v1-authentication-k8s-io)
-> Kubernetes should be running with `--service-account-lookup`. This is
defaulted to true in Kubernetes 1.7, but any versions prior should ensure
the Kubernetes API server is started with this setting.
- [**ServiceAccount**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#read-serviceaccount-v1-core)
(`get`)
The following is an example
[RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
configuration snippet to grant the necessary permissions to a service account
named `consul-auth-method-example`:
```yaml
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: review-tokens
namespace: default
subjects:
- kind: ServiceAccount
name: consul-auth-method-example
namespace: default
roleRef:
kind: ClusterRole
name: system:auth-delegator
apiGroup: rbac.authorization.k8s.io
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: service-account-getter
namespace: default
rules:
- apiGroups: ['']
resources: ['serviceaccounts']
verbs: ['get']
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: get-service-accounts
namespace: default
subjects:
- kind: ServiceAccount
name: consul-auth-method-example
namespace: default
roleRef:
kind: ClusterRole
name: service-account-getter
apiGroup: rbac.authorization.k8s.io
```
## Kubernetes Authentication Details
Initially the
[`ServiceAccountJWT`](/docs/security/acl/auth-methods/kubernetes#serviceaccountjwt)
given to the Consul leader uses the TokenReview API to validate the provided
JWT. The trusted attributes of `serviceaccount.namespace`,
`serviceaccount.name`, and `serviceaccount.uid` are populated directly from the
Service Account metadata.
The Consul leader makes an additional query, this time to the ServiceAccount
API to check for the existence of an annotation of
`consul.hashicorp.com/service-name` on the ServiceAccount object. If one is
found its value will override the trusted attribute of `serviceaccount.name`
for the purposes of evaluating any binding rules.
## Trusted Identity Attributes
The authentication step returns the following trusted identity attributes for
use in binding rule selectors and bind name interpolation.
| Attributes | Supported Selector Operations | Can be Interpolated |
| -------------------------- | -------------------------------------------------- | ------------------- |
| `serviceaccount.namespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |
| `serviceaccount.name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |
| `serviceaccount.uid` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |