openshift-docs/modules/cco-ccoctl-configuring.adoc

// Module included in the following assemblies:
//
//Postinstall  and update content
// * post_installation_configuration/cluster-tasks.adoc
// * updating/preparing_for_updates/preparing-manual-creds-update.adoc
//
//Platforms that must use `ccoctl` and update content
// * installing/installing_ibm_cloud/configuring-iam-ibm-cloud.adoc
// * installing/installing_ibm_powervs/preparing-to-install-on-ibm-power-vs.doc
// * installing/installing_nutanix/preparing-to-install-on-nutanix.adoc
//
// AWS assemblies:
// * installing/installing_aws/installing-aws-customizations.adoc
// * installing/installing_aws/installing-aws-network-customizations.adoc
// * installing/installing_aws/installing-restricted-networks-aws-installer-provisioned.adoc
// * installing/installing_aws/installing-aws-vpc.adoc
// * installing/installing_aws/installing-aws-private.adoc
// * installing/installing_aws/installing-aws-government-region.adoc
// * installing/installing_aws/installing-aws-secret-region.adoc
// * installing/installing_aws/installing-aws-china.adoc
// * installing/installing_aws/installing-aws-outposts-remote-workers.adoc
//
// GCP assemblies:
// * installing/installing_gcp/installing-gcp-customizations.adoc
// * installing/installing_gcp/installing-gcp-network-customizations.adoc
// * installing/installing_gcp/installing-restricted-networks-gcp-installer-provisioned.adoc
// * installing/installing_gcp/installing-gcp-vpc.adoc
// * installing/installing_gcp/installing-gcp-shared-vpc.adoc
// * installing/installing_gcp/installing-gcp-private.adoc
//
// Azure assemblies
// * installing/installing_azure/installing-azure-customizations.adoc
// * installing/installing_azure/installing-azure-government-region.adoc
// * installing/installing_azure/installing-azure-network-customizations.adoc
// * installing/installing_azure/installing-azure-private.adoc
// * installing/installing_azure/installing-azure-vnet.adoc
// * installing/installing_azure/installing-restricted-networks-azure-installer-provisioned.adoc

//Postinstall  and update content
ifeval::["{context}" == "changing-cloud-credentials-configuration"]
:postinstall:
endif::[]
ifeval::["{context}" == "preparing-manual-creds-update"]
:update:
endif::[]

//Platforms that must use `ccoctl`
ifeval::["{context}" == "configuring-iam-ibm-cloud"]
:ibm-cloud:
endif::[]
ifeval::["{context}" == "preparing-to-install-on-nutanix"]
:nutanix:
endif::[]
ifeval::["{context}" == "preparing-to-install-on-ibm-power-vs"]
:ibm-power-vs:
endif::[]

//AWS install assemblies
ifeval::["{context}" == "installing-aws-customizations"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-network-customizations"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-aws-installer-provisioned"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-vpc"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-private"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-government-region"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-secret-region"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-china-region"]
:aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-outposts-remote-workers"]
:aws-sts:
endif::[]

//GCP install assemblies
ifeval::["{context}" == "installing-gcp-customizations"]
:google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-network-customizations"]
:google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
:google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-vpc"]
:google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-shared-vpc"]
:google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-private"]
:google-cloud-platform:
endif::[]

//global Azure install assemblies
ifeval::["{context}" == "installing-azure-customizations"]
:azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-government-region"]
:azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-network-customizations"]
:azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-private"]
:azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-vnet"]
:azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-azure-installer-provisioned"]
:azure-workload-id:
endif::[]

:_mod-docs-content-type: PROCEDURE
[id="cco-ccoctl-configuring_{context}"]
ifndef::update[= Configuring the Cloud Credential Operator utility]
ifdef::update[= Configuring the Cloud Credential Operator utility for a cluster update]

//Nutanix-only intro because it needs context in its install procedure.
ifdef::nutanix[]
The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). To install a cluster on Nutanix, you must set the CCO to `manual` mode as part of the installation process.
endif::nutanix[]
ifdef::ibm-power-vs[]
The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). To install a cluster on {ibm-power-server-name}, you must set the CCO to `manual` mode as part of the installation process.
endif::ibm-power-vs[]

//The upgrade and postinstall procs also have a different intro, so they are excluded here.
ifndef::update,postinstall[]
To create and manage cloud credentials from outside of the cluster when the Cloud Credential Operator (CCO) is operating in manual mode, extract and prepare the CCO utility (`ccoctl`) binary.
endif::update,postinstall[]

//Intro for the postinstall procs.
ifdef::postinstall[]
To configure an existing cluster to create and manage cloud credentials from outside of the cluster, extract and prepare the Cloud Credential Operator utility (`ccoctl`) binary.
endif::postinstall[]

//Intro for the upgrade procs.
ifdef::update[]
To upgrade a cluster that uses the Cloud Credential Operator (CCO) in manual mode to create and manage cloud credentials from outside of the cluster, extract and prepare the CCO utility (`ccoctl`) binary.
endif::update[]

[NOTE]
====
The `ccoctl` utility is a Linux binary that must run in a Linux environment.
====

.Prerequisites

* You have access to an {product-title} account with cluster administrator access.
* You have installed the {oc-first}.

//Upgrade prereqs
ifdef::update[]
* Your cluster was configured using the `ccoctl` utility to create and manage cloud credentials from outside of the cluster.

* You have extracted the `CredentialsRequest` custom resources (CRs) from the {product-title} release image and ensured that a namespace that matches the text in the `spec.secretRef.namespace` field exists in the cluster.
endif::update[]

//AWS permissions needed when running ccoctl during install (I think we can omit from upgrade, since they already have an appropriate AWS account if they are upgrading).
ifdef::aws-sts[]
* You have created an AWS account for the `ccoctl` utility to use with the following permissions:
+
.Required AWS permissions
[%collapsible]
====
**Required `iam` permissions**

* `iam:CreateOpenIDConnectProvider`
* `iam:CreateRole`
* `iam:DeleteOpenIDConnectProvider`
* `iam:DeleteRole`
* `iam:DeleteRolePolicy`
* `iam:GetOpenIDConnectProvider`
* `iam:GetRole`
* `iam:GetUser`
* `iam:ListOpenIDConnectProviders`
* `iam:ListRolePolicies`
* `iam:ListRoles`
* `iam:PutRolePolicy`
* `iam:TagOpenIDConnectProvider`
* `iam:TagRole`

**Required `s3` permissions**

* `s3:CreateBucket`
* `s3:DeleteBucket`
* `s3:DeleteObject`
* `s3:GetBucketAcl`
* `s3:GetBucketTagging`
* `s3:GetObject`
* `s3:GetObjectAcl`
* `s3:GetObjectTagging`
* `s3:ListBucket`
* `s3:PutBucketAcl`
* `s3:PutBucketPolicy`
* `s3:PutBucketPublicAccessBlock`
* `s3:PutBucketTagging`
* `s3:PutObject`
* `s3:PutObjectAcl`
* `s3:PutObjectTagging`

**Required `cloudfront` permissions**

* `cloudfront:ListCloudFrontOriginAccessIdentities`
* `cloudfront:ListDistributions`
* `cloudfront:ListTagsForResource`
====
+
If you plan to store the OIDC configuration in a private S3 bucket that is accessed by the IAM identity provider through a public CloudFront distribution URL, the AWS account that runs the `ccoctl` utility requires the following additional permissions:
+
.Additional permissions for a private S3 bucket with CloudFront
[%collapsible]
====
* `cloudfront:CreateCloudFrontOriginAccessIdentity`
* `cloudfront:CreateDistribution`
* `cloudfront:DeleteCloudFrontOriginAccessIdentity`
* `cloudfront:DeleteDistribution`
* `cloudfront:GetCloudFrontOriginAccessIdentity`
* `cloudfront:GetCloudFrontOriginAccessIdentityConfig`
* `cloudfront:GetDistribution`
* `cloudfront:TagResource`
* `cloudfront:UpdateDistribution`

[NOTE]
=====
These additional permissions support the use of the `--create-private-s3-bucket` option when processing credentials requests with the `ccoctl aws create-all` command.
=====
====
endif::aws-sts[]

//Azure permissions needed when running ccoctl during install.
ifdef::azure-workload-id[]
* You have created a global Microsoft Azure account for the `ccoctl` utility to use with the following permissions:
+
.Required Azure permissions
[%collapsible]
====
* Microsoft.Resources/subscriptions/resourceGroups/read
* Microsoft.Resources/subscriptions/resourceGroups/write
* Microsoft.Resources/subscriptions/resourceGroups/delete
* Microsoft.Authorization/roleAssignments/read
* Microsoft.Authorization/roleAssignments/delete
* Microsoft.Authorization/roleAssignments/write
* Microsoft.Authorization/roleDefinitions/read
* Microsoft.Authorization/roleDefinitions/write
* Microsoft.Authorization/roleDefinitions/delete
* Microsoft.Storage/storageAccounts/listkeys/action
* Microsoft.Storage/storageAccounts/delete
* Microsoft.Storage/storageAccounts/read
* Microsoft.Storage/storageAccounts/write
* Microsoft.Storage/storageAccounts/blobServices/containers/write
* Microsoft.Storage/storageAccounts/blobServices/containers/delete
* Microsoft.Storage/storageAccounts/blobServices/containers/read
* Microsoft.ManagedIdentity/userAssignedIdentities/delete
* Microsoft.ManagedIdentity/userAssignedIdentities/read
* Microsoft.ManagedIdentity/userAssignedIdentities/write
* Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials/read
* Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials/write
* Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials/delete
* Microsoft.Storage/register/action
* Microsoft.ManagedIdentity/register/action
====
endif::azure-workload-id[]

//GCP permissions needed when running ccoctl during install.
ifdef::google-cloud-platform[]
* You have added one of the following authentication options to the GCP account that the installation program uses:

** The **IAM Workload Identity Pool Admin** role.

** The following granular permissions:
+
.Required GCP permissions
[%collapsible]
====
* compute.projects.get
* iam.googleapis.com/workloadIdentityPoolProviders.create
* iam.googleapis.com/workloadIdentityPoolProviders.get
* iam.googleapis.com/workloadIdentityPools.create
* iam.googleapis.com/workloadIdentityPools.delete
* iam.googleapis.com/workloadIdentityPools.get
* iam.googleapis.com/workloadIdentityPools.undelete
* iam.roles.create
* iam.roles.delete
* iam.roles.list
* iam.roles.undelete
* iam.roles.update
* iam.serviceAccounts.create
* iam.serviceAccounts.delete
* iam.serviceAccounts.getIamPolicy
* iam.serviceAccounts.list
* iam.serviceAccounts.setIamPolicy
* iam.workloadIdentityPoolProviders.get
* iam.workloadIdentityPools.delete
* resourcemanager.projects.get
* resourcemanager.projects.getIamPolicy
* resourcemanager.projects.setIamPolicy
* storage.buckets.create
* storage.buckets.delete
* storage.buckets.get
* storage.buckets.getIamPolicy
* storage.buckets.setIamPolicy
* storage.objects.create
* storage.objects.delete
* storage.objects.list
====
endif::google-cloud-platform[]

.Procedure

. Set a variable for the {product-title} release image by running the following command:
+
[source,terminal]
ifndef::update,postinstall[]
----
$ RELEASE_IMAGE=$(./openshift-install version | awk '/release image/ {print $3}')
----
endif::update,postinstall[]
ifdef::update,postinstall[]
----
$ RELEASE_IMAGE=$(oc get clusterversion -o jsonpath={..desired.image})
----
endif::update,postinstall[]

. Obtain the CCO container image from the {product-title} release image by running the following command:
+
[source,terminal]
----
$ CCO_IMAGE=$(oc adm release info --image-for='cloud-credential-operator' $RELEASE_IMAGE -a ~/.pull-secret)
----
+
[NOTE]
====
Ensure that the architecture of the `$RELEASE_IMAGE` matches the architecture of the environment in which you will use the `ccoctl` tool.
====

. Extract the `ccoctl` binary from the CCO container image within the {product-title} release image by running the following command:
+
[source,terminal]
----
$ oc image extract $CCO_IMAGE \
  --file="/usr/bin/ccoctl.<rhel_version>" \// <1>
  -a ~/.pull-secret
----
<1> For `<rhel_version>`, specify the value that corresponds to the version of {op-system-base-full} that the host uses.
If no value is specified, `ccoctl.rhel8` is used by default.
The following values are valid:
+
* `rhel8`: Specify this value for hosts that use {op-system-base} 8.
* `rhel9`: Specify this value for hosts that use {op-system-base} 9.

. Change the permissions to make `ccoctl` executable by running the following command:
+
[source,terminal]
----
$ chmod 775 ccoctl.<rhel_version>
----

.Verification

* To verify that `ccoctl` is ready to use, display the help file. Use a relative file name when you run the command, for example:
+
[source,terminal]
----
$ ./ccoctl.rhel9
----
+
.Example output
[source,terminal]
----
OpenShift credentials provisioning tool

Usage:
  ccoctl [command]

Available Commands:
  aws          Manage credentials objects for AWS cloud
  azure        Manage credentials objects for Azure
  gcp          Manage credentials objects for Google cloud
  help         Help about any command
  ibmcloud     Manage credentials objects for {ibm-cloud-title}
  nutanix      Manage credentials objects for Nutanix

Flags:
  -h, --help   help for ccoctl

Use "ccoctl [command] --help" for more information about a command.
----

//Postinstall and update content
ifeval::["{context}" == "changing-cloud-credentials-configuration"]
:!postinstall:
endif::[]
ifeval::["{context}" == "preparing-manual-creds-update"]
:!update:
endif::[]

//Platforms that must use `ccoctl` and update content
ifeval::["{context}" == "configuring-iam-ibm-cloud"]
:!ibm-cloud:
endif::[]
ifeval::["{context}" == "preparing-to-install-on-nutanix"]
:!nutanix:
endif::[]
ifeval::["{context}" == "preparing-to-install-on-ibm-power-vs"]
:!ibm-power-vs:
endif::[]

//AWS install assemblies
ifeval::["{context}" == "installing-aws-customizations"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-network-customizations"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-aws-installer-provisioned"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-vpc"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-private"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-government-region"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-secret-region"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-china-region"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-outposts-remote-workers"]
:!aws-sts:
endif::[]

//GCP install assemblies
ifeval::["{context}" == "installing-gcp-customizations"]
:!google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-network-customizations"]
:!google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
:!google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-vpc"]
:!google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-shared-vpc"]
:!google-cloud-platform:
endif::[]
ifeval::["{context}" == "installing-gcp-private"]
:!google-cloud-platform:
endif::[]

//global Azure install assemblies
ifeval::["{context}" == "installing-azure-customizations"]
:!azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-government-region"]
:!azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-network-customizations"]
:!azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-private"]
:!azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-azure-vnet"]
:!azure-workload-id:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-azure-installer-provisioned"]
:!azure-workload-id:
endif::[]