Azure Landing Zones Subscription Vending with Terraform, Terraform Cloud and GitHub

This example shows one approach to self-service subscription vending in Azure. It leverages the ALZ Terrafrom subscription vending module, Terraform Cloud and GitHub to demonstrate an end to end process of vending subscriptions for different use cases.

Content

Features

This demo has the following concepts:

• A central GitHub repo and pipeline that vends subscriptions.
• A subscription vending process that creates a Terraform Cloud workspace and vends a subscription via the workspace.
• A vended subscription includes a number of other resources:
  • Resource groups
  • Permissions
  • User Assigned Managed Identity and Federated Credentials for Terraform Cloud
  • A user Terraform Cloud workspace
  • A repository for a persona template which includes variables, secrets, action and example code to deploy a VM

The process flow is:

1. Setup the config to vend your subscription
2. Trigger the vend GitHub action via repository_dispatch API call
3. Wait for the management workspace, subscription, user repository and user workspace to be created
4. Naviagate to the user repository and trigger the action to deploy the example VM workload into the newly vended subscription

Getting Started

Prerequisites

• HashiCorp Terraform CLI: Download
• Azure CLI: Download
• An Azure Tenant with Billing Account Access
• A GitHub Organization: Free Organization
• A licensed Terraform Cloud organization: Portal

NOTE: This example does not currently have an option for the free tier of Terraform Cloud. It is dependent on being able to create Teams and API Tokens for teams.

Installation

• Fork the repository. This is important as you need to be able to run the GitHub Actions in your organisation.
• Clone it locally.
• Follow the quickstart.

Quickstart

There are a few manual steps to get this demo up and running. Please note that this demo is conceptual. You will note that we are using GitHub PAT tokens and Terraform Cloud user API tokens. If you want to use this example for a production scenario, you should use alternative authentication.

Setup a Service Principal for Subscription Vending

In order to use this demo, you need create a Service Principal and assign billing account permissions. You then need to generate a secret for it. We'll need the tenant id, client id and client secret for this service principal later on. Follow these intructions to setup the permissions if you haven't done it before.

You will also need at least one pre-existing subscription in your tenant. We won't deploy or alter anything in that subscription, but due to a limitation of the azurerm provider, we need to provide a subsscription id. Take a note of the subscription id for later.

Create the Service Principal

The following command is over-permissive but works well for a demo, you will need to be a global admin and tick the "access management for Azure resources" box in Entra ID.

$ az ad sp create-for-rbac -n "terraform-sub-vending-demo" --role "Owner" --scopes "/"

Entra ID permissions for the Service Principal

The SPN needs the User.ReadAll permission. See the AzureAD provider documentation.

Create a Management Group

For now need a management group other than whatever you default Management Group is to use this demo. If you already have one, then take a note of it's name and use that in place of sub-vending-demo in future steps.

1. Login to the Azure Portal
2. Search for Management Groups
3. Click + Create
4. Enter sub-vending-demo in both the Management group ID and Management group display name fields
5. Click Submit

Generate a GitHub PAT Token

1. Navigate to github.com.
2. Click on your user icon in the top right and select Settings.
3. Scroll down and click on Developer Settings in the left navigation.
4. Click Personal access tokens in the left navigation and select Tokens (classic).
5. Click Generate new token at the top and select Generate new token (classic).
6. Enter Azure Landing Zone Terraform Accelerator in the Note field.
7. Alter the Expiration drop down and select Custom.
8. Choose tommorrows date in the date picker.
9. Check the following scopes:
   1. repo
   2. delete_repo
10. Click Generate token.
11. Copy the token and save it somewhere safe.
12. If you are a Microsoft Employee, you must grant your token SSO access to any one Microsoft org you are a member of.
13. Select an organization and click Authorize, then follow the prompts to allow SSO.

Generate a Terraform Cloud API Token

Note you must be an owner of the Terraform Cloud organization. We need this permission so that we can create and manage teams.

1. Login to Terraform Cloud
2. Click the user image in the top left and select User Settings
3. Navigate to Tokens and click Create an API token
4. Type Subscription Vending Demo into the Description field and click Generate token
5. Copy the generated token and save it somewhere secure for the next parts of thr setup

Setup Terraform Cloud

1. Login to your Terraform Cloud organisation.
2. Ensure you have Project and workspaces selected.
3. Click New and select Project.
4. Enter sub-vend-demo-mgmt and click Create.
5. Click New and select Project.
6. Enter sub-vend-demo-user and click Create.
7. Navigate to Settings and select Variable sets.
8. Click Create variable set.
9. Enter sub-vend-demo-mgmt into the Name.
10. Ensure Apply to specific projects and workspaces is selected.
11. Click Select projects and select sub-vend-demo-mgmt.
12. Scroll down and repeat the process of clicking Add variable, selecting Environment variable, filling our the Key and Value and clicking Add variable as follows:
    1. Check the Sensitive box for TFE_TOKEN: The Terraform Cloud API Token you created earlier
    2. Check the Sensitive box for GITHUB_TOKEN: The GitHub PAT you created earlier
    3. ARM_TENANT_ID: Your Azure Tenant Id
    4. ARM_SUBSCRIPTION_ID: Your Azure Subscription Id (remember this won't be used, but is require by the Terraform provider)
    5. ARM_CLIENT_ID: The client ID of the service principal that was setup for subscription vending
    6. Check the Sensitive box for ARM_CLIENT_SECRET: The client secret of the service principal that was setup for subscription vending
13. Repeat the process of clicking Add variable, selecting Terraform variable, filling our the Key and Value and clicking Add variable as follows:
    1. terraform_cloud_organisation: This is the name of you Terraform Cloud Organisation.
    2. terraform_cloud_user_project: This is sub-vend-demo-user.
    3. billing_account_type: Choose between ea, mca or mpa depending on your account type
    4. billing_account_name: The name of your billing account. This is the Billing account ID of your billing account, such as 7690848 for EA or e879cf0f-2b4d-5431-109a-f72fc9868693:024cabf4-7321-4cf9-be59-df0c77ca51de_2019-05-31 for MCA or MPA.
    5. If you are using EA Billing then enter these variables:
       1. billing_enrollment_account_name: This is the billing enrollment. This is the Account ID of your billing enrollment, such as 340388.
    6. If you are using MCA Billing, then enter these variables:
       1. billing_profile_name: This is the billing profile id, such as PE2Q-NOIT-BG7-TGB.
       2. billing_invoice_section_name: This is the billing invoice section id, such as MTT4-OBS7-PJA-TGB.
    7. If you are using MPA Billing, then enter these variables:
       1. billing_customer_name: This is the billing customer id, such as 2281f543-7321-4cf9-1e23-edb4Oc31a31c.
14. Ok, we are all done with the Terraform Cloud configuration.

Fork the Repo and Setup the GitHub Variables

1. Create a fork of this repository in your own organisation.
2. Open the repository, click Settings, then Secrets and variable and click Actions.
3. Ensure the Secrets tab is select, then click New repository secret.
4. Enter TERRAFORM_CLOUD_TOKEN into the Name and paste your Terraform Cloud API Token into the Secret, then click Add secret.
5. Now select the Variable tab.
6. We are going to add the following variables by clicking New repository variable an filling out the Name and Value fields, then clicking Add variable:
   1. TERRAFORM_CLOUD_URL: This is app.terraform.io, unless you are using Terraform Enterprise, in which case enter the the url of your instance.
   2. TERRAFORM_CLOUD_ORGANISATION: This is the name of you Terraform Cloud Organisation.
   3. TERRAFORM_CLOUD_PROJECT: This is sub-vend-demo-mgmt.
7. Click Actions in the top menu.
8. Click I understand my workflows, go ahead and enable them.
9. Ok, we are all done with the GitHub configuration.

Setup the demo

1. Open Visual Studio Code and open the folder of your forked repository.
2. Copy the examples/trigger_vend_example.ps1 and name the file examples/trigger_vend_demo.ps1.
3. Open the trigger_vend_demo.ps1 and edit the variable values as follows:
   1. $owner: This is the GitHub organisation that you forked this repository into
   2. $repository: This is the name of your forked repository
   3. $access_token: This is the GitHub PAT you created earlier
   4. $subscriptionData: This is the payload for our example. Edit the following values as follow:
      1. subscription_name: You only need to change this if it clashes with an existing subscription you have.
      2. location: Change this to your desired Azure region
      3. subscription_offer: Choose DevTest or Production depending on what is available for your billing account
      4. subscription_description: Only change this if you changed the subscription_name
      5. subscription_management_group: This should be left as sub-vending-demo as per the management group you creatd earlier
      6. resource_groups: Only change these if you wish to update the locations.
      7. subscription_owners: This must be updated to a valid SPN in your Entra ID directory. For example [ "[email protected]" ]. If you don't update this you won't get access to the vended subscription and the demo will fail.
      8. persona_template_organisation: Don't change this
      9. persona_template_repository: Don't change this
      10. repository_organisation: Set this to the GitHub organisation you wish your user repository to be created in.
4. Save the file.
5. Copy the examples/trigger_destroy_example.ps1 and name the file examples/trigger_destroy_demo.ps1.
6. Open the trigger_destroy_demo.ps1 and edit the variable values as follows:
   1. $owner: This is the GitHub organisation that you forked this repository into
   2. $repository: This is the name of your forked repository
   3. $access_token: This is the GitHub PAT you created earlier
   4. $subscriptionData: This is the payload for our example. Edit the following values as follow:
      1. subscription_name: You only need to change this if you changed it in the vend file
7. Save the file
8. Ok, we are all done with the setup.

Run the demo

1. Open a terminal in Visual Studio Code.
2. Navigate to the the examples folder with cd examples.
3. Run ./trigger_vend_demo.ps1.
4. Open your GitHub forked repository in the browser.
5. Navigate to Actions in the top menu.
6. Click on the running action and watch what it is doing.
7. Also navigate to Terrafrom Cloud and watch the workspaces being created and run.
8. When all the runs are finished, you can navigate to the Azure portal and take a look at the subscription and resources that have been created.

Clean up

1. Open a terminal in Visual Studio Code.
2. Navigate to the the examples folder with cd examples.
3. Run ./trigger_destroy_demo.ps1.
4. Open your GitHub forked repository in the browser.
5. Navigate to Actions in the top menu.
6. Click on the running action and watch what it is doing.
7. Also navigate to Terrafrom Cloud and watch the workspaces run and deleted.
8. When all the runs are finished, you can navigate to the Azure portal and take a look at the subscription to see it has been cleaned to.