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

Updates to Accelerator Documentation #614

Merged
merged 3 commits into from
Aug 18, 2023
Merged

Updates to Accelerator Documentation #614

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7d9c7b3
Removed duplicate pwsh test
oZakari Aug 15, 2023
32cb00e
Updates to accelerator documentation for clarity
oZakari Aug 16, 2023
16e34a3
Removed unneeded accelerator note in doc
oZakari Aug 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 42 additions & 88 deletions docs/wiki/Accelerator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,91 +42,73 @@ The only thing that differs across the workflows is which ALZ Bicep modules are

![Accelerator Workflows Low Level Diagram](media/alz-bicep-accelerator-workflow-lld.png "Accelerator Workflows Low Level Diagram")

### Getting Started if you're using GitHub Actions
### Pre-Requisites

In order to setup the Accelerator framework with the production GitHub Action Workflows, the following steps must be completed in the order listed:
Below are the required pre-requisites that need to be installed prior to using the ALZ Bicep Accelerator framework:

1. Install the [ALZ PowerShell Module](https://github.com/Azure/ALZ-PowerShell-Module#installation) on your local development machine or within the Azure Cloud Shell using the following command:
1. [PowerShell - 7.1 or higher](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3)
1. [Az PowerShell Module - 10.0.0 or higher](https://learn.microsoft.com/en-us/powershell/azure/install-azure-powershell?view=azps-10.2.0)
1. [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
1. [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#install-manually)
1. [Visual Studio Code](https://code.visualstudio.com/#alt-downloads)
1. [ALZ PowerShell Module](https://github.com/Azure/ALZ-PowerShell-Module#installation)

> **Warning:**
> In order to use this module, [PowerShell 7.1 or higher](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3) needs to be installed
### Getting Started if you're using GitHub Actions

```powershell
Install-Module -Name ALZ
```
In order to setup the Accelerator framework with the production GitHub Action Workflows, the following steps must be completed in the order listed:

1. Before you can utilize the module, ensure you have the prerequisites installed with the following command:
1. Follow this [GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/get-started/quickstart/create-a-repo#create-a-repository) to create a new remote GitHub repository that is not initialized with a README.md file.

```powershell
Test-ALZRequirement
```
1. Within your local workstation, open PowerShell, create and change into a directory (e.g., C:\Repos) of your choice for where you would like to manage the ALZ Bicep Accelerator framework.

Currently this tests for:
1. Clone the non-initialized remote repository to your local workstation with the following command:

- [Supported minimum PowerShell version](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3)
- [Azure PowerShell Module](https://learn.microsoft.com/en-us/powershell/azure/install-azure-powershell?view=azps-10.1.0)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
- [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#install-manually)
```powershell
# Clones the remote repository to your local workstation
git clone https://github.com/<OrganizationName>/<RepositoryName>.git

1. Create your ALZ Bicep Accelerator framework with the following command:
1. Create your ALZ Bicep Accelerator framework with the following ALZ PowerShell Module cmdlet:

```powershell
New-ALZEnvironment -o <output_directory>
```

> **Note:**
> If the directory structure specified for the output location does not exist, the module will create the directory structure programatically.

Various prompts (listed below) will be displayed which will be used to replace parameter values as well as to create an environment variables file (.env) that will be used by the GitHub Action workflows.

1. Depending upon your preferred [network topology deployment](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Setup-azure#2-grant-access-to-user-andor-service-principal-at-root-scope--to-deploy-enterprise-scale-reference-implementation), remove the associated workflow file for each deployment model
- Traditional VNet Hub and Spoke = .github\workflows\alz-bicep-4a-hubspoke.yml
- Virtual WAN = .github\workflows\alz-bicep-4b-vwan.yml

> **Note:**
> These workflow files and associated deployment scripts will be programatically removed in the future.

1. Review all parameter files within config/custom-parameters and update the values as needed for your desired ALZ configuration.
1. Review all parameter files within config/custom-parameters and update the values as needed for your desired ALZ configuration. All files pertaining to the default ALZ Bicep modules are located within the upstream-releases directory. The parameter files are located within the config/custom-parameters directory.

1. Follow this [GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/get-started/quickstart/create-a-repo#create-a-repository) to create a new remote GitHub repository that is NOT initialized

1. If you need to authenticate the GitHub remote repository from your local workstation or from the Azure Cloud Shell, please select an option below depending upon your preferences and requirements:
- [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) - This will automatically prompt you to login when you attempt to push your commit in the following step
- [GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/overview/getting-started-with-github-desktop)
- [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/quickstart)
- [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
- [Personal Access Token with SAML](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)

Otherwise, proceed to the next step.
> **Note:** To further understand the purpose of each parameter, please review the [deployment flow documentation](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow). For design considerations, please review our page in the [Azure Architecture Center](https://learn.microsoft.com/azure/architecture/landing-zones/bicep/landing-zone-bicep).

1. Run the following Git commands to get your remote branch in-sync with the local branch

```shell
# Changes the current working directory to the newly created directory
cd <output_directory>
# Matches the remote URL with a name
git remote add origin https://github.com/<OrganizationName>/<RepositoryName>.git
# Ensures that your local branch name is set to main
git branch -m main
```Powershell
# Adds all changes in the working directory to the staging area
git add .
# Records a snapshot of your repository's staging area
git commit -m "Initial commit"
# Updates the remote branch with the local commit(s) if you did not initialize your remote repository.
git push -u origin main
git push
```

>> **Note:**
>> If you initialized your remote repository with a README.md file, you will need to run the following command to force the push to the remote repository
>> ```git push -u origin main --force```

1. Now that the remote branch has the latest commit(s), you can configure your OpenID Connect (OIDC) identity provider with GitHub which will give the workflows access to your Azure environment.
1. [Create an Azure Active Directory application/service principal](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#create-an-azure-active-directory-application-and-service-principal)
1. [Add your federated credentials](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#add-federated-credentials-preview)
1. [Create an Azure Active Directory service principal](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#create-an-azure-active-directory-application-and-service-principal)
1. [Add your federated credentials](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#add-federated-credentials)
1. Add one federated credential with the entity type set to 'Branch' and with a value for "Based on Selection" set to 'main'
1. Add a secondary federated credential with the entity type set to 'Pull Request'
1. [Create GitHub secrets](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#create-github-secrets)
> **Note:**
> The workflows reference secret names AZURE_TENANT_ID and AZURE_CLIENT_ID. If you choose to use different names, you will need to update the workflows accordingly.
1. [Create RBAC Assignment for the application/service principal](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Setup-azure#2-grant-access-to-user-andor-service-principal-at-root-scope--to-deploy-enterprise-scale-reference-implementation)
1. [Grant permissions for the service principal to be able to deploy the resources](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Setup-azure#2-grant-access-to-user-andor-service-principal-at-root-scope--to-deploy-enterprise-scale-reference-implementation)

1. All workflows are now ready to be deployed! For the initial deployment, manually trigger each workflow in the following order
1. ALZ-Bicep-1-Core
Expand All @@ -145,81 +127,53 @@ In order to setup the Accelerator framework with the production GitHub Action Wo

In order to setup the Accelerator framework with the production ready Azure DevOps Pipelines, the following steps must be completed in the order listed:

1. Install the [ALZ PowerShell Module](https://github.com/Azure/ALZ-PowerShell-Module#installation) on your local development machine or within the Azure Cloud Shell using the following command:
1. Follow this [Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal) to create a new remote Azure DevOps Git repository that is not initialized with a README.md file.

> **Warning:**
> In order to use this module, [PowerShell 7.1 or higher](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3) needs to be installed
1. Within your local workstation, open PowerShell, create and change into a directory (e.g., C:\Repos) of your choice for where you would like to manage the ALZ Bicep Accelerator framework.

```powershell
Install-Module -Name ALZ
```

1. Before you can utilize the module, ensure you have the prerequisites installed with the following command:
1. Clone the non-initialized remote repository to your local workstation with the following command:

```powershell
Test-ALZRequirement
```
# Clones the remote repository to your local workstation
git clone https://[email protected]/<OrganizationName>/<ProjectName>/_git/<RepositoryName>

Currently this tests for:

- [Supported minimum PowerShell version](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3)
- [Azure PowerShell Module](https://learn.microsoft.com/en-us/powershell/azure/install-azure-powershell?view=azps-10.1.0)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
- [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#install-manually)

1. Create your ALZ Bicep Accelerator framework with the following command:
1. Create your ALZ Bicep Accelerator framework with the following ALZ PowerShell Module cmdlet:

```powershell
New-ALZEnvironment -o <output_directory> -cicd "azuredevops"
```

> **Note:**
> If the directory structure specified for the output location does not exist, the module will create the directory structure programatically.

Various prompts will be displayed which will be used to replace parameter values as well as to create an environment variables file (.env) that will be used by the Azure DevOps pipelines.

1. Depending upon your preferred [network topology deployment](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Setup-azure#2-grant-access-to-user-andor-service-principal-at-root-scope--to-deploy-enterprise-scale-reference-implementation), remove the associated workflow file for each deployment model
- Traditional VNet Hub and Spoke = .azuredevops\workflows\alz-bicep-4a-hubspoke.yml
- Virtual WAN = .azuredevops\workflows\alz-bicep-4b-vwan.yml

> **Note:**
> These workflow files and associated deployment scripts will be programatically removed in the future.

1. Review all parameter files within config/custom-parameters and update the values as needed for your desired ALZ configuration.

1. Create an [Azure Active Directory application/service principal](https://learn.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal)

1. Create an [Azure Resource Manager Service Connection within Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-with-an-existing-service-principal) at the Scope Level of Management Group. All pipeline files, except for the PR pipeline files reference a variable called SERVICE_CONNECTION_NAME. You will need to update the variable with the name of the service connection you created within this step.
1. Review all parameter files within config/custom-parameters and update the values as needed for your desired ALZ configuration. All files pertaining to the default ALZ Bicep modules are located within the upstream-releases directory. The parameter files are located within the config/custom-parameters directory.

1. Create an [RBAC Assignment for the application/service principal](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Setup-azure#2-grant-access-to-user-andor-service-principal-at-root-scope--to-deploy-enterprise-scale-reference-implementation)
> **Note:** To further understand the purpose of each parameter, please review the [deployment flow documentation](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow). For design considerations, please review our page in the [Azure Architecture Center](https://learn.microsoft.com/azure/architecture/landing-zones/bicep/landing-zone-bicep).

1. Follow this [Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal) to create a new remote Azure DevOps Git repository that is NOT initialized with a README.md file.
1. [Grant permissions for the service principal to be able to deploy the resources](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Setup-azure#2-grant-access-to-user-andor-service-principal-at-root-scope--to-deploy-enterprise-scale-reference-implementation)

1. If you need to authenticate the Azure DevOps remote repository from your local workstation or from the Azure Cloud Shell, please select an option below depending upon your preferences and requirements:
- [SSH](https://learn.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops)
- [Git Credential Manager](https://learn.microsoft.com/en-us/azure/devops/repos/git/set-up-credential-managers?view=azure-devops)

Otherwise, proceed to the next step.
1. Create an [Azure Resource Manager Service Connection within Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-with-an-existing-service-principal) at the Scope Level of Management Group. All pipeline files, except for the PR pipeline files reference a variable called SERVICE_CONNECTION_NAME. You will need to update the variable with the name of the service connection you created within this step.

1. Run the following Git commands to get your remote branch in-sync with the local branch

```shell
# Changes the current working directory to the newly created directory
cd <output_directory>
# Matches the remote URL with a name
git remote add origin https://github.com/<OrganizationName>/<RepositoryName>.git
# Ensures that your local branch name is set to main
git branch -m main
```Powershell
# Adds all changes in the working directory to the staging area
git add .
# Records a snapshot of your repository's staging area
git commit -m "Initial commit"
# Updates the remote branch with the local commit(s) if you did not initialize your remote repository.
git push -u origin main
git push
```

>> **Note:**
>> If you initialized your remote repository with a README.md file, you will need to run the following command to force the push to the remote repository
>> ```git push -u origin main --force```

1. Create your new pipelines within Azure DevOps. Ensure you select "Existing Azure Pipelines YAML file" when prompted and select the pipeline files from the .azuredevops/pipelines

1. [Assign pipeline permissions to access the Service Connection you created previously](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml#pipeline-permissions) ```
Expand Down
Loading