OSDOCS-1594 AWS IAM webhook for pod authentication

_topic_maps/_topic_map.yml

@@ -1728,6 +1728,8 @@ Topics:
     File: nodes-pods-vertical-autoscaler
   - Name: Providing sensitive data to Pods
     File: nodes-pods-secrets
+  - Name: Allowing pods to authenticate with a cloud provider
+    File: nodes-pods-authenticating-with-cloud-provider
   - Name: Creating and using config maps
     File: nodes-pods-configmaps
   - Name: Using Device Manager to make devices available to nodes

modules/creating-eks-pod-identity-webhook.adoc

@@ -0,0 +1,112 @@
+// Module included in the following assemblies:
+//
+// * nodes/pods/nodes-pods-authenticating-with-cloud-provider.adoc
+
+[id="creating-eks-pod-identity-webhook_{context}"]
+= Creating an Amazon Elastic Kubernetes Service pod identity webhook
+
+For pods that require AWS IAM access, you must create an Amazon Elastic Kubernetes Service (EKS) pod identity webhook.
+
+.Prerequisites
+
+* You have an {product-title} cluster installed on AWS.
+* You have the AWS CLI installed on your local machine.
+
+.Procedure
+
+. Create an OIDC provider in IAM for your cluster. For more information on creating an OIDC provider, see Amazon's link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html[documentation]. You can find the OIDC discovery endpoint by describing your EKS cluster with the following command:
++
+[source,terminal]
+----
+$ aws eks describe-cluster --name $CLUSTER_NAME --query cluster.identity.oidc
+----
++
+Enter `sts.amazonaws.com` as the `client-id`.
+
+. Create an IAM role for your pods and modify the trust policy to allow your pod's service account to use the role. For more information, see Amazon's link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html[documentation]. The following snippet is an example trust policy:
++
+[source,json]
+----
+{
+ "Version": "2012-10-17",
+ "Statement": [
+  {
+   "Effect": "Allow",
+   "Principal": {
+    "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.us-west-2.eks.amazonaws.com/624a142e-43fc-4a4e-9a65-0adbfe9d6a85"
+   },
+   "Action": "sts:AssumeRoleWithWebIdentity",
+   "Condition": {
+    "__doc_comment": "Scope the role to the service account (optional)",
+    "StringEquals": {
+     "oidc.us-west-2.eks.amazonaws.com/624a142e-43fc-4a4e-9a65-0adbfe9d6a85:sub": "system:serviceaccount:default:my-serviceaccount"
+    },
+    "__doc_comment": "Scope the role to a namespace (optional)",
+    "StringLike": {
+     "oidc.us-west-2.eks.amazonaws.com/624a142e-43fc-4a4e-9a65-0adbfe9d6a85:sub": "system:serviceaccount:default:*"
+    }
+   }
+  }
+ ]
+}
+----
++
+[NOTE]
+====
+When running a container with a non-root user, you must grant the container access to the token file by setting the `fsGroup` field in the `SecurityContext` object. The `fsGroup` field dictates the allowable values for the security context.
+====
+
+. Modify your pod's service account to be annotated with the Amazon Resource Name (ARN) of the role you want the pod to use.
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: my-serviceaccount
+  namespace: default
+  annotations:
+    eks.amazonaws.com/role-arn: "arn:aws:iam::111122223333:role/s3-reader" <1>
+----
+<1> The ARN of the role your pod must use.
+
+All of the new pods launched using this service account are modified to use IAM for pods.
+
+.Verification
+
+* Verify that the environment variables and volume fields you configured are added to your pod specification by the webhook. For example:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: my-pod
+  namespace: default
+spec:
+  serviceAccountName: my-serviceaccount
+  containers:
+  - name: container-name
+    image: container-image:version
+    env: <1>
+    - name: AWS_DEFAULT_REGION
+      value: us-west-2
+    - name: AWS_REGION
+      value: us-west-2
+    - name: AWS_ROLE_ARN
+      value: "arn:aws:iam::111122223333:role/s3-reader"
+    - name: AWS_WEB_IDENTITY_TOKEN_FILE
+      value: "/var/run/secrets/eks.amazonaws.com/serviceaccount/token"
+    volumeMounts:
+    - mountPath: "/var/run/secrets/eks.amazonaws.com/serviceaccount/"
+      name: aws-token
+  volumes:
+  - name: aws-token
+    projected:
+      sources:
+      - serviceAccountToken:
+          audience: "sts.amazonaws.com"
+          expirationSeconds: 86400
+          path: token
+----
+<1> All content listed below this line is auto-generated by the webhook.

modules/scheduling-windows-workloads-node-selector.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * nodes/pods/nodes-pods-authenticating-with-cloud-provider.adoc
+
+[id="scheduling-windows-workloads-node-selector_{context}"]
+= Scheduling Windows workloads with a node selector
+
+You can schedule Windows workloads on a pod by using a node selector.
+
+.Procedure
+
+* In the `Pod` object, set the node selector to target the Windows operating system:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+
+  ... 
+
+  spec:
+    nodeSelector: 
+      kubernetes.io/os: windows
+
+    ... 
+----
+
+[NOTE]
+====
+Workloads targeting `windows` nodes using `nodeAffinity` are currently not supported.
+====

nodes/pods/nodes-pods-authenticating-with-cloud-provider.adoc

@@ -0,0 +1,22 @@
+[id="nodes-pods-authenticating-with-cloud-provider"]
+= Allowing pods to authenticate with a cloud provider
+include::modules/common-attributes.adoc[]
+:context: nodes-pods-authenticating-with-cloud-provider
+
+toc::[]
+
+Pods that require authentication with a cloud provider before being integrated with {product-title} must be mutated using a pod webhook.
+
+include::modules/creating-eks-pod-identity-webhook.adoc[leveloffset=+1]
+
+[id="additional-resources_nodes-pods-authenticating-with-cloud-provider"]
+=== Additional resources
+
+* Refer to the following link:https://github.com/aws/amazon-eks-pod-identity-webhook#usage[Amazon EKS Pod Identity webhook parameters] for ways to configure the webhook to mutate your pods.
+
+[id="configuring-windows-container-workloads_{context}"]
+== Configuring Windows container workloads
+
+To ensure workloads that are scheduled on Windows nodes have the right environment variables, you must use a node selector to target Windows as the operating system.
+
+include::modules/scheduling-windows-workloads-node-selector.adoc[leveloffset=+2]