Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

OSDOCS#5384: Document the explicit list of required credential permissions for Azure #56274

Merged
merged 1 commit into from
Apr 5, 2023
Merged

OSDOCS#5384: Document the explicit list of required credential permissions for Azure #56274

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 3 additions & 2 deletions installing/installing_azure/installing-azure-account.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ include::modules/installation-azure-increasing-limits.adoc[leveloffset=+1]

include::modules/installation-azure-permissions.adoc[leveloffset=+1]

include::modules/minimum-required-permissions-ipi-azure.adoc[leveloffset=+1]

include::modules/installation-azure-service-principal.adoc[leveloffset=+1]

[role="_additional-resources"]
Expand All @@ -42,5 +44,4 @@ include::modules/installation-azure-regions.adoc[leveloffset=+1]
* Install an {product-title} cluster on Azure. You can
xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[install a customized cluster]
or
xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[quickly install a cluster]
with default options.
xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[quickly install a cluster] with default options.
1 change: 1 addition & 0 deletions installing/installing_azure/installing-azure-user-infra.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ 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/minimum-required-permissions-upi-azure.adoc[leveloffset=+2]
include::modules/installation-azure-service-principal.adoc[leveloffset=+2]

[role="_additional-resources"]
Expand Down
11 changes: 11 additions & 0 deletions modules/installation-azure-create-resource-group-and-identity.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,17 @@ $ export RESOURCE_GROUP_ID=`az group show -g ${RESOURCE_GROUP} --query id --out
----
$ az role assignment create --assignee "${PRINCIPAL_ID}" --role 'Contributor' --scope "${RESOURCE_GROUP_ID}"
----
+
[NOTE]
====
If you want to assign a custom role with all the required permissions to the identity, run the following command:
[source,terminal]
----
$ az role assignment create --assignee "${PRINCIPAL_ID}" --role <custom_role> \ <1>
--scope "${RESOURCE_GROUP_ID}"
----
<1> Specifies the custom role name.
====
endif::azure[]

ifeval::["{context}" == "installing-azure-user-infra"]
Expand Down
51 changes: 51 additions & 0 deletions modules/installation-azure-finalizing-encryption.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,30 @@
// * installing/installing_azure/installing-azure-private.adoc
// * installing/installing_azure/installing-azure-vnet.adoc


ifeval::["{context}" == "installing-azure-customizations"]
:azure-public:
endif::[]
ifeval::["{context}" == "installing-azure-government-region"]
:azure-gov:
endif::[]
ifeval::["{context}" == "installing-azure-network-customizations"]
:azure-public:
endif::[]
ifeval::["{context}" == "installing-azure-private"]
:azure-public:
endif::[]
ifeval::["{context}" == "installing-azure-vnet"]
:azure-public:
endif::[]

:_content-type: PROCEDURE
[id="finalizing-encryption_{context}"]
= Finalizing user-managed encryption after installation
If you installed {product-title} using a user-managed encryption key, you can complete the installation by creating a new storage class and granting write permissions to the Azure cluster resource group.

.Procedure

. Obtain the identity of the cluster resource group used by the installer:
.. If you specified an existing resource group in `install-config.yaml`, obtain its Azure identity by running the following command:
+
Expand Down Expand Up @@ -63,6 +81,7 @@ $ az identity show -g <cluster_resource_group> \// <1>
<1> Specifies the name of the cluster resource group created by the installation program.
<2> Specifies the name of the cluster service principal created by the installation program.
The identity is in the format of `12345678-1234-1234-1234-1234567890`.
ifdef::azure-gov[]
. Create a role assignment that grants the cluster service principal `Contributor` privileges to the disk encryption set by running the following command:
+
[source,terminal]
Expand All @@ -73,6 +92,20 @@ $ az role assignment create --assignee <cluster_service_principal_id> \// <1>
----
<1> Specifies the ID of the cluster service principal obtained in the previous step.
<2> Specifies the ID of the disk encryption set.
endif::azure-gov[]
ifdef::azure-public[]
. Create a role assignment that grants the cluster service principal necessary privileges to the disk encryption set by running the following command:
+
[source,terminal]
----
$ az role assignment create --assignee <cluster_service_principal_id> \// <1>
--role <privileged_role> \// <2>
--scope <disk_encryption_set_id> \// <3>
----
<1> Specifies the ID of the cluster service principal obtained in the previous step.
<2> Specifies the Azure role name. You can use the `Contributor` role or a custom role with the necessary permissions.
<3> Specifies the ID of the disk encryption set.
endif::azure-public[]
+
. Create a storage class that uses the user-managed disk encryption set:
.. Save the following storage class definition to a file, for example `storage-class-definition.yaml`:
Expand Down Expand Up @@ -102,3 +135,21 @@ volumeBindingMode: WaitForFirstConsumer
$ oc create -f storage-class-definition.yaml
----
. Select the `managed-premium` storage class when you create persistent volumes to use encrypted storage.



ifeval::["{context}" == "installing-azure-customizations"]
:!azure-public:
endif::[]
ifeval::["{context}" == "installing-azure-government-region"]
:!azure-gov:
endif::[]
ifeval::["{context}" == "installing-azure-network-customizations"]
:!azure-public:
endif::[]
ifeval::["{context}" == "installing-azure-private"]
:!azure-public:
endif::[]
ifeval::["{context}" == "installing-azure-vnet"]
:!azure-public:
endif::[]
4 changes: 1 addition & 3 deletions modules/installation-azure-permissions.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,4 @@
* `User Access Administrator`
* `Owner`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be Contributor. I will create a separate bug to address this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xenolinux We can address this as part of separate PR, may be through a Bug, as this is not part of this work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay. Ack

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reverting the changes

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created https://issues.redhat.com/browse/OCPBUGS-8088 to address this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created the PR for above bug #56648


To set roles on the Azure portal, see the
link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[Manage access to Azure resources using RBAC and the Azure portal]
in the Azure documentation.
To set roles on the Azure portal, see the link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[Manage access to Azure resources using RBAC and the Azure portal] in the Azure documentation.
51 changes: 50 additions & 1 deletion modules/installation-azure-service-principal.adoc
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to replace the command on lines 174-175 with the command in the [NOTE], like this:

[source,terminal]
----
$ az ad sp create-for-rbac --role <role_name> \// <1>
     --name <service_principal> \// <2>
     --scopes /subscriptions/<subscription_id> <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.

Then on line 199, you can say "If you applied the Contributor role to your service principal, assign the User Administrator Access role by running the following command." This lets you remove the [NOTE] entirely.

The problem with having the [NOTE] after the procedure is that the customer might work through the procedure, then find the note and realize that they have to undo and redo some work.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should also add a prerequisite on line 25 saying "If you want to use a custom role, you have created a custom role with the required permissions listed in the section titled 'Required Azure permissions'" or something similar, so that customers prepare this role before going through the procedure. What do you think?

Copy link
Contributor Author

@xenolinux xenolinux Mar 31, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First point addressed

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for adding a prerequisite. I addressed it as https://github.com/openshift/openshift-docs/pull/56274/files#diff-ffc3e09f08e289cfe3c74a47f411658813e9b68f96708e1a8feaeca5636e0c5aR37-R42.
I used ifdefs to include the exact name of the section. I thought it would be easier for a user. Please let me know if you have any suggestions on this.

Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-account"]
:ash:
endif::[]
ifeval::["{context}" == "installing-azure-account"]
:ipi:
endif::[]
ifeval::["{context}" == "installing-azure-user-infra"]
:upi:
endif::[]

:_content-type: PROCEDURE
[id="installation-azure-service-principal_{context}"]
Expand All @@ -22,6 +28,12 @@ Because {product-title} and its installation program create Microsoft Azure reso

* Install or update the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI].
* Your Azure account has the required roles for the subscription that you use.
ifdef::ipi[]
* If you want to use a custom role, you have created a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the required permissions listed in the _Required Azure permissions for installer-provisioned infrastructure_ section.
endif::ipi[]
ifdef::upi[]
* If you want to use a custom role, you have created a link:https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles[custom role] with the required permissions listed in the _Required Azure permissions for user-provisioned infrastructure_ section.
endif::upi[]

.Procedure

Expand Down Expand Up @@ -167,6 +179,7 @@ endif::[]

. Record the `tenantId` and `id` parameter values from the output. You need these values during the {product-title} installation.

ifdef::ash[]
. Create the service principal for your account:
+
[source,terminal]
Expand All @@ -181,6 +194,35 @@ $ az ad sp create-for-rbac --role Contributor --name <service_principal> \ <1>
[source,terminal]
----
Creating 'Contributor' role assignment under scope '/subscriptions/<subscription_id>'
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": "ac461d78-bf4b-4387-ad16-7e32e328aec6",
"displayName": <service_principal>",
"password": "00000000-0000-0000-0000-000000000000",
"tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee"
}
----
endif::ash[]

ifndef::ash[]
. Create the service principal for your account:
+
[source,terminal]
----
$ az ad sp create-for-rbac --role <role_name> \// <1>
--name <service_principal> \// <2>
--scopes /subscriptions/<subscription_id> <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/<subscription_id>'
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
Expand All @@ -191,12 +233,13 @@ control. For more information, see https://aka.ms/azadsp-cli
"tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee"
}
----
endif::ash[]

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

ifndef::ash[]
. Assign the `User Access Administrator` role by running the following command:
. If you applied the `Contributor` role to your service principal, assign the `User Administrator Access` role by running the following command:
+
[source,terminal]
----
Expand All @@ -212,3 +255,9 @@ endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-account"]
:!ash:
endif::[]
ifeval::["{context}" == "installing-azure-account"]
:!ipi:
endif::[]
ifeval::["{context}" == "installing-azure-user-infra"]
:!upi:
endif::[]