Authentication

kOps has support for configuring authentication systems. This should not be used with kubernetes versions before 1.8.5 because of a serious bug with apimachinery #55022.

kopeio authentication

If you want to experiment with kopeio authentication, you can use --authentication kopeio. However please be aware that kopeio authentication has not yet been formally released, and thus there is not a lot of upstream documentation.

Alternatively, you can add this block to your cluster:

  1. authentication:
  2.   kopeio: {}

For example:

  1. apiVersion: kops.k8s.io/v1alpha2
  2. kind: Cluster
  3. metadata:
  4.   name: cluster.example.com
  5. spec:
  6.   authentication:
  7.     kopeio: {}
  8.   authorization:
  9.     rbac: {}

AWS IAM Authenticator

To turn on AWS IAM Authenticator, you’ll need to add the stanza bellow to your cluster configuration.

  1. authentication:
  2.   aws: {}

For example:

  1. apiVersion: kops.k8s.io/v1alpha2
  2. kind: Cluster
  3. metadata:
  4.   name: cluster.example.com
  5. spec:
  6.   authentication:
  7.     aws: {}
  8.   authorization:
  9.     rbac: {}

If no backendMode is configured, by default the aws-iam-authenticator will require the creation of an AWS IAM authenticator config as a ConfigMap. For more details on AWS IAM authenticator please visit kubernetes-sigs/aws-iam-authenticator

Example config using a ConfigMap:

  1. ---
  2. apiVersion: v1
  3. kind: ConfigMap
  4. metadata:
  5.   namespace: kube-system
  6.   name: aws-iam-authenticator
  7.   labels:
  8.     k8s-app: aws-iam-authenticator
  9. data:
  10.   config.yaml: |
  11.     # a unique-per-cluster identifier to prevent replay attacks
  12.     # (good choices are a random token or a domain name that will be unique to your cluster)
  13.     clusterID: my-dev-cluster.example.com
  14.     server:
  15.       # each mapRoles entry maps an IAM role to a username and set of groups
  16.       # Each username and group can optionally contain template parameters:
  17.       #  1) "{{ AccountID }}" is the 12 digit AWS ID.
  18.       #  2) "{{ SessionName }}" is the role session name.
  19.       mapRoles:
  20.       # statically map arn:aws:iam::000000000000:role/KubernetesAdmin to a cluster admin
  21.       - roleARN: arn:aws:iam::000000000000:role/KubernetesAdmin
  22.         username: kubernetes-admin
  23.         groups:
  24.         - system:masters
  25.       # map EC2 instances in my "KubernetesNode" role to users like
  26.       # "aws:000000000000:instance:i-0123456789abcdef0". Only use this if you
  27.       # trust that the role can only be assumed by EC2 instances. If an IAM user
  28.       # can assume this role directly (with sts:AssumeRole) they can control
  29.       # SessionName.
  30.       - roleARN: arn:aws:iam::000000000000:role/KubernetesNode
  31.         username: aws:{{ AccountID }}:instance:{{ SessionName }}
  32.         groups:
  33.         - system:bootstrappers
  34.         - aws:instances
  35.       # map federated users in my "KubernetesAdmin" role to users like
  36.       # "admin:alice-example.com". The SessionName is an arbitrary role name
  37.       # like an e-mail address passed by the identity provider. Note that if this
  38.       # role is assumed directly by an IAM User (not via federation), the user
  39.       # can control the SessionName.
  40.       - roleARN: arn:aws:iam::000000000000:role/KubernetesAdmin
  41.         username: admin:{{ SessionName }}
  42.         groups:
  43.         - system:masters
  44.       # each mapUsers entry maps an IAM role to a static username and set of groups
  45.       mapUsers:
  46.       # map user IAM user Alice in 000000000000 to user "alice" in "system:masters"
  47.       - userARN: arn:aws:iam::000000000000:user/Alice
  48.         username: alice
  49.         groups:
  50.         - system:masters

It is also possible to configure alternative backend modes for aws-iam-authenticator. The backendMode configuration option allows defining multiple backends in a comma separated string. The mappings in these backends will be merged. When the same mapping is found in multiple backends, the first backend in the list will take precedence. If MountedFile is not included in the list of backends, no configmap is required and the cluster-id will default to the cluster’s name. The cluster-id can be overridden by setting the clusterID API field. If you wish to continue using a configmap for authenticator settings other than mappings, MountedFile must be included in the backendMode list.

This requires an aws-iam-authenticator image >= 0.5.0 For more information see usergroup-mappings

  1. authentication:
  2.   aws:
  3.     backendMode: CRD,MountedFile
  4.     clusterID: demo.cluster.us-west-2

When setting the backendMode configuration to CRD, it is possible to provide a list of inline AWS IAM identity mappings in the cluster template.

  1. authentication:
  2.   aws:
  3.     backendMode: CRD
  4.     clusterID: demo.cluster.us-west-2
  5.     identityMappings:
  6.     - arn: arn:aws:iam::000000000000:role/KubernetesAdmin
  7.       username: admin:{{ SessionName }}
  8.       groups:
  9.       - system:masters
  10.     - arn: arn:aws:iam::000000000000:user/Alice
  11.       username: alice
  12.       groups:
  13.       - system:masters

Creating a new cluster with IAM Authenticator on.

  • Create a cluster following the AWS getting started guide
  • When you reach the “Customize Cluster Configuration” section of the guide modify the cluster spec and add the Authentication and Authorization configs to the YAML config.
  • Optionally set the backendMode: CRD and configure the identityMappings inline.
  • Continue following the cluster creation guide to build the cluster.
    • :warning: When no backendMode is configured (or it is set to MountedFile) and the cluster first comes up the aws-iam-authenticator PODs will be in a bad state as it is trying to find the aws-iam-authenticator ConfigMap and we have not yet created it.

If no backendMode is configured, or it is set to `MountedFile, the following additional steps are necessary:

  • Once the cluster is up, you’ll need to create an aws-iam-authenticator configMap on the cluster kubectl apply -f aws-iam-authenticator_example-config.yaml

  • Once the configuration is created you need to delete the initially created aws-iam-authenticator PODs, this will force new ones to come and correctly find the ConfigMap.

    1. kubectl get pods -n kube-system | grep aws-iam-authenticator | awk '{print $1}' | xargs kubectl delete pod -n kube-system

Turning on IAM Authenticator on an existing cluster.

  • Create an aws-iam-authenticator configMap on the cluster kubectl apply -f aws-iam-authenticator_example-config.yaml
  • Edit the clusters configuration kops edit cluster ${NAME} and add the Authentication and Authorization configs to the YAML config.
  • Update the clusters configuration kops update cluster ${CLUSTER_NAME} --yes
  • Temporarily disable aws-iam-authenticator DaemonSet kubectl patch daemonset -n kube-system aws-iam-authenticator -p '{"spec": {"template": {"spec": {"nodeSelector": {"disable-aws-iam-authenticator": "true"}}}}}'
  • Perform a rolling update of the masters kops rolling-update cluster ${CLUSTER_NAME} --instance-group-roles=Master --force --yes
  • Re-enable aws-iam-authenticator DaemonSet kubectl patch daemonset -n kube-system aws-iam-authenticator --type json -p='[{"op": "remove", "path": "/spec/template/spec/nodeSelector/disable-aws-iam-authenticator"}]'