Dockertools¶

Functions for creating the Dockerfile or asset files.

concoursetools.dockertools.create_script_file(path, resource_class, method_name, executable='/usr/bin/env python3', permissions=493, encoding=None)[source]¶

Create a script file at a given path.

Parameters:

path (Path) – The path at which the file will be created.
resource_class (type[ConcourseResource[Any]]) – The ConcourseResource class to be exported.
method_name (Literal['check_main', 'in_main', 'out_main']) – The name of the method to be invoked.
executable (str) – The executable to use for the script (at the top).
permissions (int) – The (Linux) permissions the file should have. Defaults to rwxr-xr-x.
encoding (str | None) – The encoding of the file as passed to write_text(). Setting to None (default) will use the user’s default encoding.

Return type:

None

Dockerfile¶

For easier dynamic creation of Dockerfiles, the module contains a number of Instruction classes:

class concoursetools.dockertools.Instruction[source]¶

Represents an instruction in a Dockerfile.

abstractmethod to_string()[source]¶

Return the string representation of the item.

Return type:: str

A Comment class is also included:

class concoursetools.dockertools.Comment(comment)[source]¶

Represents a comment in a Dockerfile.

Comment:

The comment to be added.

Example:

>>> print(Comment("This is a comment"))
# This is a comment

Parameters:

comment (str)

to_string()[source]¶

Return the string representation of the item.

Return type:: str

All instructions and comments are added to a A Dockerfile instance in instruction groups:

class concoursetools.dockertools.Dockerfile(instruction_groups=None)[source]¶

Represents the contents of a Dockerfile.

Parameters:: instruction_groups (list[list[Instruction | Comment]] | None) – A list of lists of instructions or comments. Separation between groups is larger than between instructions within the group to imply sections to the Dockerfile.

new_instruction_group(*instructions)[source]¶

Add instructions to a new instruction group within the Dockerfile.

Parameters:: instructions (Instruction | Comment) – Instructions or comments to add to the new group.
Return type:: None

write_to_file(file_path, encoding=None)[source]¶

Write the contents of the Dockerfile to a path.

Parameters:

file_path (Path) – The location to which to write the contents.
encoding (str | None) – The encoding of the file. Defaults to the system default.

Return type:

None

to_string()[source]¶

Return the contents of the Dockerfile.

Return type:: str

Dockerfile Instructions¶

All currently relevant instructions have been implemented:

Instruction	Description	Classes
`ADD`	Add local or remote files and directories.
`ARG`	Use build-time variables.
`CMD`	Specify default commands.
`COPY`	Copy files and directories.	`CopyInstruction`
`ENTRYPOINT`	Specify default executable.	`EntryPointInstruction`
`ENV`	Set environment variables.	`EnvInstruction`
`EXPOSE`	Describe which ports your application is listening on.
`FROM`	Check a container’s health on startup.	`FromInstruction`
`HEALTHCHECK`	Check a container’s health on startup.
`LABEL`	Add metadata to an image.
`MAINTAINER`	Specify the author of an image.
`ONBUILD`	Specify instructions for when the image is used in a build.
`RUN`	Execute build commands.	`RunInstruction`, `MultiLineRunInstruction`
`SHELL`	Set the default shell of an image.
`STOPSIGNAL`	Specify the system call signal for exiting a container.
`USER`	Set user and group ID.
`VOLUME`	Create volume mounts.
`WORKDIR`	Change working directory.	`WorkDirInstruction`

class concoursetools.dockertools.CopyInstruction(source, dest=None)[source]¶

Represents a COPY instruction.

Parameters:

source (str) – The file/folder to be copied.
dest (str | None) – The destination on the image of the file/folder. If None, the destination will be the name of the source file/folder, and will be placed in the working directory on the image.

Example:

>>> print(CopyInstruction("folder/file.txt"))
COPY folder/file.txt file.txt
>>> print(CopyInstruction("folder/file.txt", "folder/new_file.txt"))
COPY folder/file.txt folder/new_file.txt

class concoursetools.dockertools.EntryPointInstruction(commands)[source]¶

Represents an ENTRYPOINT instruction.

Note

Docker recommends the “exec” form of this instruction over the “shell” form, and so the former is used here.

Parameters:

commands (list[str]) – The commands to be run.

Example:

>>> print(EntryPointInstruction(["python3", "-m", "http.server"]))
ENTRYPOINT ["python3", "-m", "http.server"]

class concoursetools.dockertools.EnvInstruction(variables)[source]¶

Represents an ENV instruction.

Parameters:

variables (dict[str, str]) – A mapping of environment variables to be set.

Example:

>>> print(EnvInstruction({"MY_NAME": "John Doe"}))
ENV MY_NAME="John Doe"
>>> print(EnvInstruction({"MY_NAME": "John Doe", "MY_AGE": "42"}))
ENV MY_NAME="John Doe" MY_AGE="42"

class concoursetools.dockertools.FromInstruction(image, tag=None, digest=None, platform=None)[source]¶

Represents a FROM instruction.

Parameters:

image (str) – The base image to be used.
tag (str | None) – An optional image tag.
digest (str | None) – An optional digest of the image.
platform (str | None) – Pass to specify the platform to be used, i.e. "windows/amd64".

Example:

>>> print(FromInstruction("python"))
FROM python
>>> print(FromInstruction("python", tag="3.11-slim"))
FROM python:3.11-slim
>>> print(FromInstruction("python", digest="sha256:380094..."))
FROM python@sha256:380094...
>>> print(FromInstruction("python", tag="3.11-slim", platform="linux/386"))
FROM --platform=linux/386 python:3.11-slim

class concoursetools.dockertools.RunInstruction(commands)[source]¶

Represents a RUN instruction.

Note

The shell form of this command is more common than the exec form, so the former is used.

Parameters:

commands (list[str]) – A list of commands to be run.

Example:

>>> print(RunInstruction(["pip install --upgrade pip"]))
RUN pip install --upgrade pip
>>> print(RunInstruction(["pip install --upgrade pip", "pip install -r requirements.txt"]))
RUN pip install --upgrade pip && pip install -r requirements.txt

class concoursetools.dockertools.MultiLineRunInstruction(commands, mounts=None)[source]¶

Represents a RUN instruction which will be split across multiple lines.

Parameters:

commands (list[str]) – A list of commands to be run.
mounts (list[Mount] | None) – A list of mounts to be used.

Example:

>>> print(MultiLineRunInstruction(
...     ["pip install --upgrade pip", "pip install -r requirements.txt"]
... ))
RUN \
    pip install --upgrade pip && \
    pip install -r requirements.txt
>>> print(MultiLineRunInstruction(
...     ["pip install --upgrade pip", "pip install -r requirements.txt"],
...     [SecretMount(secret_id="aws", target="/root/.aws/credentials")]
... ))
RUN \
    --mount=type=secret,id=aws,target=/root/.aws/credentials \
    pip install --upgrade pip && \
    pip install -r requirements.txt

class concoursetools.dockertools.WorkDirInstruction(work_dir)[source]¶

Represents a WORKDIR instruction.

Parameters:: work_dir (str) – The directory to set as the working directory on the image.

Dockerfile Mounts¶

The module also implements some mounts for the RUN step to facilitate secrets:

class concoursetools.dockertools.Mount[source]¶

Represents a mount for the run command.

to_string()[source]¶

Return a string representation of the mount.

Return type:: str

abstractmethod to_dict()[source]¶

Return a key/value mapping corresponding to the Dockerfile keys for this mount.

Return type:: dict[str, str]

All currently relevant mount types have been implemented:

Mount	Description	Classes
`bind`	Bind-mount context directories (read-only).
`cache`	Mount a temporary directory to cache directories for compilers and package managers.
`tmpfs`	Mount a `tmpfs` in the build container.
`secret`	Allow the build container to access secure files such as private keys without baking them into the image or build cache.	`SecretMount`
`ssh`	Allow the build container to access SSH keys via SSH agents, with support for passphrases.

class concoursetools.dockertools.SecretMount(secret_id=None, target=None, required=None, mode=None, user_id=None, group_id=None)[source]¶

Represents a mounted secret value.

Parameters:

secret_id (str | None) – The ID of the secret.
target (str | None) – The location at which the secret will be mounted.
required (bool | None) – If True, the instruction errors out when the secret is unavailable.
mode (int | None) – The file mode for secret file in octal.
user_id (int | None) – The user ID for secret file.
group_id (int | None) – The group ID for secret file.

Example:

>>> print(SecretMount(secret_id="aws", target="/root/.aws/credentials"))
--mount=type=secret,id=aws,target=/root/.aws/credentials