Skip to content

Commit feceba5

Browse files
adellapeadellape
authored
Merge pull request #70222 from adellape/azure_sts
OSDOCS#8868,8869: Add Azure Identity CCO/OLM docs
2 parents e025deb + 9b6d35c commit feceba5

File tree

13 files changed

+291
-33
lines changed

13 files changed

+291
-33
lines changed

‎_attributes/common-attributes.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,7 @@ endif::[]
251251
//Azure
252252
:azure-full: Microsoft Azure
253253
:azure-short: Azure
254+
:azure-id: Azure AD Workload Identity
254255
//vSphere
255256
:vmw-full: VMware vSphere
256257
:vmw-short: vSphere

‎_topic_maps/_topic_map.yml

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1927,8 +1927,15 @@ Topics:
19271927
File: osdk-working-bundle-images
19281928
- Name: Complying with pod security admission
19291929
File: osdk-complying-with-psa
1930-
- Name: Token authentication for Operators on cloud providers
1931-
File: osdk-token-auth
1930+
- Name: Token authentication
1931+
Dir: token_auth
1932+
Topics:
1933+
- Name: Token authentication for Operators on cloud providers
1934+
File: osdk-token-auth
1935+
- Name: CCO-based workflow for OLM-managed Operators with AWS STS
1936+
File: osdk-cco-aws-sts
1937+
- Name: CCO-based workflow for OLM-managed Operators with Azure AD Workload Identity
1938+
File: osdk-cco-azure
19321939
- Name: Validating Operators using the scorecard
19331940
File: osdk-scorecard
19341941
- Name: Validating Operator bundles

‎authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ include::modules/cco-short-term-creds-aws-olm.adoc[leveloffset=+2]
5555

5656
[role="_additional-resources"]
5757
.Additional resources
58-
* xref:../../operators/operator_sdk/osdk-token-auth.adoc#osdk-cco-aws-sts_osdk-token-auth[CCO-based workflow for OLM-managed Operators with AWS STS]
58+
* xref:../../operators/operator_sdk/token_auth/osdk-cco-aws-sts.adoc#osdk-cco-aws-sts[CCO-based workflow for OLM-managed Operators with AWS STS]
5959

6060
[id="cco-short-term-creds-gcp_{context}"]
6161
== GCP Workload Identity
@@ -96,12 +96,9 @@ include::modules/cco-short-term-creds-component-permissions-azure.adoc[leveloffs
9696
//OLM-managed Operator support for authentication with Azure AD Workload Identity
9797
include::modules/cco-short-term-creds-azure-olm.adoc[leveloffset=+2]
9898

99-
////
100-
// Azure will need a link off to OLM docs like AWS when ready.
10199
[role="_additional-resources"]
102100
.Additional resources
103-
* xref:../../operators/operator_sdk/osdk-token-auth.adoc#osdk-cco-aws-sts_osdk-token-auth[CCO-based workflow for OLM-managed Operators with AWS STS]
104-
////
101+
* xref:../../operators/operator_sdk/token_auth/osdk-cco-azure.adoc#osdk-cco-azure[CCO-based workflow for OLM-managed Operators with {azure-id}]
105102

106103
[role="_additional-resources"]
107104
[id="additional-resources_{context}"]

‎modules/olm-installing-from-operatorhub-using-cli.adoc

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -158,21 +158,56 @@ spec:
158158
<11> The `resources` parameter defines resource constraints for all the containers in the pod created by OLM.
159159
<12> The `nodeSelector` parameter defines a `NodeSelector` for the pod created by OLM.
160160

161-
. If the cluster is in STS mode, include the following fields in the `Subscription` object:
161+
. For clusters on cloud providers with token authentication enabled:
162+
163+
.. Ensure the `Subscription` object is set to manual update approvals:
162164
+
163165
[source,yaml]
164166
----
165167
kind: Subscription
166168
# ...
167169
spec:
168170
installPlanApproval: Manual <1>
171+
----
172+
<1> Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update.
173+
174+
.. Include the relevant cloud provider-specific fields in the `Subscription` object's `config` section:
175+
+
176+
--
177+
* If the cluster is in AWS STS mode, include the following fields:
178+
+
179+
[source,yaml]
180+
----
181+
kind: Subscription
182+
# ...
183+
spec:
169184
config:
170185
env:
171186
- name: ROLEARN
172-
value: "<role_arn>" <2>
187+
value: "<role_arn>" <1>
173188
----
174-
<1> Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update.
175-
<2> Include the role ARN details.
189+
<1> Include the role ARN details.
190+
191+
* If the cluster is in {azure-id} mode, include the following fields:
192+
+
193+
[source,yaml]
194+
----
195+
kind: Subscription
196+
# ...
197+
spec:
198+
config:
199+
env:
200+
- name: CLIENTID
201+
value: "<client_id>" <1>
202+
- name: TENANTID
203+
value: "<tenant_id>" <2>
204+
- name: SUBSCRIPTIONID
205+
value: "<subscription_id>" <3>
206+
----
207+
<1> Include the client ID.
208+
<2> Include the tenant ID.
209+
<3> Include the subscription ID.
210+
--
176211
177212
. Create the `Subscription` object:
178213
+

‎modules/olm-installing-from-operatorhub-using-web-console.adoc

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,18 +77,25 @@ endif::[]
7777
ifdef::olm-user[]
7878
.. Choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace.
7979
endif::[]
80-
.. If the cluster is in AWS STS mode, enter the Amazon Resource Name (ARN) of the AWS IAM role of your service account in the *role ARN* field.
80+
81+
.. For clusters on cloud providers with token authentication enabled:
82+
+
83+
--
84+
* If the cluster is in AWS STS mode, enter the Amazon Resource Name (ARN) of the AWS IAM role of your service account in the *role ARN* field.
8185
+
8286
image::oadp-install-operator-role-arn.png[Entering the ARN]
8387
To create the role's ARN, follow the procedure described in link:https://access.redhat.com/documentation/en-us/red_hat_openshift_service_on_aws/4/html/tutorials/cloud-experts-deploy-api-data-protection#prepare-aws-account_cloud-experts-deploy-api-data-protection[Preparing AWS account].
8488

89+
* If the cluster is in {azure-id} mode, add the client ID, tenant ID, and subscription ID in the appropriate field.
90+
--
91+
8592
.. If more than one update channel is available, select an *Update channel*.
8693

8794
.. Select *Automatic* or *Manual* approval strategy, as described earlier.
8895
+
8996
[IMPORTANT]
9097
====
91-
If the web console shows that the cluster is in "STS mode", you must set *Update approval* to *Manual*.
98+
If the web console shows that the cluster is in AWS STS or {azure-id} mode, you must set *Update approval* to *Manual*.
9299
93100
Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update.
94101
====

‎modules/osdk-cco-azure-enabling.adoc

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/token_auth/osdk-cco-azure.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="osdk-cco-azure-enabling_{context}"]
7+
= Enabling Operators to support CCO-based workflows with {azure-id}
8+
9+
As an Operator author designing your project to run on Operator Lifecycle Manager (OLM), you can enable your Operator to authenticate against {azure-id}-enabled {product-title} clusters by customizing your project to support the Cloud Credential Operator (CCO).
10+
11+
With this method, the Operator is responsible for creating the `CredentialsRequest` object, which means the Operator requires RBAC permission to create these objects. Then, the Operator must be able to read the resulting `Secret` object.
12+
13+
[NOTE]
14+
====
15+
By default, pods related to the Operator deployment mount a `serviceAccountToken` volume so that the service account token can be referenced in the resulting `Secret` object.
16+
====
17+
18+
.Prerequisities
19+
20+
* {product-title} 4.14 or later
21+
* Cluster in {azure-id} mode
22+
* OLM-based Operator project
23+
24+
.Procedure
25+
26+
. Update your Operator project's `ClusterServiceVersion` (CSV) object:
27+
28+
.. Ensure your Operator has RBAC permission to create `CredentialsRequests` objects:
29+
+
30+
.Example `clusterPermissions` list
31+
[%collapsible]
32+
====
33+
[source,yaml]
34+
----
35+
# ...
36+
install:
37+
spec:
38+
clusterPermissions:
39+
- rules:
40+
- apiGroups:
41+
- "cloudcredential.openshift.io"
42+
resources:
43+
- credentialsrequests
44+
verbs:
45+
- create
46+
- delete
47+
- get
48+
- list
49+
- patch
50+
- update
51+
- watch
52+
----
53+
====
54+
55+
.. Add the following annotation to claim support for this method of CCO-based workflow with {azure-id}:
56+
+
57+
[source,yaml]
58+
----
59+
# ...
60+
metadata:
61+
annotations:
62+
features.operators.openshift.io/token-auth-azure: "true"
63+
----
64+
65+
. Update your Operator project code:
66+
67+
.. Get the client ID, tenant ID, and subscription ID from the environment variables set on the pod by the `Subscription` object. For example:
68+
+
69+
[source,go]
70+
----
71+
// Get ENV var
72+
clientID := os.Getenv("CLIENTID")
73+
tenantID := os.Getenv("TENANTID")
74+
subscriptionID := os.Getenv("SUBSCRIPTIONID")
75+
azureFederatedTokenFile := "/var/run/secrets/openshift/serviceaccount/token"
76+
----
77+
78+
.. Ensure you have a `CredentialsRequest` object ready to be patched and applied.
79+
+
80+
[NOTE]
81+
====
82+
Adding a `CredentialsRequest` object to the Operator bundle is not currently supported.
83+
====
84+
85+
.. Add the Azure credentials information and web identity token path to the credentials request and apply it during Operator initialization:
86+
+
87+
.Example applying `CredentialsRequest` object during Operator initialization
88+
[%collapsible]
89+
====
90+
[source,go]
91+
----
92+
// apply credentialsRequest on install
93+
credReqTemplate.Spec.AzureProviderSpec.AzureClientID = clientID
94+
credReqTemplate.Spec.AzureProviderSpec.AzureTenantID = tenantID
95+
credReqTemplate.Spec.AzureProviderSpec.AzureRegion = "centralus"
96+
credReqTemplate.Spec.AzureProviderSpec.AzureSubscriptionID = subscriptionID
97+
credReqTemplate.CloudTokenPath = azureFederatedTokenFile
98+
99+
c := mgr.GetClient()
100+
if err := c.Create(context.TODO(), credReq); err != nil {
101+
if !errors.IsAlreadyExists(err) {
102+
setupLog.Error(err, "unable to create CredRequest")
103+
os.Exit(1)
104+
}
105+
}
106+
----
107+
====
108+
109+
.. Ensure your Operator can wait for a `Secret` object to show up from the CCO, as shown in the following example, which is called along with the other items you are reconciling in your Operator:
110+
+
111+
.Example wait for `Secret` object
112+
[%collapsible]
113+
====
114+
[source,go]
115+
----
116+
// WaitForSecret is a function that takes a Kubernetes client, a namespace, and a v1 "k8s.io/api/core/v1" name as arguments
117+
// It waits until the secret object with the given name exists in the given namespace
118+
// It returns the secret object or an error if the timeout is exceeded
119+
func WaitForSecret(client kubernetes.Interface, namespace, name string) (*v1.Secret, error) {
120+
// set a timeout of 10 minutes
121+
timeout := time.After(10 * time.Minute) <1>
122+
123+
// set a polling interval of 10 seconds
124+
ticker := time.NewTicker(10 * time.Second)
125+
126+
// loop until the timeout or the secret is found
127+
for {
128+
select {
129+
case <-timeout:
130+
// timeout is exceeded, return an error
131+
return nil, fmt.Errorf("timed out waiting for secret %s in namespace %s", name, namespace)
132+
// add to this error with a pointer to instructions for following a manual path to a Secret that will work on STS
133+
case <-ticker.C:
134+
// polling interval is reached, try to get the secret
135+
secret, err := client.CoreV1().Secrets(namespace).Get(context.Background(), name, metav1.GetOptions{})
136+
if err != nil {
137+
if errors.IsNotFound(err) {
138+
// secret does not exist yet, continue waiting
139+
continue
140+
} else {
141+
// some other error occurred, return it
142+
return nil, err
143+
}
144+
} else {
145+
// secret is found, return it
146+
return secret, nil
147+
}
148+
}
149+
}
150+
}
151+
----
152+
<1> The `timeout` value is based on an estimate of how fast the CCO might detect an added `CredentialsRequest` object and generate a `Secret` object. You might consider lowering the time or creating custom feedback for cluster administrators that could be wondering why the Operator is not yet accessing the cloud resources.
153+
====
154+
155+
.. Read the secret created by the CCO from the `CredentialsRequest` object to authenticate with Azure and receive the necessary credentials.

‎operators/operator_sdk/token_auth/_attributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../_attributes/

‎operators/operator_sdk/token_auth/images

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../images

‎operators/operator_sdk/token_auth/modules

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../modules

‎modules/osdk-cco-aws-sts.adoc renamed to ‎operators/operator_sdk/token_auth/osdk-cco-aws-sts.adoc

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
// Module included in the following assemblies:
2-
//
3-
// * operators/operator_sdk/osdk-token-auth.adoc
4-
5-
:_mod-docs-content-type: CONCEPT
6-
[id="osdk-cco-aws-sts_{context}"]
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="osdk-cco-aws-sts"]
73
= CCO-based workflow for OLM-managed Operators with AWS STS
4+
include::_attributes/common-attributes.adoc[]
5+
:context: osdk-cco-aws-sts
6+
7+
toc::[]
88

99
When an {product-title} cluster running on AWS is in Security Token Service (STS) mode, it means the cluster is utilizing features of AWS and {product-title} to use IAM roles at an application level. STS enables applications to provide a JSON Web Token (JWT) that can assume an IAM role.
1010

@@ -32,3 +32,15 @@ If you plan to support {product-title} clusters earlier than version 4.14, consi
3232
3333
Your code should check for secrets that never appear and warn users to follow the fallback instructions you have provided. For more information, see the "Alternative method" subsection.
3434
====
35+
36+
[role="_additional-resources"]
37+
.Additional resources
38+
39+
* xref:../../../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds-aws-olm_cco-short-term-creds[OLM-managed Operator support for authentication with AWS STS]
40+
* xref:../../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster[Installing from OperatorHub using the web console]
41+
* xref:../../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-operator-from-operatorhub-using-cli_olm-adding-operators-to-a-cluster[Installing from OperatorHub using the CLI]
42+
43+
include::modules/osdk-cco-aws-sts-enabling.adoc[leveloffset=+1]
44+
include::modules/osdk-cco-aws-sts-role.adoc[leveloffset=+1]
45+
include::modules/osdk-cco-aws-sts-tshooting.adoc[leveloffset=+1]
46+
include::modules/osdk-cco-aws-sts-alt.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)