openshift-docs/modules/create-wif-cluster-cli.adoc

// Module included in the following assemblies:
//
// * osd_install_access_delete_cluster/creating-a-gcp-cluster-with-workload-identity-federation.adoc


:_mod-docs-content-type: PROCEDURE
[id="create-wif-cluster-cli_{context}"]
= Creating a Workload Identity Federation cluster using the OCM CLI

You can create an {product-title} on {GCP} cluster with Workload Identity Federation (WIF) using the OpenShift Cluster Manager CLI (`ocm`) in interactive or non-interactive mode.

[IMPORTANT]
====
To create a WIF-enabled cluster, the OpenShift Cluster Manager CLI (`ocm`) must be version 1.0.2 or greater.
====

Before creating the cluster, you must first create a WIF configuration.
[NOTE]
====
Migrating an existing non-WIF cluster to a WIF configuration is not supported. This feature can only be enabled during new cluster creation.
====

[id="create-wif-configuration_{context}"]
== Creating a WIF configuration

.Procedure
You can create a WIF configuration using the `auto` mode or the `manual` mode.

The `auto` mode enables you to automatically create the service accounts for {product-title} components as well as other IAM resources.

Alternatively, you can use the `manual` mode. In `manual` mode, you are provided with commands within a `script.sh` file which you use to manually create the service accounts for {product-title} components as well as other IAM resources.

* Based on your mode preference, run one of the following commands to create a WIF configuration:

** Create a WIF configuration in auto mode by running the following command:
+
[source,terminal]
----
$ ocm gcp create wif-config --name <wif_name> \ <1>
  --project <gcp_project_id> \ <2>
----
<1> Replace `<wif_name>` with the name of your WIF configuration.
<2> Replace `<gcp_project_id>` with the ID of the {GCP} project where the WIF configuration will be implemented.
+
--
.Example output
[source,terminal]
----
2024/09/26 13:05:41 Creating workload identity configuration...
2024/09/26 13:05:47 Workload identity pool created with name 2e1kcps6jtgla8818vqs8tbjjls4oeub
2024/09/26 13:05:47 workload identity provider created with name oidc
2024/09/26 13:05:48 IAM service account osd-worker-oeub created
2024/09/26 13:05:49 IAM service account osd-control-plane-oeub created
2024/09/26 13:05:49 IAM service account openshift-gcp-ccm-oeub created
2024/09/26 13:05:50 IAM service account openshift-gcp-pd-csi-driv-oeub created
2024/09/26 13:05:50 IAM service account openshift-image-registry-oeub created
2024/09/26 13:05:51 IAM service account openshift-machine-api-gcp-oeub created
2024/09/26 13:05:51 IAM service account osd-deployer-oeub created
2024/09/26 13:05:52 IAM service account cloud-credential-operator-oeub created
2024/09/26 13:05:52 IAM service account openshift-cloud-network-c-oeub created
2024/09/26 13:05:53 IAM service account openshift-ingress-gcp-oeub created
2024/09/26 13:05:55 Role "osd_deployer_v4.18" updated
----
--
+
** Create a WIF configuration in manual mode by running the following command:
+
[source,terminal]
----
$ ocm gcp create wif-config --name <wif_name> \ <1>
  --project <gcp_project_id> \ <2>
  --mode=manual
----
<1> Replace `<wif_name>` with the name of your WIF configuration.
<2> Replace `<gcp_project_id>` with the ID  of the {GCP} project where the WIF configuration will be implemented.
+
Once the WIF is configured, the following service accounts, roles, and groups are created.
+
.WIF configuration service accounts, group and roles
[cols="2a,3a",options="header"]
|===

|Service Account/Group
|GCP pre-defined roles and Red Hat custom roles


|osd-deployer
|osd_deployer_v4.18


|osd-control-plane
|- compute.instanceAdmin
- compute.networkAdmin
- compute.securityAdmin
- compute.storageAdmin

|osd-worker
|- compute.storageAdmin
- compute.viewer

|cloud-credential-operator-gcp-ro-creds
|cloud_credential_operator_gcp_ro_creds_v{product-version}

|openshift-cloud-network-config-controller-gcp
|openshift_cloud_network_config_controller_gcp_v{product-version}

|openshift-gcp-ccm
|openshift_gcp_ccm_v{product-version}

|openshift-gcp-pd-csi-driver-operator
|- compute.storageAdmin
- iam.serviceAccountUser
- resourcemanager.tagUser
- openshift_gcp_pd_csi_driver_operator_v{product-version}

|openshift-image-registry-gcp
|openshift_image_registry_gcs_v{product-version}

|openshift-ingress-gcp
|openshift_ingress_gcp_v{product-version}

|openshift-machine-api-gcp
|openshift_machine_api_gcp_v{product-version}

|Access via SRE group:sd-sre-platform-gcp-access
|sre_managed_support

|===

For further details about WIF configuration roles and their assigned permissions, see link:https://github.com/openshift/managed-cluster-config/blob/master/resources/wif/4.18/vanilla.yaml[managed-cluster-config].

[id="create-wif-cluster_{context}"]
== Creating a WIF cluster

.Procedure
You can create a WIF cluster using the `interactive` mode or the `non-interactive` mode.

In `interactive` mode, cluster attributes are displayed automatically as prompts during the creation of the cluster. You enter the values for those prompts based on specified requirements in the fields provided.

In `non-interactive` mode, you specify the values for specific parameters within the command.

* Based on your mode preference, run one of the following commands to create an {product-title} on (GCP) cluster with WIF configuration:

** Create a cluster in interactive mode by running the following command:
+
[source,terminal]
----
$ ocm create cluster --interactive <1>
----
<1> `interactive` mode enables you to specify configuration options at the interactive prompts.
+
** Create a cluster in non-interactive mode by running the following command:
+
[NOTE]
====
The following example is made up optional and required parameters and may differ from your `non-interactive` mode command. Parameters not identified as optional are required. For additional details about these and other parameters, run the `ocm create cluster --help flag` command in you terminal window.
====
+
[source,terminal]
----
$ ocm create cluster <cluster_name> \ <1>
--provider=gcp \ <2>
--ccs=true \ <3>
--wif-config <wif_name> \ <4>
--region <gcp_region> \ <5>
--subscription-type=marketplace-gcp \ <6>
--marketplace-gcp-terms=true \ <7>
--version <version> \ <8>
--multi-az=true  \ <9>
--enable-autoscaling=true \ <10>
--min-replicas=3 \ <11>
--max-replicas=6 \ <12>
--secure-boot-for-shielded-vms=true <13>
----
<1> Replace `<cluster_name>` with a name for your cluster.
<2> Set value to `gcp`.
<3> Set value to `true`.
<4> Replace `<wif_name>` with the name of your WIF configuration.
<5> Replace `<gcp_region>` with the {GCP} region where the new cluster will be deployed.
<6> Optional: The subscription billing model for the cluster.
<7> Optional: If you provided a value of `marketplace-gcp` for the `subscription-type` parameter, `marketplace-gcp-terms` must be equal to `true`.
<8> Optional: The desired OpenShift version.
<9> Optional: Deploy to multiple data centers.
<10> Optional: Enable autoscaling of compute nodes.
<11> Optional: Minimum number of compute nodes.
<12> Optional: Maximum number of compute nodes.
<13> Optional: Secure Boot enables the use of Shielded VMs in the Google Cloud Platform.

[id="ocm-cli-list-wif-commands_{context}"]
== Listing WIF clusters

To list all of your {product-title} clusters that have been deployed using the WIF authentication type, run the following command:

[source,terminal]
----
$ ocm list clusters --parameter search="gcp.authentication.wif_config_id != ''"
----
To list all of your {product-title} clusters that have been deployed using a specific wif-config, run the following command:
[source,terminal]
----
$ ocm list clusters --parameter search="gcp.authentication.wif_config_id = '<wif_config_id>'" <1>
----
<1> Replace `<wif_config_id>` with the ID of the WIF configuration.

[id="wif-configuration-update_{context}"]
== Updating a WIF configuration

[NOTE]
====
Updating a WIF configuration is only applicable for y-stream updates. For an overview of the update process, including details regarding version semantics, see link:https://www.redhat.com/en/blog/the-ultimate-guide-to-openshift-release-and-upgrade-process-for-cluster-administrators#:~:text=Ongoing%20security%20patches%20and%20bug,is%20the%20dark%20green%20bar.[The Ultimate Guide to OpenShift Release and Upgrade Process for Cluster Administrators].
====
Before updating a WIF-enabled {product-title} cluster to a newer version, you must update the wif-config to that version as well. If you do not update the wif-config version before attempting to update the cluster version, the cluster version update will fail.

You can update a wif-config to a specific {product-title} version by running the following command:

[source,terminal]
----
ocm gcp update wif-config --version <version> \ <1>
--name <wif_name> <2>
----
<1> Replace `<version>` with the {product-title} y-stream version you plan to update the cluster to.
<2> Replace `<wif_name>` with the name of the WIF configuration you want to update.

[id="ocm-cli-verify-wif-commands_{context}"]
== Verifying a WIF configuration
You can verify that the configuration of resources associated with a WIF configuration are correct by running the `ocm gcp verify wif-config` command. If a misconfiguration is found, the output provides details about the misconfiguration and recommends that you update the WIF configuration.

You need the name and ID of the WIF configuration you want to verify before verification.
To obtain the name and ID of your active WIF configurations, run the following command:

[source,terminal]
----
$ ocm gcp list wif-configs
----

To determine if the WIF configuration you want to verify is configured correctly, run the following command:

[source,terminal]
----
$ ocm gcp verify wif-config <wif_config_name>|<wif_config_id> <1>
----
<1> Replace `<wif_config_name>` and `<wif_config_id>` with the name and ID of your WIF configuration, respectively.

--
.Example output
[source,terminal]
----
Error: verification failed with error: missing role 'compute.storageAdmin'.
Running 'ocm gcp update wif-config' may fix errors related to cloud resource misconfiguration.
exit status 1.
----
--