Starter Kits

Source code & Installation

The source code of this kit module can be found here

Run the following command to install the kit module:

collie kit import azure/buildingblocks/starterkit/backplane

This is an implementation of "Cloud Starter Kits" that provides application teams with

• a GitHub repository, seeded with an application starter kit
• a GitHub actions pipeline
• a service account solution that enables the GitHub actions pipeline to deploy to their Azure Subscription

Prerequisites

GitHub App

Apart from an Azure Landing Zone (we recommend using starter kits only with Sandbox Landing Zones) you will need a GitHub organization and the ability to create and install a private GitHub App on the organization. This app will need the following permissions

• Permissions
  • Read access to metadata and organization administration
  • Read and write access to actions, administration, code, secrets, and workflows
• Repository access: All repositories

You will also need to generate a private key .PEM file for the app to be used by the github terraform provider when deploying instances of the buildingblock/ module.

Template Repository

You will also need a template repository that contains code and GitHub actions pipelines. The "official example" that we use for testing is likvid-bank/starterkit-template-azure-static-website. This template sets up an Azure Static Website including a PR workflow for terraform and code.

Structure of this Kit module

This kit module comes with three components, each responsible for enabling deployment of the next

• the kit module itself, acting as the building block's "backplane" that sets up all required infrastructure for deploying starterkits for application teams
• a terraform module that forms the definition for each "building block", i.e. the instance of the starterkit deployed for a particular application team including a GitHub repo and GitHub actions pipeline
• terraform code that lives in the starterkit template, deployed by a GitHub actions pipeline

The following sections explain these parts in more detail

Deployment of the Building Block backplane

Before we can deploy building blocks, we need to first set up the backplane. This operation is only performed once by deploying this kit module using collie as any other kit module with collie kit apply and collie foundation deploy.

Unforutnately it's currently not possible to setup a GitHub app via terraform, so please perform this manually.

This will deploy the following resources:

flowchart TD
  subgraph github[GitHub Organization]
    ghapp[GitHub App]
    ghrepotemplate[GitHub Template Repository]
  end
  subgraph Azure
    subgraph bbsub[Building Block Backplane Subscription]
      bbsubtfstate[StarterKit BB TF State]
      bbspn[StarterKit SPN]

    end
  end

  BB((Starter Kit<br>Building Block))

  BB --> github
  BB --> Azure
  bbspn --Storage Blob Owner--> bbsubtfstate

Deployment of a Building Block

Now that we the backplane deployed, we can use the backplane to deploy an instance of the buildingblock terraform module into a sandbox subscription supplied by the application team. The easiest way to do this is to create a building block definition from the buildingblock terraform module in meshStack and configure it with the config_tf file produced by the backplane module.

The chart below shows the interaction of cloud resources when deploying a new building block using the backplane:

flowchart TD
  subgraph GitHub[GitHub Organization]
    ghapp[GitHub App]
    subgraph ghrepo [GitHub Repo]
      ghpipeline[Deploy Pipeline]
    end
    ghrepotemplate[GitHub Template Repository]
  end
  subgraph Azure
    subgraph bbsub[Building Block Backplane Subscription]
      bbsubtfstate[StarterKit BB TF State]
      bbspn[StarterKit SPN]

    end
    subgraph sbsub[Sandbox Subscription]
      subgraph rgcicd[Resource Group ci-cd]
        ghactionsuami[UAMI for GitHub Actions]
        sbsubtfstate[Pipeline TF State]
      end
      subgraph rgapp[Resource Group app]
        staticwebsite
      end
    end
  end

  BB((Starter Kit Building Block))

  ghapp -.deploys.-> ghrepo
  bbspn -.deploys.-> rgcicd
  bbspn -.deploys.-> rgapp
  BB -.via github provider.-> ghapp
  BB -.via azurerm provider.-> bbspn
  ghrepotemplate -.from template.-> ghrepo
  ghactionsuami --Storage Blob Owner--> sbsubtfstate
  ghpipeline --Workload Identity Federation--> ghactionsuami
  bbspn --Storage Blob Owner--> bbsubtfstate
  ghactionsuami --Owner--> rgapp

  linkStyle 0,1,2,3,4,5 stroke:#ff3,stroke-width:4px;

Deployment of the App

Now that we have the application team's sandbox subscription and their GitHub repository configured, the team can use the setup to deploy their staticwebsite app.

flowchart TD
  subgraph GitHub[GitHub Organization]
    subgraph ghrepo [GitHub Repo]
      ghpipeline[Deploy Pipeline]
    end
  end
  subgraph Azure
    subgraph sbsub[Sandbox Subscription]
      subgraph rgcicd[Resource Group ci-cd]
        ghactionsuami[UAMI for GitHub Actions]
        sbsubtfstate[Pipeline TF State]
      end
      subgraph rgapp[Resource Group app]
        staticwebsite
      end
    end
  end

  ghactionsuami -.deploys.-> staticwebsite

  ghactionsuami --Storage Blob Owner--> sbsubtfstate
  ghpipeline --Workload Identity Federation--> ghactionsuami
  ghactionsuami --Owner--> rgapp

  linkStyle 0 stroke:#ff3,stroke-width:4px;

Creating Custom Starter Kits

Using this kit module as a template, you can quickly develop similar starter kits. You will typically only need to customize the template repository with code and GitHub Actions workflows.

For advanced use cases, you can of course also want to customize the buildingblock/ terraform module itself or even the backplane terraform module.

Requirements

Name	Version
terraform	>= 1.0
azuread	3.0.2
azurerm	3.116.0
github	5.42.0
random	3.6.0
time	0.11.1

Modules

No modules.

Resources

Name	Type
azuread_app_role_assignment.starterkit-directory	resource
azuread_application.starterkit	resource
azuread_service_principal.starterkit	resource
azuread_service_principal_password.starterkit	resource
azurerm_resource_group.tfstates	resource
azurerm_role_assignment.starterkit_access	resource
azurerm_role_assignment.terraform_state	resource
azurerm_role_definition.starterkit_access	resource
azurerm_role_definition.starterkit_deploy	resource
azurerm_storage_account.tfstates	resource
azurerm_storage_container.tfstates	resource
github_repository.staticwebsite_template	resource
random_string.resource_code	resource
time_rotating.key_rotation	resource
azuread_application_published_app_ids.well_known	data source
azuread_group.project_admins	data source
azuread_service_principal.msgraph	data source
azurerm_subscription.current	data source

Inputs

Name	Description	Type	Default	Required
github_app_id	id of your GitHub App	number	n/a	yes
github_app_installation_id	id of your GitHub App installation as it appears in URLs on GitHub.com	number	n/a	yes
github_org	id of your GitHub organization as it appears in URLs on GitHub.com	string	n/a	yes
location	Azure location for deploying the building block terraform state storage account	string	n/a	yes
scope	Scope where the building block should be deployable, typically a Sandbox Landing Zone Management Group	string	n/a	yes

Outputs

Name	Description
config_tf	Generates a config.tf that can be dropped into meshStack's BuildingBlockDefinition as an encrypted file input to configure this building block.
documentation_md	n/a