Concepts

Build

The process to generate a Docker image.

Builder

A Builder arranges a set of parameters to build a Docker image, as well as the driver to perform the build. Among those parameters, you can define the Docker build context or Dockerfile location.

A Builder can be defined as global builder or in-line builder. Global builders are defined within the builders’ folder and can be used by any image’s definition. Refer to configuration to know how to set the builders’ location path.

On the snipped below there are defined two global builders: code, at line 2 and global-infr-builder, at line 7.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

builders:
  code:
    driver: docker
    options:
      context:
        path: .
  global-infr-builder:
    driver: ansible-playbook
    options:
      inventory: inventory/all
      playbook: build_applications.yml

You can define a builder inside the image definition. That builder is known as in-line builder.

On the next snipped is defined an in-line builder:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

simple-go-helloworld:
  "0.0.1":
    version: "{{ .Version }}"
    builder:
      driver: docker
      options:
        context:
          git: 
            repository: https://github.com/apenella/simple-go-helloworld.git
      variables_mapping:
        image_name_key: image
        image_tag_key: tag

Credentials

Credentials are those secrets that Stevedore uses to authenticate on your behalf to a Docker registry.

Driver

Stevedore does not implement a mechanism to build Docker images, but it uses other tools created for that purpose. The driver prepares the build parameters, using the image’s definition as well as the builders’ ones, and performs the request to build the image.

As of today, Stevedore supports the following drivers:

• docker driver that uses the Docker API. When a builder is defined to use the docker driver, it must provide at least the context, along with other parameters such as Dockerfiles location. For further information refer to reference guide.
• ansible-playbook driver builds Docker images by executing ansible playbooks. When a builder is defined to use an ansible-playbook driver, it must provide the playbook location as well as the Ansible inventory. For further information refer to reference guide.

Image

An image definition, which is also known as image in Stevedore’s context, defines the Docker image you want to build, how to build it and the relationship with other images.

An image must be defined within the Images-tree, and you can refer to it by its name and version. For further information refer to reference guide.

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

my-image-base:
    "0.0.1":
        registry: my-registry.my-domain.cat 
        namespace: library
        tags:
        - latest 
        children:
            my-ms1:
            - stable
            - devel
            my-ms2:
            - stable
        builder:
            driver: docker
            options:
                context:
                    path: my-image-base

Images-tree

The Images-tree contains the definition of the images, as well as the relationship among them.

On the snipped below you can see three images defined within the Images-tree: my-image-base, at line 2, my-ms1, at line 21, and my-ms2, at line 32.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

images_tree:
    my-image-base:
        "stable":
            registry: my-registry.example.com 
            namespace: library
            tags:
            - latest 
            children:
                my-ms1:
                - "0.0.1"
                - devel
                - "*"
                my-ms2:
                - "0.1.5"
                - "*"
            builder:
                driver: docker
                options:
                    context:
                        path: my-image-base
    my-ms1:
        "0.0.1":
            registry: my-registry.example.com 
            namespace: library
        devel:
            registry: my-registry.example.com 
            namespace: library
        "*":
            registry: my-registry.example.com 
            namespace: library
            version: "{{ .Version }}"
    my-ms2:
        "0.1.5":
            registry: my-registry.example.com 
            namespace: library
        "*":
            registry: my-registry.example.com 
            namespace: library
            version: "{{ .Version }}"

Promote

Promoting an image, in Stevedore’s context, means pushing an image to the Docker registry or another namespace on the same Docker registry.

Semver tag

When a tag is semantic version 2.0.0 compliance is known as semver tag.

Wildcard version

An image is identified by a name and version. But you can also identify it by just the image name. In that case, that image must define a wildcard version on it. You can recognize when an image has defined a wildcard version because its value is * (start).

The wildcard version provides a fallback definition that can be used to build an image by giving any value to the version.

The next snipped provides an image with a wildcard version definition, at line 5. The {{ .Version }} could be set as any value used to build the my-app image.

1
2
3
4
5
6
7
8

my-app:
    "0.1.5":
        registry: my-registry.example.com 
        namespace: library
    "*":
        registry: my-registry.example.com 
        namespace: library
        version: "{{ .Version }}"

Variables mapping

Variables mapping (a.k.a. varmap or varmapping) is a builder’s optional attribute that defines the name of those variables that are automatically generated by Stevedore and used by the driver to perform the request to build an image.

Each driver defines its variables mapping. For further information refer to variables mapping reference guide.