[OSDOCS-19522]: Setting up workload identities for HCP on Azure

hosted_control_planes/hcp-deploy/hcp-deploy-azure.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-With {hcp} on {azure-first}, you can reduce the cost and overhead associated with dedicated control-plane node VMs for each cluster. You can provision compute nodes as {azure-short} Virtual Machine Scale sets for dynamic scaling, and ensure credential isolation with per-cluster {azure-short} service principals.
+With {hcp} on {azure-first}, you can reduce the cost associated with dedicated control-plane node VMs for each cluster. You can provision compute nodes as {azure-short} Virtual Machine Scale sets for dynamic scaling, and ensure credential isolation with per-cluster {azure-short} service principals.
 
 :FeatureName: {hcp-capital} on {azure-short}
 include::snippets/technology-preview.adoc[]
@@ -19,17 +19,24 @@ include::modules/hcp-azure-overview.adoc[leveloffset=+1]
 
 * link:https://azure.github.io/azure-workload-identity/docs/[{azure-short} Workload Identity documentation]
 
-include::modules/hcp-azure-infra-creds.adoc[leveloffset=+1]
+include::modules/hcp-azure-infra-creds.adoc[leveloffset=+2]
 
-// include::modules/hcp-azure-env.adoc[leveloffset=+1]
+include::modules/hcp-azure-setup-resources.adoc[leveloffset=+1]
 
-//include::modules/hcp-azure-wkld-id.adoc[leveloffset=+2]
+include::modules/hcp-azure-oidc.adoc[leveloffset=+2]
 
-//include::modules/hcp-azure-iam-res.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/solutions/7001811[How to obtain the ccoctl tool for OpenShift 4 (Red{nbsp}Hat Knowledgebase article)]
 
-//include::modules/hcp-azure-infra-sep.adoc[leveloffset=+2]
+include::modules/hcp-azure-workload-id.adoc[leveloffset=+2]
 
-//include::modules/hcp-azure-mgmt-cluster.adoc[leveloffset=+2]
+include::modules/hcp-azure-workload-id-delete.adoc[leveloffset=+2]
+
+// include::modules/hcp-azure-infra-sep.adoc[leveloffset=+2]
+
+//include::modules/hcp-azure-mgmt-cluster.adoc[leveloffset=+1]
 
 // include::modules/hcp-azure-create-hosted.adoc[leveloffset=+1]
 
@@ -40,8 +47,3 @@ include::modules/hcp-azure-infra-creds.adoc[leveloffset=+1]
 // include::modules/hcp-azure-hc-config-params.adoc[leveloffset=+1]
 
 // include::modules/hcp-azure-nodepool-config-params.adoc[leveloffset=+2]
-
-// [role="_additional-resources"]
-// .Additional resources
-
-// * 

modules/hcp-azure-infra-sep.adoc

@@ -0,0 +1,11 @@
+//Module included in the following assemblies:
+// hosted_control_planes/hcp-deploy/hcp-deploy-azure.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-azure-infra-sep_{context}"]
+= Creating {azure-short} infrastructure separately
+
+[role="_abstract"]
+
+
+.Procedure

modules/hcp-azure-oidc.adoc

@@ -0,0 +1,89 @@
+//Module included in the following assemblies:
+// hosted_control_planes/hcp-deploy/hcp-deploy-azure.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-azure-oidc_{context}"]
+= Setting up an OIDC issuer
+
+[role="_abstract"]
+To prepare to deploy {hcp} on {azure-short}, you need to set up {azure-short} Workload Identities and an OIDC issuer for hosted clusters.
+
+.Prerequisites
+
+* The {azure-short} command-line interface (CLI) is installed and configured.
+* The `jq` command-line JSON processor is installed.
+* The Cloud Credential Operator utility (`ccoctl`) is installed. For more information, see "How to obtain the ccoctl tool for OpenShift 4".
+* The appropriate {azure-short} permissions are set.
+
+.Procedure
+
+. Set your environment variables as shown in the following example:
++
+[source,terminal]
+----
+PERSISTENT_RG_NAME="os4-common"
+LOCATION="eastus"
+AZURE_CREDS="/path/to/azure-creds.json"
+SUBSCRIPTION_ID="my-subscription-id"
+----
+
+. Create a persistent resource group by entering the following command:
++
+[source,terminal]
+----
+$ az group create --name $PERSISTENT_RG_NAME --location $LOCATION
+----
+
+. Configure an OIDC issuer URL by using the Cloud Credential Operator tool to complete the following steps:
++
+.. Set the OIDC issuer variables as shown in the following example:
++
+[source,terminal]
+----
+OIDC_STORAGE_ACCOUNT_NAME="yourstorageaccount"
+TENANT_ID="your-tenant-id"
+----
++
+.. Create an RSA key pair and save the private and public key by entering the following command:
++
+[source,terminal]
+----
+$ ccoctl azure create-key-pair
+----
++
+.. Set variables for the token issuer key paths as shown in the following example:
++
+[source,terminal]
+----
+SA_TOKEN_ISSUER_PRIVATE_KEY_PATH="/path/to/serviceaccount-signer.private"
+SA_TOKEN_ISSUER_PUBLIC_KEY_PATH="/path/to/serviceaccount-signer.public"
+----
++
+.. Create an OIDC issuer by entering the following command:
++
+[source,terminal]
+----
+$ ccoctl azure create-oidc-issuer \
+    --oidc-resource-group-name ${PERSISTENT_RG_NAME} \
+    --tenant-id ${TENANT_ID} \
+    --region ${LOCATION} \
+    --name ${OIDC_STORAGE_ACCOUNT_NAME} \
+    --subscription-id ${SUBSCRIPTION_ID} \
+    --public-key-file ${SA_TOKEN_ISSUER_PUBLIC_KEY_PATH}
+----
++
+.. Set the OIDC issuer URL as shown in the following example:
++
+[source,terminal]
+----
+OIDC_ISSUER_URL="https://${OIDC_STORAGE_ACCOUNT_NAME}.blob.core.windows.net/${OIDC_STORAGE_ACCOUNT_NAME}"
+----
+
+.Verification
+
+* Try to access the OIDC issuer by entering the following command:
++
+[source,terminal]
+----
+$ curl -s "${OIDC_ISSUER_URL}/.well-known/openid-configuration" | jq .
+----

modules/hcp-azure-setup-resources.adoc

@@ -0,0 +1,10 @@
+//Module included in the following assemblies:
+// hosted_control_planes/hcp-deploy/hcp-deploy-azure.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="hcp-azure-setup-resources_{context}"]
+= Setting up {azure-short} resources
+
+[role="_abstract"]
+Before you can create management and hosted clusters for your deployment of {hcp} on {azure-short}, you need to set up an OIDC issuer, Workload Identities, and your {azure-short} infrastructure.
+

modules/hcp-azure-workload-id-delete.adoc

@@ -0,0 +1,43 @@
+//Module included in the following assemblies:
+// hosted_control_planes/hcp-deploy/hcp-deploy-azure.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-azure-workload-delete_{context}"]
+= Deleting {azure-short} Workload Identities
+
+[role="_abstract"]
+As part of the process to delete a hosted cluster on {azure-short}, you need to delete the Workload Identities.
+
+To delete the Workload Identities, you enter a command on the {hcp} command-line interface, `hcp`. The command uses the file that was generated when you created the Workload Identities to identify the identities to delete. Both the managed identities and their federated credentials are removed.
+
+.Prerequisites
+
+* If you created infrastructure by using the Workload Identities, delete the infrastructure before you delete the identities.
+
+.Procedure
+
+* Enter the following command:
++
+[source,terminal]
+----
+$ hcp destroy iam azure \
+    --azure-creds <azure_credentials_file> \
+    --workload-identities-file <workload_identities_file> \
+    --resource-group-name <resource_group> \
+    --name <my_cluster_name> \
+    --infra-id <infra_id> \
+    --dns-zone-rg-name <dns_zone_rg> \
+    --cloud <my_cloud_environment>
+----
++
+where:
++
+`<azure_credentials_file>`:: Specifies the {azure-short} credentials file with permission to create managed identities and federated credentials.
+`<workload_identities_file>`:: Specifies the path to the Workload Identities JSON file, such as `my-cluster-name-iam-output.json`.
+`<resource_group>`:: Specifies the name of the resource group where you created identities.
+`<my_cluster_name>`:: Specifies the name of your hosted cluster.
+`<infra_id>`:: Specifies the unique identifier for naming {azure-short} resources. Typically, this identifier is the cluster name with a suffix.
+`<dns_zone_rg>`:: Specifies the DNS zone resource group. 
++
+Optionally, you can also specify the `--cloud` flag to set the {azure-short} cloud environment. The default value is `AzurePublicCloud`.
+

modules/hcp-azure-workload-id.adoc

@@ -0,0 +1,108 @@
+//Module included in the following assemblies:
+// hosted_control_planes/hcp-deploy/hcp-deploy-azure.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-azure-workload-id_{context}"]
+= Creating {azure-short} Workload Identities
+
+[role="_abstract"]
+To ensure control over Identity and Access Management (IAM) resources in your {azure-short} deployment, create Workload Identities separately from your infrastructure.
+
+Workload Identities authenticate hosted cluster components to {azure-short} services by using OIDC federation. You must create identities separately and then consume them during infrastructure or cluster creation.
+
+.Prerequisites
+
+* You have an {azure-short} credentials file in the following format:
++
+.Example file
+[source,terminal]
+----
+{
+  "subscriptionId": "your-subscription-id",
+  "tenantId": "your-tenant-id",
+  "clientId": "your-client-id",
+  "clientSecret": "your-client-secret"
+}
+----
+
+* You have a resource group to create the managed identities in.
+* You have an OIDC issuer URL for Workload Identity federation. For more information, see "Setting up an OIDC issuer".
+
+.Procedure
+
+. Set environment variables as shown in the following example:
++
+[source,terminal]
+----
+CLUSTER_NAME="my-self-managed-cluster"
+INFRA_ID="${CLUSTER_NAME}-$(openssl rand -hex 4)"
+----
+
+. On the {hcp} command-line interface, `hcp`, enter the following command:
++
+[source,terminal]
+----
+$ hcp create iam azure \
+    --name <my_cluster_name> \
+    --infra-id <infra_id> \
+    --azure-creds <azure_credentials_file> \
+    --resource-group-name <resource_group> \
+    --oidc-issuer-url <oidc_issuer_url> \
+    --output-file <workload_identities_file> \
+    --location <my_region> \
+    --cloud <my_cloud_environment>
+----
++
+where:
++
+`<my_cluster_name>`:: Specifies the name of the cluster you intend to create.
+`<infra_id>`:: Specifies the unique identifier for naming {azure-short} resources. Typically, this identifier is the cluster name with a suffix.
+`<azure_credentials_file>`:: Specifies the {azure-short} credentials file with permission to create managed identities and federated credentials.
+`<resource_group>`:: Specifies the name of the resource group where you intend to create identities.
+`<oidc_issuer_url>`:: Specifies the URL of the OIDC identity provider for Workload Identity federation.
+`<workload_identities_file>`:: Specifies the output file path, such as `my-cluster-name-iam-output.json`.
++
+You can also add these optional flags to the `hcp create iam azure` command:
++
+`<my_region>`:: Specifies the {azure-short} region for the managed identities. The default value is `eastus`.
+`<my_cloud_environment>`:: Specifies the {azure-short} cloud environment. The default value is `AzurePublicCloud`.
+
+.Verification
+
+* Review the output file, which looks like the following example:
++
+.Example output
+[source,terminal]
+----
+{
+  "disk": {
+    "tenantID": "...",
+    "clientID": "...",
+    "resourceID": "/subscriptions/.../providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-cluster-abc123-disk"
+  },
+  "file": {
+    "tenantID": "...",
+    "clientID": "...",
+    "resourceID": "..."
+  },
+  "imageRegistry": { ... },
+  "ingress": { ... },
+  "cloudProvider": { ... },
+  "nodePoolManagement": { ... },
+  "network": { ... },
+  "controlPlaneOperator": { ... }
+}
+----
++
+The output includes 8 user-assigned identities, one per cluster component, along with federated credentials for each identity:
++
+** Disk CSI driver
+** File CSI driver
+** Image registry
+** Ingress Operator
+** Cloud provider
+** Node pool management
+** Network Operator
+** Control Plane Operator
+
+// Add note about private endpoint access? or include that in the steps to deploy private clusters on Azure?