Configuration Reference

tplbuild has two main configuration files. The project configuration controls how tplbuild interacts and behaves with a specific tplbuild project. It should be included in source control and shared among all developers on the project. The user configuration, on the other hand, controls user-level configuration options like which builder to use, what level of parallelism to build with, and how to authenticate with registries and is not shared.

Project Config

A project can be configured by creating a file named tplbuild.yml. When tplbuild is invoked it will look for this file in the current directory to configure the current project. Very basic projects that just need source image locks do not require a tplbuild.yml file. The schema for tplbuild.yml is given by the tplbuild.config.TplConfig model. An example tplbuild.yml file is below:

tplbuild.yml
# Must be version '1.0' (will be assumed to be latest if omitted)
version: "1.0"

# Define how base images are named and where they are pushed. This is required
# if using base images in your build file.
base_image_repo: docker.myorg.com/base-{stage_name}

# Define how to tag top-level images.
stage_image_name: "{{ stage_name }}"

# Define how to publish top-level images to a registry.
stage_push_name: msg555/{{ stage_name }}:{{ profile }}

# List of platforms to build images for.
platforms:
  - linux/amd64
  - linux/arm64

# Define build profiles. Each profile can be any free-form yaml data that
# will be made available when rendering under the variable name `vars`.
default_profile: dev
profiles:
  dev:
    python_version: '3.8'
    install_dev: yes
  release:
    python_version: '3.8'
    install_dev: no

# Control what file data is passed to the build.
contexts:
  default:
    ignore: |
      *
      !myproject
      !requirements*

# Control which stages are base images and how stages are tagged/pushed.
# Usually you can just prefix your stage names with "base-" (or "base_")
# to mark stages as base images. Similarly you can use "anon-" to mark an
# image as non-base but also not meant to be tagged/pushed.
stages:
  my-base-image:
    base: yes
  my-main-image:
    base: no

# Configure where tplbuild will look for the entrypoint template and any
# other templates referenced with include statements.
template_paths:
  - build
  - build/lib

# Define the main template entrypoint to render all stages
template_entrypoint: Dockerfile

Full documentation of each field within the tplbuild configure file can be found below:

pydantic model TplConfig[source]

Configuration settings for a single tplbuild project

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "TplConfig",
   "description": "Configuration settings for a single tplbuild project",
   "type": "object",
   "properties": {
      "version": {
         "title": "Version",
         "default": "1.0",
         "enum": [
            "1.0"
         ],
         "type": "string"
      },
      "base_image_repo": {
         "title": "Base Image Repo",
         "type": "string"
      },
      "stage_image_name": {
         "title": "Stage Image Name",
         "default": "{{ stage_name}}",
         "type": "string"
      },
      "stage_push_name": {
         "title": "Stage Push Name",
         "default": "{{ stage_name}}",
         "type": "string"
      },
      "dockerfile_syntax": {
         "title": "Dockerfile Syntax",
         "default": "",
         "pattern": "^[^\\s]*$",
         "type": "string"
      },
      "platforms": {
         "title": "Platforms",
         "default": [
            "linux/amd64"
         ],
         "type": "array",
         "items": {
            "type": "string"
         }
      },
      "profiles": {
         "title": "Profiles",
         "default": {
            "default": {}
         },
         "type": "object",
         "additionalProperties": {
            "type": "object"
         }
      },
      "default_profile": {
         "title": "Default Profile",
         "default": "",
         "type": "string"
      },
      "contexts": {
         "title": "Contexts",
         "default": {
            "default": {
               "base_dir": ".",
               "umask": "022",
               "ignore_file": null,
               "ignore": null
            }
         },
         "type": "object",
         "additionalProperties": {
            "$ref": "#/definitions/TplContextConfig"
         }
      },
      "stages": {
         "title": "Stages",
         "default": {},
         "type": "object",
         "additionalProperties": {
            "$ref": "#/definitions/StageConfig"
         }
      },
      "template_paths": {
         "title": "Template Paths",
         "default": [
            "."
         ],
         "type": "array",
         "items": {
            "type": "string"
         }
      },
      "template_entrypoint": {
         "title": "Template Entrypoint",
         "default": "Dockerfile",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "definitions": {
      "TplContextConfig": {
         "title": "TplContextConfig",
         "description": "Config model representing a build context.",
         "type": "object",
         "properties": {
            "base_dir": {
               "title": "Base Dir",
               "default": ".",
               "type": "string"
            },
            "umask": {
               "title": "Umask",
               "default": "022",
               "type": "string"
            },
            "ignore_file": {
               "title": "Ignore File",
               "type": "string"
            },
            "ignore": {
               "title": "Ignore",
               "type": "string"
            }
         },
         "additionalProperties": false
      },
      "StageConfig": {
         "title": "StageConfig",
         "description": "Configuration data for a named build stage",
         "type": "object",
         "properties": {
            "base": {
               "title": "Base",
               "default": false,
               "type": "boolean"
            },
            "image_names": {
               "title": "Image Names",
               "type": "array",
               "items": {
                  "type": "string"
               }
            },
            "push_names": {
               "title": "Push Names",
               "type": "array",
               "items": {
                  "type": "string"
               }
            }
         },
         "additionalProperties": false
      }
   }
}

Config:

  • extra: Extra = forbid

Fields:
field version: Literal['1.0'] = '1.0'

Must be “1.0”

field base_image_repo: Optional[str] = None

Jinja template that renders to the image repo where a base image will be stored. This should not include a tag as tplbuild uses the tag itself to identify the content-addressed build. This template is passed “stage_name”, “profile”, and “platform” corresponding to the name of the stage, the name of the profile that rendered the image, and the name of the build platform respectively.

field stage_image_name: str = '{{ stage_name}}'

A Jinja template that renders to the default image name for a given stage_name. This template is passed “vars”, “stage_name”, “profile”, “and “platform” parameters.

field stage_push_name: str = '{{ stage_name}}'

A Jinja template that renders to the default push name for a given stage_name. This template is passed “vars”, “stage_name”, “profile”, “and “platform” parameters.

field dockerfile_syntax: ConstrainedStrValue = ''

The dockerfile “syntax” to use as the build frontend when running against builders that understand the “syntax” directive. For some build clients specifiying a syntax may be required (e.g. the buildx client requires docker/dockerfile:1.4 or later).

Constraints:

  • pattern = ^[^s]*$

field platforms: List[str] = ['linux/amd64']

List of platforms to build images for. This defaults to linux/amd64 but should be explicitly configured. Base images will be built for each platform listed here allowing for top-level images to be built in any of those platforms or as manifest lists when pushed.

field profiles: Dict[str, Dict[str, Any]] = {'default': {}}

A mapping of profile names to string-key template arguments to pass to any documents rendered through Jinja for each profile. Defaults to a single empty profile named ‘default’.

field default_profile: str = ''

The name of the default profile to use. If this is empty the first profile name from profiles will be used instead. Profile data will be made availble when rendering under the variable name vars.

field contexts: Dict[str, TplContextConfig] = {'default': TplContextConfig(base_dir='.', umask='022', ignore_file=None, ignore=None)}
field stages: Dict[str, StageConfig] = {}

A mapping of stage names to stage configs. This can be used to override the default behavior of tplbuild or apply different or more than just a single image name to a given stage. See Tplbuild.default_stage_config() for information about default stage configuration.

field template_paths: List[str] = ['.']

Search directories for included tempates. Paths must be relative to the project base directory.

field template_entrypoint: str = 'Dockerfile'

Template entrypoint to render to generate all build stages. Path should be relative to one of the template_paths.

pydantic model TplContextConfig[source]

Config model representing a build context.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "TplContextConfig",
   "description": "Config model representing a build context.",
   "type": "object",
   "properties": {
      "base_dir": {
         "title": "Base Dir",
         "default": ".",
         "type": "string"
      },
      "umask": {
         "title": "Umask",
         "default": "022",
         "type": "string"
      },
      "ignore_file": {
         "title": "Ignore File",
         "type": "string"
      },
      "ignore": {
         "title": "Ignore",
         "type": "string"
      }
   },
   "additionalProperties": false
}

Config:

  • extra: Extra = forbid

Fields:
field base_dir: str = '.'

The base directory (relative to the config base directory) of the build context. This must be a relative path and cannot point above the config base directory.

field umask: Optional[str] = '022'

The umask as a three digit octal string. This may also be set to None if the context permissions should be passed through directly. This parameter helps ensure base images are stable across developers who may have different group/all permissions set.

field ignore_file: Optional[str] = None

The ignore_file to load patterns from. If this and ignore are both None then this will attempt to load “.dockerignore”, using an empty list of patterns if that cannot be loaded.

field ignore: Optional[str] = None

Ignore file string. If present this will be used over ignore_file.

pydantic model StageConfig[source]

Configuration data for a named build stage

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "StageConfig",
   "description": "Configuration data for a named build stage",
   "type": "object",
   "properties": {
      "base": {
         "title": "Base",
         "default": false,
         "type": "boolean"
      },
      "image_names": {
         "title": "Image Names",
         "type": "array",
         "items": {
            "type": "string"
         }
      },
      "push_names": {
         "title": "Push Names",
         "type": "array",
         "items": {
            "type": "string"
         }
      }
   },
   "additionalProperties": false
}

Config:

  • extra: Extra = forbid

Fields:
field base: bool = False

Is the stage a base stage. If True then image_names and push_names must be left as None.

field image_names: Optional[List[str]] = None

All image names to assign to the built image. These values are templates that will be rendered in the same manner as tplbuild.config.TplConfig.stage_image_name. If left as None TplConfig.stage_image_name will be used instead as the default.

field push_names: Optional[List[str]] = None

All image names to assign and then push to remote registries when when publishing images. These values are templates that will be rendered in the same manner as tplbuild.config.TplConfig.stage_push_name. If left as None TplConfig.stage_push_name will be used instead as the default.

User Config

The user configuration controls configuration options that are not specific to a particular project like what builder backend to use. tplbuild will look for a user configuration in the following places

  • ~/.tplbuildconfig.yml

  • .tplbuildconfig.yml

If multiple configuration files are present the top-level values of the later configuration files will overwrite the earlier ones.

pydantic model UserConfig[source]

User settings controlling tplbuild behavior

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "UserConfig",
   "description": "User settings controlling tplbuild behavior",
   "type": "object",
   "properties": {
      "version": {
         "title": "Version",
         "default": "1.0",
         "enum": [
            "1.0"
         ],
         "type": "string"
      },
      "client_type": {
         "title": "Client Type",
         "default": "docker",
         "type": "string"
      },
      "client": {
         "title": "Client",
         "default": {
            "build": {
               "template": ""
            },
            "tag": {
               "template": ""
            },
            "pull": null,
            "push": {
               "template": ""
            },
            "untag": {
               "template": ""
            },
            "platform": null
         },
         "allOf": [
            {
               "$ref": "#/definitions/ClientConfig"
            }
         ]
      },
      "build_jobs": {
         "title": "Build Jobs",
         "default": 0,
         "type": "integer"
      },
      "push_jobs": {
         "title": "Push Jobs",
         "default": 4,
         "type": "integer"
      },
      "tag_jobs": {
         "title": "Tag Jobs",
         "default": 8,
         "type": "integer"
      },
      "build_retry": {
         "title": "Build Retry",
         "default": 0,
         "type": "integer"
      },
      "push_retry": {
         "title": "Push Retry",
         "default": 0,
         "type": "integer"
      },
      "ssl_context": {
         "title": "Ssl Context",
         "default": {
            "insecure": false,
            "cafile": null,
            "capath": null,
            "cadata": null,
            "load_default_certs": false
         },
         "allOf": [
            {
               "$ref": "#/definitions/UserSSLContext"
            }
         ]
      },
      "auth_file": {
         "title": "Auth File",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "definitions": {
      "ClientCommand": {
         "title": "ClientCommand",
         "description": "Configuration to invoke an external build command.",
         "type": "object",
         "properties": {
            "template": {
               "title": "Template",
               "type": "string"
            }
         },
         "required": [
            "template"
         ],
         "additionalProperties": false
      },
      "ClientConfig": {
         "title": "ClientConfig",
         "description": "Configuration of commands to perform various container operations. This is\nmeant to be a generic interface that could plug into a variety of container\nbuild systems. Typically you can just set :attr:`UserConfig.client_type` to\nselect from preconfigured client configurations.",
         "type": "object",
         "properties": {
            "build": {
               "$ref": "#/definitions/ClientCommand"
            },
            "tag": {
               "$ref": "#/definitions/ClientCommand"
            },
            "pull": {
               "$ref": "#/definitions/ClientCommand"
            },
            "push": {
               "$ref": "#/definitions/ClientCommand"
            },
            "untag": {
               "$ref": "#/definitions/ClientCommand"
            },
            "platform": {
               "$ref": "#/definitions/ClientCommand"
            }
         },
         "required": [
            "build",
            "tag",
            "push",
            "untag"
         ],
         "additionalProperties": false
      },
      "UserSSLContext": {
         "title": "UserSSLContext",
         "description": "Custom SSL context used to contact registries",
         "type": "object",
         "properties": {
            "insecure": {
               "title": "Insecure",
               "default": false,
               "type": "boolean"
            },
            "cafile": {
               "title": "Cafile",
               "type": "string"
            },
            "capath": {
               "title": "Capath",
               "type": "string"
            },
            "cadata": {
               "title": "Cadata",
               "type": "string"
            },
            "load_default_certs": {
               "title": "Load Default Certs",
               "default": false,
               "type": "boolean"
            }
         },
         "additionalProperties": false
      }
   }
}

Config:

  • extra: Extra = forbid

Fields:
field version: Literal['1.0'] = '1.0'

Must be “1.0”

field client_type: str = 'docker'

If client is None this field will be used to set the client configuration. Supported values are currently “docker” and “podman”. If client is not None this field is ignored.

field client: ClientConfig = ClientConfig(build=ClientCommand(template=''), tag=ClientCommand(template=''), pull=None, push=ClientCommand(template=''), untag=ClientCommand(template=''), platform=None)

Client commands to use to perform different container actions. If unset a default configuration will be provided based on the value of client_type. If you wish to use a different builder or supply additional arguments to the build this would be the place to do it.

field build_jobs: int = 0

Maximum number of concurrent build jbs. If set to 0 this will be set to os.cpu_count().

field push_jobs: int = 4

Maximum number of concurrent push or pull jobs.

field tag_jobs: int = 8

Maximum number of concurrent tag jobs.

field build_retry: int = 0

Maximum number of times a build will be retried before failing a build.

field push_retry: int = 0

Maximum number of times a push or pull will be retried before failing a build.

field ssl_context: UserSSLContext = UserSSLContext(insecure=False, cafile=None, capath=None, cadata=None, load_default_certs=False)

Configure the SSL context used to contact registries. This only controls accesses made by tplbuild itself. The client builder may need to be configured separately.

field auth_file: Optional[str] = None

The path to the container auth configuration file to use when contacting registries. By default this will check the default search paths and conform to the syntax described in https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md.

pydantic model ClientConfig[source]

Configuration of commands to perform various container operations. This is meant to be a generic interface that could plug into a variety of container build systems. Typically you can just set UserConfig.client_type to select from preconfigured client configurations.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "ClientConfig",
   "description": "Configuration of commands to perform various container operations. This is\nmeant to be a generic interface that could plug into a variety of container\nbuild systems. Typically you can just set :attr:`UserConfig.client_type` to\nselect from preconfigured client configurations.",
   "type": "object",
   "properties": {
      "build": {
         "$ref": "#/definitions/ClientCommand"
      },
      "tag": {
         "$ref": "#/definitions/ClientCommand"
      },
      "pull": {
         "$ref": "#/definitions/ClientCommand"
      },
      "push": {
         "$ref": "#/definitions/ClientCommand"
      },
      "untag": {
         "$ref": "#/definitions/ClientCommand"
      },
      "platform": {
         "$ref": "#/definitions/ClientCommand"
      }
   },
   "required": [
      "build",
      "tag",
      "push",
      "untag"
   ],
   "additionalProperties": false,
   "definitions": {
      "ClientCommand": {
         "title": "ClientCommand",
         "description": "Configuration to invoke an external build command.",
         "type": "object",
         "properties": {
            "template": {
               "title": "Template",
               "type": "string"
            }
         },
         "required": [
            "template"
         ],
         "additionalProperties": false
      }
   }
}

Config:

  • extra: Extra = forbid

Fields:
field build: ClientCommand [Required]

Build command config template. This should render an appropriate command to build an image using a dockerfile named “Dockerfile” and build context provided by stdin. The output should be tagged as the passed argument image.

Parameters:

  • image – str - The image name to tag the output

  • platform – str? - The build platform to use if known.

field tag: ClientCommand [Required]

Tag command config template. This should tag an existing image with a new image name.

Parameters:

  • source_image – str - The source image name

  • dest_image – str - The new name to tag source_image as

field pull: Optional[ClientCommand] = None

Pull command config template. This should pull the named image from the remote registry into local storage.

Parameters:

image – str - The name of the image to pull

field push: ClientCommand [Required]

Push command config template. This should push the named image to the remote registry from local storage.

Parameters:

image – str - The name of the image to push

field untag: ClientCommand [Required]

Un-tag command config template. This should untag the named image allowing data referenced by the image to be reclaimed.

Parameters:

image – str - The name of the image to untag

field platform: Optional[ClientCommand] = None

Command that should print out the default build platform for the client. This template is passed no additional arguments. If this command is not available the default build platform will be calculated using the local client platform instead. The output will be normalized to convert e.g. “linux/x64_64” to “linux/amd64”. This will only be used for platform aware build configurations.

pydantic model ClientCommand[source]

Configuration to invoke an external build command.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "ClientCommand",
   "description": "Configuration to invoke an external build command.",
   "type": "object",
   "properties": {
      "template": {
         "title": "Template",
         "type": "string"
      }
   },
   "required": [
      "template"
   ],
   "additionalProperties": false
}

Config:

  • extra: Extra = forbid

Fields:
field template: str [Required]

A jinja template used to construct invoke arguments and environment variables based on the template arguments passed. Depending on the build command different template arguments may be passed. All templates are passed an args list and an environment dict that they should populate with the command arguments and environment variables used to invoke the build command. The output of the template will be ignored.

render(jinja_env: Environment, params: Dict[str, str]) → Tuple[List[str], Dict[str, str]][source]

Return the list of arguments and addition environment variables to pass to execute the rendered command.

pydantic model UserSSLContext[source]

Custom SSL context used to contact registries

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema
{
   "title": "UserSSLContext",
   "description": "Custom SSL context used to contact registries",
   "type": "object",
   "properties": {
      "insecure": {
         "title": "Insecure",
         "default": false,
         "type": "boolean"
      },
      "cafile": {
         "title": "Cafile",
         "type": "string"
      },
      "capath": {
         "title": "Capath",
         "type": "string"
      },
      "cadata": {
         "title": "Cadata",
         "type": "string"
      },
      "load_default_certs": {
         "title": "Load Default Certs",
         "default": false,
         "type": "boolean"
      }
   },
   "additionalProperties": false
}

Config:

  • extra: Extra = forbid

Fields:
field insecure: bool = False

Disable SSL/TLS verification

field cafile: Optional[str] = None

File path to load CA certificates to trust.

field capath: Optional[str] = None

Folder container CA certificate files to trust.

field cadata: Optional[str] = None

Raw certificate data to trust.

field load_default_certs: bool = False

If True default system certs will be loaded in addition to any certs implied by cafile, capath, or cadata. Normally these will only be loaded if those are all unset.

create_context() → SSLContext[source]

Returns a SSLContext constructed from the passed options