The ansible-container build command spins up the builder container and runs your playbook against the base images described in the container.yml file. At the end of a successful run of this command, in your container engine you will have images built for each of the containers in your orchestration. This is analogous to docker build.


By default, Ansible Container commits the changes your playbook made to the base image, but it retains the original layers from that base image. Specifying this option, Ansible Container flattens the union filesystem of your image to a single layer.


The image is flattened by exporting the container to a tar file and re-importing the tar file as a new image. A side effect of performing this operation is a loss of image metadata.


By default, Ansible Container starts with the last instance of your containers and runs your playbook against it. That way, if a build fails, you’re not starting from zero when rebuilding. With this option, Ansible Container starts with fresh copies of your base images and rebuilds from zero.


New in version 0.2.0

Instead of using the Ansible Builder Container image from Docker Hub, generate one locally.


New in version 0.2.0

By default, upon successful completion of a build, the previously latest builds for your hosts are deleted and purged from the engine. Specifying this option, the prior builds are retained.


New in version 0.2.0

Leave the Ansible Builder Container intact upon build completion. Use for debugging and testing.


Rather than performing an orchestrated build, only build the specified set of services.

--with-variables WITH_VARIABLES [WITH_VARIABLES ...]

New in version 0.2.0

Define one or more environment variables in the Ansible Builder Container. Format each variable as a key=value string.

--with-volumes WITH_VOLUMES [WITH_VOLUMES ...]

New in version 0.2.0

Mount one or more volumes to the Ansible Builder Container. Specify volumes as strings using the Docker volume format.

--roles-path LOCAL_PATH

New in version 0.2.0

If you have Ansible roles in a local path other than your ansible/ directory that you wish to use during your build/run/shipit, specify that path with this option.


You may also provide additional commandline arguments to give Ansible in executing your playbook. Use this option with care, as there is no real sanitation or validation of your input. It is recommended you only use this option to limit the hosts you build against (for example, if you only want to rebuild one container), to add extra variables, or to specify tags.

Note that for proper parsing, you will likely have to use -- to separate the ansible-container options from the ansible-playbook options.


Ansible ordinarily connects to hosts it is managing via the SSH protocol. Ansible Container uses the latest Docker connection plugin to communicate from the Ansible Builder Container to the other containers. Since not all modules presently function with the Docker connection plugin, it limits the modules your playbook may rely on. As examples:

  • The become methods do not work with Ansible Container, as su is disallowed in the Docker connection plugin (see #16226) and sudo requires a TTY. Instead, use the remote_user parameter.
  • The synchronize plugin requires rsync and an ssh transport. Unless you manually install ssh and link the ports for that service among your containers, you will have to rely on other modules. For example, you can use combinations of find, fetch, and copy to achieve similar effects.

Also, remember that the ansible-playbook executable runs on your builder container, not your local host, and thus operates in the filesystem and network context of the build container.