Configuration — ansible-bender 0.8.1 documentation

# Configuration

## Target image metadata

With dockerfiles, this is being usually done with instructions such as `LABEL`, `ENV` or `EXPOSE`. Bender supports two ways of configuring the metadata:

- Setting specific Ansible variables inside your playbook.

- CLI options of `ansible-bender build`.

### Via playbook vars

Configuration is done using a top-level Ansible variable `ansible_bender`. All the values are nested under it. The values are processed before a build starts. The changes to values are not reflected during a playbook run.

If your playbook has multiple plays, the `ansible_bender` variable is processed only from the first play. All the plays will end up in a single container image.

#### Top-level keys

Key name | type | description
--- | --- | ---
`base_image` | string | name of the container image to use as a base
`buildah_from_extra_args` | string | extra CLI arguments to pass to buildah from command
`ansible_extra_args` | string | extra CLI arguments to pass to ansible-playbook command
`working_container` | dict | settings for the container where the build occurs
`target_image` | dict | metadata of the final image which we built
`cache_tasks` | bool | When true, enable caching mechanism
`layering` | bool | When true, snapshot the image after a task is executed
`squash` | bool | When true, squash the final image down to a single layer
`verbose_layer_names` | bool | tag layers with a verbose name if true (image-name + timestamp), defaults to false

#### `working_container`

Key name | type | description
--- | --- | ---
`volumes` | list of strings | volumes mappings for the working container (`HOST:CONTAINER:PARAMS`)
`user` | string | UID or username to invoke the container during build (run ansible)

#### `target_image`

Key name | type | description
--- | --- | ---
`name` | string | name of the image
`labels` | dict | key/value data to apply to the final image
`annotations` | dict | key/value data to apply to the final image (buildah/runc specific)
`environment` | dict | implicit environment variables to set in a container
`cmd` | string | a default command to invoke the container
`entrypoint` | string | entrypoint script to configure for the container
`user` | string | UID or username used to invoke the container
`ports` | list of strings | a list of ports which are meant to be exposed on the host
`volumes` | list of strings | a list of paths which are meant to be hosted outside of the container
`working_dir` | string | path to a working directory within a container image

Example of a playbook with variables:

    - hosts: all
      vars:
        ansible_bender:
          base_image: "docker.io/library/python:3-alpine"
          buildah_from_extra_args: "--dns 8.8.8.8"
          ansible_extra_args: "-vvv"

          working_container:
            volumes:
              - "{{ playbook_dir }}:/src"

          target_image:
            name: challet
            labels:
              x: y
            environment:
              asd: '{{ playbook_dir }}'

Before bender processes the variables, it runs a no-op playbook so that Ansible expand them. Therefore you can utilize some of the Ansible’s native variables. Please bear in mind that most of the facts won’t be available.

### Via CLI

Please check out `ansible-bender build --help` for up to date options:

    $ ansible-bender build -h
    usage: ansible-bender build [-h] [--builder {docker,buildah}] [--no-cache]
                                [--squash]
                                [--build-volumes [BUILD_VOLUMES [BUILD_VOLUMES ...]]]
                                [--build-user BUILD_USER] [-w WORKDIR]
                                [-l [LABELS [LABELS ...]]]
                                [--annotation [ANNOTATIONS [ANNOTATIONS ...]]]
                                [-e [ENV_VARS [ENV_VARS ...]]] [--cmd CMD]
                                [--entrypoint ENTRYPOINT]
                                [-u USER] [-p [PORTS [PORTS ...]]]
                                [--runtime-volumes [RUNTIME_VOLUMES [RUNTIME_VOLUMES ...]]]
                                [--extra-buildah-from-args EXTRA_BUILDAH_FROM_ARGS]
                                [--extra-ansible-args EXTRA_ANSIBLE_ARGS]
                                [--python-interpreter PYTHON_INTERPRETER]
                                PLAYBOOK_PATH [BASE_IMAGE] [TARGET_IMAGE]

    positional arguments:
      PLAYBOOK_PATH         path to Ansible playbook
      BASE_IMAGE            name of a container image to use as a base
      TARGET_IMAGE          name of the built container image

    optional arguments:
      -h, --help            show this help message and exit
      --builder {docker,buildah}
                            pick preferred builder backend
      --no-cache            disable caching mechanism: storing layers and loading
                            them if a task is unchanged; this option also implies
                            the final image is composed of a base image and one
                            additional layer
      --squash              squash final image down to a single layer
      --build-volumes [BUILD_VOLUMES [BUILD_VOLUMES ...]]
                            mount selected directory inside the container during
                            build, should be specified as
                            '/host/dir:/container/dir'
      --build-user BUILD_USER
                            the container gets invoked with this user during build
      -w WORKDIR, --workdir WORKDIR
                            path to an implicit working directory in the container
      -l [LABELS [LABELS ...]], --label [LABELS [LABELS ...]]
                            add a label to the metadata of the image, should be
                            specified as 'key=value'
      --annotation [ANNOTATIONS [ANNOTATIONS ...]]
                            Add key=value annotation for the target image
      -e [ENV_VARS [ENV_VARS ...]], --env-vars [ENV_VARS [ENV_VARS ...]]
                            add an environment variable to the metadata of the
                            image, should be specified as 'KEY=VALUE'
      --cmd CMD             command to run by default in the container
      --entrypoint ENTRYPOINT
                            entrypoint script to configure for the container
      -u USER, --user USER  the container gets invoked with this user by default
      -p [PORTS [PORTS ...]], --ports [PORTS [PORTS ...]]
                            ports to expose from container by default
      --runtime-volumes [RUNTIME_VOLUMES [RUNTIME_VOLUMES ...]]
                            path a directory which has data stored outside of the
                            container
      --extra-buildah-from-args EXTRA_BUILDAH_FROM_ARGS
                            arguments passed to buildah from command (be careful!)
      --extra-ansible-args EXTRA_ANSIBLE_ARGS
                            arguments passed to ansible-playbook command (be
                            careful!)
      --python-interpreter PYTHON_INTERPRETER
                            Path to a python interpreter inside the base image

    Please use '--' to separate options and arguments.

## Ansible

If you want to configure Ansible itself, you can set any environment variable and ansible-bender will relay them to `ansible-playbook` command, an example:

    ANSIBLE_STDOUT_CALLBACK=debug ansible-bender build simple-playbook.yaml

Bender creates ansible.cfg on the fly which is then used during an ansible-playbook run. If you define `ANSIBLE_CONFIG`, it will likely break the build process: you’ve been warned.

## Ansible roles

If you are using roles in your playbook and they are in a non-standard place, you can utilize `ANSIBLE_ROLES_PATH` environment variable to tell ansible where your roles lives. Bender does not tamper with environment variables, all are passed to ansible-playbook.

## Buildah

If you are familiar with podman and buildah, you know that you can configure these tools. Ansible-bender doesn’t change this configuration in any way so it’s up to you how you set up buildah and podman. The same applies for running ansible-bender as root or not: buildah allows you to utilize rootless containers.

My suggestion is to use the overlay storage backend. Vfs backend is slow and inefficient.