Skip to content

Automation runtime environments

Supported runtimes

There are two supported runtimes where the automation is expected to be executed inside of:

  1. Docker Desktop (Container engine)
  2. Multipass (VM)

The Terraform automation can be run from the local operating system, but it is recommended to use either of the runtimes listed above, which provide a consistent and controlled environment, with all dependencies preinstalled.

Docker Desktop

Docker Desktop is an easy-to-use application that enables you to build and share containerized applications.

It provides a simple interface that enables you to manage your containers, applications, and images directly from your machine without having to use the CLI to perform core actions.

Docker Desktop is supported across Mac, Windows, and Linux, and can be downloaded and installed directly from: https://www.docker.com/products/docker-desktop/

Once installed, use the automation template's launch.sh script to launch an interactive shell where the Terraform automation can be executed.

Multipass

Multipass is a simplified Ubuntu Linux Virtual Machine that you can spin up with a single command. With this option you spin up a virtual machine with a predefined configuration that is ready to run the Terraform automation.

You can download and install Multipass from https://multipass.run/install

Once you have installed Multipass, open up a command line terminal and cd into the parent directory where you cloned the automation repo.

Download the cloud-init script for use by the virtual machine using:

curl https://raw.githubusercontent.com/cloud-native-toolkit/sre-utilities/main/cloud-init/cli-tools.yaml --output cli-tools.yaml

The cli-tools cloud init script prepares a VM with the same tools available in the quay.io/cloudnativetoolkit/cli-tools-ibmcloud container image. Particularly:

  • terraform
  • terragrunt
  • git
  • jq
  • yq
  • oc
  • kubectl
  • helm
  • ibmcloud cli

Launch the Multipass virtual machine using the following command:

multipass launch --name cli-tools --cloud-init ./cli-tools.yaml

This will take several minutes to start the virtual machine and apply the configuration.

Once the virtual machine is started, you need to mount the local file system for use within the virtual machine.

Then mount the file system using the following command:

multipass mount $PWD cli-tools:/automation

This will mount the parent directory to the /automation directory inside of the virtual machine.

⚠️ MacOS users may encounter the following error if Multipass has not been granted file system access.

mount failed: source "{current directory}" is not readable

If you encounter this error, then you need to enable full disk access in the operating system before you can successfully mount the volume. Go to System Preferences, then go to Security and Privacy, and select the Privacy tab. Scroll the list on the left and select "Full Disk Access" and allow access for multipassd.

Multipass security settings

After granting access to multipassd, then re-run the multipass mount $PWD cli-tools:/automation command.

Once the virtual machine has started, run the following command to enter an interactive shell:

multipass shell cli-tools

Once in the shell, cd into the /automation/{template} folder, where {template} is the Terraform template you configured. Then you need to load credentials into environment variables using the following command:

source credentials.properties

Once complete, you will be in an interactive shell that is pre-configured with all dependencies necessary to execute the Terraform automation.

Unsupported runtimes

Additional container engines, such as podman or colima may be used at your own risk. They may work, however, there are known issues using these environments, and the development team does not provide support for these environments.

Known issues include:

  1. Network/DNS failures under load
  2. Read/write permissions to local storage volumes
  3. Issues running binary executables from volumes mounted from the host
  4. Time drift issues when hosts are suspended/resumed

Colima instructions

  • Install Brew
  • Install Colima (a replacement for Docker Desktop ) and the docker cli
brew install colima docker

Podman instructions

Unlike Docker which traditionally has separated a cli from a daemon-based container engine, Podman is a daemon-less container engine originally developed for Linux systems. There is a MacOS port which has sufficient features to support running the automation based on container images. Podman can run containers in root or rootless mode. Current permissions setup in the launch.sh script will require root mode.

Getting started with Podman for MacOS

  • Install Brew
  • Install Podman (a replacement for Docker Desktop ) and the docker cli
brew install podman docker
  • Create a podman machine, set it to run in rootful mode and start it
podman machine init
podman machine set --rootful
podman machine start

Once the podman vm is started, use the automation template's launch.sh script to launch an interactive shell where the Terraform automation can be executed.

Dealing with known issues for Podman on MacOS

  • When resuming from suspend, if the podman machine is left running, it will not automatically synchronize to the host clock. This will cause the podman machine to lose time. Either stop/restart the podman machine or define an alias like this in your startup scripts:

    alias fpt="podman machine ssh \"sudo chronyc -m 'burst 4/4' makestep; date -u\""

    then fix podman time with the fpt command.

  • There is currently an QEMU bug which prevents binary files that should be executable by the podman machine vm from operating from inside a mounted volume path. This is most common when using the host automation directory, vs a container volume like /workspaces for running the automation. Generally the cli-tools image will have any binary needed and the utils-cli module will symbolically link, vs. download a new binary into this path. However there can be drift between binaries in cli-tools image used by launch.sh and those requested to the utils-cli module.

Getting started with Podman for Linux

Once the podman application is installed provide sudo podman as the first argument to the automation template's launch.sh script to launch an interactive shell where the Terraform automation can be executed:

./launch.sh 'sudo podman'