diff --git a/installing/installing_aws/manually-creating-iam.adoc b/installing/installing_aws/manually-creating-iam.adoc index 90bacbb07065..b0b46028e652 100644 --- a/installing/installing_aws/manually-creating-iam.adoc +++ b/installing/installing_aws/manually-creating-iam.adoc @@ -3,6 +3,8 @@ include::modules/common-attributes.adoc[] :context: manually-creating-iam-aws +//TO-DO: this should be one file for AWS, Azure, and GCP with conditions for specifics. + toc::[] 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, you can put the Cloud Credential Operator (CCO) into manual mode before you install the cluster. @@ -11,7 +13,10 @@ include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[level .Additional resources -See xref:../../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator] for a detailed description of all available CCO credential modes and their supported platforms. +// Not supported in Azure. Condition out if combining topic for AWS/Azure/GCP. +* To learn how to rotate or remove the administrator-level credential secret after installing {product-title}, see xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials]. + +* See xref:../../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator] for a detailed description of all available CCO credential modes and their supported platforms. include::modules/manually-create-identity-access-management.adoc[leveloffset=+1] diff --git a/installing/installing_azure/manually-creating-iam-azure.adoc b/installing/installing_azure/manually-creating-iam-azure.adoc index a6253e633c86..561513252cd6 100644 --- a/installing/installing_azure/manually-creating-iam-azure.adoc +++ b/installing/installing_azure/manually-creating-iam-azure.adoc @@ -5,6 +5,14 @@ include::modules/common-attributes.adoc[] toc::[] +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, you can put the Cloud Credential Operator (CCO) into manual mode before you install the cluster. + +include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[leveloffset=+1] + +.Additional resources + +* See xref:../../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator] for a detailed description of all available CCO credential modes and their supported platforms. + include::modules/manually-create-identity-access-management.adoc[leveloffset=+1] include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1] @@ -12,3 +20,11 @@ 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] + +[id="manually-creating-iam-azure-next-steps"] +== Next steps + +* Install an {product-title} cluster: +** xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[Quickly install a cluster] with default options on installer-provisioned infrastructure +** xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[Install a cluster with cloud customizations on installer-provisioned infrastructure] +** xref:../../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-network-customizations[Install a cluster with network customizations on installer-provisioned infrastructure] diff --git a/installing/installing_gcp/manually-creating-iam-gcp.adoc b/installing/installing_gcp/manually-creating-iam-gcp.adoc index a3aaf71df32f..31ade8f36f9d 100644 --- a/installing/installing_gcp/manually-creating-iam-gcp.adoc +++ b/installing/installing_gcp/manually-creating-iam-gcp.adoc @@ -5,6 +5,16 @@ include::modules/common-attributes.adoc[] toc::[] +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, you can put the Cloud Credential Operator (CCO) into manual mode before you install the cluster. + +include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[leveloffset=+1] + +.Additional resources + +* To learn how to rotate or remove the administrator-level credential secret after installing {product-title}, see xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials]. + +* See xref:../../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator] for a detailed description of all available CCO credential modes and their supported platforms. + include::modules/manually-create-identity-access-management.adoc[leveloffset=+1] include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1] @@ -12,3 +22,13 @@ 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] + +[id="manually-creating-iam-gcp-next-steps"] +== Next steps + +* Install an {product-title} cluster: +** xref:../../installing/installing_gcp/installing-gcp-default.adoc#installing-gcp-default[Quickly install a cluster] with default options on installer-provisioned infrastructure +** xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[Install a cluster with cloud customizations on installer-provisioned infrastructure] +** xref:../../installing/installing_gcp/installing-gcp-network-customizations.adoc#installing-gcp-network-customizations[Install a cluster with network customizations on installer-provisioned infrastructure] diff --git a/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc b/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc index 69acc74ebc0f..bbba6fa7cbb8 100644 --- a/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc +++ b/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc @@ -1,14 +1,44 @@ // 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="alternatives-to-storing-admin-secrets-in-kube-system.adoc_{context}"] -= Alternatives to storing administrator-level secrets in the `kube-system` project += Alternatives to storing administrator-level secrets in the kube-system project The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). You can configure the CCO to suit the security requirements of your organization by setting different values for the `credentialsMode` parameter in the `install-config.yaml` file. -If you prefer not to store an administrator-level credential secret in the cluster `kube-system` project, you can choose one of the following options when installing {product-title} on AWS: +ifdef::aws,google-cloud-platform[] +If you prefer not to store an administrator-level credential secret in the cluster `kube-system` project, you can choose one of the following options when installing {product-title}: + +* *Manage cloud credentials manually*: ++ +You can set the `credentialsMode` parameter for the CCO to `Manual` to manage cloud credentials manually. Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. You can also use this mode if your environment does not have connectivity to the cloud provider public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. You must also manually supply credentials for every component that requests them. + +* *Remove the administrator-level credential secret after installing {product-title} with mint mode*: ++ +If you are using the CCO with the `credentialsMode` parameter set to `Mint`, you can remove or rotate the administrator-level credential after installing {product-title}. Mint mode is the default configuration for the CCO. This option requires the presence of the administrator-level credential during an installation. The administrator-level credential is used during the installation to mint other credentials with some permissions granted. The original credential secret is not stored in the cluster permanently. + +[NOTE] +==== +Prior to a non z-stream upgrade, you must reinstate the credential secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. +==== + +endif::aws,google-cloud-platform[] -* *Manage cloud credentials manually*. You can set the `credentialsMode` for the CCO to `Manual` to manage cloud credentials manually. Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. You can also use this mode if your environment does not have connectivity to the AWS public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. You must also manually supply credentials for every component that requests them. +ifdef::azure[] +If you prefer not to store an administrator-level credential secret in the cluster `kube-system` project, you can set the `credentialsMode` parameter for the CCO to `Manual` when installing {product-title} and manage your cloud credentials manually. -* *Remove the administrator-level credential secret after installing {product-title} with mint mode*. You can remove or rotate the administrator-level credential after installing {product-title} with the `Mint` CCO credentials mode applied. The `Mint` CCO credentials mode is the default. This option requires the presence of the administrator-level credential during an installation. The administrator-level credential is used during the installation to mint other credentials with some permissions granted. The original credential secret is not stored in the cluster permanently. \ No newline at end of file +Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. You can also use this mode if your environment does not have connectivity to the cloud provider public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. You must also manually supply credentials for every component that requests them. +endif::azure[] diff --git a/modules/cloud-credential-operator.adoc b/modules/cloud-credential-operator.adoc index ce233f8607ea..c9624817563a 100644 --- a/modules/cloud-credential-operator.adoc +++ b/modules/cloud-credential-operator.adoc @@ -8,41 +8,24 @@ [discrete] == Purpose -The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). The CCO syncs on `credentialsRequest` custom resources (CRs) to allow {product-title} components to request cloud provider credentials with the specific permissions that are required for the cluster to run. +The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). The CCO syncs on `CredentialsRequest` custom resources (CRs) to allow {product-title} components to request cloud provider credentials with the specific permissions that are required for the cluster to run. By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in several different modes. If no mode is specified, or the `credentialsMode` parameter is set to an empty string (`""`), the CCO operates in its default mode. -[discrete] -=== Default behavior -For platforms where multiple modes are supported (AWS, Azure, and GCP), when the CCO operates in its default mode, it checks the provided credentials dynamically to determine for which mode they are sufficient to process `credentialsRequest` CRs. - -By default, the CCO determines whether the credentials are sufficient for mint mode, which is the preferred mode of operation, and uses those credentials to create appropriate credentials for components in the cluster. If the credentials are not sufficient for mint mode, it determines whether they are sufficient for passthrough mode. If the credentials are not sufficient for passthrough mode, the CCO cannot adequately process `credentialsRequest` CRs. - -[NOTE] -==== -The CCO cannot verify whether Azure credentials are sufficient for passthrough mode. If Azure credentials are insufficient for mint mode, the CCO operates with the assumption that the credentials are sufficient for passthrough mode. -==== - -If the provided credentials are determined to be insufficient during installation, the installation fails. For AWS, the installer fails early in the process and indicates which required permissions are missing. Other providers might not provide specific information about the cause of the error until errors are encountered. - -If the credentials are changed after a successful installation and the CCO determines that the new credentials are insufficient, the CCO puts conditions on any new `credentialsRequest` CRs to indicate that it cannot process them because of the insufficient credentials. - -To resolve insufficient credentials issues, provide a credential with sufficient permissions. If an error occurred during installation, try installing again. For issues with new `credentialsRequest` CRs, wait for the CCO to try to process the CR again. As an alternative, you can manually create IAM for AWS, Azure, or GCP. For details, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. - [discrete] === Modes -By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in _mint_, _passthrough_, or _manual_ mode. These options provide transparency and flexibility in how the CCO uses cloud credentials to process `credentialsRequest` CRs in the cluster, and allow the CCO to be configured to suit the security requirements of your organization. Not all CCO modes are supported for all cloud providers. +By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in _mint_, _passthrough_, or _manual_ mode. These options provide transparency and flexibility in how the CCO uses cloud credentials to process `CredentialsRequest` CRs in the cluster, and allow the CCO to be configured to suit the security requirements of your organization. Not all CCO modes are supported for all cloud providers. [discrete] ==== Mint mode Mint mode is supported for AWS, Azure, and GCP. -Mint mode is the default and recommended best practice setting for the CCO to use. In this mode, the CCO uses the provided admin-level cloud credential to run the cluster. +Mint mode is the default and recommended best practice setting for the CCO to use on the platforms for which it is supported. In this mode, the CCO uses the provided administrator-level cloud credential to run the cluster. -If the credential is not removed after installation, it is stored and used by the CCO to process `credentialsRequest` CRs for components in the cluster and create new credentials for each with only the specific permissions that are required. The continuous reconciliation of cloud credentials in mint mode allows actions that require additional credentials or permissions, such as upgrading, to proceed. +If the credential is not removed after installation, it is stored and used by the CCO to process `CredentialsRequest` CRs for components in the cluster and create new credentials for each with only the specific permissions that are required. The continuous reconciliation of cloud credentials in mint mode allows actions that require additional credentials or permissions, such as upgrading, to proceed. -The requirement that mint mode stores the admin-level credential in the cluster `kube-system` namespace might not suit the security requirements of every organization. +The requirement that mint mode stores the administrator-level credential in the cluster `kube-system` namespace might not suit the security requirements of every organization. When using the CCO in mint mode, ensure that the credential you provide meets the requirements of the cloud on which you are running or installing {product-title}. If the provided credentials are not sufficient for mint mode, the CCO cannot create an IAM user. @@ -82,14 +65,14 @@ When using the CCO in mint mode, ensure that the credential you provide meets th |==== [discrete] -===== Mint mode with removal or rotation of the admin-level credential -Mint mode with removal or rotation of the admin-level credential is supported for AWS in {product-title} version 4.4 and later. +===== Mint mode with removal or rotation of the administrator-level credential +Mint mode with removal or rotation of the administrator-level credential is supported for AWS in {product-title} version 4.4 and later and for GCP in {product-title} version 4.7 and later. -This option requires the presence of the admin-level credential during installation, but the credential is not stored in the cluster permanently and does not need to be long-lived. +This option requires the presence of the administrator-level credential during installation, but the credential is not stored in the cluster permanently and does not need to be long-lived. -After installing {product-title} in mint mode, you can remove the admin-level credential Secret from the cluster. If you remove the Secret, the CCO uses a previously minted read-only credential that allows it to verify whether all `credentialsRequest` CRs have their required permissions. Once removed, the associated credential can be destroyed on the underlying cloud if desired. +After installing {product-title} in mint mode, you can remove the administrator-level credential Secret from the cluster. If you remove the Secret, the CCO uses a previously minted read-only credential that allows it to verify whether all `CredentialsRequest` CRs have their required permissions. Once removed, the associated credential can be destroyed on the underlying cloud if desired. -The admin-level credential is not required unless something that requires an admin-level credential needs to be changed, for instance during an upgrade. Prior to each upgrade, you must reinstate the credential Secret with the admin-level credential. If the credential is not present, the upgrade might be blocked. +The administrator-level credential is not required unless something that requires an administrator-level credential needs to be changed, for instance during an upgrade. Prior to each upgrade, you must reinstate the credential Secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. [discrete] ==== Passthrough mode @@ -99,9 +82,9 @@ In passthrough mode, the CCO passes the provided cloud credential to the compone [discrete] ===== Passthrough mode permissions requirements -When using the CCO in passthrough mode, ensure that the credential you provide meets the requirements of the cloud on which you are running or installing {product-title}. If the provided credentials the CCO passes to a component that creates a `credentialsRequest` CR are not sufficient, that component will report an error when it tries to call an API that it does not have permissions for. +When using the CCO in passthrough mode, ensure that the credential you provide meets the requirements of the cloud on which you are running or installing {product-title}. If the provided credentials the CCO passes to a component that creates a `CredentialsRequest` CR are not sufficient, that component will report an error when it tries to call an API that it does not have permissions for. -The credential you provide for passthrough mode in AWS, Azure, or GCP must have all the requested permissions for all `credentialsRequest` CRs that are required by the version of {product-title} you are running or installing. To locate the `credentialsRequest` CRs that are required for your cloud provider, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. +The credential you provide for passthrough mode in AWS, Azure, or GCP must have all the requested permissions for all `CredentialsRequest` CRs that are required by the version of {product-title} you are running or installing. To locate the `CredentialsRequest` CRs that are required for your cloud provider, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. To install an {product-title} cluster on {rh-openstack-first}, the CCO requires a credential with the permissions of a `member` user role. @@ -149,32 +132,44 @@ To install an {product-title} cluster on VMware vSphere, the CCO requires a cred [discrete] ===== Passthrough mode credential maintenance -If `credentialsRequest` CRs change over time as the cluster is upgraded, you must manually update the passthrough mode credential to meet the requirements. To avoid credentials issues during an upgrade, check the `credentialsRequest` CRs in the release image for the new version of {product-title} before upgrading. To locate the `credentialsRequest` CRs that are required for your cloud provider, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. +If `CredentialsRequest` CRs change over time as the cluster is upgraded, you must manually update the passthrough mode credential to meet the requirements. To avoid credentials issues during an upgrade, check the `CredentialsRequest` CRs in the release image for the new version of {product-title} before upgrading. To locate the `CredentialsRequest` CRs that are required for your cloud provider, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. [discrete] ===== Reducing permissions after installation When using passthrough mode, each component has the same permissions used by all other components. If you do not reduce the permissions after installing, all components have the broad permissions that are required to run the installer. -After installation, you can reduce the permissions on your credential to only those that are required to run the cluster, as defined by the `credentialsRequest` CRs in the release image for the version of {product-title} that you are using. +After installation, you can reduce the permissions on your credential to only those that are required to run the cluster, as defined by the `CredentialsRequest` CRs in the release image for the version of {product-title} that you are using. -To locate the `credentialsRequest` CRs that are required for AWS, Azure, or GCP and learn how to change the permissions the CCO uses, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. +To locate the `CredentialsRequest` CRs that are required for AWS, Azure, or GCP and learn how to change the permissions the CCO uses, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. [discrete] ==== Manual mode -Manual mode is supported for AWS. +Manual mode is supported for AWS, Azure, and GCP. +//4.7+ for Azure and GCP -In manual mode, a user manages cloud credentials instead of the CCO. To use this mode, you must examine the `credentialsRequest` CRs in the release image for the version of {product-title} that you are running or installing, create corresponding credentials in the underlying cloud provider, and create Kubernetes Secrets in the correct namespaces to satisfy all `credentialsRequest` CRs for the cluster's cloud provider. +In manual mode, a user manages cloud credentials instead of the CCO. To use this mode, you must examine the `CredentialsRequest` CRs in the release image for the version of {product-title} that you are running or installing, create corresponding credentials in the underlying cloud provider, and create Kubernetes Secrets in the correct namespaces to satisfy all `CredentialsRequest` CRs for the cluster's cloud provider. -Using manual mode allows each cluster component to have only the permissions it requires, without storing an admin-level credential in the cluster. This mode also does not require connectivity to the AWS public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. +Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. This mode also does not require connectivity to the AWS public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. //later include upgrade info from manually-maintained-credentials-upgrade -For information about configuring AWS to use manual mode, see _Manually creating IAM for AWS_. +For more information, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. [discrete] -==== Disabled CCO -Disabled CCO is supported for Azure and GCP. +=== Default behavior +For platforms where multiple modes are supported (AWS, Azure, and GCP), when the CCO operates in its default mode, it checks the provided credentials dynamically to determine for which mode they are sufficient to process `CredentialsRequest` CRs. + +By default, the CCO determines whether the credentials are sufficient for mint mode, which is the preferred mode of operation, and uses those credentials to create appropriate credentials for components in the cluster. If the credentials are not sufficient for mint mode, it determines whether they are sufficient for passthrough mode. If the credentials are not sufficient for passthrough mode, the CCO cannot adequately process `CredentialsRequest` CRs. + +[NOTE] +==== +The CCO cannot verify whether Azure credentials are sufficient for passthrough mode. If Azure credentials are insufficient for mint mode, the CCO operates with the assumption that the credentials are sufficient for passthrough mode. +==== + +If the provided credentials are determined to be insufficient during installation, the installation fails. For AWS, the installer fails early in the process and indicates which required permissions are missing. Other providers might not provide specific information about the cause of the error until errors are encountered. + +If the credentials are changed after a successful installation and the CCO determines that the new credentials are insufficient, the CCO puts conditions on any new `CredentialsRequest` CRs to indicate that it cannot process them because of the insufficient credentials. -To manually manage credentials for Azure or GCP, you must disable the CCO. Disabling the CCO has many of the same configuration and maintenance requirements as running the CCO in manual mode, but is accomplished by a different process. For more information, see the _Manually creating IAM_ section of the installation content for Azure or GCP. +To resolve insufficient credentials issues, provide a credential with sufficient permissions. If an error occurred during installation, try installing again. For issues with new `CredentialsRequest` CRs, wait for the CCO to try to process the CR again. As an alternative, you can manually create IAM for AWS, Azure, or GCP. For details, see the _Manually creating IAM_ section of the installation content for AWS, Azure, or GCP. [discrete] == Project @@ -186,7 +181,7 @@ link:https://github.com/openshift/cloud-credential-operator[openshift-cloud-cred * `credentialsrequests.cloudcredential.openshift.io` ** Scope: Namespaced -** CR: `credentialsrequest` +** CR: `CredentialsRequest` ** Validation: Yes [discrete] diff --git a/modules/manually-create-identity-access-management.adoc b/modules/manually-create-identity-access-management.adoc index 774d20c27a0d..5e3a74291df0 100644 --- a/modules/manually-create-identity-access-management.adoc +++ b/modules/manually-create-identity-access-management.adoc @@ -23,8 +23,7 @@ installation in environments where the cloud identity and access management administrator-level credential secret in the cluster `kube-system` namespace. .Procedure -ifdef::aws[] -//credentialsMode=Manual only verified supported on AWS in 4.6 GA + . Change to the directory that contains the installation program and create the `install-config.yaml` file: + [source,terminal] @@ -46,7 +45,7 @@ compute: ... ---- <1> This line is added to set the `credentialsMode` parameter to `Manual`. -endif::aws[] + . To generate the manifests, run the following command from the directory that contains the installation program: + [source,terminal] @@ -55,33 +54,6 @@ $ openshift-install create manifests --dir= <1> ---- <1> For ``, specify the directory name to store the files that the installation program creates. -ifndef::aws[] -//ConfigMap method is verified supported for Azure and GCP. This step can be removed when credentialsMode=Manual support is verified for these platforms. -. Insert a config map into the manifests directory so that the Cloud Credential -Operator is placed in manual mode: -+ -[source,terminal] ----- -$ cat < 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 ----- -endif::aws[] -. Remove the `admin` credential secret created using your local cloud credentials. -This removal prevents your `admin` credential from being stored in the cluster: -+ -[source,terminal] ----- -$ rm mycluster/openshift/99_cloud-creds-secret.yaml ----- . From the directory that contains the installation program, obtain details of the {product-title} release image that your `openshift-install` binary is built to use: + @@ -115,7 +87,7 @@ $ oc adm release extract quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64 ---- endif::google-cloud-platform[] + -This displays the details for each request. +This command creates a YAML file for each `CredentialsRequest` object. + ifdef::aws[] .Sample `CredentialsRequest` object @@ -189,7 +161,7 @@ spec: ---- 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 the `spec.secretRef` for each `credentialsRequest`. The format for the secret data varies for each cloud provider. +. 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 the `spec.secretRef` for each `CredentialsRequest` object. The format for the secret data varies for each cloud provider. . From the directory that contains the installation program, proceed with your cluster creation: + diff --git a/modules/manually-removing-cloud-creds.adoc b/modules/manually-removing-cloud-creds.adoc new file mode 100644 index 000000000000..0598126b5436 --- /dev/null +++ b/modules/manually-removing-cloud-creds.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * post_installation_configuration/cluster-tasks.adoc + +[id="manually-removing-cloud-creds_{context}"] += Removing cloud provider credentials + +After installing an {product-title} cluster with the Cloud Credential Operator (CCO) in mint mode, you can remove the administrator-level credential secret from the `kube-system` namespace in the cluster. The administrator-level credential is not required unless something that requires an administrator-level credential needs to be changed, for instance during an upgrade. + +[NOTE] +==== +Prior to a non z-stream upgrade, you must reinstate the credential secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. +==== + +.Prerequisites + +* Your cluster is installed on a platform that supports removing cloud credentials from the CCO. Supported platforms are AWS and GCP. + +.Procedure + +. In the *Administrator* perspective of the web console, navigate to *Workloads* -> *Secrets*. + +. In the table on the *Secrets* page, find the root secret for your cloud provider. ++ +[cols=2,options=header] +|=== +|Platform +|Secret name + +|AWS +|`aws-creds` + +|GCP +|`gcp-credentials` + +|=== + +. Click the *Options* menu {kebab} in the same row as the secret and select *Delete Secret*. diff --git a/modules/manually-rotating-cloud-creds.adoc b/modules/manually-rotating-cloud-creds.adoc new file mode 100644 index 000000000000..50a260d40c27 --- /dev/null +++ b/modules/manually-rotating-cloud-creds.adoc @@ -0,0 +1,159 @@ +// Module included in the following assemblies: +// +// * post_installation_configuration/cluster-tasks.adoc + +[id="manually-rotating-cloud-creds_{context}"] += Rotating cloud provider credentials manually + +If your cloud provider credentials are changed for any reason, you must manually update the secret that the Cloud Credential Operator (CCO) uses to manage cloud provider credentials. + +The process for rotating cloud credentials depends on the mode that the CCO is configured to use. After you rotate credentials for a cluster that is using mint mode, you must manually remove the component credentials that were created by the removed credential. + +//// +[NOTE] +==== +You can also use the command line interface to complete all parts of this procedure. +==== +//// + +.Prerequisites + +* Your cluster is installed on a platform that supports rotating cloud credentials manually with the CCO mode that you are using: + +** For mint mode, AWS, Azure, and GCP are supported. + +** For passthrough mode, AWS, Azure, GCP, {rh-openstack-first}, {rh-virtualization-first}, and VMware vSphere are supported. + +* You have changed the credentials that are used to interface with your cloud provider. + +* The new credentials have sufficient permissions for the mode CCO is configured to use in your cluster. + +.Procedure + +. In the *Administrator* perspective of the web console, navigate to *Workloads* -> *Secrets*. + +. In the table on the *Secrets* page, find the root secret for your cloud provider. ++ +[cols=2,options=header] +|=== +|Platform +|Secret name + +|AWS +|`aws-creds` + +|Azure +|`azure-credentials` + +|GCP +|`gcp-credentials` + +|=== + +. Click the *Options* menu {kebab} in the same row as the secret and select *Edit Secret*. + +. Record the contents of the *Value* field or fields. You can use this information to verify that the value is different after updating the credentials. + +. Update the text in the *Value* field or fields with the new authentication information for your cloud provider, and then click *Save*. + +. If the CCO for your cluster is configured to use mint mode, delete each component secret that is referenced by the individual `CredentialsRequest` objects. + +.. Log in to the {product-title} CLI as a user with the `cluster-admin` role. + +.. Get the names and namespaces of all referenced component secrets: ++ +[source,terminal] +---- +$ oc -n openshift-cloud-credential-operator get CredentialsRequest -o json | jq -r '.items[] | select (.spec[].kind=="") | .spec.secretRef' +---- ++ +Where `` is the corresponding value for your cloud provider: `AWSProviderSpec` for AWS, `AzureProviderSpec` for Azure, or `GCPProviderSpec` for GCP. ++ +.Partial example output for AWS ++ +[source,json] +---- +{ + "name": "ebs-cloud-credentials", + "namespace": "openshift-cluster-csi-drivers" +} +{ + "name": "cloud-credential-operator-iam-ro-creds", + "namespace": "openshift-cloud-credential-operator" +} +... +---- + +.. Delete each of the referenced component secrets: ++ +[source,terminal] +---- +$ oc delete secret -n +---- ++ +Where `` is the name of a secret and `` is the namespace that contains the secret. ++ +.Example deletion of an AWS secret ++ +[source,terminal] +---- +$ oc delete secret ebs-cloud-credentials -n openshift-cluster-csi-drivers +---- ++ +You do not need to manually delete the credentials from your provider console. Deleting the referenced component secrets will cause the CCO to delete the existing credentials from the platform and create new ones. + +. To verify that the credentials have changed: + +.. In the *Administrator* perspective of the web console, navigate to *Workloads* -> *Secrets*. + +.. Verify that the contents of the *Value* field or fields are different than the previously recorded information. + +//// +// Provider-side verification also possible, though cluster-side is cleaner process. +. To verify that the credentials have changed from the console of your cloud provider: + +.. Get the `CredentialsRequest` CR names for your platform: ++ +[source,terminal] +---- +$ oc -n openshift-cloud-credential-operator get CredentialsRequest -o json | jq -r '.items[] | select (.spec[].kind=="") | .metadata.name' +---- ++ +Where `` is the corresponding value for your cloud provider: `AWSProviderSpec` for AWS, `AzureProviderSpec` for Azure, or `GCPProviderSpec` for GCP. ++ +.Example output for AWS ++ +[source,terminal] +---- +aws-ebs-csi-driver-operator +cloud-credential-operator-iam-ro +openshift-image-registry +openshift-ingress +openshift-machine-api-aws +---- + +.. Get the IAM username that corresponds to each `CredentialsRequest` CR name: ++ +[source,terminal] +---- +$ oc get credentialsrequest -n openshift-cloud-credential-operator -o json | jq -r ".status.providerStatus" +---- ++ +Where `` is the name of a `CredentialsRequest` CR. ++ +.Example output for AWS ++ +[source,json] +---- +{ + "apiVersion": "cloudcredential.openshift.io/v1", + "kind": "AWSProviderStatus", + "policy": "", + "user": "" +} +---- ++ +Where `` is the name of an IAM user on the cloud provider. + +.. For each IAM username, view the details for the user on the cloud provider. The credentials should show that they were created after being rotated on the cluster. +//// diff --git a/modules/mint-mode-with-removal-of-admin-credential.adoc b/modules/mint-mode-with-removal-of-admin-credential.adoc index 3fc999ec593c..72597b21ef07 100644 --- a/modules/mint-mode-with-removal-of-admin-credential.adoc +++ b/modules/mint-mode-with-removal-of-admin-credential.adoc @@ -3,25 +3,19 @@ // * 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 += Mint mode with removal or rotation of the admin credential -Currently, this mode is only supported on AWS. +Currently, this mode is only supported on AWS and GCP. -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. +In this mode, a user installs {product-title} with an administrator-level credential just like the normal mint mode. However, this process removes the administrator-level 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 `CredentialsRequest` objects -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. +The administrator can have the Cloud Credential Operator make its own request for a read-only credential that allows it to verify if all `CredentialsRequest` objects have their required permissions, thus the administrator-level credential is not required unless something needs to be changed. After the associated credential is removed, it can be deleted or deactivated 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. +[NOTE] +==== +Prior to a non z-stream upgrade, you must reinstate the credential secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. +==== -The `admin` credential is not stored in the cluster permanently. +The administrator-level 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. +Following these steps still requires the administrator-level credential in the cluster for brief periods of time. It also requires manually re-instating the secret with administrator-level credentials for each upgrade. diff --git a/operators/operator-reference.adoc b/operators/operator-reference.adoc index 275dfdc2b725..f15b82caa19d 100644 --- a/operators/operator-reference.adoc +++ b/operators/operator-reference.adoc @@ -6,6 +6,14 @@ include::modules/common-attributes.adoc[] toc::[] include::modules/cloud-credential-operator.adoc[leveloffset=+1] +[discrete] +[id="red-hat-operators-cco-addtl-resources"] +=== Additional resources + +* xref:../rest_api/security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[CredentialsRequest custom resource] +* Manually creating IAM for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], and xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP] +* xref:../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials] + include::modules/cluster-authentication-operator.adoc[leveloffset=+1] include::modules/cluster-autoscaler-operator.adoc[leveloffset=+1] include::modules/cluster-image-registry-operator.adoc[leveloffset=+1] diff --git a/post_installation_configuration/cluster-tasks.adoc b/post_installation_configuration/cluster-tasks.adoc index 950bbb964295..0d26129a1cb3 100644 --- a/post_installation_configuration/cluster-tasks.adoc +++ b/post_installation_configuration/cluster-tasks.adoc @@ -579,3 +579,22 @@ Understand and configure pod disruption budgets. include::modules/nodes-pods-pod-disruption-about.adoc[leveloffset=+2] include::modules/nodes-pods-pod-disruption-configuring.adoc[leveloffset=+2] + +[id="post-install-rotate-remove-cloud-creds"] +== Rotating or removing cloud provider credentials +After installing {product-title}, some organizations require the rotation or removal of the cloud provider credentials that were used during the initial installation. + +To allow the cluster to use the new credentials, you must update the secrets that the xref:../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator (CCO)] uses to manage cloud provider credentials. + +include::modules/manually-rotating-cloud-creds.adoc[leveloffset=+2] + +include::modules/manually-removing-cloud-creds.adoc[leveloffset=+2] + +[discrete] +[id="manually-rotating-cloud-creds-addtl-resources"] +=== Additional resources + +* xref:../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator] +* xref:../installing/installing_aws/manually-creating-iam.adoc#admin-credentials-root-secret-formats_manually-creating-iam-aws[Amazon Web Services (AWS) secret format] +* xref:../installing/installing_azure/manually-creating-iam-azure.adoc#admin-credentials-root-secret-formats_manually-creating-iam-azure[Microsoft Azure secret format] +* xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#admin-credentials-root-secret-formats_manually-creating-iam-gcp[Google Cloud Platform (GCP) secret format]