Skip to content

Commit 7d035e0

Browse files
pneedle-rhpneedle-rh
authored
Merge pull request openshift#51026 from pneedle-rh/osdocs-1594-add-pod-identity-webhook-content-rosa
OSDOCS-1594 - Adding pod identity webhook content for ROSA
2 parents 748f256 + 7d6dff7 commit 7d035e0

10 files changed

+609
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

+7
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,13 @@ Topics:
254254
- Name: Managing security context constraints
255255
File: managing-security-context-constraints
256256
---
257+
Name: Authentication and authorization
258+
Dir: authentication
259+
Distros: openshift-rosa
260+
Topics:
261+
- Name: Assuming an AWS IAM role for a service account
262+
File: assuming-an-aws-iam-role-for-a-service-account
263+
---
257264
Name: Upgrading
258265
Dir: upgrading
259266
Distros: openshift-rosa

‎authentication/assuming-an-aws-iam-role-for-a-service-account.adoc

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:_content-type: ASSEMBLY
2+
[id="assuming-an-aws-iam-role-for-a-service-account"]
3+
= Assuming an AWS IAM role for a service account
4+
include::_attributes/common-attributes.adoc[]
5+
ifdef::openshift-rosa,openshift-dedicated[]
6+
include::_attributes/attributes-openshift-dedicated.adoc[]
7+
endif::openshift-rosa,openshift-dedicated[]
8+
:context: assuming-an-aws-iam-role-for-a-service-account
9+
10+
toc::[]
11+
12+
[role="_abstract"]
13+
ifdef::openshift-rosa[]
14+
{product-title} clusters that use the AWS Security Token Service (STS) include a pod identity webhook for use with pods that run in user-defined projects.
15+
endif::openshift-rosa[]
16+
17+
You can use the pod identity webhook to enable a service account to automatically assume an AWS Identity and Access Management (IAM) role in your own pods. If the assumed IAM role has the required AWS permissions, the pods can run AWS SDK operations by using temporary STS credentials.
18+
19+
include::modules/understanding-pod-identity-webhook-workflow-in-user-defined-projects.adoc[leveloffset=+1]
20+
include::modules/assuming-an-aws-iam-role-in-your-own-pods.adoc[leveloffset=+1]
21+
include::modules/setting-up-an-aws-iam-role-a-service-account.adoc[leveloffset=+2]
22+
include::modules/creating-a-service-account-in-your-project.adoc[leveloffset=+2]
23+
include::modules/creating-an-example-aws-sdk-container-image.adoc[leveloffset=+2]
24+
include::modules/deploying-a-pod-that-includes-an-aws-sdk.adoc[leveloffset=+2]
25+
include::modules/verifying-the-assumed-iam-role-in-your-pod.adoc[leveloffset=+2]
26+
27+
[role="_additional-resources"]
28+
[id="additional-resources_configuring-alert-notifications"]
29+
== Additional resources
30+
31+
* For more information about using AWS IAM roles with service accounts, see link:https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html[IAM roles for service accounts] in the AWS documentation.
32+
33+
* For information about AWS IAM role delegation, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html[Creating a role to delegate permissions to an AWS service] in the AWS documentation.
34+
35+
* For details about AWS SDKs, see link:https://docs.aws.amazon.com/sdkref/latest/guide/overview.html[AWS SDKs and Tools Reference Guide] in the AWS documentation.
36+
37+
* For more information about installing and using the AWS Boto3 SDK for Python, see the link:https://boto3.amazonaws.com/v1/documentation/api/latest/index.html[AWS Boto3 documentation].
38+
39+
ifdef::openshift-rosa,openshift-dedicated[]
40+
* For general information about webhook admission plug-ins for OpenShift, see link:https://docs.openshift.com/container-platform/4.11/architecture/admission-plug-ins.html#admission-webhooks-about_admission-plug-ins[Webhook admission plug-ins] in the OpenShift Container Platform documentation.
41+
endif::openshift-rosa,openshift-dedicated[]

‎images/pod-identity-webhook-workflow-in-user-defined-projects.png

180 KB
Loading

‎modules/assuming-an-aws-iam-role-in-your-own-pods.adoc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="assuming-an-aws-iam-role-in-your-own-pods_{context}"]
7+
= Assuming an AWS IAM role in your own pods
8+
9+
Follow the procedures in this section to enable a service account to assume an AWS Identity and Access Management (IAM) role in a pod deployed in a user-defined project.
10+
11+
You can create the required resources, including an AWS IAM role, a service account, a container image that includes an AWS SDK, and a pod deployed by using the image. In the example, the AWS Boto3 SDK for Python is used. You can also verify that the pod identity webhook mutates the AWS environment variables, the volume mount, and the token volume into your pod. Additionally, you can check that the service account assumes the AWS IAM role in your pod and can successfully run AWS SDK operations.

‎modules/creating-a-service-account-in-your-project.adoc

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="creating-a-service-account-in-your-project_{context}"]
7+
= Creating a service account in your project
8+
9+
Add a service account in your user-defined project. Include an `eks.amazonaws.com/role-arn` annotation in the service account configuration that references the Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role that you want the service account to assume.
10+
11+
.Prerequisites
12+
13+
* You have created an AWS IAM role for your service account. For more information, see _Setting up an AWS IAM role for a service account_.
14+
* You have access to a {product-title} with AWS Security Token Service (STS) cluster. Admin-level user privileges are not required.
15+
* You have installed the OpenShift CLI (`oc`).
16+
17+
.Procedure
18+
19+
. In your {product-title} cluster, create a project:
20+
+
21+
[source,terminal]
22+
----
23+
$ oc new-project <project_name> <1>
24+
----
25+
<1> Replace `<project_name>` with the name of your project. The name must match the project name that you specified in your AWS IAM role configuration.
26+
+
27+
[NOTE]
28+
====
29+
You are automatically switched to the project when it is created.
30+
====
31+
32+
. Create a file named `test-service-account.yaml` with the following service account configuration:
33+
+
34+
[source,yaml]
35+
----
36+
apiVersion: v1
37+
kind: ServiceAccount
38+
metadata:
39+
name: <service_account_name> <1>
40+
namespace: <project_name> <2>
41+
annotations:
42+
eks.amazonaws.com/role-arn: "<aws_iam_role_arn>" <3>
43+
----
44+
// Add these annotations in the preceding code block later:
45+
// eks.amazonaws.com/sts-regional-endpoints: "true" <4>
46+
// eks.amazonaws.com/token-expiration: "86400" <5>
47+
<1> Replace `<service_account_name>` with the name of your service account. The name must match the service account name that you specified in your AWS IAM role configuration.
48+
<2> Replace `<project_name>` with the name of your project. The name must match the project name that you specified in your AWS IAM role configuration.
49+
<3> Specifies the ARN of the AWS IAM role that the service account assumes for use within your pod. Replace `<aws_iam_role_arn>` with the ARN for the AWS IAM role that you created for your service account. The format of the role ARN is `arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name>`.
50+
// Add these call outs when the additional annotations are added later:
51+
//<4> Optional: When set to `true`, the `AWS_STS_REGIONAL_ENDPOINTS=regional` environment variable is defined in the pod and AWS STS requests are sent to endpoints for the active region. When this option is not set to `true`, the AWS STS requests are by default sent to the global endpoint \https://sts.amazonaws.com. For more information, see link:https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html[AWS STS Regionalized endpoints] in the AWS documentation.
52+
//<5> Optional: Specifies the token expiration time in seconds. The default is `86400`.
53+
54+
. Create the service account in your project:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc create -f test-service-account.yaml
59+
----
60+
+
61+
.Example output:
62+
[source,terminal]
63+
----
64+
serviceaccount/<service_account_name> created
65+
----
66+
67+
. Review the details of the service account:
68+
+
69+
[source,terminal]
70+
----
71+
$ oc describe serviceaccount <service_account_name> <1>
72+
----
73+
<1> Replace `<service_account_name>` with the name of your service account.
74+
+
75+
.Example output:
76+
+
77+
[source,terminal]
78+
----
79+
Name: <service_account_name> <1>
80+
Namespace: <project_name> <2>
81+
Labels: <none>
82+
Annotations: eks.amazonaws.com/role-arn: <aws_iam_role_arn> <3>
83+
Image pull secrets: <service_account_name>-dockercfg-rnjkq
84+
Mountable secrets: <service_account_name>-dockercfg-rnjkq
85+
Tokens: <service_account_name>-token-4gbjp
86+
Events: <none>
87+
----
88+
// Add these annotations in the preceding code block later:
89+
// eks.amazonaws.com/sts-regional-endpoints: true <3>
90+
// eks.amazonaws.com/token-expiration: 86400 <3>
91+
<1> Specifies the name of the service account.
92+
<2> Specifies the project that contains the service account.
93+
<3> Lists the annotation for the ARN of the AWS IAM role that the service account assumes.
94+
// Update the preceding call out to the following when the additional annotations are added later:
95+
//<3> Lists the annotations for the ARN of the AWS IAM role that the service account assumes, the optional regional endpoint configuration, and the optional token expiration specification.

‎modules/creating-an-example-aws-sdk-container-image.adoc

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="creating-an-example-aws-sdk-container-image_{context}"]
7+
= Creating an example AWS SDK container image
8+
9+
The steps in this procedure provide an example method to create a container image that includes an AWS SDK.
10+
11+
The example steps use Podman to create the container image and Quay.io to host the image. For more information about Quay.io, see link:https://docs.quay.io/solution/getting-started.html[Getting Started with Quay.io]. The container image can be used to deploy pods that can run AWS SDK operations.
12+
13+
[NOTE]
14+
====
15+
In this example procedure, the AWS Boto3 SDK for Python is installed into a container image. For more information about installing and using the AWS Boto3 SDK, see the link:https://boto3.amazonaws.com/v1/documentation/api/latest/index.html[AWS Boto3 documentation]. For details about other AWS SDKs, see link:https://docs.aws.amazon.com/sdkref/latest/guide/overview.html[AWS SDKs and Tools Reference Guide] in the AWS documentation.
16+
====
17+
18+
.Prerequisites
19+
20+
* You have installed Podman on your installation host.
21+
* You have a Quay.io user account.
22+
23+
.Procedure
24+
25+
. Add the following configuration to a file named `Containerfile`:
26+
+
27+
[source,terminal]
28+
----
29+
FROM ubi9/ubi <1>
30+
RUN dnf makecache && dnf install -y python3-pip && dnf clean all && pip3 install boto3>=1.15.0 <2>
31+
----
32+
<1> Specifies the Red Hat Universal Base Image version 9.
33+
<2> Installs the AWS Boto3 SDK by using the `pip` package management system. In this example, AWS Boto3 SDK version 1.15.0 or later is installed.
34+
35+
. From the directory that contains the file, build a container image named `awsboto3sdk`:
36+
+
37+
[source,terminal]
38+
----
39+
$ podman build -t awsboto3sdk .
40+
----
41+
42+
. Log in to Quay.io:
43+
+
44+
[source,terminal]
45+
----
46+
$ podman login quay.io
47+
----
48+
49+
. Tag the image in preparation for the upload to Quay.io:
50+
+
51+
[source,terminal]
52+
----
53+
$ podman tag localhost/awsboto3sdk quay.io/<quay_username>/awsboto3sdk:latest <1>
54+
----
55+
<1> Replace `<quay_username>` with your Quay.io username.
56+
57+
. Push the tagged container image to Quay.io:
58+
+
59+
[source,terminal]
60+
----
61+
$ podman push quay.io/<quay_username>/awsboto3sdk:latest <1>
62+
----
63+
<1> Replace `<quay_username>` with your Quay.io username.
64+
65+
. Make the Quay.io repository that contains the image public. This publishes the image so that it can be used to deploy a pod in your {product-title} cluster:
66+
.. On https://quay.io/, navigate to the *Repository Settings* page for repository that contains the image.
67+
.. Click *Make Public* to make the repository publicly available.

‎modules/deploying-a-pod-that-includes-an-aws-sdk.adoc

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="deploying-a-pod-that-includes-an-aws-sdk_{context}"]
7+
= Deploying a pod that includes an AWS SDK
8+
9+
Deploy a pod in a user-defined project from a container image that includes an AWS SDK. In your pod configuration, specify the service account that includes the `eks.amazonaws.com/role-arn` annotation.
10+
11+
With the service account reference in place for your pod, the pod identity webhook injects the AWS environment variables, the volume mount, and the token volume into your pod. The pod mutation enables the service account to automatically assume the AWS IAM role in the pod.
12+
13+
.Prerequisites
14+
15+
* You have created an AWS Identity and Access Management (IAM) role for your service account. For more information, see _Setting up an AWS IAM role for a service account_.
16+
* You have access to a {product-title} cluster that uses the AWS Security Token Service (STS). Admin-level user privileges are not required.
17+
* You have installed the OpenShift CLI (`oc`).
18+
* You have created a service account in your project that includes an `eks.amazonaws.com/role-arn` annotation that references the Amazon Resource Name (ARN) for the IAM role that you want the service account to assume.
19+
* You have a container image that includes an AWS SDK and the image is available to your cluster. For detailed steps, see _Creating an example AWS SDK container image_.
20+
+
21+
[NOTE]
22+
====
23+
In this example procedure, the AWS Boto3 SDK for Python is used. For more information about installing and using the AWS Boto3 SDK, see the link:https://boto3.amazonaws.com/v1/documentation/api/latest/index.html[AWS Boto3 documentation]. For details about other AWS SDKs, see link:https://docs.aws.amazon.com/sdkref/latest/guide/overview.html[AWS SDKs and Tools Reference Guide] in the AWS documentation.
24+
====
25+
26+
.Procedure
27+
28+
. Create a file named `awsboto3sdk-pod.yaml` with the following pod configuration:
29+
+
30+
[source,yaml]
31+
----
32+
apiVersion: v1
33+
kind: Pod
34+
metadata:
35+
namespace: <project_name> <1>
36+
name: awsboto3sdk <2>
37+
spec:
38+
serviceAccountName: <service_account_name> <3>
39+
containers:
40+
- name: awsboto3sdk
41+
image: quay.io/<quay_username>/awsboto3sdk:latest <4>
42+
command:
43+
- /bin/bash
44+
- "-c"
45+
- "sleep 100000" <5>
46+
terminationGracePeriodSeconds: 0
47+
restartPolicy: Never
48+
----
49+
<1> Replace `<project_name>` with the name of your project. The name must match the project name that you specified in your AWS IAM role configuration.
50+
<2> Specifies the name of the pod.
51+
<3> Replace `<service_account_name>` with the name of the service account that is configured to assume the AWS IAM role. The name must match the service account name that you specified in your AWS IAM role configuration.
52+
<4> Specifies the location of your `awsboto3sdk` container image. Replace `<quay_username>` with your Quay.io username.
53+
<5> In this example pod configuration, this line keeps the pod running for 100000 seconds to enable verification testing in the pod directly. For detailed verification steps, see _Verifying the assumed IAM role in your pod_.
54+
55+
. Deploy an `awsboto3sdk` pod:
56+
+
57+
[source,terminal]
58+
----
59+
$ oc create -f awsboto3sdk-pod.yaml
60+
----
61+
+
62+
.Example output:
63+
+
64+
[source,terminal]
65+
----
66+
pod/awsboto3sdk created
67+
----

‎modules/setting-up-an-aws-iam-role-a-service-account.adoc

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="setting-up-an-aws-iam-role-a-service-account_{context}"]
7+
= Setting up an AWS IAM role for a service account
8+
9+
Create an AWS Identity and Access Management (IAM) role to be assumed by a service account in your {product-title} cluster. Attach the permissions that are required by your service account to run AWS SDK operations in a pod.
10+
11+
.Prerequisites
12+
13+
* You have the permissions required to install and configure IAM roles in your AWS account.
14+
* You have access to a {product-title} cluster that uses the AWS Security Token Service (STS). Admin-level user privileges are not required.
15+
* You have the Amazon Resource Name (ARN) for the OpenID Connect (OIDC) provider that is configured as the service account issuer in your {product-title} with STS cluster.
16+
+
17+
[NOTE]
18+
====
19+
In {product-title} with STS clusters, the OIDC provider is created during install and set as the service account issuer by default. If you do not know the OIDC provider ARN, contact your cluster administrator.
20+
====
21+
* You have installed the AWS CLI (`aws`).
22+
23+
.Procedure
24+
25+
. Create a file named `trust-policy.json` with the following JSON configuration:
26+
+
27+
--
28+
[source,json]
29+
----
30+
{
31+
"Version": "2012-10-17",
32+
"Statement": [
33+
{
34+
"Effect": "Allow",
35+
"Principal": {
36+
"Federated": "<oidc_provider_arn>" <1>
37+
},
38+
"Action": "sts:AssumeRoleWithWebIdentity",
39+
"Condition": {
40+
"StringEquals": {
41+
"<oidc_provider_name>:sub": "system:serviceaccount:<project_name>:<service_account_name>" <2>
42+
}
43+
}
44+
}
45+
]
46+
}
47+
----
48+
<1> Replace `<oidc_provider_arn>` with the ARN of your OIDC provider, for example `arn:aws:iam::<aws_account_id>:oidc-provider/rh-oidc.s3.us-east-1.amazonaws.com/1v3r0n44npxu4g58so46aeohduomfres`.
49+
<2> Limits the role to the specified project and service account. Replace `<oidc_provider_name>` with the name of your OIDC provider, for example `rh-oidc.s3.us-east-1.amazonaws.com/1v3r0n44npxu4g58so46aeohduomfres`. Replace `<project_name>:<service_account_name>` with your project name and service account name, for example `my-project:test-service-account`.
50+
+
51+
[NOTE]
52+
====
53+
Alternatively, you can limit the role to any service account within the specified project by using `"<oidc_provider_name>:sub": "system:serviceaccount:<project_name>:*"`. If you supply the `*` wildcard, you must replace `StringEquals` with `StringLike` in the preceding line.
54+
====
55+
--
56+
57+
. Create an AWS IAM role that uses the trust policy that is defined in the `trust-policy.json` file:
58+
+
59+
[source,terminal]
60+
----
61+
$ aws iam create-role \
62+
--role-name <aws_iam_role_name> \ <1>
63+
--assume-role-policy-document file://trust-policy.json <2>
64+
----
65+
<1> Replace `<aws_iam_role_name>` with the name of your IAM role, for example `pod-identity-test-role`.
66+
<2> References the `trust-policy.json` file that you created in the preceding step.
67+
+
68+
.Example output:
69+
[source,terminal]
70+
----
71+
ROLE arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name> 2022-09-28T12:03:17+00:00 / AQWMS3TB4Z2N3SH7675JK <aws_iam_role_name>
72+
ASSUMEROLEPOLICYDOCUMENT 2012-10-17
73+
STATEMENT sts:AssumeRoleWithWebIdentity Allow
74+
STRINGEQUALS system:serviceaccount:<project_name>:<service_account_name>
75+
PRINCIPAL <oidc_provider_arn>
76+
----
77+
+
78+
Retain the ARN for the role in the output. The format of the role ARN is `arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name>`.
79+
80+
. Attach any managed AWS permissions that are required when the service account runs AWS SDK operations in your pod:
81+
+
82+
[source,terminal]
83+
----
84+
$ aws iam attach-role-policy \
85+
--policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess \ <1>
86+
--role-name <aws_iam_role_name> <2>
87+
----
88+
<1> The policy in this example adds read-only access permissions to the IAM role.
89+
<2> Replace `<aws_iam_role_name>` with the name of the IAM role that you created in the preceding step.
90+
91+
. Optional: Add custom attributes or a permissions boundary to the role. For more information, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html[Creating a role to delegate permissions to an AWS service] in the AWS documentation.

0 commit comments

Comments
 (0)