From 4366dd776705b2c7ac5aab17885da63948dd085f Mon Sep 17 00:00:00 2001 From: Mike Pytlak Date: Thu, 27 Jul 2023 09:50:46 -0400 Subject: [PATCH] OSDOCS#5126: Using an Azure managed identity as an alternative to a service principal --- .../installing-azure-account.adoc | 11 +- .../installing-azure-user-infra.adoc | 10 +- modules/installation-azure-identities.adoc | 13 ++ ...allation-azure-subscription-tenant-id.adoc | 121 ++++++++++++++++++ ...tion-creating-azure-service-principal.adoc | 57 +++++++++ modules/installation-initializing.adoc | 65 +++++++--- modules/installation-launching-installer.adoc | 107 ++++++++++------ ...lation-using-azure-managed-identities.adoc | 21 +++ ...inimum-required-permissions-ipi-azure.adoc | 14 +- ...inimum-required-permissions-upi-azure.adoc | 13 +- 10 files changed, 362 insertions(+), 70 deletions(-) create mode 100644 modules/installation-azure-identities.adoc create mode 100644 modules/installation-azure-subscription-tenant-id.adoc create mode 100644 modules/installation-creating-azure-service-principal.adoc create mode 100644 modules/installation-using-azure-managed-identities.adoc diff --git a/installing/installing_azure/installing-azure-account.adoc b/installing/installing_azure/installing-azure-account.adoc index 95f2c8420bfb..037ea38f24ee 100644 --- a/installing/installing_azure/installing-azure-account.adoc +++ b/installing/installing_azure/installing-azure-account.adoc @@ -6,8 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] -Before you can install {product-title}, you must configure a Microsoft Azure -account. +Before you can install {product-title}, you must configure a Microsoft Azure account to meet installation requirements. [IMPORTANT] ==== @@ -29,11 +28,13 @@ include::modules/installation-azure-network-config.adoc[leveloffset=+1] include::modules/installation-azure-increasing-limits.adoc[leveloffset=+1] -include::modules/installation-azure-permissions.adoc[leveloffset=+1] +include::modules/installation-azure-subscription-tenant-id.adoc[leveloffset=+1] -include::modules/minimum-required-permissions-ipi-azure.adoc[leveloffset=+1] +include::modules/installation-azure-identities.adoc[leveloffset=+1] -include::modules/installation-azure-service-principal.adoc[leveloffset=+1] +include::modules/minimum-required-permissions-ipi-azure.adoc[leveloffset=+2] +include::modules/installation-using-azure-managed-identities.adoc[leveloffset=+2] +include::modules/installation-creating-azure-service-principal.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources diff --git a/installing/installing_azure/installing-azure-user-infra.adoc b/installing/installing_azure/installing-azure-user-infra.adoc index c54858c8f497..e1ded92bf569 100644 --- a/installing/installing_azure/installing-azure-user-infra.adoc +++ b/installing/installing_azure/installing-azure-user-infra.adoc @@ -57,9 +57,15 @@ include::modules/installation-azure-increasing-limits.adoc[leveloffset=+2] include::modules/csr-management.adoc[leveloffset=+2] -include::modules/installation-azure-permissions.adoc[leveloffset=+2] +include::modules/installation-azure-subscription-tenant-id.adoc[leveloffset=+2] + +include::modules/installation-azure-identities.adoc[leveloffset=+2] + include::modules/minimum-required-permissions-upi-azure.adoc[leveloffset=+2] -include::modules/installation-azure-service-principal.adoc[leveloffset=+2] + +include::modules/installation-using-azure-managed-identities.adoc[leveloffset=+2] + +include::modules/installation-creating-azure-service-principal.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources diff --git a/modules/installation-azure-identities.adoc b/modules/installation-azure-identities.adoc new file mode 100644 index 000000000000..af28e62468ee --- /dev/null +++ b/modules/installation-azure-identities.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * installing/installing_azure/installing-azure-account.adoc + +:_content-type: CONCEPT +[id="installation-azure-identities_{context}"] += Supported identities to access Azure resources + +An {product-title} cluster requires an Azure identity to create and manage Azure resources. As such, you need one of the following types of identities to complete the installation: + +* A service principal +* A system-assigned managed identity +* A user-assigned managed identity diff --git a/modules/installation-azure-subscription-tenant-id.adoc b/modules/installation-azure-subscription-tenant-id.adoc new file mode 100644 index 000000000000..a4278b45b1fa --- /dev/null +++ b/modules/installation-azure-subscription-tenant-id.adoc @@ -0,0 +1,121 @@ +// Module included in the following assemblies: +// +// * installing/installing_azure/installing-azure-account.adoc + +:_content-type: PROCEDURE +[id="installation-azure-subscription-tenant-id_{context}"] += Recording the subscription and tenant IDs + +The installation program requires the subscription and tenant IDs that are associated with your Azure account. You can use the Azure CLI to gather this information. + +.Prerequisites + +* You have installed or updated the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI]. + +.Procedure + +. Log in to the Azure CLI by running the following command: ++ +[source,terminal] +---- +$ az login +---- + +. Ensure that you are using the right subscription: + +.. View a list of available subscriptions by running the following command: ++ +[source,terminal] +---- +$ az account list --refresh +---- ++ +.Example output +[source,terminal] +---- +[ + { + "cloudName": "AzureCloud", + "id": "8xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "isDefault": true, + "name": "Subscription Name 1", + "state": "Enabled", + "tenantId": "6xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "user": { + "name": "you@example.com", + "type": "user" + } + }, + { + "cloudName": "AzureCloud", + "id": "9xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "isDefault": false, + "name": "Subscription Name 2", + "state": "Enabled", + "tenantId": "7xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "user": { + "name": "you2@example.com", + "type": "user" + } + } +] +---- + +.. View the details of the active account, and confirm that this is the subscription you want to use, by running the following command: ++ +[source,terminal] +---- +$ az account show +---- ++ +.Example output +[source,terminal] +---- +{ + "environmentName": "AzureCloud", + "id": "8xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "isDefault": true, + "name": "Subscription Name 1", + "state": "Enabled", + "tenantId": "6xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "user": { + "name": "you@example.com", + "type": "user" + } +} +---- + +. If you are not using the right subscription: + +.. Change the active subscription by running the following command: ++ +[source,terminal] +---- +$ az account set -s +---- + +.. Verify that you are using the subscription you need by running the following command: ++ +[source,terminal] +---- +$ az account show +---- ++ +.Example output +[source,terminal] +---- +{ + "environmentName": "AzureCloud", + "id": "9xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "isDefault": true, + "name": "Subscription Name 2", + "state": "Enabled", + "tenantId": "7xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "user": { + "name": "you2@example.com", + "type": "user" + } +} +---- + +. Record the `id` and `tenantId` parameter values from the output. You require these values to install an {product-title} cluster. diff --git a/modules/installation-creating-azure-service-principal.adoc b/modules/installation-creating-azure-service-principal.adoc new file mode 100644 index 000000000000..5561e1ee2399 --- /dev/null +++ b/modules/installation-creating-azure-service-principal.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * installing/installing_azure/installing-azure-account.adoc + +:_content-type: PROCEDURE +[id="installation-creating-azure-service-principal_{context}"] += Creating a service principal + +The installation program requires an Azure identity to complete the installation. You can use a service principal. + +If you are unable to use a service principal, you can use a managed identity. + +.Prerequisites + +* You have installed or updated the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI]. +* You have an Azure subscription ID. +* If you are not going to assign the the `Contributor` and `User Administrator Access` roles to the service principal, you have created a custom role with the required Azure permissions. + +.Procedure + +. Create the service principal for your account by running the following command: ++ +[source,terminal] +---- +$ az ad sp create-for-rbac --role \// <1> + --name \// <2> + --scopes /subscriptions/ <3> +---- +<1> Defines the role name. You can use the `Contributor` role, or you can specify a custom role which contains the necessary permissions. +<2> Defines the service principal name. +<3> Specifies the subscription ID. ++ +.Example output +[source,terminal] +---- +Creating 'Contributor' role assignment under scope '/subscriptions/' +The output includes credentials that you must protect. Be sure that you do not +include these credentials in your code or check the credentials into your source +control. For more information, see https://aka.ms/azadsp-cli +{ + "appId": "axxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "displayName": ", + "password": "00000000-0000-0000-0000-000000000000", + "tenantId": "8xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +} +---- + +. Record the values of the `appId` and `password` parameters from the output. You require these values when installing the cluster. + +. If you applied the `Contributor` role to your service principal, assign the `User Administrator Access` role by running the following command: ++ +[source,terminal] +---- +$ az role assignment create --role "User Access Administrator" \ + --assignee-object-id $(az ad sp show --id --query id -o tsv) <1> +---- +<1> Specify the `appId` parameter value for your service principal. diff --git a/modules/installation-initializing.adoc b/modules/installation-initializing.adoc index a1f1f0e4ef04..4a37a1acc108 100644 --- a/modules/installation-initializing.adoc +++ b/modules/installation-initializing.adoc @@ -210,30 +210,40 @@ endif::nutanix[] .Prerequisites -* Obtain the {product-title} installation program and the pull secret for your cluster. +* You have the {product-title} installation program and the pull secret for your cluster. ifdef::restricted[] For a restricted network installation, these files are on your mirror host. ifndef::nutanix[] -* Have the `imageContentSources` values that were generated during mirror registry creation. +* You have the `imageContentSources` values that were generated during mirror registry creation. endif::nutanix[] ifdef::nutanix+restricted[] -* Have the `imageContentSourcePolicy.yaml` file that was created when you mirrored your registry. -* Have the location of the {op-system-first} image you download. +* You have the `imageContentSourcePolicy.yaml` file that was created when you mirrored your registry. +* You have the location of the {op-system-first} image you download. endif::nutanix+restricted[] -* Obtain the contents of the certificate for your mirror registry. +* You have obtained the contents of the certificate for your mirror registry. ifndef::aws,gcp[] -* Retrieve a {op-system-first} image and upload it to an accessible location. +* You have retrieved a {op-system-first} image and uploaded it to an accessible location. endif::aws,gcp[] endif::restricted[] -ifndef::nutanix[] -* Obtain service principal permissions at the subscription level. -endif::nutanix[] +ifdef::azure[] +* You have an Azure subscription ID and tenant ID. +* If you are installing the cluster using a service principal, you have its application ID and password. +* If you are installing the cluster using a system-assigned managed identity, you have enabled it on the virtual machine that you will run the installation program from. +* If you are installing the cluster using a user-assigned managed identity, you have met these prerequisites: +** You have its client ID. +** You have assigned it to the virtual machine that you will run the installation program from. +endif::azure[] ifdef::nutanix[] -* Verify that you have met the Nutanix networking requirements. For more information, see "Preparing to install on Nutanix". +* You have verified that you have met the Nutanix networking requirements. For more information, see "Preparing to install on Nutanix". endif::nutanix[] .Procedure +ifdef::azure[] +. Optional: If you have run the installation program on this computer before, and want to use an alternative service principal or managed identity, go to the `~/.azure/` directory and delete the `osServicePrincipal.json` configuration file. ++ +Deleting this file prevents the installation program from automatically reusing subscription and authentication values from a previous installation. +endif::azure[] . Create the `install-config.yaml` file. + .. Change to the directory that contains the installation program and run the following command: @@ -248,7 +258,13 @@ files that the installation program creates. When specifying the directory: * Verify that the directory has the `execute` permission. This permission is required to run Terraform binaries under the installation directory. * Use an empty directory. Some installation assets, such as bootstrap X.509 certificates, have short expiration intervals, therefore you must not reuse an installation directory. If you want to reuse individual files from another cluster installation, you can copy them into your directory. However, the file names for the installation assets might change between releases. Use caution when copying installation files from an earlier {product-title} version. - +.. At the prompts, provide the configuration details for your cloud: +... Optional: Select an SSH key to use to access your cluster machines. ++ +[NOTE] +==== +For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. +==== ifdef::alibabacloud-default,alibabacloud-custom,alibabacloud-vpc[] ... Select *alibabacloud* as the platform to target. ... Select the region to deploy the cluster to. @@ -265,16 +281,19 @@ installation program. endif::aws[] ifdef::azure[] ... Select *azure* as the platform to target. -... If you do not have a Microsoft Azure profile stored on your computer, specify the -following Azure parameter values for your subscription and service principal: -**** *azure subscription id*: The subscription ID to use for the cluster. -Specify the `id` value in your account output. -**** *azure tenant id*: The tenant ID. Specify the `tenantId` value in your -account output. -**** *azure service principal client id*: The value of the `appId` parameter -for the service principal. -**** *azure service principal client secret*: The value of the `password` -parameter for the service principal. ++ +If the installation program cannot locate the `osServicePrincipal.json` configuration file from a previous installation, you are prompted for Azure subscription and authentication values. +... Enter the following Azure parameter values for your subscription: +**** *azure subscription id*: Enter the subscription ID to use for the cluster. +**** *azure tenant id*: Enter the tenant ID. +... Depending on the Azure identity you are using to deploy the cluster, do one of the following when prompted for the *azure service principal client id*: +**** If you are using a service principal, enter its application ID. +**** If you are using a system-assigned managed identity, leave this value blank. +**** If you are using a user-assigned managed identity, specify its client ID. +... Depending on the Azure identity you are using to deploy the cluster, do one of the following when prompted for the *azure service principal client secret*: +**** If you are using a service principal, enter its password. +**** If you are using a system-assigned managed identity, leave this value blank. +**** If you are using a user-assigned managed identity, leave this value blank. ... Select the region to deploy the cluster to. ... Select the base domain to deploy the cluster to. The base domain corresponds to the Azure DNS Zone that you created for your cluster. @@ -558,6 +577,10 @@ The `install-config.yaml` file is consumed during the installation process. If you want to reuse the file, you must back it up now. ==== +ifdef::azure[] +If previously not detected, the installation program creates an `osServicePrincipal.json` configuration file and stores this file in the `~/.azure/` directory on your computer. This ensures that the installation program can load the profile when it is creating an {product-title} cluster on the target platform. +endif::azure[] + ifdef::osp-user[You now have the file `install-config.yaml` in the directory that you specified.] ifeval::["{context}" == "installing-alibaba-default"] diff --git a/modules/installation-launching-installer.adoc b/modules/installation-launching-installer.adoc index 687303dc8f91..0836481b7922 100644 --- a/modules/installation-launching-installer.adoc +++ b/modules/installation-launching-installer.adoc @@ -110,6 +110,7 @@ endif::[] ifeval::["{context}" == "installing-azure-default"] :no-config: :azure: +:azure-default: endif::[] ifeval::["{context}" == "installing-gcp-customizations"] :custom-config: @@ -147,7 +148,7 @@ endif::[] ifeval::["{context}" == "installing-azure-government-region"] :custom-config: :azure: -:single-step: +:azure-gov: endif::[] ifeval::["{context}" == "installing-azure-vnet"] :custom-config: @@ -162,7 +163,7 @@ endif::[] ifeval::["{context}" == "installing-azure-private"] :custom-config: :azure: -:single-step: +:azure-private: endif::[] ifeval::["{context}" == "installing-azure-stack-hub-default"] :custom-config: @@ -271,15 +272,27 @@ You can run the `create cluster` command of the installation program only once, .Prerequisites -ifndef::osp,vsphere,nutanix[* Configure an account with the cloud platform that hosts your cluster.] - -* Obtain the {product-title} installation program and the pull secret for your -cluster. - -* Verify the cloud provider account on your host has the correct permissions to deploy the cluster. An account with incorrect permissions causes the installation process to fail with an error message that displays the missing permissions. +ifndef::osp,vsphere,nutanix[* You have configured an account with the cloud platform that hosts your cluster.] +* You have the {product-title} installation program and the pull secret for your cluster. +ifdef::azure[] +* You have an Azure subscription ID and tenant ID. +endif::azure[] +ifdef::azure-default[] +* You have the application ID and password of a service principal. +endif::azure-default[] +ifdef::azure-gov,azure-private[] +* If you are installing the cluster using a service principal, you have its application ID and password. +* If you are installing the cluster using a system-assigned managed identity, you have enabled it on the virtual machine that you will run the installation program from. +* If you are installing the cluster using a user-assigned managed identity, you have met these prerequisites: +** You have its client ID. +** You have assigned it to the virtual machine that you will run the installation program from. +endif::azure-gov,azure-private[] +ifndef::azure[] +* You have verified that the cloud provider account on your host has the correct permissions to deploy the cluster. An account with incorrect permissions causes the installation process to fail with an error message that displays the missing permissions. +endif::azure[] ifdef::vsphere[] -* Optional: Before you create the cluster, configure an external load balancer in place of the default load balancer. +* Optional: Before you create the cluster, configure an external load balancer in place of the default load balancer. + [IMPORTANT] ==== @@ -299,9 +312,19 @@ environment variables ** The `gcloud cli` default credentials endif::gcp[] -ifdef::aws,gcp,no-config[] +ifdef::aws,azure-gov,azure-private,gcp,no-config[] +ifdef::azure-default[] +. Optional: If you have run the installation program on this computer before, and want to use an alternative service principal, go to the `~/.azure/` directory and delete the `osServicePrincipal.json` configuration file. ++ +Deleting this file prevents the installation program from automatically reusing subscription and authentication values from a previous installation. +endif::azure-default[] +ifdef::azure-gov,azure-private[] +. Optional: If you have run the installation program on this computer before, and want to use an alternative service principal or managed identity, go to the `~/.azure/` directory and delete the `osServicePrincipal.json` configuration file. ++ +Deleting this file prevents the installation program from automatically reusing subscription and authentication values from a previous installation. +endif::azure-gov,azure-private[] . Change to the directory that contains the installation program and initialize the cluster deployment: -endif::aws,gcp,no-config[] +endif::aws,azure-gov,azure-private,gcp,no-config[] ifdef::single-step[] * Change to the directory that contains the installation program and initialize the cluster deployment: endif::single-step[] @@ -320,6 +343,25 @@ directory name to store the files that the installation program creates. endif::no-config[] <2> To view different installation details, specify `warn`, `debug`, or `error` instead of `info`. + +ifdef::azure-gov,azure-private[] ++ +If the installation program cannot locate the `osServicePrincipal.json` configuration file from a previous installation, you are prompted for Azure subscription and authentication values. +. Enter the following Azure parameter values for your subscription: +** *azure subscription id*: Enter the subscription ID to use for the cluster. +** *azure tenant id*: Enter the tenant ID. +. Depending on the Azure identity you are using to deploy the cluster, do one of the following when prompted for the *azure service principal client id*: +** If you are using a service principal, enter its application ID. +** If you are using a system-assigned managed identity, leave this value blank. +** If you are using a user-assigned managed identity, specify its client ID. +. Depending on the Azure identity you are using to deploy the cluster, do one of the following when prompted for the *azure service principal client secret*: +** If you are using a service principal, enter its password. +** If you are using a system-assigned managed identity, leave this value blank. +** If you are using a user-assigned managed identity,leave this value blank. + +If previously not detected, the installation program creates an `osServicePrincipal.json` configuration file and stores this file in the `~/.azure/` directory on your computer. This ensures that the installation program can load the profile when it is creating an {product-title} cluster on the target platform. +endif::azure-gov,azure-private[] + ifdef::no-config[] + When specifying the directory: @@ -346,27 +388,18 @@ The AWS access key ID and secret access key are stored in `~/.aws/credentials` i .. Select the AWS region to deploy the cluster to. .. Select the base domain for the Route 53 service that you configured for your cluster. endif::aws[] -ifdef::azure,ash[] +ifdef::azure[] .. Select *azure* as the platform to target. -.. If the installation program cannot locate the `osServicePrincipal.json` configuration file, which contains Microsoft Azure profile information, in the `~/.azure/` directory on your computer, the installer prompts you to specify the following Azure parameter values for your subscription and service principal. -*** *azure subscription id*: The subscription ID to use for the cluster. -Specify the `id` value in your account output. -*** *azure tenant id*: The tenant ID. Specify the `tenantId` value in your -account output. -*** *azure service principal client id*: The value of the `appId` parameter -for the service principal. -*** *azure service principal client secret*: The value of the `password` -parameter for the service principal. + -[IMPORTANT] -==== -After you enter values for the previously listed parameters, the installation program creates a `osServicePrincipal.json` configuration file and stores this file in -the `~/.azure/` directory on your computer. These actions ensure that the installation program can load the profile when it is creating an {product-title} cluster on the target platform. -==== +If the installation program cannot locate the `osServicePrincipal.json` configuration file from a previous installation, you are prompted for Azure subscription and authentication values. +.. Specify the following Azure parameter values for your subscription and service principal: +*** *azure subscription id*: Enter the subscription ID to use for the cluster. +*** *azure tenant id*: Enter the tenant ID. +*** *azure service principal client id*: Enter its application ID. +*** *azure service principal client secret*: Enter its password. .. Select the region to deploy the cluster to. -.. Select the base domain to deploy the cluster to. The base domain corresponds -to the Azure DNS Zone that you created for your cluster. -endif::azure,ash[] +.. Select the base domain to deploy the cluster to. The base domain corresponds to the Azure DNS Zone that you created for your cluster. +endif::azure[] ifdef::gcp[] .. Select *gcp* as the platform to target. .. If you have not configured the service account key for your GCP account on @@ -422,11 +455,8 @@ ifdef::azure[] + [IMPORTANT] ==== -All Azure resources that are available through public endpoints are subject to -resource name restrictions, and you cannot create resources that use certain -terms. For a list of terms that Azure restricts, see -link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors] -in the Azure documentation. +All Azure resources that are available through public endpoints are subject to resource name restrictions, and you cannot create resources that use certain terms. For a list of terms that Azure restricts, see +link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resourcename[Resolve reserved resource name errors] in the Azure documentation. ==== endif::azure[] ifdef::gcp[] @@ -443,6 +473,10 @@ ifdef::openshift-origin[] * If you do not need the cluster to pull images from a private registry, you can paste `{"auths":{"fake":{"auth":"aWQ6cGFzcwo="}}}` as the pull secret. endif::openshift-origin[] +ifdef::azure[] +If previously not detected, the installation program creates an `osServicePrincipal.json` configuration file and stores this file in the `~/.azure/` directory on your computer. This ensures that the installation program can load the profile when it is creating an {product-title} cluster on the target platform. +endif::azure[] + endif::no-config[] ifdef::aws[] @@ -554,6 +588,7 @@ endif::[] ifeval::["{context}" == "installing-azure-default"] :!no-config: :!azure: +:!azure-default: endif::[] ifeval::["{context}" == "installing-azure-network-customizations"] :!custom-config: @@ -596,7 +631,7 @@ endif::[] ifeval::["{context}" == "installing-azure-government-region"] :!custom-config: :!azure: -:!single-step: +:!azure-gov: endif::[] ifeval::["{context}" == "installing-azure-vnet"] :!custom-config: @@ -606,7 +641,7 @@ endif::[] ifeval::["{context}" == "installing-azure-private"] :!custom-config: :!azure: -:!single-step: +:!azure-private: endif::[] ifeval::["{context}" == "installing-azure-stack-hub-default"] :!custom-config: diff --git a/modules/installation-using-azure-managed-identities.adoc b/modules/installation-using-azure-managed-identities.adoc new file mode 100644 index 000000000000..774c7897cf0e --- /dev/null +++ b/modules/installation-using-azure-managed-identities.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * installing/installing_azure/installing-azure-account.adoc + +:_content-type: PROCEDURE +[id="installation-using-azure-managed-identities_{context}"] += Using Azure managed identities + +The installation program requires an Azure identity to complete the installation. You can use either a system-assigned or user-assigned managed identity. + +If you are unable to use a managed identity, you can use a service principal. + +.Procedure + +. If you are using a system-assigned managed identity, enable it on the virtual machine that you will run the installation program from. +. If you are using a user-assigned managed identity: +.. Assign it to the virtual machine that you will run the installation program from. +.. Record its client ID. You require this value when installing the cluster. ++ +For more information about viewing the details of a user-assigned managed identity, see the Microsoft Azure documentation for link:https:https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp#list-user-assigned-managed-identities[listing user-assigned managed identities]. +. Verify that the required permissions are assigned to the managed identity. diff --git a/modules/minimum-required-permissions-ipi-azure.adoc b/modules/minimum-required-permissions-ipi-azure.adoc index abb45058008e..9968d75955a3 100644 --- a/modules/minimum-required-permissions-ipi-azure.adoc +++ b/modules/minimum-required-permissions-ipi-azure.adoc @@ -2,12 +2,20 @@ // // * installing/installing_azure/installing-azure-account.adoc +:_content-type: CONCEPT [id="minimum-required-permissions-ipi-azure_{context}"] = Required Azure permissions for installer-provisioned infrastructure -When you assign `Contributor` and `User Access Administrator` roles to the service principal, you automatically grant all the required permissions. +The installation program requires access to an Azure service principal or managed identity with the necessary permissions to deploy the cluster and to maintain its daily operation. These permissions must be granted to the Azure subscription that is associated with the identity. -If your organization's security policies require a more restrictive set of permissions, you can create a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the necessary permissions. The following permissions are required for creating an {product-title} cluster on Microsoft Azure. +The following options are available to you: + +* You can assign the identity the `Contributor` and `User Access Administrator` roles. Assigning these roles is the quickest way to grant all of the required permissions. ++ +For more information about assigning roles, see the Azure documentation for link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[managing access to Azure resources using the Azure portal]. +* If your organization's security policies require a more restrictive set of permissions, you can create a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the necessary permissions. + +The following permissions are required for creating an {product-title} cluster on Microsoft Azure. .Required permissions for creating authorization resources [%collapsible] @@ -277,4 +285,4 @@ The following permissions are not required to delete a private {product-title} c To install {product-title} on Azure, you must scope the permissions to your subscription. Later, you can re-scope these permissions to the installer created resource group. If the public DNS zone is present in a different resource group, then the network DNS zone related permissions must always be applied to your subscription. By default, the {product-title} installation program assigns the Azure identity the `Contributor` role. You can scope all the permissions to your subscription when deleting an {product-title} cluster. -==== \ No newline at end of file +==== diff --git a/modules/minimum-required-permissions-upi-azure.adoc b/modules/minimum-required-permissions-upi-azure.adoc index cf53674d87de..7a933a9223b8 100644 --- a/modules/minimum-required-permissions-upi-azure.adoc +++ b/modules/minimum-required-permissions-upi-azure.adoc @@ -5,9 +5,16 @@ [id="minimum-required-permissions-upi-azure_{context}"] = Required Azure permissions for user-provisioned infrastructure -When you assign `Contributor` and `User Access Administrator` roles to the service principal, you automatically grant all the required permissions. +The installation program requires access to an Azure service principal or managed identity with the necessary permissions to deploy the cluster and to maintain its daily operation. These permissions must be granted to the Azure subscription that is associated with the identity. -If your organization's security policies require a more restrictive set of permissions, you can create a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the necessary permissions. The following permissions are required for creating an {product-title} cluster on Microsoft Azure. +The following options are available to you: + +* You can assign the identity the `Contributor` and `User Access Administrator` roles. Assigning these roles is the quickest way to grant all of the required permissions. ++ +For more information about assigning roles, see the Azure documentation for link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[managing access to Azure resources using the Azure portal]. +* If your organization's security policies require a more restrictive set of permissions, you can create a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the necessary permissions. + +The following permissions are required for creating an {product-title} cluster on Microsoft Azure. .Required permissions for creating authorization resources [%collapsible] @@ -239,4 +246,4 @@ The following permissions are required for deleting an {product-title} cluster o To install {product-title} on Azure, you must scope the permissions related to resource group creation to your subscription. After the resource group is created, you can scope the rest of the permissions to the created resource group. If the public DNS zone is present in a different resource group, then the network DNS zone related permissions must always be applied to your subscription. You can scope all the permissions to your subscription when deleting an {product-title} cluster. -==== \ No newline at end of file +====