feat: Bicep contribution guidelines - OIDC setup #1773
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
eriqua
added
Type: Documentation 📄
microsoft-github-policy-service
bot
added
the
Needs: Triage 🔍
|
Important The "Needs: Triage 🔍" label must be removed once the triage process is complete! Tip For additional guidance on how to triage this issue/PR, see the AVM Issue Triage documentation. |
microsoft-github-policy-service
bot
removed
the
Needs: Triage 🔍
|
|
||
| {{< hint type=note >}} | ||
|
|
||
| Each time in the following sections we refer to 'your xyz', it is an indicator that you have to change something in your own environment. | ||
|
|
||
| {{< /hint >}} | ||
|
|
||
| {{< hint type=tip >}} | ||
| Bicep AVM Modules (Resource, Pattern and Utility modules) will be homed in the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and live within an `avm` directory that will be located at the root of the repository, as per [SNFR19](/Azure-Verified-Modules/specs/shared/#id-snfr19---category-publishing---registries-targeted). |
There was a problem hiding this comment.
Suggested change
| Bicep AVM Modules (Resource, Pattern and Utility modules) will be homed in the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and live within an `avm` directory that will be located at the root of the repository, as per [SNFR19](/Azure-Verified-Modules/specs/shared/#id-snfr19---category-publishing---registries-targeted). | |
| Bicep AVM Modules (Resource, Pattern and Utility modules) are located in the `/avm` directory of the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository, as per [SNFR19](/Azure-Verified-Modules/specs/shared/#id-snfr19---category-publishing---registries-targeted). |
|
|
||
| Checkout the [PowerShell Helper Script](#powershell-helper-script-to-setup-fork--ci-test-environment) that can do this step automatically for you! 👍 | ||
| Module owners are expected to fork the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository's `main` branch. |
There was a problem hiding this comment.
Suggested change
| Module owners are expected to fork the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository's `main` branch. | |
| Module owners are expected to fork the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and work on a branch from within their fork, before creating a Pull Request (PR) back into the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository's upstream `main` branch. |
|
|
||
| Checkout the [PowerShell Helper Script](#powershell-helper-script-to-setup-fork--ci-test-environment) that can do this step automatically for you! 👍 | ||
| AVM tests the deployments in an Azure subscription. To do so, it requires a deployment identity with access to it. |
There was a problem hiding this comment.
Suggested change
| AVM tests the deployments in an Azure subscription. To do so, it requires a deployment identity with access to it. | |
| AVM tests its module via deployments in an Azure subscription. To do so, it requires a deployment identity with access to it. |
|
|
||
| {{< hint type=warning title="Deprecating the Service Principal + Secret authentication method">}} | ||
|
|
||
| Support to Service Principal + Secret authentication method has been deprecated and will be decommissioned going forward. |
There was a problem hiding this comment.
Suggested change
| Support to Service Principal + Secret authentication method has been deprecated and will be decommissioned going forward. | |
| Support for the 'Service Principal + Secret' authentication method has been deprecated and will be decommissioned in the future. |
| {{< /hint >}} | ||
| To do so, simply navigate to the [Public Bicep Registry](https://github.com/Azure/bicep-registry-modules) repository, select the `'Fork'` button to the top right of the UI, select where the fork should be created (i.e., the owning organization) and finally click 'Create fork'. | ||
|
|
||
| ### 1.1 Create a GitHub environment |
There was a problem hiding this comment.
Is this environment also required without OIDC? If not, would it make sense to move the instructions into 'Option 1' below?
|
|
||
| Module owners are expected to fork the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository's `main` branch. | ||
| 1. Create a new or leverage an existing user-assigned managed identity with at least `Contributor` & `User Access Administrator` permissions on the Management-Group/Subscription you want to test the modules in. You might find the following links useful: |
There was a problem hiding this comment.
If wonder if it would make sense to recommend the newer Role Based Access Control Administrator role instead if the original User Access Administrator.
|
|
||
| Some Azure resources may require additional roles to be assigned to the deployment identity. An example is the `avm/res/aad/domain-service` module, which requires the deployment identity to have the Domain Services Contributor Azure role to create the required Domain Services resources. | ||
|
|
||
| In those cases, for the first PR adding such modules to the public registry, we recommend the author to reach out to AVM maintainers or, alternatively, to [create a CI environment GitHub issue](https://github.com/Azure/bicep-registry-modules/issues/new?template=avm_ci_environment_issue.yml) in BRM, specifying the additional prerequisites. This is to make sure that the required additional roles get assigned in the upstream CI environment before the corresponding module PR gets merged. |
There was a problem hiding this comment.
Suggested change
| In those cases, for the first PR adding such modules to the public registry, we recommend the author to reach out to AVM maintainers or, alternatively, to [create a CI environment GitHub issue](https://github.com/Azure/bicep-registry-modules/issues/new?template=avm_ci_environment_issue.yml) in BRM, specifying the additional prerequisites. This is to make sure that the required additional roles get assigned in the upstream CI environment before the corresponding module PR gets merged. | |
| In those cases, for the first PR adding such modules to the public registry, we recommend the author to reach out to AVM maintainers or, alternatively, to [create a CI environment GitHub issue](https://github.com/Azure/bicep-registry-modules/issues/new?template=avm_ci_environment_issue.yml) in BRM, specifying the additional prerequisites. This ensures that the required additional roles get assigned in the upstream CI environment before the corresponding PR gets merged. |
Comment on lines
+182
to
+183
| - In the Federated credential scenario dropdown box, select `GitHub Actions deploying Azure resources` | ||
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_02.png" alt="OIDC scenario" width=80%> |
There was a problem hiding this comment.
Suggested change
| - In the Federated credential scenario dropdown box, select `GitHub Actions deploying Azure resources` | |
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_02.png" alt="OIDC scenario" width=80%> | |
| - In the Federated credential scenario dropdown box, select `GitHub Actions deploying Azure resources` | |
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_02.png" alt="OIDC scenario" width=80%> |
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_01.png" alt="OIDC federated credentials" width=60%> | ||
| - In the Federated credential scenario dropdown box, select `GitHub Actions deploying Azure resources` | ||
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_02.png" alt="OIDC scenario" width=80%> | ||
| - For Organization, specify your GitHub organization name, for Repository specify the value `bicep-registry-modules`. |
There was a problem hiding this comment.
Suggested change
| - For Organization, specify your GitHub organization name, for Repository specify the value `bicep-registry-modules`. | |
| - For the `Organization`, specify your GitHub organization name, for the `Repository` the value `bicep-registry-modules`. |
| - In the Federated credential scenario dropdown box, select `GitHub Actions deploying Azure resources` | ||
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_02.png" alt="OIDC scenario" width=80%> | ||
| - For Organization, specify your GitHub organization name, for Repository specify the value `bicep-registry-modules`. | ||
| - For Entity type, select `Environment` and specify the value `avm-validation`. |
There was a problem hiding this comment.
Suggested change
| - For Entity type, select `Environment` and specify the value `avm-validation`. | |
| - For the `Entity` type, select `Environment` and specify the value `avm-validation`. |
| - For Organization, specify your GitHub organization name, for Repository specify the value `bicep-registry-modules`. | ||
| - For Entity type, select `Environment` and specify the value `avm-validation`. | ||
| - Add a Name for the federated credential, for example, `avm-gh-env-validation`. | ||
| - The Issuer, Audiences, and Subject identifier fields autopopulate based on the values you entered. |
There was a problem hiding this comment.
Suggested change
| - The Issuer, Audiences, and Subject identifier fields autopopulate based on the values you entered. | |
| - The `Issuer`, `Audiences`, and `Subject identifier` fields autopopulate based on the values you entered. |
Comment on lines
+188
to
+189
| - Select `Add` to configure the federated credential. | ||
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_03.png" alt="OIDC Add" width=80%> |
There was a problem hiding this comment.
Suggested change
| - Select `Add` to configure the federated credential. | |
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_03.png" alt="OIDC Add" width=80%> | |
| - Select `Add` to configure the federated credential. | |
| <img src="../../../img/bicep-ci/msiOIDCAddFederatedIdentity_03.png" alt="OIDC Add" width=80%> |
|
|
||
| {{< expand "➕ Option 2 [Deprecated]: Configure Service Principal + Secret" "expand/collapse" >}} | ||
|
|
||
| 1. Create a new or leverage an existing Service Principal with at least `Contributor` & `User Access Administrator` permissions on the Management-Group/Subscription you want to test the modules in. You might find the following links useful: |
There was a problem hiding this comment.
Same ask as in this comment, whether we should recommend a different role than User Access Administrator
| To use the environment's pipelines you should use the information you gathered during the [Azure setup](#1-setup-your-azure-test-environment) to set up the following repository secrets: | ||
| #### 3.1.1 Shared repository secrets | ||
|
|
||
| To use the environment's pipelines you should set up the following repository secrets: |
There was a problem hiding this comment.
Suggested change
| To use the environment's pipelines you should set up the following repository secrets: | |
| To use the _Continuous Integration_ environment's workflows you should set up the following repository secrets: |
|
|
||
| To lower the barrier to entry and allow users to easily define their own naming conventions, we introduced a default 'name prefix' for all deployed resources. | ||
|
|
||
| This prefix is **only** used by the CI environment you validate your modules in, and doesn't affect the naming of any resources you deploy as part of any multi-module solutions (applications/workloads) based on the modules. |
There was a problem hiding this comment.
Suggested change
| This prefix is **only** used by the CI environment you validate your modules in, and doesn't affect the naming of any resources you deploy as part of any multi-module solutions (applications/workloads) based on the modules. | |
| This prefix is **only** used by the CI environment you validate your modules in, and doesn't affect the naming of any resources you deploy as part of any solutions (applications/workloads) based on the modules. |
Would just recommend to remove that one word as some solutions (e.g., my image creation construct) only use a single module.
|
|
||
| This prefix is **only** used by the CI environment you validate your modules in, and doesn't affect the naming of any resources you deploy as part of any multi-module solutions (applications/workloads) based on the modules. | ||
|
|
||
| Each pipeline in AVM deploying resources uses a logic that automatically replaces "tokens" (i.e., placeholders) in any module test file. These tokens are, for example, included in the resources names (e.g. `'name: kvlt-${namePrefix}'`). Tokens are stored as repository secrets to facilitate maintenance. |
There was a problem hiding this comment.
Suggested change
| Each pipeline in AVM deploying resources uses a logic that automatically replaces "tokens" (i.e., placeholders) in any module test file. These tokens are, for example, included in the resources names (e.g. `'name: kvlt-${namePrefix}'`). Tokens are stored as repository secrets to facilitate maintenance. | |
| Each workflow in AVM deploying resources uses a logic that automatically replaces "tokens" (i.e., placeholders) in any module test file. These tokens are, for example, included in the resources names (e.g. `'name: kvlt-${namePrefix}'`). Tokens are stored as repository secrets to facilitate maintenance. |
|
|
||
| #### 3.1.2 Authentication secrets | ||
|
|
||
| In addition to shared repository secrets detailed above, additional GitHub secrets are required to allow the deployment identity authentication to Azure. |
There was a problem hiding this comment.
Suggested change
| In addition to shared repository secrets detailed above, additional GitHub secrets are required to allow the deployment identity authentication to Azure. | |
| In addition to shared repository secrets detailed above, additional GitHub secrets are required to allow the deploying identity to authentication to Azure. |
|
|
||
| {{< expand "➕ Option 1 [Recommended]: Authenticate via OIDC" "expand/collapse" >}} | ||
|
|
||
| Create the following environment secrets in the `avm-validation` GitHub environment created at [Step 1](#1-fork-the-module-source-repository) |
There was a problem hiding this comment.
Depending on the answer to this comment, the environment may or may not exist...
Comment on lines
+301
to
+315
| 1. Navigate to the repository's `Settings`. | ||
|
|
||
| <img src="../../../img/bicep-ci/forkSettings.png" alt="Navigate to settings" width=100%> | ||
|
|
||
| 2. In the list of settings, select `Environments`. Click on the previously created `avm-validation` environment. | ||
|
|
||
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentConfigure.png" alt="Navigate to environments" width=100%> | ||
|
|
||
| 3. In the `Environment secrets` Section click on the `Add environment secret` button. | ||
|
|
||
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentSecretAdd.png" alt="Navigate to env secrets" width=70%> | ||
|
|
||
| 3. In the opening view, you can create a secret by providing a secret `Name`, a secret `Value`, followed by a click on the `Add secret` button. | ||
|
|
||
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentSecretAdd_02.png" alt="Add env secret" width=100%> |
There was a problem hiding this comment.
Suggested change
| 1. Navigate to the repository's `Settings`. | |
| <img src="../../../img/bicep-ci/forkSettings.png" alt="Navigate to settings" width=100%> | |
| 2. In the list of settings, select `Environments`. Click on the previously created `avm-validation` environment. | |
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentConfigure.png" alt="Navigate to environments" width=100%> | |
| 3. In the `Environment secrets` Section click on the `Add environment secret` button. | |
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentSecretAdd.png" alt="Navigate to env secrets" width=70%> | |
| 3. In the opening view, you can create a secret by providing a secret `Name`, a secret `Value`, followed by a click on the `Add secret` button. | |
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentSecretAdd_02.png" alt="Add env secret" width=100%> | |
| 1. Navigate to the repository's `Settings`. | |
| <img src="../../../img/bicep-ci/forkSettings.png" alt="Navigate to settings" width=100%> | |
| 2. In the list of settings, select `Environments`. Click on the previously created `avm-validation` environment. | |
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentConfigure.png" alt="Navigate to environments" width=100%> | |
| 3. In the `Environment secrets` Section click on the `Add environment secret` button. | |
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentSecretAdd.png" alt="Navigate to env secrets" width=70%> | |
| 3. In the opening view, you can create a secret by providing a secret `Name`, a secret `Value`, followed by a click on the `Add secret` button. | |
| <img src="../../../img/bicep-ci/forkSettingsEnvironmentSecretAdd_02.png" alt="Add env secret" width=100%> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview/Summary
Add OIDC authentication option to Bicep contribution guidelines
This PR fixes/adds/changes/removes
Breaking Changes
As part of this Pull Request I have
mainbranch