Bill of Material Concepts¶

A Bill of Material, often referred to as a BOM, is used to orchestrate a set of modules to define a required computing environment.

What is a Bill of Material?¶

A bill of material is a yaml file, that defines a computing environment by including the modules that will provide the automation to realize the required computing environment.

The structure of the yaml file has been modelled after the Kubernetes Custom Resource Definition. Details of the yaml file syntax and content can be found in the Bill of Materials reference

A bill of material does not need to specify every module that must be deployed because modules specify their dependencies. This allows the Toolkit tooling to resolve dependencies automatically unless:

• a dependency doesn't resolve to a specific module, such as an interface
• there are more complex dependency requirements, such as where a dependency may need to be shared between multiple modules in the BOM, rather than each module getting its own copy of its dependent modules

A Bill of Materials allows you to provide module configuration using the variables property. In general you should think of a Bill of Materials as a template that can be used to create multiple instances of a desired environment.

You might want to provide configuration data in the BOM for properties that need to apply to all instances of the environment created, such as the number of worker nodes for a BOM deploying a Kubernetes cluster for testing, but shouldn't include properties that need to change for each environment instance.

How does a Bill of Material work?¶

The Bill of Material specifies the modules that should be deployed to realize the required environment. To create the desired environment there are 3 steps needed:

1. run the iascable tool to process the BOM
2. [optionally] run the generated launch.sh script to enter the tooling VM or container environment
3. run the generated apply.sh script to run the required automation

Process the BOM¶

The first process needed when deploying a Bill of Material is to resolve all the module dependencies. The iascable build command creates:

• a fully resolved BOM, where all module dependencies are fully resolved and included in the resolved BOM
• the launch.sh and apply.sh scripts
• the Terraform application from the modules specified in the fully resolved BOM to create the desired environment

By default the iascable command line tool uses the Toolkit default module catalog, but additional catalog URLs can be specified in the BOM or as iascable command line arguments to allow private or 3rd party module catalogs to be used.

If the BOM contains a module that the dependencies cannot be resolved, then an error will be reported and you will need to add the missing dependency to the BOM.

Launching the standard Tooling runtime¶

docs/getting-started/setup/setup.md

As discussed in the Getting Started section there are a number of tools used when deploying an environment. To remove issues with version incompatibility and the differences between command line processors a standard environment should be used as a virtual machine (using multipass) or as a container (using Docker). The launch.sh script generated by the iascable build command provides a convenient way to launch the standard toolkit environment. It also ensures that any environment variables configured by the user are set in the virtual machine or container.

Running the automation to create the desired environment¶

The apply.sh script is generated by the iascable build command. It is used to run the automation to deploy the desired environment, but before starting the deployment it ensures that all required configuration data is provided.

Module configuration can be fulfilled from a number of sources:

• Module configuration can have default values
• the BOM can contain values for configuration
• environment variables can be configured
• a variables.yaml file can be use to provide configuration data

If there is no value provided for any of the configuration properties of any module in the BOM then the apply script will prompt for the value to be entered on the command line.

Once all the configuration data is fully provided then the apply script will start the Terraform application to realize the environment specified in the BOM by running the terraform init then terraform apply commands.