Add token auth via CCO for Operator authors (AWS STS)

Author: adellape

_topic_maps/_topic_map.yml

@@ -1850,6 +1850,8 @@ Topics:
     File: osdk-working-bundle-images
   - Name: Complying with pod security admission
     File: osdk-complying-with-psa
+  - Name: Token authentication for Operators on cloud providers
+    File: osdk-token-auth
   - Name: Validating Operators using the scorecard
     File: osdk-scorecard
   - Name: Validating Operator bundles

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

@@ -53,11 +53,9 @@ include::modules/cco-short-term-creds-component-permissions-aws.adoc[leveloffset
 //OLM-managed Operator support for authentication with AWS STS
 include::modules/cco-short-term-creds-aws-olm.adoc[leveloffset=+2]
 
-////
 [role="_additional-resources"]
 .Additional resources
-* xr\ef:../../operators/operator_sdk/osdk-token-auth.html#osdk-aws-sts_osdk-token-auth[CCO-based workflow for OLM-managed Operators with AWS STS]
-////
+* 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]
 
 [id="cco-short-term-creds-gcp_{context}"]
 == GCP Workload Identity

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

@@ -153,11 +153,27 @@ spec:
 <6> The `env` parameter defines a list of Environment Variables that must exist in all containers in the pod created by OLM.
 <7> The `envFrom` parameter defines a list of sources to populate Environment Variables in the container.
 <8> The `volumes` parameter defines a list of Volumes that must exist on the pod created by OLM.
-<9> The `volumeMounts` parameter defines a list of VolumeMounts that must exist in all containers in the pod created by OLM. If a `volumeMount` references a `volume` that does not exist, OLM fails to deploy the Operator.
+<9> The `volumeMounts` parameter defines a list of volume mounts that must exist in all containers in the pod created by OLM. If a `volumeMount` references a `volume` that does not exist, OLM fails to deploy the Operator.
 <10> The `tolerations` parameter defines a list of Tolerations for the pod created by OLM.
 <11> The `resources` parameter defines resource constraints for all the containers in the pod created by OLM.
 <12> The `nodeSelector` parameter defines a `NodeSelector` for the pod created by OLM.
 
+. If the cluster is in STS mode, include the following fields in the `Subscription` object:
++
+[source,yaml]
+----
+kind: Subscription
+# ...
+spec:
+  installPlanApproval: Manual <1>
+  config:
+    env:
+    - name: ROLEARN
+      value: "<role_arn>" <2>
+----
+<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.
+<2> Include the role ARN details.
+
 . Create the `Subscription` object:
 +
 [source,terminal]

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

@@ -78,9 +78,18 @@ ifdef::olm-user[]
 .. 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.
 endif::[]
 
-.. Select an *Update channel* (if more than one is available).
+.. If the cluster is in STS mode, add the role ARN in the *role ARN* field.
+
+.. If more than one update channel is available, select an *Update channel*.
 
 .. Select *Automatic* or *Manual* approval strategy, as described earlier.
++
+[IMPORTANT]
+====
+If the web console shows that the cluster is in "STS mode", you must set *Update approval* to *Manual*.
+
+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.
+====
 
 . Click *Install* to make the Operator available to the selected namespaces on this {product-title} cluster.
 

modules/osdk-cco-aws-sts-alt.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/osdk-token-auth.adoc
+
+:_content-type: CONCEPT
+[id="osdk-cco-aws-sts-alt_{context}"]
+= Alternative method
+
+As an alternative method for Operator authors, you can indicate that the user is responsible for creating the `CredentialsRequest` object for the Cloud Credential Operator (CCO) before installing the Operator.
+
+The Operator instructions must indicate the following to users:
+
+* Provide a YAML version of a `CredentialsRequest` object, either by providing the YAML inline in the instructions or pointing users to a download location
+* Instruct the user to create the `CredentialsRequest` object
+
+In {product-title} 4.14 and later, after the `CredentialsRequest` object appears on the cluster with the appropriate STS information added, the Operator can then read the CCO-generated `Secret` or mount it, having defined the mount in the cluster service version (CSV).
+
+For earlier versions of {product-title}, the Operator instructions must also indicate the following to users:
+
+* Use the CCO utility (`ccoctl`) to generate the `Secret` YAML object from the `CredentialsRequest` object
+* Apply the `Secret` object to the cluster in the appropriate namespace
+
+The Operator still must be able to consume the resulting secret to communicate with cloud APIs. Because in this case the secret is created by the user before the Operator is installed, the Operator can do either of the following:
+
+* Define an explicit mount in the `Deployment` object within the CSV
+* Programmatically read the `Secret` object from the API server, as shown in the recommended "Enabling Operators to support CCO-based workflows with AWS STS" method