Docker driver options

Docker driver options specification

Tags:

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

Keywords reference for Docker driver

Keyword	Type	Description	Value
context	map/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.
dockerfile	string	`Dockerfiles`’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

Keyword	Type	Description	Value
path	string	It 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

Keyword	Type	Description	Value
git	map	It 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

Keyword	Type	Description	Value
auth	map	You 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	-
path	string	Is the relative path within the repository, to use as build context.	The root of the repository is considered the default path.
repository	string	Repository specifies the git repository to find the files to build the image. `repository` keyword is placed under `git`. mandatory	-
reference	string	Repository 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.

Keyword	Type	Description	Value
username	string	This attribute provides the username for the basic authentication method. optional	-
password	string	This attribute provides the password for the basic authentication method. optional	-
git_ssh_user	string	The username to use when authenticating. optional	git
private_key_file	string	The private_key_file attribute is used to provide the path to the private key file. optional	-
private_key_password	string	Holds the password for the private key file. optional	-
credentials_id	string	Is 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 name	Description	Default argument-name	Default argument-value
image_from_fully_qualified_name	This 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_name	This is the argument-name that provides you with fully-qualified parent image name.
image_from_name_key	This 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_name	The argument-value is set as the parent image’s name within the images-tree.
image_from_registry_host_key	This is the argument-name that you can use to set the Docker registry host where the base image is located.	image_from_registry_host	The argument-value is set as the parent image’s registry host within the images-tree.
image_from_registry_namespace_key	This 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_namespace	The argument-value is set as the parent image’s namespace within the images-tree.
image_from_tag_key	This 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_tag	The 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)