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 a 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 builders_path configuration parameter.

You can also set a directory on the builders_path. There you can create several files with the builders block defined on them. In that case, Stevedore loads the builders found within all files.

 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 builders_path configuration parameter.

$ stevedore get configuration

 builders_path: stevedore.yaml
 concurrency: 4
 semantic_version_tags_enabled: false
 images_path: stevedore.yaml
 push_images: false
 semantic_version_tags_templates:
   - {{ .Major }}.{{ .Minor }}.{{ .Patch }}
 credentials:
   storage_type: local
   format: json
   local_storage_path: credentials
   encryption_key: 12345asdfg

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 to the driver that comes from the variables_mapping, it searches for the corresponding argument-name in the variables_mapping dictionary in the builder’s definition. Users can override the default name of the argument by providing a new name for that argument in the same variables_mapping block.

For example, Stevedore sends the parent name and version to the driver even if the user doesn’t request them. These parameters are then passed as build arguments to Docker, making them available in the Dockerfile.

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 an argument to create during the image’s 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, CLI flags or by Stevedore itself. For more information on how Stevedore sets the argument value using variables-mapping, please refer to variables-mapping for Ansible playbook driver or variables-mapping for Docker driver.

Each driver receives a distinct set of parameters coming from variables-mapping. Refer to the following links to know more about the 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: /src/my-app
  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. Besides, the Git repository https://github.com/apenella/simple-go-helloworld.git is used as the build context with the reference v1.2.3.

1
2
3
4
5
6
7
8

code:
  driver: docker
  options:
    context:
      git: 
        repository: https://github.com/apenella/simple-go-helloworld.git
        reference: v1.2.3
    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