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:

yaml

authentication:
  kopeio: {}

For example:

yaml

apiVersion: kops.k8s.io/v1alpha2
kind: Cluster
metadata:
  name: cluster.example.com
spec:
  authentication:
    kopeio: {}
  authorization:
    rbac: {}

AWS IAM Authenticator

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

yaml

authentication:
  aws: {}

For example:

yaml

apiVersion: kops.k8s.io/v1alpha2
kind: Cluster
metadata:
  name: cluster.example.com
spec:
  authentication:
    aws: {}
  authorization:
    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:

yaml

---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: kube-system
  name: aws-iam-authenticator
  labels:
    k8s-app: aws-iam-authenticator
data:
  config.yaml: |
    # a unique-per-cluster identifier to prevent replay attacks
    # (good choices are a random token or a domain name that will be unique to your cluster)
    clusterID: my-dev-cluster.example.com
    server:
      # each mapRoles entry maps an IAM role to a username and set of groups
      # Each username and group can optionally contain template parameters:
      #  1) "{{AccountID}}" is the 12 digit AWS ID.
      #  2) "{{SessionName}}" is the role session name.
      mapRoles:
      # statically map arn:aws:iam::000000000000:role/KubernetesAdmin to a cluster admin
      - roleARN: arn:aws:iam::000000000000:role/KubernetesAdmin
        username: kubernetes-admin
        groups:
        - system:masters
      # map EC2 instances in my "KubernetesNode" role to users like
      # "aws:000000000000:instance:i-0123456789abcdef0". Only use this if you
      # trust that the role can only be assumed by EC2 instances. If an IAM user
      # can assume this role directly (with sts:AssumeRole) they can control
      # SessionName.
      - roleARN: arn:aws:iam::000000000000:role/KubernetesNode
        username: aws:{{AccountID}}:instance:{{SessionName}}
        groups:
        - system:bootstrappers
        - aws:instances
      # map federated users in my "KubernetesAdmin" role to users like
      # "admin:alice-example.com". The SessionName is an arbitrary role name
      # like an e-mail address passed by the identity provider. Note that if this
      # role is assumed directly by an IAM User (not via federation), the user
      # can control the SessionName.
      - roleARN: arn:aws:iam::000000000000:role/KubernetesAdmin
        username: admin:{{SessionName}}
        groups:
        - system:masters
      # each mapUsers entry maps an IAM role to a static username and set of groups
      mapUsers:
      # map user IAM user Alice in 000000000000 to user "alice" in "system:masters"
      - userARN: arn:aws:iam::000000000000:user/Alice
        username: alice
        groups:
        - 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

yaml

authentication:
  aws:
    backendMode: CRD,MountedFile
    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.

yaml

authentication:
  aws:
    backendMode: CRD
    clusterID: demo.cluster.us-west-2
    identityMappings:
    - arn: arn:aws:iam::000000000000:role/KubernetesAdmin
      username: admin:{{SessionName}}
      groups:
      - system:masters
    - arn: arn:aws:iam::000000000000:user/Alice
      username: alice
      groups:
      - 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.

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"}]'