Setup you learning and development environment¶

The automation used within the toolkit uses a number of open source tools and utilities. To avoid issues with different operating systems, command line interpreters (shells) and versions of the various tools, it is recommended that a container or virtual machine is used, so you will have a verified working environment for the automation to run in.

Some of the tools used are:

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

Supported runtime environments¶

The developers do not have the bandwidth to run and test will all possible combinations of runtimes across different operating systems, so these are the recommended, tested OS/runtime environments:

Docker¶

Docker Desktop provides a container environment for MacOS. It is free to use for non-commercial uses, but requires a license for commercial use.

If the license isn't an issue then this is the simplest, recommended option to use.

If running on Linux or Windows Subsystem for Linux, then docker engine is the recommended option to use.

Multipass¶

Multipass is a free virtual machine environment for Windows, MacOS and Linux to run Ubuntu images. Only Multipass on MacOS is supported within this documentation.

Additional unsupported options¶

There are some additional environments that are used within the community, but these are not supported and cannot be guaranteed to work. There are also some known issues with the environments listed below:

• podman
• colima

Podman¶

Podman is an open source tool, free to use, that provides much the same functionality as Docker Desktop. There are some known issues with Podman:

• 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.

Colima¶

Colima is an open source container engine for Intel or Arm based Mac systems. It is free to use, but there are some known issues with Colima:

• Network/DNS failures under load
• Read/write permissions to local storage volumes
• Issues running binary executables from volumes mounted from the host

Setup instructions¶

Instructions for setting up your chosen container or VM environment are covered in the first tutorial