Skip to content

MACH configuration deployment

A MACH configuration deployment (or simply put: MACH deployment) will generate and apply a Terraform configuration per site so that it can deploy

1. MACH-managed resources

The resources that are managed by MACH depend on the cloud integration:

2. Integration resources

Resources needed for the integrations such as

3. Components

Since components are loaded into the configuration as Terraform modules, during a MACH deployment the resources defined in the component will get created.

  1. The first stage of a component deployment (uploading the assets to a component repository) is done before a component is deployed as part of a MACH stack.

  2. The second stage is getting the previously deployed component assets actually up and running in your MACH stack and to create other necessary resources.

More info about the second stage deployment.

Component deployment - first and second stage

Not all components have a 'first stage' which means: some components might just have a Terraform configuration to be applied and no serverless function assets.
In that case, there is no need of a 'first stage' component deployment.

Providing credentials

MACH needs to be able to access:

  • The components repositories
  • The AWS account / Azure subscription it needs to manage resources in

When running MACH composer directly from the command line, whenever you have been authenticated (either by setting the correct AWS environment variables or on Azure using az login) you should be able to deploy using MACH without any issues.

When running the MACH Docker image, the necessary environment variables need to be passed on to the docker container:

docker run --rm \
    --volume $(pwd):/code \
    --volume $SSH_AUTH_SOCK:/ssh-agent \
    -e SSH_AUTH_SOCK=/ssh-agent \
    -e AWS_DEFAULT_REGION=<your-region> \
    -e AWS_ACCESS_KEY_ID=<your-access-key-id> \
    -e AWS_SECRET_ACCESS_KEY=<your-secret-access-key> \
    docker.pkg.github.com/labd/mach-composer/mach:latest \
    apply
docker run --rm \
    --volume $(pwd):/code \
    --volume $SSH_AUTH_SOCK:/ssh-agent \
    -e SSH_AUTH_SOCK=/ssh-agent \
    -e ARM_CLIENT_ID=<your-client-id> \
    -e ARM_CLIENT_SECRET=<your-client-secret> \
    -e ARM_SUBSCRIPTION_ID=<your-subscription-id> \
    -e ARM_TENANT_ID=<your-tenant-id> \
    docker.pkg.github.com/labd/mach-composer/mach:latest \
    apply --with-sp-login

For Azure you'll need to run it with the --with-sp-login option let MACH composer perform an az login command.
More info.

Cache Terraform providers

MACH composer comes with Terraform providers pre-installed in the Docker image.

If you're overwriting these versions with in your terraform_config block, these providers will be downloaded.

To avoid having to re-download it everytime you run MACH through the Docker image, make sure you mount the plugin cache directory;

docker run --rm \
    --volume $(pwd):/code \
    --volume $(pwd)/.terraform_cache:/root/.terraform.d/plugin-cache \
    docker.pkg.github.com/labd/mach-composer/mach:latest \
    apply

Caching in CI/CD

For an example on how to setup the Terraform plugin cache, see the examples in the how-to's for:

  • GitLab
  • GitHub actions (todo)
  • Azure DevOps (todo)