1---
2layout: docs
3page_title: Kubernetes Auth Method
4description: >-
5  The Kubernetes auth method type allows for a Kubernetes service account token
6  to be used to authenticate to Consul. This method of authentication makes it
7  easy to introduce a Consul token into a Kubernetes pod.
8---
9
10# Kubernetes Auth Method
11
12-> **1.5.0+:** This feature is available in Consul versions 1.5.0 and newer.
13
14The `kubernetes` auth method type allows for a Kubernetes service account token
15to be used to authenticate to Consul. This method of authentication makes it
16easy to introduce a Consul token into a Kubernetes pod.
17
18This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and
19the concepts described in the main [auth method
20documentation](/docs/acl/auth-methods).
21
22## Config Parameters
23
24The following auth method [`Config`](/api/acl/auth-methods#config)
25parameters are required to properly configure an auth method of type
26`kubernetes`:
27
28- `Host` `(string: <required>)` - Must be a host string, a host:port pair, or a
29  URL to the base of the Kubernetes API server.
30
31- `CACert` `(string: <required>)` - PEM encoded CA cert for use by the TLS
32  client used to talk with the Kubernetes API. NOTE: Every line must end with a
33  newline (`\n`). If not set, system certificates are used.
34
35- `ServiceAccountJWT` `(string: <required>)` - A Service Account Token
36  ([JWT](https://jwt.io/ 'JSON Web Token')) used by the Consul leader to
37  validate application JWTs during login.
38
39- `MapNamespaces` `(bool: <false>)` <EnterpriseAlert inline /> -
40  **Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).**
41  Indicates whether the auth method should attempt to map the Kubernetes namespace to a Consul
42  namespace instead of creating tokens in the auth methods own namespace. Note
43  that mapping namespaces requires the auth method to reside within the
44  `default` namespace.
45  Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).
46
47- `ConsulNamespacePrefix` `(string: <optional>)` <EnterpriseAlert inline /> -
48  **Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).**
49  When `MapNamespaces` is enabled, this value will be prefixed to the Kubernetes
50  namespace to determine the Consul namespace to create the new token within.
51  Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).
52
53- `ConsulNamespaceOverrides` `(map: <string:string>)` <EnterpriseAlert inline /> -
54  **Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).**
55  This field is a mapping of Kubernetes namespace names to Consul namespace
56  names. If a Kubernetes namespace is present within this map, the value will
57  be used without adding the `ConsulNamespacePrefix`. If the value in the map
58  is `""` then the auth methods namespace will be used instead of attempting
59  to determine an alternate namespace.
60  Deprecated in Consul 1.8.0 in favor of [namespace rules](/api/acl/auth-methods#namespacerules).
61
62### Sample Config
63
64```json
65{
66    ...other fields...
67    "Config": {
68        "Host": "https://192.0.2.42:8443",
69        "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
70        "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
71    }
72}
73```
74
75## RBAC
76
77The Kubernetes service account corresponding to the configured
78[`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes#serviceaccountjwt)
79needs to have access to two Kubernetes APIs:
80
81- [**TokenReview**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#create-tokenreview-v1-authentication-k8s-io)
82
83  -> Kubernetes should be running with `--service-account-lookup`. This is
84  defaulted to true in Kubernetes 1.7, but any versions prior should ensure
85  the Kubernetes API server is started with this setting.
86
87- [**ServiceAccount**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#read-serviceaccount-v1-core)
88  (`get`)
89
90The following is an example
91[RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
92configuration snippet to grant the necessary permissions to a service account
93named `consul-auth-method-example`:
94
95```yaml
96---
97kind: ClusterRoleBinding
98apiVersion: rbac.authorization.k8s.io/v1
99metadata:
100  name: review-tokens
101  namespace: default
102subjects:
103  - kind: ServiceAccount
104    name: consul-auth-method-example
105    namespace: default
106roleRef:
107  kind: ClusterRole
108  name: system:auth-delegator
109  apiGroup: rbac.authorization.k8s.io
110---
111kind: ClusterRole
112apiVersion: rbac.authorization.k8s.io/v1
113metadata:
114  name: service-account-getter
115  namespace: default
116rules:
117  - apiGroups: ['']
118    resources: ['serviceaccounts']
119    verbs: ['get']
120---
121kind: ClusterRoleBinding
122apiVersion: rbac.authorization.k8s.io/v1
123metadata:
124  name: get-service-accounts
125  namespace: default
126subjects:
127  - kind: ServiceAccount
128    name: consul-auth-method-example
129    namespace: default
130roleRef:
131  kind: ClusterRole
132  name: service-account-getter
133  apiGroup: rbac.authorization.k8s.io
134```
135
136## Kubernetes Authentication Details
137
138Initially the
139[`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes#serviceaccountjwt)
140given to the Consul leader uses the TokenReview API to validate the provided
141JWT. The trusted attributes of `serviceaccount.namespace`,
142`serviceaccount.name`, and `serviceaccount.uid` are populated directly from the
143Service Account metadata.
144
145The Consul leader makes an additional query, this time to the ServiceAccount
146API to check for the existence of an annotation of
147`consul.hashicorp.com/service-name` on the ServiceAccount object. If one is
148found its value will override the trusted attribute of `serviceaccount.name`
149for the purposes of evaluating any binding rules.
150
151## Trusted Identity Attributes
152
153The authentication step returns the following trusted identity attributes for
154use in binding rule selectors and bind name interpolation.
155
156| Attributes                 | Supported Selector Operations                      | Can be Interpolated |
157| -------------------------- | -------------------------------------------------- | ------------------- |
158| `serviceaccount.namespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes                 |
159| `serviceaccount.name`      | Equal, Not Equal, In, Not In, Matches, Not Matches | yes                 |
160| `serviceaccount.uid`       | Equal, Not Equal, In, Not In, Matches, Not Matches | yes                 |
161