Container Structure Test

It’s common practice to validate built container images before deploying them to our cluster. To do this, Skaffold has an integrated testing phase between the build and deploy phases of the pipeline. Natively, Skaffold has support for running container-structure-tests on built images, which validate the structural integrity of container images. The container-structure-test binary must be installed to run these tests.

Structure tests are defined per image in the Skaffold config. Every time an artifact is rebuilt, Skaffold runs the associated structure tests on that image. If the tests fail, Skaffold will not continue on to the deploy stage. If frequent tests are prohibitive, long-running tests should be moved to a dedicated Skaffold profile. Users can opt out of running container structure tests by using the --skip-tests flag.


This following example shows the test section from a skaffold.yaml. It instructs Skaffold to run all container structure tests in the structure-test folder relative to the Skaffold root directory:

  - image:
      - './structure-test/*'

The files matched by the structureTests key are container-structure-test test configurations, such as:

schemaVersion: 2.0.0

  - name: 'no go binary'
    path: '/usr/bin/go'
    shouldExist: false

For a reference how to write container structure tests, see its documentation.

In order to restrict the executed structure tests, a profile section can override the file pattern:

  - name: quickcheck
      - image:
          - './structure-test/profile_structure_test.yaml'

To execute the tests once, run skaffold build --profile quickcheck.

Last modified April 14, 2021: release: v1.22.0 (4e67ac7)