Package: dockerensure
Docker EnsureDocker Ensure is a tool that ensures Docker images are available on your system by building or downloading the image if necessary.Installing Docker Ensurepip install dockerensureBasic UsageSay we have a Dockerfilefirst.Dockerfilethat we build intofirst-image. The following code will ensure that an image calledfirst-imageexists by building it if it doesn't yet exist.TheBuildConfigwill not make any files available to the build context by using a wildcard.dockerignorefile.DockerImage(
    "first-image",
    build_config=BuildConfig(
        "first.Dockerfile",
        files=FilePolicy.Nothing
    )
).ensure()The simple declaration above will only rebuild iffirst-imagedoesn't exist on the system. If we have an image registry we can include that as a place to search for images:registry = DockerRegistry("my.registry")
DockerImage(
    "first-image",
    build_config=BuildConfig(
        "first.Dockerfile",
        files=FilePolicy.Nothing
    ),
    registry=registry
).ensure()DockerEnsure will check the registry for the image before building. If the image doesn't exist the build will take place and the image will be pushed to the registry.
You can control how the registry is used with theremote_policyargument.In the above examples if the Dockerfile is changed the image won't be rebuild as long as it exists. We can include a hash in the image tag consisting of the state of the build config to detect any changes to that config:image = DockerImage(
    "first-image",
    with_hash=True,
    build_config=BuildConfig(
        "first.Dockerfile",
        files=FilePolicy.Nothing
    )
)
print(image.ref)  # e.g. first-image:abcd9876If the contents offirst.Dockerfilechange the hash will also change and a new image will be built. In these situations the full reference of the image is not known in advance and you must use.refto return the name and tag so you can use the image elsewhere.Other build config parametersThe build config object contains all inputs to your build. You can pass a number of different parameters to this object:dockerfile: The dockerfile to build withbuild_args: Docker build args that will be passed to the build.parents: List of DockerImages that this image depends on. These images will be ensured before this image is built.files: A FilePolicy object describing what files are to be made available to the buildmetadata: Additional metadata to include in the hash. This won't be passed to the Docker buildinterval: An interval to refresh the hash after.directory: Directory to set the build context to. Leave as None for the current directoryunhashed_build_args: Docker build_args that won't be included in the hash. These could include credentials and other data that is required by the build but won't affect the built image.File PolicyYou can control what files are available to the build context by using aFilePolicy.FilePolicy.Allis the default and makes all files available.FilePolicy.Nothingis the opposite - all files will be excluded. If you ranCOPY . .in your Dockerfile, nothing would be copied.FilePolicy.Onlyspecifies certain files to include - everything else is excluded. This is used when you know exactly which files your build needs. For example, if you're runningpip install -r requirements.txtin your Dockerfile your file policy would beFilePolicy.Only(["requirements.txt"]).FilePolicy.AllButexcludes certain files. Maybe you're building from a Git repo - in that case useFilePolicy.AllBut([".git/"]).If you are including the hash of the build state in your image name you are limited to usingNothingorOnlyfile policies. This is because all the files included in the file policy are used to calculate the hash. Furthermore when usingOnlyyou must use files, not directories.MetadataYou can include extra string metadata that will affect the hash but not be included in the build. This is completely arbitrary and user defined.IntervalTo prevent builds becoming outdated you can use the interval parameter to force a rebuild after a period of time. Rhis is recommended if your Dockerfile installs from a repository (e.g.apt get update && apt get upgrade).IntervalOffset(timedelta(days=1))will change the hash every day.Note that you must be usingwith_hash=Trueon the DockerImage for this to have any effect.Unhashed build argsYou may want to pass build args to the build without affecting the build state hash. For example, temporary credentials that are discarded after use. In this case we need the build to have these credentials but we don't want the hash to change every time the credentials are rotated.BuildConfig(..., unhashed_build_args={"REPO_TOKEN": "abcxyz"})Versioning ImagesImages without BuildConfig