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