Docker driver options

Docker driver options specification

The following table describes the attributes that can be configured on the Docker driver.

Keywords reference for Docker driver

KeywordTypeDescriptionValue
contextmap/list(map)The Docker build context is a set of files required to build a Docker image. It can be located on a local path or in a git repository.
Starting from Stevedore v0.11, you can define a list of contexts that get merged to create the ultimate Docker build context.
mandatory
Each context type has its own specifications.
Refer to the Docker build contexts section for a detailed description of how to configure each context.
dockerfilestringDockerfiles’s location path. The path is relative to context root.
optional
By default, is used the Dockerfile located at the root of the context.

Docker build contexts

Stevedore supports two kinds of Docker build context. The path context, which uses a local folder to create the Docker build context, and the git context, which creates the Docker build context from a git repository.

Path context

KeywordTypeDescriptionValue
pathstringIt specifies where to find the files required to build the image.
mandatory
-

Here you have an example where you can see all the options of the path context.

Path context example

The goal of the following example is to show you all the configuration options for the path context.

1
2
3
4
5
6
builder:
  driver: docker
  options:
    dockerfile: Dockerfile.alpine
    context:
      - path: /src/my-app

Git context

KeywordTypeDescriptionValue
gitmapIt is the keyword under which are defined the git repository details.
Refer here to know the accepted attributes.
mandatory
-

Here you have an example where you can see all the options of the git context.

Git attributes
KeywordTypeDescriptionValue
authmapYou can provide authorization mechanisms over a Git server to achive the Docker build context from there.
Refer here to know more about the available auth mechanisms.
optional
-
pathstringIs the relative path within the repository, to use as build context.The root of the repository is considered the default path.
repositorystringRepository specifies the git repository to find the files to build the image. repository keyword is placed under git.
mandatory
-
referencestringRepository reference required to build the image. reference keyword is placed under git.
optional
By default, is used refs/heads/master reference, that belongs to go-git project.
Git authorization

Stevedore enables you to obtain authorization from a Git server using basic authentication, which involves providing a username and password, or by using a private key. Alternatively, the SSH agent on your system can be used as a fallback method.

You can provide the necessary information for obtaining authorization either by directly setting the auth attribute or by specifying a credential ID, in which case the information will be retrieved from the credential store.

For security concerns, the recommendation is to use the credentials store or the SSH agent rather than set the credentials directly in the builder.

KeywordTypeDescriptionValue
usernamestringThis attribute provides the username for the basic authentication method.
optional
-
passwordstringThis attribute provides the password for the basic authentication method.
optional
-
git_ssh_userstringThe username to use when authenticating.
optional
git
private_key_filestringThe private_key_file attribute is used to provide the path to the private key file.
optional
-
private_key_passwordstringHolds the password for the private key file.
optional
-
credentials_idstringIs the ID of the credential used to retrieve the authorization information from the credentials store.
optional
-
Git context example

The goal of that example is to show you all the configuration options for the git context, including the various authentication mechanisms that can be used to access a Git repository.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
builder:
  driver: docker
  options:
    dockerfile: Dockerfile.alpine
    context:
      - git:
          repository: git@gitserver.stevedore.test:/git/repos/my-app.git
          reference: v0.1.2
          path: src
          auth:
            username: user
            password: pAss
            git_ssh_user: git
            private_key_file: /home/user/.ssh/id_rsa
            private_key_password: s3cr3t
            credentials_id: gitserver.stevedore.test

Variables-mapping reference

Docker driver passes variables mapping to Docker API as build arguments and each variable can be consumed as an ARG inside the Dockerfile definition.

Key nameDescriptionDefault
argument-name
Default
argument-value
image_from_fully_qualified_nameThis is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.2.
image_from_fully_qualified_nameThis is the argument-name that provides you with fully-qualified parent image name.
image_from_name_keyThis is the argument-name that you can use to set the name of the base image that you want to use as a starting point for your Docker image.image_from_nameThe argument-value is set as the parent image’s name within the images-tree.
image_from_registry_host_keyThis is the argument-name that you can use to set the Docker registry host where the base image is located.image_from_registry_hostThe argument-value is set as the parent image’s registry host within the images-tree.
image_from_registry_namespace_keyThis is the argument-name that you can use to set the namespace of the Docker registry where the base image is located.image_from_registry_namespaceThe argument-value is set as the parent image’s namespace within the images-tree.
image_from_tag_keyThis is the argument-name that you can use to set the tag of the base image that you want to use as a starting point for your Docker image.image_from_tagThe argument-value is set as the parent image’s version within the images-tree.

Docker driver example

The following example is provided for illustrative purposes only and should not be copied and pasted into your configuration.

The goal of the following example is to show you all the configuration options for a builder which uses the docker driver.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
builder:
  driver: docker
  options:
    dockerfile: Dockerfile.alpine
    context:
      - path: /src/my-app
      - git:
          repository: git@gitserver.stevedore.test:/git/repos/build.git
          reference: v0.1.2
          path: dockerfiles
          auth:
            username: user
            password: pAss
            git_ssh_user: git
            private_key_file: /home/user/.ssh/id_rsa
            private_key_password: s3cr3t
            credentials_id: gitserver.stevedore.test
    variables_mapping:
      image_from_name_key: image_from_name_custom
      image_from_registry_host_key: image_from_registry_host_custom
      image_from_registry_namespace_key: image_from_registry_namespace_custom
      image_from_tag_key: image_from_tag_custom

And finally here you have the example of the Dockerfile

1
2
3
4
5
6
ARG image_from_registry_host_custom
ARG image_from_registry_namespace_custom
ARG image_from_name_custom
ARG image_from_tag_custom
FROM ${image_from_registry_host_custom}/${image_from_registry_namespace_custom}/${image_from_name_custom}:${image_from_tag_custom}
RUN <set-your-action>

Last modified December 27, 2023: markdown linter (c2b6160)