Test GitHub go.mod Go version GitHub tag (latest SemVer)
A little bird to validate your container images.
$ canary validate --file examples/awesome.yaml your/container:latest Validating your/container:latest against awesome π¦ Required packages are installed [passed] π€ Expected services are running [passed] π Your container is awesome [passed] validation passed
Many modern compute platforms support bring-your-own-container models where the user can provide container images with their custom software environment. However platforms commonly have a set of requirements that the container must conform to, such as using a non-root user, having the home directory in a specific location, having certain packages installed or running web applications on specific ports.
Container Canary is a tool for recording those requirements as a manifest that can be versioned and then validating containers against that manifest. This is particularly useful in CI environments to avoid regressions in containers.
You can find binaries and instructions on our releases page.
The Kubeflow documentation has a list of requirements for container images that can be used in the Kubeflow Notebooks service.
That list looks like this:
- expose an HTTP interface on port
8888:- kubeflow sets an environment variable
NB_PREFIXat runtime with the URL path we expect the container be listening under - kubeflow uses IFrames, so ensure your application sets
Access-Control-Allow-Origin: *in HTTP response headers
- kubeflow sets an environment variable
- run as a user called
jovyan:- the home directory of
jovyanshould be/home/jovyan - the UID of
jovyanshould be1000
- the home directory of
- start successfully with an empty PVC mounted at
/home/jovyan:- kubeflow mounts a PVC at
/home/jovyanto keep state across Pod restarts
- kubeflow mounts a PVC at
With Container Canary we could write this list as the following YAML spec.
# examples/kubeflow.yaml apiVersion: container-canary.nvidia.com/v1 kind: Validator name: kubeflow description: Kubeflow notebooks env: - name: NB_PREFIX value: /hub/jovyan/ ports: - port: 8888 protocol: TCP volumes: - mountPath: /home/jovyan checks: - name: user description: π© User is jovyan probe: exec: command: - /bin/sh - -c - "[ $(whoami) = jovyan ]" - name: uid description: π User ID is 1000 probe: exec: command: - /bin/sh - -c - "id | grep uid=1000" - name: home description: π Home directory is /home/jovyan probe: exec: command: - /bin/sh - -c - "[ $HOME = /home/jovyan ]" - name: http description: π Exposes an HTTP interface on port 8888 probe: httpGet: path: / port: 8888 initialDelaySeconds: 10 - name: NB_PREFIX description: π§ Correctly routes the NB_PREFIX probe: httpGet: path: /hub/jovyan/lab port: 8888 initialDelaySeconds: 10 - name: allow-origin-all description: "π Sets 'Access-Control-Allow-Origin: *' header" probe: httpGet: path: / port: 8888 responseHttpHeaders: - name: Access-Control-Allow-Origin value: "*" initialDelaySeconds: 10
The Canary Validator spec reuses parts of the Kubernetes configuration API including probes. In Kubernetes probes are used to check on the health of a pod, but in Container Canary we use them to validate if the container meets our specification.
We can then run our specification against any desired container image to see a pass/fail breakdown of requirements. We can test one of the default images that ships with Kubeflow as that should pass.
$ canary validate --file examples/kubeflow.yaml public.ecr.aws/j1r0q0g6/notebooks/notebook-servers/jupyter-scipy:v1.5.0-rc.1 Validating public.ecr.aws/j1r0q0g6/notebooks/notebook-servers/jupyter-scipy:v1.5.0-rc.1 against kubeflow π© User is jovyan [passed] π User ID is 1000 [passed] π Home directory is /home/jovyan [passed] π Exposes an HTTP interface on port 8888 [passed] π§ Correctly routes the NB_PREFIX [passed] π Sets 'Access-Control-Allow-Origin: *' header [passed] validation passed
For more examples see the examples directory.
Validator manifests are YAML files that describe how to validate a container image. Check out the examples directory for real world applications.
Each manifests starts with some metadata.
# Manifest versioning apiVersion: container-canary.nvidia.com/v1 kind: Validator # Metadata name: foo # The name of the platform that this manifest validates for description: Foo runs containers for you # A description of that platform documentation: https://example.com # A link to the documentation that defines the container requirements in prose
Next you can set runtime configuration for the container you are validating. You should set these to mimic the environment that the compute platform will create. When you validate a container it will be run locally using Docker.
A list of environment variables that should be set on the container.
env: - name: HELLO value: world - name: FOO value: bar
Ports that need to be exposed on the container. These need to be configured in order for Container Canary to perform connectivity tests.
ports: - port: 8888 protocol: TCP
Volumes to be mounted to the container. This is useful if the compute platform will always mount an empty volume to a specific location.
volumes: - mountPath: /home/jovyan
You can specify a custom command to be run inside the container.
command: - foo - --bar=true
Checks are the tests that we want to run against the container to ensure it is compliant. Each check contains a probe, and those probes are superset of the Kubernetes probes API and so any valid Kubernetes probe can be used in a check.
checks: - name: mycheck # Name of the check description: Ensuring a thing # Descrption of what is being checked (will be used in output) probe: ... # A probe to run
An exec check runs a command inside the running container. If the command exits with 0 the check will pass.
checks: - name: uid description: User ID is 1234 probe: exec: command: - /bin/sh - -c - "id | grep uid=1234"
An HTTP Get check will perform an HTTP GET request against your container. If the response code is <300 and the optional response headers match the check will pass.
checks: - name: http description: Exposes an HTTP interface on port 80 probe: httpGet: path: / port: 80 httpHeaders: # Optional, headers to set in the request - name: Foo-Header value: "myheader" responseHttpHeaders: # Optional, headers that you expect to see in the response - name: Access-Control-Allow-Origin value: "*"
A TCP Socket check will ensure something is listening on a specific TCP port.
checks: - name: tcp description: Is listening via TCP on port 80 probe: tcpSocket: port: 80
Checks also support the same delays, timeouts, periods and thresholds that Kubernetes probes do.
checks: - name: uid description: User ID is 1234 probe: exec: command: [...] initialDelaySeconds: 0 # Delay after starting the container before the check should be run timeoutSeconds: 30 # Overall timeout for the check successThreshold: 1 # Number of times the check must pass before moving on failureThreshold: 1 # Number of times the check is allowed to fail before giving up periodSeconds: 1 # Interval between runs if threasholds are >1
Contributions are very welcome, be sure to review the contribution guidelines.
Maintenance steps can be found here.
Apache License Version 2.0, see LICENSE.