Bug 1824840, Document manual creation of IAM for AWS

_topic_map.yml

@@ -127,6 +127,8 @@ Topics:
   Topics:
   - Name: Configuring an AWS account
     File: installing-aws-account
+  - Name: Manually creating IAM
+    File: manually-creating-iam
   - Name: Installing a cluster quickly on AWS
     File: installing-aws-default
   - Name: Installing a cluster on AWS with customizations
@@ -148,6 +150,8 @@ Topics:
   Topics:
   - Name: Configuring an Azure account
     File: installing-azure-account
+  - Name: Manually creating IAM
+    File: manually-creating-iam-azure
   - Name: Installing a cluster quickly on Azure
     File: installing-azure-default
   - Name: Installing a cluster on Azure with customizations
@@ -167,6 +171,8 @@ Topics:
   Topics:
   - Name: Configuring a GCP project
     File: installing-gcp-account
+  - Name: Manually creating IAM
+    File: manually-creating-iam-gcp
   - Name: Installing a cluster quickly on GCP
     File: installing-gcp-default
   - Name: Installing a cluster on GCP with customizations

installing/installing_aws/installing-aws-customizations.adoc

@@ -31,6 +31,11 @@ program.
 ====
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_aws/installing-aws-default.adoc

@@ -29,6 +29,11 @@ program.
 ====
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_aws/installing-aws-network-customizations.adoc

@@ -36,7 +36,11 @@ program.
 ====
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
-
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 // TODO
 // Concept that describes networking
 

installing/installing_aws/installing-aws-private.adoc

@@ -29,6 +29,11 @@ program.
 ====
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/private-clusters-default.adoc[leveloffset=+1]
 

installing/installing_aws/installing-aws-user-infra.adoc

@@ -42,6 +42,11 @@ xref:../../installing/install_config/configuring-firewall.adoc#configuring-firew
 ====
 Be sure to also review this site list if you are configuring a proxy.
 ====
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_aws/installing-aws-vpc.adoc

@@ -29,6 +29,11 @@ program.
 ====
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
 

installing/installing_aws/installing-restricted-networks-aws.adoc

@@ -57,6 +57,11 @@ xref:../../installing/install_config/configuring-firewall.adoc#configuring-firew
 ====
 Be sure to also review this site list if you are configuring a proxy.
 ====
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/installation-about-restricted-network.adoc[leveloffset=+1]
 

installing/installing_aws/manually-creating-iam.adoc

@@ -0,0 +1,16 @@
+[id="manually-creating-iam-aws"]
+= Manually creating IAM for AWS
+include::modules/common-attributes.adoc[]
+:context: manually-creating-iam-aws
+
+toc::[]
+
+include::modules/manually-create-identity-access-management.adoc[leveloffset=+1]
+
+include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1]
+
+include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1]
+
+include::modules/mint-mode.adoc[leveloffset=+1]
+
+include::modules/mint-mode-with-removal-of-admin-credential.adoc[leveloffset=+1]

installing/installing_azure/installing-azure-customizations.adoc

@@ -18,6 +18,11 @@ processes.
 * xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_azure/installing-azure-default.adoc

@@ -16,6 +16,11 @@ processes.
 * xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_azure/installing-azure-network-customizations.adoc

@@ -23,6 +23,11 @@ processes.
 * xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_azure/installing-azure-private.adoc

@@ -15,6 +15,11 @@ processes.
 * xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/private-clusters-default.adoc[leveloffset=+1]
 

installing/installing_azure/installing-azure-user-infra.adoc

@@ -28,6 +28,11 @@ version `2.2.0` of the Azure CLI. Azure CLI commands might perform differently
 based on the version you use.
 * If you use a firewall and plan to use telemetry, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 +
 [NOTE]
 ====

installing/installing_azure/installing-azure-vnet.adoc

@@ -15,6 +15,11 @@ processes.
 * xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/installation-about-custom-azure-vnet.adoc[leveloffset=+1]
 

installing/installing_azure/manually-creating-iam-azure.adoc

@@ -0,0 +1,14 @@
+[id="manually-creating-iam-azure"]
+= Manually creating IAM for Azure
+include::modules/common-attributes.adoc[]
+:context: manually-creating-iam-azure
+
+toc::[]
+
+include::modules/manually-create-identity-access-management.adoc[leveloffset=+1]
+
+include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1]
+
+include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1]
+
+include::modules/mint-mode.adoc[leveloffset=+1]

installing/installing_gcp/installing-gcp-customizations.adoc

@@ -19,6 +19,11 @@ processes.
 to host the cluster.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_gcp/installing-gcp-default.adoc

@@ -18,6 +18,11 @@ processes.
 to host the cluster.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_gcp/installing-gcp-network-customizations.adoc

@@ -26,6 +26,11 @@ processes.
 to host the cluster.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_gcp/installing-gcp-private.adoc

@@ -17,6 +17,11 @@ processes.
 to host the cluster.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/private-clusters-default.adoc[leveloffset=+1]
 

installing/installing_gcp/installing-gcp-user-infra-vpc.adoc

@@ -21,6 +21,11 @@ xref:../../architecture/architecture-installation.adoc#architecture-installation
 processes.
 * If you use a firewall and plan to use telemetry, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 +
 [NOTE]
 ====

installing/installing_gcp/installing-gcp-user-infra.adoc

@@ -21,6 +21,11 @@ xref:../../architecture/architecture-installation.adoc#architecture-installation
 processes.
 * If you use a firewall and plan to use telemetry, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 +
 [NOTE]
 ====

installing/installing_gcp/installing-gcp-vpc.adoc

@@ -17,6 +17,11 @@ processes.
 to host the cluster.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to.
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

installing/installing_gcp/installing-restricted-networks-gcp.adoc

@@ -35,7 +35,11 @@ xref:../../architecture/architecture-installation.adoc#architecture-installation
 processes.
 * If you use a firewall, you must
 xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. While you might need to grant access to more sites, you must grant access to `*.googleapis.com` and `accounts.google.com`.
-
+* If you do not allow the system to manage identity and access management (IAM),
+then a cluster administrator can can
+xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually
+create and maintain IAM credentials]. Manual mode can also be used in
+environments where the cloud IAM APIs are not reachable.
 
 [id="installation-restricted-networks-gcp-user-infra-config-project"]
 == Configuring your GCP project

installing/installing_gcp/manually-creating-iam-gcp.adoc

@@ -0,0 +1,14 @@
+[id="manually-creating-iam-gcp"]
+= Manually creating IAM for GCP
+include::modules/common-attributes.adoc[]
+:context: manually-creating-iam-gcp
+
+toc::[]
+
+include::modules/manually-create-identity-access-management.adoc[leveloffset=+1]
+
+include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1]
+
+include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1]
+
+include::modules/mint-mode.adoc[leveloffset=+1]

modules/admin-credentials-root-secret-formats.adoc

@@ -0,0 +1,102 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/manually-creating-iam.adoc
+
+ifeval::["{context}" == "manually-creating-iam-aws"]
+:aws:
+endif::[]
+ifeval::["{context}" == "manually-creating-iam-azure"]
+:azure:
+endif::[]
+ifeval::["{context}" == "manually-creating-iam-gcp"]
+:google-cloud-platform:
+endif::[]
+
+[id="admin-credentials-root-secret-formats_{context}"]
+= Admin credentials root secret format
+
+Each cloud provider uses a credentials root secret in the `kube-system`
+namespace by convention, which is then used to satisfy all `CredentialsRequests`
+and create their respective secrets. This is done either by minting new
+credentials, _Mint Mode_, or by copying the credentials root secret,
+_Passthrough Mode_.
+
+The format for the secret varies by cloud, and is also used for each
+`CredentialsRequest` secret.
+
+ifdef::aws[]
+
+.Amazon Web Services (AWS) secret format
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  namespace: kube-system
+  name: aws-creds
+stringData:
+  aws_access_key_id: <AccessKeyID>
+  aws_secret_access_key: <SecretAccessKey>
+----
+
+endif::aws[]
+
+ifdef::azure[]
+
+.Microsoft Azure secret format
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  namespace: kube-system
+  name: azure-credentials
+stringData:
+  azure_subscription_id: <SubscriptionID>
+  azure_client_id: <ClientID>
+  azure_client_secret: <ClientSecret>
+  azure_tenant_id: <TenantID>
+  azure_resource_prefix: <ResourcePrefix>
+  azure_resourcegroup: <ResourceGroup>
+  azure_region: <Region>
+----
+
+On Microsoft Azure, the credentials secret format includes two properties that must
+contain the cluster's infrastructure ID, generated randomly for each cluster
+installation. This value can be found after running create manifests:
+
+----
+$ cat .openshift_install_state.json | jq '."*installconfig.ClusterID".InfraID' -r
+----
+
+.Example output
+----
+mycluster-2mpcn
+----
+
+This value would be used in the secret data as follows:
+
+[source,yaml]
+----
+azure_resource_prefix: mycluster-2mpcn
+azure_resourcegroup: mycluster-2mpcn-rg
+----
+endif::azure[]
+
+ifdef::google-cloud-platform[]
+
+.Google Cloud Platform (GCP) secret format
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  namespace: kube-system
+  name: gcp-credentials
+stringData:
+  service_account.json: <ServiceAccount>
+----
+endif::google-cloud-platform[]

modules/manually-create-identity-access-management.adoc

@@ -0,0 +1,181 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/manually-creating-iam.adoc
+// * installing/installing_azure/manually-creating-iam-azure.adoc
+// * installing/installing_gcp/manually-creating-iam-gcp.adoc
+
+ifeval::["{context}" == "manually-creating-iam-aws"]
+:aws:
+endif::[]
+ifeval::["{context}" == "manually-creating-iam-azure"]
+:azure:
+endif::[]
+ifeval::["{context}" == "manually-creating-iam-gcp"]
+:google-cloud-platform:
+endif::[]
+
+[id="manually-create-iam_{context}"]
+== Manually create IAM
+
+The Cloud Credential Operator can be put into manual mode prior to installation
+in environments where the cloud identity and access management (IAM) APIs are
+not reachable, or the administrator prefers not to store an administrator-level
+credential secret in the cluster `kube-system` namespace.
+
+.Procedure
+
+. Run the {product-title} installer to generate manifests:
++
+----
+$ openshift-install create manifests --dir=mycluster
+----
+
+. Insert a ConfigMap into the manifests directory so that the Cloud Credential
+Operator is placed in manual mode:
++
+----
+$ cat <<EOF > mycluster/manifests/cco-configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cloud-credential-operator-config
+  namespace: openshift-cloud-credential-operator
+  annotations:
+    release.openshift.io/create-only: "true"
+data:
+  disabled: "true"
+EOF
+----
+
+. Remove the `admin` credential secret created using your local cloud credentials.
+This removal prevents your `admin` credential from being stored in the cluster:
++
+----
+$ rm mycluster/openshift/99_cloud-creds-secret.yaml
+----
+
+. Obtain the {product-title} release image your `openshift-install` binary is built
+to use:
++
+----
+$ bin/openshift-install version
+----
++
+.Example output
+----
+release image quay.io/openshift-release-dev/ocp-release:4.z.z-x86_64
+----
+
+. Locate all `CredentialsRequests` in this release image that target the cloud you
+are deploying on:
++
+----
+$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4.z.z-x86_64 --to ./release-image
+----
+
+. Locate the `CredentialsRequests` in the extracted file:
++
+----
+$ grep -l "apiVersion: cloudcredential.openshift.io" * | xargs cat
+----
++
+[NOTE]
+====
+In a future {product-title} release, there will be a new `oc adm release`
+command to scan for the `CredentialsRequests` and display them.
+====
++
+This displays the details for each request. Remember to ignore any
+`CredentialsRequests` where the `spec.providerSpec.kind` does not match the cloud
+provider you are installing to.
++
+ifdef::aws[]
+.Sample CredentialsRequest
+[source,yaml]
+----
+apiVersion: cloudcredential.openshift.io/v1
+kind: CredentialsRequest
+metadata:
+  name: cloud-credential-operator-iam-ro
+  namespace: openshift-cloud-credential-operator
+spec:
+  secretRef:
+    name: cloud-credential-operator-iam-ro-creds
+    namespace: openshift-cloud-credential-operator
+  providerSpec:
+    apiVersion: cloudcredential.openshift.io/v1
+    kind: AWSProviderSpec
+    statementEntries:
+    - effect: Allow
+      action:
+      - iam:GetUser
+      - iam:GetUserPolicy
+      - iam:ListAccessKeys
+      resource: "*"
+----
+endif::aws[]
+ifdef::azure[]
+.Sample CredentialsRequest
+[source,yaml]
+----
+apiVersion: cloudcredential.openshift.io/v1
+kind: CredentialsRequest
+metadata:
+  labels:
+    controller-tools.k8s.io: "1.0"
+  name: openshift-image-registry-azure
+  namespace: openshift-cloud-credential-operator
+spec:
+  secretRef:
+    name: installer-cloud-credentials
+    namespace: openshift-image-registry
+  providerSpec:
+    apiVersion: cloudcredential.openshift.io/v1
+    kind: AzureProviderSpec
+    roleBindings:
+    - role: Contributor
+----
+endif::azure[]
+ifdef::google-cloud-platform[]
+.Sample CredentialsRequest
+[source,yaml]
+----
+apiVersion: cloudcredential.openshift.io/v1
+kind: CredentialsRequest
+metadata:
+  labels:
+    controller-tools.k8s.io: "1.0"
+  name: openshift-image-registry-gcs
+  namespace: openshift-cloud-credential-operator
+spec:
+  secretRef:
+    name: installer-cloud-credentials
+    namespace: openshift-image-registry
+  providerSpec:
+    apiVersion: cloudcredential.openshift.io/v1
+    kind: GCPProviderSpec
+    predefinedRoles:
+    - roles/storage.admin
+    - roles/iam.serviceAccountUser
+    skipServiceCheck: true
+----
+endif::google-cloud-platform[]
+
+. Create YAML files for secrets in the `openshift-install` manifests directory
+that you generated previously. The secrets must be stored using the namespace
+and secret name defined in each `request.spec.secretRef`. The format for the
+secret data varies for each cloud provider.
+
+. Proceed with cluster creation:
++
+----
+$ openshift-install create cluster --dir=mycluster
+----
++
+[IMPORTANT]
+====
+Before performing an upgrade, you might need to adjust your credentials if
+permissions have changed in the next release. In the future, the Cloud
+Credential Operator might prevent you from upgrading until you have indicated
+that you have addressed updated permissions.
+====

modules/manually-maintained-credentials-upgrade.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/manually-creating-iam.adoc
+// * installing/installing_azure/manually-creating-iam-azure.adoc
+// * installing/installing_gcp/manually-creating-iam-gcp.adoc
+
+[id="manually-maintained-credentials-upgrade_{context}"]
+== Upgrades
+
+In a future release, improvements to the Cloud Credential Operator will prevent
+situations where a user might enter an upgrade that will fail because their
+manually maintained credentials have not been updated to match the
+`CredentialsRequests` in the upcoming release image.

modules/mint-mode-with-removal-of-admin-credential.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/manually-creating-iam.adoc
+
+[id="mint-mode-with-removal-or-rotation-of-admin-credential_{context}"]
+= Mint Mode with removal or rotation of the admin credential
+
+Currently, this mode is only supported on AWS.
+
+In this mode, a user installs {product-title} with an `admin` credential just
+like the normal mint mode. However, this mode removes the `admin` credential
+secret from the cluster post-installation.
+
+The administrator can have the Cloud Credential Operator make its own request
+for a read-only credential that allows it to verify if all `CredentialsRequests`
+have their required permissions, thus the `admin` credential is not required
+unless something needs to be changed. After the associated credential is
+removed, it can be destroyed on the underlying cloud, if desired.
+
+Prior to upgrade, the `admin` credential should be restored. In the future,
+upgrade might be blocked if the credential is not present.
+
+The `admin` credential is not stored in the cluster permanently.
+
+This mode still requires the `admin` credential in the cluster for brief periods
+of time. It also requires manually re-instating the secret with `admin`
+credentials for each upgrade.

modules/mint-mode.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/manually-creating-iam.adoc
+// * installing/installing_azure/manually-creating-iam-azure.adoc
+// * installing/installing_gcp/manually-creating-iam-gcp.adoc
+
+[id="mint-mode_{context}"]
+= Mint Mode
+
+Mint Mode is supported for AWS, GCP, and Azure.
+
+The default and recommended best practice for running {product-title} is to run
+the installer with an administrator-level cloud credential. The `admin` credential is
+stored in the `kube-system` namespace, and then used by the Cloud Credential
+Operator to process the `CredentialRequests` in the cluster and create new users
+for each with specific permissions.
+
+The benefits of Mint Mode include:
+
+* Each cluster component only has the permissions it requires.
+* Automatic, on-going reconciliation for cloud credentials including upgrades,
+which might require additional credentials or permissions.
+
+One drawback is that Mint Mode requires `admin` credential storage in a cluster
+`kube-system` secret.