Skip to main content

Ensure that Docker images are ready for use

Project description

Docker Ensure

Docker Ensure is a tool that ensures Docker images are available on your system by building or downloading the image if necessary.

Installing Docker Ensure

pip install dockerensure

Basic Usage

Say we have a Dockerfile first.Dockerfile that we build into first-image. The following code will ensure that an image called first-image exists by building it if it doesn't yet exist.

The BuildConfig will not make any files available to the build context by using a wildcard .dockerignore file.

DockerImage(
    "first-image",
    build_config=BuildConfig(
        "first.Dockerfile",
        files=FilePolicy.Nothing
    )
).ensure()

The simple declaration above will only rebuild if first-image doesn'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 the remote_policy argument.

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:abcd9876

If the contents of first.Dockerfile change 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 .ref to return the name and tag so you can use the image elsewhere.

Other build config parameters

The 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 with
  • build_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 build
  • metadata: Additional metadata to include in the hash. This won't be passed to the Docker build
  • interval: An interval to refresh the hash after.
  • directory: Directory to set the build context to. Leave as None for the current directory
  • unhashed_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 Policy

You can control what files are available to the build context by using a FilePolicy. FilePolicy.All is the default and makes all files available. FilePolicy.Nothing is the opposite - all files will be excluded. If you ran COPY . . in your Dockerfile, nothing would be copied.

FilePolicy.Only specifies 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 running pip install -r requirements.txt in your Dockerfile your file policy would be FilePolicy.Only(["requirements.txt"]).

FilePolicy.AllBut excludes certain files. Maybe you're building from a Git repo - in that case use FilePolicy.AllBut([".git/"]).

If you are including the hash of the build state in your image name you are limited to using Nothing or Only file policies. This is because all the files included in the file policy are used to calculate the hash. Furthermore when using Only you must use files, not directories.

Metadata

You can include extra string metadata that will affect the hash but not be included in the build. This is completely arbitrary and user defined.

Interval

To 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 using with_hash=True on the DockerImage for this to have any effect.

Unhashed build args

You 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 Images

Images without BuildConfig

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dockerensure-0.0.3.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

dockerensure-0.0.3-py3-none-any.whl (8.4 kB view details)

Uploaded Python 3

File details

Details for the file dockerensure-0.0.3.tar.gz.

File metadata

  • Download URL: dockerensure-0.0.3.tar.gz
  • Upload date:
  • Size: 8.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.8.0 Linux/5.10.16.3-microsoft-standard-WSL2

File hashes

Hashes for dockerensure-0.0.3.tar.gz
Algorithm Hash digest
SHA256 bfe6c55bf4e8ed056ecd72708e62ff9a8aa229d891c2cb5b02a9cddf4d8b84ad
MD5 c3ee0697dc3d509d8996c471df6fa832
BLAKE2b-256 bc12600c482bf3ff28be6209118756a4c389285b959cd7ba8db36b87ffa2c697

See more details on using hashes here.

File details

Details for the file dockerensure-0.0.3-py3-none-any.whl.

File metadata

  • Download URL: dockerensure-0.0.3-py3-none-any.whl
  • Upload date:
  • Size: 8.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.8.0 Linux/5.10.16.3-microsoft-standard-WSL2

File hashes

Hashes for dockerensure-0.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 107daa41614a892a3939170cbda05eea27bf10dd73e813c52c3242fa550c345d
MD5 4032def10f1a374b19372036dd3dd826
BLAKE2b-256 9afe01f353e7e48c7d658744767a29771d2447d469f3b27ba3537fa17619c1be

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page