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

// Module included in the following assemblies:
//
//Postinstall and update content
// * post_installation_configuration/changing-cloud-credentials-configuration.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-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-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-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-specialized-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-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[]

//Permissions requirements (per platform, for install and key rotation)
include::snippets/ccoctl-provider-permissions-requirements.adoc[]

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

+
[NOTE]
====
The `ccoctl` binary is created in the directory from where you executed the command and not in `/usr/bin/`. You must rename the directory or move the `ccoctl.<rhel_version>` binary to `ccoctl`.
====

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

.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
----
+
.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-restricted-networks-aws-installer-provisioned"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-vpc"]
:!aws-sts:
endif::[]
ifeval::["{context}" == "installing-aws-specialized-region"]
: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-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::[]