page_type | languages | name | description | products | urlFragment | |||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
sample |
|
Azure Landing Zones Subscription Vending with Terraform, Terraform Cloud and GitHub |
A sample showing an example of self-service subscription vending with GitHub and Terraform Cloud. |
|
alz-terraform-sub-vending |
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.
File/folder | Description |
---|---|
.github/workflows/*.yml |
GitHub Actions to vend and destroy subscriptions. |
examples |
Scripts showing how to trigger vend and destroy. |
modules |
Terraform sub-modules used in the vending module. |
scripts |
Scripts used in the GitHub action to interact with Terraform Cloud. |
*.tf |
Terraform root module for vending and destroying subscriptions. |
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:
- Setup the config to vend your subscription
- Trigger the vend GitHub action via repository_dispatch API call
- Wait for the management workspace, subscription, user repository and user workspace to be created
- Naviagate to the user repository and trigger the action to deploy the example VM workload into the newly vended subscription
- 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.
- 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.
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.
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.
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 "/"
The SPN needs the User.ReadAll
permission. See the AzureAD provider documentation.
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.
- Login to the Azure Portal
- Search for
Management Groups
- Click
+ Create
- Enter
sub-vending-demo
in both theManagement group ID
andManagement group display name
fields - Click
Submit
- Navigate to github.com.
- Click on your user icon in the top right and select
Settings
. - Scroll down and click on
Developer Settings
in the left navigation. - Click
Personal access tokens
in the left navigation and selectTokens (classic)
. - Click
Generate new token
at the top and selectGenerate new token (classic)
. - Enter
Azure Landing Zone Terraform Accelerator
in theNote
field. - Alter the
Expiration
drop down and selectCustom
. - Choose tommorrows date in the date picker.
- Check the following scopes:
repo
delete_repo
- Click
Generate token
. - Copy the token and save it somewhere safe.
- If you are a Microsoft Employee, you must grant your token SSO access to any one Microsoft org you are a member of.
- Select an organization and click
Authorize
, then follow the prompts to allow SSO.
Note you must be an owner of the Terraform Cloud organization. We need this permission so that we can create and manage teams.
- Login to Terraform Cloud
- Click the user image in the top left and select
User Settings
- Navigate to
Tokens
and clickCreate an API token
- Type
Subscription Vending Demo
into theDescription
field and clickGenerate token
- Copy the generated token and save it somewhere secure for the next parts of thr setup
- Login to your Terraform Cloud organisation.
- Ensure you have
Project and workspaces
selected. - Click
New
and selectProject
. - Enter
sub-vend-demo-mgmt
and clickCreate
. - Click
New
and selectProject
. - Enter
sub-vend-demo-user
and clickCreate
. - Navigate to
Settings
and selectVariable sets
. - Click
Create variable set
. - Enter
sub-vend-demo-mgmt
into theName
. - Ensure
Apply to specific projects and workspaces
is selected. - Click
Select projects
and selectsub-vend-demo-mgmt
. - Scroll down and repeat the process of clicking
Add variable
, selectingEnvironment variable
, filling our theKey
andValue
and clickingAdd variable
as follows:- Check the
Sensitive
box forTFE_TOKEN
: The Terraform Cloud API Token you created earlier - Check the
Sensitive
box forGITHUB_TOKEN
: The GitHub PAT you created earlier ARM_TENANT_ID
: Your Azure Tenant IdARM_SUBSCRIPTION_ID
: Your Azure Subscription Id (remember this won't be used, but is require by the Terraform provider)ARM_CLIENT_ID
: The client ID of the service principal that was setup for subscription vending- Check the
Sensitive
box forARM_CLIENT_SECRET
: The client secret of the service principal that was setup for subscription vending
- Check the
- Repeat the process of clicking
Add variable
, selectingTerraform variable
, filling our theKey
andValue
and clickingAdd variable
as follows:terraform_cloud_organisation
: This is the name of you Terraform Cloud Organisation.terraform_cloud_user_project
: This issub-vend-demo-user
.billing_account_type
: Choose betweenea
,mca
ormpa
depending on your account typebilling_account_name
: The name of your billing account. This is theBilling account ID
of your billing account, such as7690848
for EA ore879cf0f-2b4d-5431-109a-f72fc9868693:024cabf4-7321-4cf9-be59-df0c77ca51de_2019-05-31
for MCA or MPA.- If you are using EA Billing then enter these variables:
billing_enrollment_account_name
: This is the billing enrollment. This is theAccount ID
of your billing enrollment, such as340388
.
- If you are using MCA Billing, then enter these variables:
billing_profile_name
: This is the billing profile id, such asPE2Q-NOIT-BG7-TGB
.billing_invoice_section_name
: This is the billing invoice section id, such asMTT4-OBS7-PJA-TGB
.
- If you are using MPA Billing, then enter these variables:
billing_customer_name
: This is the billing customer id, such as2281f543-7321-4cf9-1e23-edb4Oc31a31c
.
- Ok, we are all done with the Terraform Cloud configuration.
- Create a fork of this repository in your own organisation.
- Open the repository, click
Settings
, thenSecrets and variable
and clickActions
. - Ensure the
Secrets
tab is select, then clickNew repository secret
. - Enter
TERRAFORM_CLOUD_TOKEN
into theName
and paste your Terraform Cloud API Token into theSecret
, then clickAdd secret
. - Now select the
Variable
tab. - We are going to add the following variables by clicking
New repository variable
an filling out theName
andValue
fields, then clickingAdd variable
:TERRAFORM_CLOUD_URL
: This isapp.terraform.io
, unless you are using Terraform Enterprise, in which case enter the the url of your instance.TERRAFORM_CLOUD_ORGANISATION
: This is the name of you Terraform Cloud Organisation.TERRAFORM_CLOUD_PROJECT
: This issub-vend-demo-mgmt
.
- Click
Actions
in the top menu. - Click
I understand my workflows, go ahead and enable them
. - Ok, we are all done with the GitHub configuration.
- Open Visual Studio Code and open the folder of your forked repository.
- Copy the
examples/trigger_vend_example.ps1
and name the fileexamples/trigger_vend_demo.ps1
. - Open the
trigger_vend_demo.ps1
and edit the variable values as follows:$owner
: This is the GitHub organisation that you forked this repository into$repository
: This is the name of your forked repository$access_token
: This is the GitHub PAT you created earlier$subscriptionData
: This is the payload for our example. Edit the following values as follow:subscription_name
: You only need to change this if it clashes with an existing subscription you have.location
: Change this to your desired Azure regionsubscription_offer
: ChooseDevTest
orProduction
depending on what is available for your billing accountsubscription_description
: Only change this if you changed thesubscription_name
subscription_management_group
: This should be left assub-vending-demo
as per the management group you creatd earlierresource_groups
: Only change these if you wish to update the locations.subscription_owners
: This must be updated to a valid SPN in your Entra ID directory. For example[ "first.last@org.com" ]
. If you don't update this you won't get access to the vended subscription and the demo will fail.persona_template_organisation
: Don't change thispersona_template_repository
: Don't change thisrepository_organisation
: Set this to the GitHub organisation you wish your user repository to be created in.
- Save the file.
- Copy the
examples/trigger_destroy_example.ps1
and name the fileexamples/trigger_destroy_demo.ps1
. - Open the
trigger_destroy_demo.ps1
and edit the variable values as follows:$owner
: This is the GitHub organisation that you forked this repository into$repository
: This is the name of your forked repository$access_token
: This is the GitHub PAT you created earlier$subscriptionData
: This is the payload for our example. Edit the following values as follow:subscription_name
: You only need to change this if you changed it in the vend file
- Save the file
- Ok, we are all done with the setup.
- Open a terminal in Visual Studio Code.
- Navigate to the the
examples
folder withcd examples
. - Run
./trigger_vend_demo.ps1
. - Open your GitHub forked repository in the browser.
- Navigate to
Actions
in the top menu. - Click on the running action and watch what it is doing.
- Also navigate to Terrafrom Cloud and watch the workspaces being created and run.
- 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.
- Open a terminal in Visual Studio Code.
- Navigate to the the
examples
folder withcd examples
. - Run
./trigger_destroy_demo.ps1
. - Open your GitHub forked repository in the browser.
- Navigate to
Actions
in the top menu. - Click on the running action and watch what it is doing.
- Also navigate to Terrafrom Cloud and watch the workspaces run and deleted.
- 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.