openshift-docs/modules/cloud-credential-operator.adoc

// Module included in the following assemblies:
//
// * operators/operator-reference.adoc

[id="cloud-credential-operator_{context}"]
= Cloud Credential Operator

[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.

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.

[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.

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.

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.

.Mint mode credential requirements
[cols="1,9a"]
|====
|Cloud |Permissions

|AWS
|* `iam:CreateAccessKey`
* `iam:CreateUser`
* `iam:DeleteAccessKey`
* `iam:DeleteUser`
* `iam:DeleteUserPolicy`
* `iam:GetUser`
* `iam:GetUserPolicy`
* `iam:ListAccessKeys`
* `iam:PutUserPolicy`
* `iam:TagUser`
* `iam:SimulatePrincipalPolicy`

|Azure
|Service principal with the permissions specified in the _Creating a service principal_ section of the _Configuring an Azure account_ content.

|GCP
|* `resourcemanager.projects.get`
* `serviceusage.services.list`
* `iam.serviceAccountKeys.create`
* `iam.serviceAccountKeys.delete`
* `iam.serviceAccounts.create`
* `iam.serviceAccounts.delete`
* `iam.serviceAccounts.get`
* `iam.roles.get`
* `resourcemanager.projects.getIamPolicy`
* `resourcemanager.projects.setIamPolicy`

|====

[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.

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.

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.

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.

[discrete]
==== Passthrough mode
Passthrough mode is supported for AWS, Azure, GCP, {rh-openstack-first},
{rh-virtualization-first}, and VMware vSphere.

In passthrough mode, the CCO passes the provided cloud credential to the components that request cloud credentials. The credential must have permissions to perform the installation and complete the operations that are required by components in the cluster, but does not need to be able to create new credentials. The CCO does not attempt to create additional limited-scoped credentials in passthrough mode.

[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.

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.

To install an {product-title} cluster on {rh-virtualization-first}, the CCO requires a credential with the following privileges:

* `DiskOperator`
* `DiskCreator`
* `UserTemplateBasedVm`
* `TemplateOwner`
* `TemplateCreator`
* `ClusterAdmin` on the specific cluster that is targeted for {product-title} deployment

To install an {product-title} cluster on VMware vSphere, the CCO requires a credential with the following vSphere privileges:

.Required vSphere privileges
[cols="1,2"]
|====
|Category |Privileges

|Datastore
|_Allocate space_

|Folder
|_Create folder_, _Delete folder_

|vSphere Tagging
|All privileges

|Network
|_Assign network_

|Resource
|_Assign virtual machine to resource pool_

|Profile-driven storage
|All privileges

|vApp
|All privileges

|Virtual machine
|All privileges

|====

[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.

[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.

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.

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.

//later include upgrade info from manually-maintained-credentials-upgrade

For information about configuring AWS to use manual mode, see _Manually creating IAM for AWS_.

[discrete]
==== Disabled CCO
Disabled CCO is supported for Azure and GCP.

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.

[discrete]
== Project

link:https://github.com/openshift/cloud-credential-operator[openshift-cloud-credential-operator]

[discrete]
== CRDs

* credentialsrequests.cloudcredential.openshift.io
** Scope: Namespaced
** CR: credentialsrequest
** Validation: Yes

[discrete]
== Configuration objects

No configuration required.