Skip to content

Commit 3d01a76

Browse files
apinnickapinnick
committed
GH#45375: Azure installation admin role
1 parent fcc165a commit 3d01a76

File tree

1 file changed

+32
-86
lines changed

1 file changed

+32
-86
lines changed

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

Lines changed: 32 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -16,42 +16,39 @@ endif::[]
1616
[id="installation-azure-service-principal_{context}"]
1717
= Creating a service principal
1818

19-
Because {product-title} and its installation program must create Microsoft Azure
20-
resources through Azure Resource Manager, you must create a service principal
21-
to represent it.
19+
Because {product-title} and its installation program create Microsoft Azure resources by using the Azure Resource Manager, you must create a service principal to represent it.
2220

2321
.Prerequisites
2422

2523
* Install or update the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI].
26-
* Install the `jq` package.
2724
* Your Azure account has the required roles for the subscription that you use.
2825
2926
.Procedure
3027

3128
ifdef::ash[]
32-
. Register your Azure Stack Cloud environment with your Azure CLI. For more details on this process, see Microsoft's documentation for link:https://docs.microsoft.com/en-us/azure-stack/mdc/azure-stack-version-profiles-azurecli-2-tzl#connect-to-azure-stack-hub[Connecting to Azure Stack Hub].
33-
34-
.. Register your environment with the Azure CLI:
29+
. Register your environment:
3530
+
3631
[source,terminal]
3732
----
38-
$ az cloud register -n <environment_name> --endpoint-resource-manager <arm_endpoint>
33+
$ az cloud register -n AzureStackCloud --endpoint-resource-manager <endpoint> <1>
3934
----
35+
<1> Specify the Azure Resource Manager endpoint, \`https://management.<region>.<fqdn>/`.
36+
+
37+
See the link:https://docs.microsoft.com/en-us/azure-stack/mdc/azure-stack-version-profiles-azurecli-2-tzl#connect-to-azure-stack-hub[Microsoft documentation] for details.
4038

41-
.. Set the active environment:
39+
. Set the active environment:
4240
+
4341
[source,terminal]
4442
----
45-
$ az cloud set -n <environment_name>
43+
$ az cloud set -n AzureStackCloud
4644
----
4745

48-
.. Update your environment configuration to use the specific API version for Azure Stack Hub:
46+
. Update your environment configuration to use the specific API version for Azure Stack Hub:
4947
+
5048
[source,terminal]
5149
----
5250
$ az cloud update --profile 2019-03-01-hybrid
5351
----
54-
5552
endif::ash[]
5653

5754
. Log in to the Azure CLI:
@@ -60,14 +57,14 @@ endif::ash[]
6057
----
6158
$ az login
6259
----
63-
+
64-
Log in to Azure in the web console by using your credentials.
6560
ifdef::ash[]
61+
+
6662
If you are in a multitenant environment, you must also supply the tenant ID.
6763
endif::ash[]
6864

6965
. If your Azure account uses subscriptions, ensure that you are using the right
70-
subscription.
66+
subscription:
67+
7168
.. View the list of available accounts and record the `tenantId` value for the
7269
subscription you want to use for your cluster:
7370
+
@@ -129,19 +126,17 @@ endif::[]
129126
}
130127
}
131128
----
132-
<1> Ensure that the value of the `tenantId` parameter is the UUID of the
133-
correct subscription.
129+
<1> Ensure that the value of the `tenantId` parameter is the correct subscription ID.
134130

135131
.. If you are not using the right subscription, change the active subscription:
136132
+
137133
[source,terminal]
138134
----
139-
$ az account set -s <id> <1>
135+
$ az account set -s <subscription_id> <1>
140136
----
141-
<1> Substitute the value of the `id` for the subscription that you want to
142-
use for `<id>`.
137+
<1> Specify the subscription ID.
143138

144-
.. If you changed the active subscription, display your account information again:
139+
.. Verify the subscription ID update:
145140
+
146141
[source,terminal]
147142
----
@@ -170,94 +165,45 @@ endif::[]
170165
}
171166
----
172167

173-
. Record the values of the `tenantId` and `id` parameters from the previous
174-
output. You need these values during {product-title} installation.
168+
. Record the `tenantId` and `id` parameter values from the output. You need these values during the {product-title} installation.
175169

176170
. Create the service principal for your account:
177171
+
178172
[source,terminal]
179173
----
180-
$ az ad sp create-for-rbac --role Contributor --name <service_principal> <1>
174+
$ az ad sp create-for-rbac --role Contributor --name <service_principal> \ <1>
175+
--scopes /subscriptions/<subscription_id> <2>
181176
----
182-
<1> Replace `<service_principal>` with the name to assign to the service principal.
177+
<1> Specify the service principal name.
178+
<2> Specify the subscription ID.
183179
+
184180
.Example output
185181
[source,terminal]
186182
----
187-
Changing "<service_principal>" to a valid URI of "http://<service_principal>", which is the required format used for service principal names
188-
Retrying role assignment creation: 1/36
189-
Retrying role assignment creation: 2/36
190-
Retrying role assignment creation: 3/36
191-
Retrying role assignment creation: 4/36
183+
Creating 'Contributor' role assignment under scope '/subscriptions/<subscription_id>'
184+
The output includes credentials that you must protect. Be sure that you do not
185+
include these credentials in your code or check the credentials into your source
186+
control. For more information, see https://aka.ms/azadsp-cli
192187
{
193-
"appId": "8bd0d04d-0ac2-43a8-928d-705c598c6956",
194-
"displayName": "<service_principal>",
195-
"name": "http://<service_principal>",
196-
"password": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
197-
"tenant": "6048c7e9-b2ad-488d-a54e-dc3f6be6a7ee"
188+
"appId": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
189+
"displayName": <service_principal>",
190+
"password": "00000000-0000-0000-0000-000000000000",
191+
"tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee"
198192
}
199193
----
200194

201195
. Record the values of the `appId` and `password` parameters from the previous
202196
output. You need these values during {product-title} installation.
203197

204198
ifndef::ash[]
205-
. Grant additional permissions to the service principal.
206-
+
207-
--
208-
** You must always add the `Contributor` and `User Access Administrator` roles to the app registration service principal so the cluster can assign credentials for its components.
209-
** To operate the Cloud Credential Operator (CCO) in _mint mode_, the app registration service principal also requires the `Azure Active Directory Graph/Application.ReadWrite.OwnedBy` API permission.
210-
** To operate the CCO in _passthrough mode_, the app registration service principal does not require additional API permissions.
211-
--
212-
+
213-
For more information about CCO modes, see "About the Cloud Credential Operator" in the "Managing cloud provider credentials" section of the _Authentication and authorization_ guide.
214-
+
215-
[NOTE]
216-
====
217-
If you limit the service principal scope of the {product-title} installation program to an already existing Azure resource group, you must ensure all other resources used by the installation program in your environment have the necessary permissions, such as the public DNS zone and virtual network. Destroying a cluster using the installation program deletes this resource group.
218-
====
219-
220-
.. To assign the `User Access Administrator` role, run the following command:
199+
. Assign the `User Access Administrator` role by running the following command:
221200
+
222201
[source,terminal]
223202
----
224203
$ az role assignment create --role "User Access Administrator" \
225-
--assignee-object-id $(az ad sp list --filter "appId eq '<appId>'" \
226-
| jq '.[0].id' -r) <1>
227-
----
228-
<1> Replace `<appId>` with the `appId` parameter value for your service principal.
229-
230-
.. To assign the `Azure Active Directory Graph` permission, run the following
231-
command:
232-
+
233-
[source,terminal]
234-
----
235-
$ az ad app permission add --id <appId> \ <1>
236-
--api 00000002-0000-0000-c000-000000000000 \
237-
--api-permissions 824c81eb-e3f8-4ee6-8f6d-de7f50d565b7=Role
238-
----
239-
<1> Replace `<appId>` with the `appId` parameter value for your service principal.
240-
+
241-
.Example output
242-
[source,terminal]
243-
----
244-
Invoking "az ad app permission grant --id 46d33abc-b8a3-46d8-8c84-f0fd58177435 --api 00000002-0000-0000-c000-000000000000" is needed to make the change effective
245-
----
246-
+
247-
For more information about the specific permissions that you grant with this
248-
command, see the
249-
link:https://blogs.msdn.microsoft.com/aaddevsup/2018/06/06/guid-table-for-windows-azure-active-directory-permissions/[GUID Table for Windows Azure Active Directory Permissions].
250-
.. Approve the permissions request. If your account does not have the
251-
Azure Active Directory tenant administrator role, follow the guidelines for
252-
your organization to request that the tenant administrator approve your
253-
permissions request.
254-
+
255-
[source, terminal]
256-
----
257-
$ az ad app permission grant --id <appId> \ <1>
258-
--api 00000002-0000-0000-c000-000000000000
204+
--assignee-object-id $(az ad sp show --id <appId> --query id -o tsv) <1>
259205
----
260-
<1> Replace `<appId>` with the `appId` parameter value for your service principal.
206+
<1> Specify the `appId` parameter value for your service principal.
261207
endif::ash[]
262208

263209
ifeval::["{context}" == "installing-azure-stack-hub-user-infra"]

0 commit comments

Comments
 (0)