Skip to content

Commit 4366dd7

Browse files
mjpytlakmjpytlak
committed
OSDOCS#5126: Using an Azure managed identity as an alternative to a service principal
1 parent 23e8a47 commit 4366dd7

10 files changed

+362
-70
lines changed

‎installing/installing_azure/installing-azure-account.adoc

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9-
Before you can install {product-title}, you must configure a Microsoft Azure
10-
account.
9+
Before you can install {product-title}, you must configure a Microsoft Azure account to meet installation requirements.
1110

1211
[IMPORTANT]
1312
====
@@ -29,11 +28,13 @@ include::modules/installation-azure-network-config.adoc[leveloffset=+1]
2928

3029
include::modules/installation-azure-increasing-limits.adoc[leveloffset=+1]
3130

32-
include::modules/installation-azure-permissions.adoc[leveloffset=+1]
31+
include::modules/installation-azure-subscription-tenant-id.adoc[leveloffset=+1]
3332

34-
include::modules/minimum-required-permissions-ipi-azure.adoc[leveloffset=+1]
33+
include::modules/installation-azure-identities.adoc[leveloffset=+1]
3534

36-
include::modules/installation-azure-service-principal.adoc[leveloffset=+1]
35+
include::modules/minimum-required-permissions-ipi-azure.adoc[leveloffset=+2]
36+
include::modules/installation-using-azure-managed-identities.adoc[leveloffset=+2]
37+
include::modules/installation-creating-azure-service-principal.adoc[leveloffset=+2]
3738

3839
[role="_additional-resources"]
3940
.Additional resources

‎installing/installing_azure/installing-azure-user-infra.adoc

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,15 @@ include::modules/installation-azure-increasing-limits.adoc[leveloffset=+2]
5757

5858
include::modules/csr-management.adoc[leveloffset=+2]
5959

60-
include::modules/installation-azure-permissions.adoc[leveloffset=+2]
60+
include::modules/installation-azure-subscription-tenant-id.adoc[leveloffset=+2]
61+
62+
include::modules/installation-azure-identities.adoc[leveloffset=+2]
63+
6164
include::modules/minimum-required-permissions-upi-azure.adoc[leveloffset=+2]
62-
include::modules/installation-azure-service-principal.adoc[leveloffset=+2]
65+
66+
include::modules/installation-using-azure-managed-identities.adoc[leveloffset=+2]
67+
68+
include::modules/installation-creating-azure-service-principal.adoc[leveloffset=+2]
6369

6470
[role="_additional-resources"]
6571
.Additional resources

‎modules/installation-azure-identities.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_azure/installing-azure-account.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="installation-azure-identities_{context}"]
7+
= Supported identities to access Azure resources
8+
9+
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:
10+
11+
* A service principal
12+
* A system-assigned managed identity
13+
* A user-assigned managed identity

‎modules/installation-azure-subscription-tenant-id.adoc

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_azure/installing-azure-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="installation-azure-subscription-tenant-id_{context}"]
7+
= Recording the subscription and tenant IDs
8+
9+
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.
10+
11+
.Prerequisites
12+
13+
* 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].
14+
15+
.Procedure
16+
17+
. Log in to the Azure CLI by running the following command:
18+
+
19+
[source,terminal]
20+
----
21+
$ az login
22+
----
23+
24+
. Ensure that you are using the right subscription:
25+
26+
.. View a list of available subscriptions by running the following command:
27+
+
28+
[source,terminal]
29+
----
30+
$ az account list --refresh
31+
----
32+
+
33+
.Example output
34+
[source,terminal]
35+
----
36+
[
37+
{
38+
"cloudName": "AzureCloud",
39+
"id": "8xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
40+
"isDefault": true,
41+
"name": "Subscription Name 1",
42+
"state": "Enabled",
43+
"tenantId": "6xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
44+
"user": {
45+
"name": "[email protected]",
46+
"type": "user"
47+
}
48+
},
49+
{
50+
"cloudName": "AzureCloud",
51+
"id": "9xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
52+
"isDefault": false,
53+
"name": "Subscription Name 2",
54+
"state": "Enabled",
55+
"tenantId": "7xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
56+
"user": {
57+
"name": "[email protected]",
58+
"type": "user"
59+
}
60+
}
61+
]
62+
----
63+
64+
.. View the details of the active account, and confirm that this is the subscription you want to use, by running the following command:
65+
+
66+
[source,terminal]
67+
----
68+
$ az account show
69+
----
70+
+
71+
.Example output
72+
[source,terminal]
73+
----
74+
{
75+
"environmentName": "AzureCloud",
76+
"id": "8xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
77+
"isDefault": true,
78+
"name": "Subscription Name 1",
79+
"state": "Enabled",
80+
"tenantId": "6xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
81+
"user": {
82+
"name": "[email protected]",
83+
"type": "user"
84+
}
85+
}
86+
----
87+
88+
. If you are not using the right subscription:
89+
90+
.. Change the active subscription by running the following command:
91+
+
92+
[source,terminal]
93+
----
94+
$ az account set -s <subscription_id>
95+
----
96+
97+
.. Verify that you are using the subscription you need by running the following command:
98+
+
99+
[source,terminal]
100+
----
101+
$ az account show
102+
----
103+
+
104+
.Example output
105+
[source,terminal]
106+
----
107+
{
108+
"environmentName": "AzureCloud",
109+
"id": "9xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
110+
"isDefault": true,
111+
"name": "Subscription Name 2",
112+
"state": "Enabled",
113+
"tenantId": "7xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
114+
"user": {
115+
"name": "[email protected]",
116+
"type": "user"
117+
}
118+
}
119+
----
120+
121+
. Record the `id` and `tenantId` parameter values from the output. You require these values to install an {product-title} cluster.

‎modules/installation-creating-azure-service-principal.adoc

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_azure/installing-azure-account.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="installation-creating-azure-service-principal_{context}"]
7+
= Creating a service principal
8+
9+
The installation program requires an Azure identity to complete the installation. You can use a service principal.
10+
11+
If you are unable to use a service principal, you can use a managed identity.
12+
13+
.Prerequisites
14+
15+
* 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].
16+
* You have an Azure subscription ID.
17+
* 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.
18+
19+
.Procedure
20+
21+
. Create the service principal for your account by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ az ad sp create-for-rbac --role <role_name> \// <1>
26+
--name <service_principal> \// <2>
27+
--scopes /subscriptions/<subscription_id> <3>
28+
----
29+
<1> Defines the role name. You can use the `Contributor` role, or you can specify a custom role which contains the necessary permissions.
30+
<2> Defines the service principal name.
31+
<3> Specifies the subscription ID.
32+
+
33+
.Example output
34+
[source,terminal]
35+
----
36+
Creating 'Contributor' role assignment under scope '/subscriptions/<subscription_id>'
37+
The output includes credentials that you must protect. Be sure that you do not
38+
include these credentials in your code or check the credentials into your source
39+
control. For more information, see https://aka.ms/azadsp-cli
40+
{
41+
"appId": "axxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
42+
"displayName": <service_principal>",
43+
"password": "00000000-0000-0000-0000-000000000000",
44+
"tenantId": "8xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
45+
}
46+
----
47+
48+
. Record the values of the `appId` and `password` parameters from the output. You require these values when installing the cluster.
49+
50+
. If you applied the `Contributor` role to your service principal, assign the `User Administrator Access` role by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ az role assignment create --role "User Access Administrator" \
55+
--assignee-object-id $(az ad sp show --id <appId> --query id -o tsv) <1>
56+
----
57+
<1> Specify the `appId` parameter value for your service principal.

‎modules/installation-initializing.adoc

Lines changed: 44 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -210,30 +210,40 @@ endif::nutanix[]
210210

211211
.Prerequisites
212212

213-
* Obtain the {product-title} installation program and the pull secret for your cluster.
213+
* You have the {product-title} installation program and the pull secret for your cluster.
214214
ifdef::restricted[]
215215
For a restricted network installation, these files are on your mirror host.
216216
ifndef::nutanix[]
217-
* Have the `imageContentSources` values that were generated during mirror registry creation.
217+
* You have the `imageContentSources` values that were generated during mirror registry creation.
218218
endif::nutanix[]
219219
ifdef::nutanix+restricted[]
220-
* Have the `imageContentSourcePolicy.yaml` file that was created when you mirrored your registry.
221-
* Have the location of the {op-system-first} image you download.
220+
* You have the `imageContentSourcePolicy.yaml` file that was created when you mirrored your registry.
221+
* You have the location of the {op-system-first} image you download.
222222
endif::nutanix+restricted[]
223-
* Obtain the contents of the certificate for your mirror registry.
223+
* You have obtained the contents of the certificate for your mirror registry.
224224
ifndef::aws,gcp[]
225-
* Retrieve a {op-system-first} image and upload it to an accessible location.
225+
* You have retrieved a {op-system-first} image and uploaded it to an accessible location.
226226
endif::aws,gcp[]
227227
endif::restricted[]
228-
ifndef::nutanix[]
229-
* Obtain service principal permissions at the subscription level.
230-
endif::nutanix[]
228+
ifdef::azure[]
229+
* You have an Azure subscription ID and tenant ID.
230+
* If you are installing the cluster using a service principal, you have its application ID and password.
231+
* 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.
232+
* If you are installing the cluster using a user-assigned managed identity, you have met these prerequisites:
233+
** You have its client ID.
234+
** You have assigned it to the virtual machine that you will run the installation program from.
235+
endif::azure[]
231236
ifdef::nutanix[]
232-
* Verify that you have met the Nutanix networking requirements. For more information, see "Preparing to install on Nutanix".
237+
* You have verified that you have met the Nutanix networking requirements. For more information, see "Preparing to install on Nutanix".
233238
endif::nutanix[]
234239
235240
.Procedure
236241

242+
ifdef::azure[]
243+
. 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.
244+
+
245+
Deleting this file prevents the installation program from automatically reusing subscription and authentication values from a previous installation.
246+
endif::azure[]
237247
. Create the `install-config.yaml` file.
238248
+
239249
.. Change to the directory that contains the installation program and run the following command:
@@ -248,7 +258,13 @@ files that the installation program creates.
248258
When specifying the directory:
249259
* Verify that the directory has the `execute` permission. This permission is required to run Terraform binaries under the installation directory.
250260
* 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.
251-
261+
.. At the prompts, provide the configuration details for your cloud:
262+
... Optional: Select an SSH key to use to access your cluster machines.
263+
+
264+
[NOTE]
265+
====
266+
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.
267+
====
252268
ifdef::alibabacloud-default,alibabacloud-custom,alibabacloud-vpc[]
253269
... Select *alibabacloud* as the platform to target.
254270
... Select the region to deploy the cluster to.
@@ -265,16 +281,19 @@ installation program.
265281
endif::aws[]
266282
ifdef::azure[]
267283
... Select *azure* as the platform to target.
268-
... If you do not have a Microsoft Azure profile stored on your computer, specify the
269-
following Azure parameter values for your subscription and service principal:
270-
**** *azure subscription id*: The subscription ID to use for the cluster.
271-
Specify the `id` value in your account output.
272-
**** *azure tenant id*: The tenant ID. Specify the `tenantId` value in your
273-
account output.
274-
**** *azure service principal client id*: The value of the `appId` parameter
275-
for the service principal.
276-
**** *azure service principal client secret*: The value of the `password`
277-
parameter for the service principal.
284+
+
285+
If the installation program cannot locate the `osServicePrincipal.json` configuration file from a previous installation, you are prompted for Azure subscription and authentication values.
286+
... Enter the following Azure parameter values for your subscription:
287+
**** *azure subscription id*: Enter the subscription ID to use for the cluster.
288+
**** *azure tenant id*: Enter the tenant ID.
289+
... 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*:
290+
**** If you are using a service principal, enter its application ID.
291+
**** If you are using a system-assigned managed identity, leave this value blank.
292+
**** If you are using a user-assigned managed identity, specify its client ID.
293+
... 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*:
294+
**** If you are using a service principal, enter its password.
295+
**** If you are using a system-assigned managed identity, leave this value blank.
296+
**** If you are using a user-assigned managed identity, leave this value blank.
278297
... Select the region to deploy the cluster to.
279298
... Select the base domain to deploy the cluster to. The base domain corresponds
280299
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
558577
you want to reuse the file, you must back it up now.
559578
====
560579
580+
ifdef::azure[]
581+
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.
582+
endif::azure[]
583+
561584
ifdef::osp-user[You now have the file `install-config.yaml` in the directory that you specified.]
562585
563586
ifeval::["{context}" == "installing-alibaba-default"]

0 commit comments

Comments
 (0)