container-structure-test

For Bazel users, you can declare a container_structure_test target in your BUILD file.

Requirements:

• For Bazel 6+ with bzlmod, use the registry module: https://registry.bazel.build/modules/container_structure_test.
• For older versions, load the rule and dependencies in your WORKSPACE.

load("@container_structure_test//:defs.bzl", "container_structure_test")

container_structure_test(
    name = "hello_test",
    configs = ["testdata/hello.yaml"],
    image = ":hello",
)

If you cannot use a Docker daemon (e.g., in environments where Docker cannot be installed), you can use the tar driver. The tar driver extracts the image filesystem and runs file/metadata tests against it.

Limitation: The tar driver does not support command tests.

By default, container_structure_test uses the socket at /var/run/docker.sock. If your environment uses a different path or requires TLS, you must pass these via --test_env flags during bazel test.

Custom Socket Path

If the socket is in a non-standard location: --test_env=DOCKER_HOST='unix://<path_to_sock>'

Remote Docker with TLS

If using a remote daemon protected by TLS: --test_env=DOCKER_TLS_VERIFY=1 --test_env=DOCKER_CERT_PATH=<path_to_certs>

Permanent Configuration

To avoid typing these flags every time, add the following to your .bazelrc file to instruct Bazel to read the DOCKER_HOST from your terminal environment: test --test_env=DOCKER_HOST

To run tests, you need the container-structure-test binary (or Docker image), a target container image, and a .yaml or .json configuration file defining your tests.

By default, the framework looks for the target image in your local Docker daemon. Use the --pull flag to force a pull of a remote image before running tests.

Multiple configuration files can be specified in a single run, and they will be executed in the order they are provided.

You can use container-structure-test as a builder image in your cloudbuild.yaml workflow. The image is available at gcr.io/gcp-runtimes/container-structure-test.

steps:
# Build an image.
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/image', '.']
# Test the image.
- name: 'gcr.io/gcp-runtimes/container-structure-test'
  args: ['test', '--image', 'gcr.io/$PROJECT_ID/image', '--config', 'test_config.yaml']

# Push the image.
images: ['gcr.io/$PROJECT_ID/image']

The container-structure-test CLI provides a framework to validate the structure of a container image. It allows you to verify the output of commands executed within the image, as well as validate image metadata and filesystem contents.

Available commands:

• test: The primary command used to run structure tests against a container image.
• version: Displays the current version of the tool.

If your image is stored in an OCI layout rather than a registry or local Docker daemon, use the --image-from-oci-layout flag.

Constraints and Requirements:

• Driver Requirement: This feature is only supported when using the docker driver.
• Mutual Exclusivity: You cannot use --pull when using --image-from-oci-layout.
• Tagging: If the OCI layout does not contain a reference annotation (org.opencontainers.image.ref.name), you must provide a --default-image-tag to identify the image when it is loaded into the daemon.
• Multi-arch: Multi-arch images are not currently supported via OCI layouts.

License tests verify that a container image contains only allowed copyright files. You can check against the standard Debian license list or provide a custom list of files.

Supported Fields:

• debian (bool, required): If true, the tool checks where Debian lists all licenses.
• files (string[], optional): A list of specific file paths to check for licenses.

licenseTests:
- debian: true
  files: ["/foo/bar", "/baz/bat"]

You can specify environment variables to be set globally for all test runs within your configuration file. This supports Unix-style environment variable substitution (e.g., using $PATH).

globalEnvVars:
  - key: "VIRTUAL_ENV"
    value: "/env"
  - key: "PATH"
    value: "/env/bin:$PATH"