Builder

A builder provides relevant information about how to build a Docker image. It is defined using a YAML data structure, and its schema is described on Keywords reference for builders configuration.

There are two types of builders: global and in-line. Global builders are defined in the builders configuration file and can be used by any image. Information on how to set the location path for the builders configuration file can be found in the configuration documentation.

In-line builders, on the other hand, are defined within the image definition itself.

Global builder

A global builder must be defined under the builders block inside the Stevedore configuration. It means that Stevedore looks for the builders block within the file defined in builder_path configuration parameter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

builders:
  builder1:
    driver: docker
    options:
      context:
        path: ./my-apps-golang
  builder2:
    driver: docker
    options:
      context:
        path: ./my-apps-phyton
  builder3:
    driver: ansible-playbook
    options:
      playbook: my-apps-base/site.yml
      inventory: my-apps-base/all

Through Stevedore CLI command, you can retrieve the value of the builder_path configuration parameter.

$ stevedore get configuration
PARAMETER                           VALUE
tree_path                           stevedore.yaml
builder_path                        stevedore.yaml
log_path                            /dev/null
num_workers                         4
push_images                         true
build_on_cascade                    false
docker_registry_credentials_dir     ~/.config/stevedore/credentials
semantic_version_tags_enabled       false
semantic_version_tags_templates     [{{ .Major }}.{{ .Minor }}.{{ .Patch }}]

In-line builder

When you want to create an image using an ad-hoc builder, you can provide it in the image definition itself. In that case, the builder is known as an in-line builder.

In-line builders are defined following the Keywords reference for builders configuration as well.

1
2
3
4
5
6
7
8
9

my-image-base:
  "0.0.1":
    registry: my-registry.my-domain.cat 
    namespace: library
    builder:
      driver: docker
      options:
        context:
          path: my-image-base

Keywords reference

The coming section describes the keyword attributes required to define a builder.

Builder options

Builder options are defined in a YAML data structure, and each driver has its own unique set of options. To learn more about which options are accepted by a particular driver, refer to the corresponding section:

• Keywords reference for Ansible playbook driver options
• Keywords reference for Docker driver options

Variables-mapping reference

Stevedore always sends a set of parameters to the driver when building a Docker image. These parameters are organized in a key-value data structure called variables_mapping. Importantly, these parameters are sent to the driver by Stevedore regardless of whether they have been explicitly specified in the image definition or as a CLI flag.

When Stevedore sets a parameter, it looks for the corresponding argument-name in the variables_mapping block within the builder’s definition. Users can override the default value of the argument-name by setting a new value for the argument in the variables_mapping block.

It’s important to understand the concepts within the variables-mapping context, such as the key name, argument name, and argument value:

• key name: This is used internally by Stevedore to identify the name of the argument to use during the image building process.
• argument name: This is the name of the argument that the driver receives to create a Docker image. Users can override it in the builder definition
• argument value: This is the value of the argument that the driver receives to create a Docker image. It can be specified in the image definition or CLI flags.

Each drivers receives a distinct set of parameters comming from variables-mapping. Refer to the following links to know more about variables that each driver receives:

• Variables-mapping for Ansible playbook driver
• Variables-mapping for Docker driver

Examples

Docker driver using path context

The following example demonstrates how to define a builder that uses Docker as the driver, with a local build context and a Dockerfile located at build/Dockerfile:

1
2
3
4
5
6

code:
  driver: docker
  options:
  context:
    path: .
  dockerfile: build/Dockerfile

Docker driver using git context

The following example demonstrates how to define a builder that uses Docker as the driver, with a remote Git repository as the build context and a Dockerfile located at build/Dockerfile. In this example, the Git repository https://github.com/apenella/simple-go-helloworld.git is used as the build context with the reference v0.0.0.

1
2
3
4
5
6
7
8

code:
  driver: docker
  options:
    context:
      git: 
        repository: https://github.com/apenella/simple-go-helloworld.git
        reference: v0.0.0
    dockerfile: build/Dockerfile

Ansible playbook driver

The following example shows how to define a builder that uses the ansible-playbook driver. In this example, the builder optiosn defines the ansible inventory and playbook, pointing to the Ansible inventory file located at inventory/all and the playbook file located at build_applications.yml.

1
2
3
4
5

infrastructure:
  driver: ansible-playbook
  options:
    inventory: inventory/all
    playbook: build_applications.yml