Skip to main content

Container image handling

Concepts​

Container images are usually given a name such as collector or example/mycontainer. Image names can also include a registry hostname (or address), for example registry.example.com/imagename (it can even include a port number, for example registry.example.com:4433/imagename).

An image name always has a tag which is latest by default (i.e. if it is left out, it is assumed to be latest). The tag is written as the last portion of the image name following a colon, for example: example/mycontainer:3.5 or nginx:stable-alpine. Instead of a tag an image can also be referred to by its digest, using the form NAME@sha256:DIGEST for example:

nginx@sha256:26716e37188bd01374360199773bc8ad8736edb7e234a2a1956a13b9800fccc4

While tags may change (can refer to different versions of an image at different times), the digest is a constant (a hash based on the contents of an image and how the image was built).

Registry - place where you can fetch (and store) images. When using k8s or docker, the default registry is the Docker public registry (you can browse it at https://hub.docker.com/ although the registry address is actually registry-1.docker.io). In the Avassa system there is no built in default registry (but you can configure one). I.e. an image name that isn't prefixed with a registry name is assumed to refer to the default registry.

Repository - in a registry, images are said to reside in repositories. A repository can contain many different versions of an image, typically the individual images are referred to by its tag. For example: the registry.example.com/os/alpine refers to the registry running on registry.exampl.com and the repository os/alpine and, since it wasn’t specified, the image that has the default tag of latest. Where as registry.example.com/os/alpine:3.14 refers to the same registry, but the image that is tagged 3.14 in the os/alpine repository.

Control Tower container registry​

The Control Tower has a built in container image registry, it conforms to the OCI distribution spec and users can (but do not have to) interact with it using an OCI compliant client (e.g. docker). The Control Tower registry keeps all the images needed by applications that are to be deployed to sites (in fact, applications will not be deployed to any site before all the images that are needed by the application are present in the registry).

Site container registry​

Each site also runs a container registry to manage images that are needed for the applications scheduled to this site. The container registry is built into the Edge Enforcer, and it does not require any user management or configuration. When an application is scheduled to a site, all required container images are pulled from the Control Tower, and to ensure resiliency, images are kept in replicas locally on the site. When an image is no longer needed at a site it is automatically removed.

Specifying what image a container should run​

In Avassa images are part of the container section in the application specification. The image name can contain the registry address, or be specified without it, for example:

name: webserver
services:
  - name: server
    containers:
      - name: front
        image: registry-1.docker.io/nginx:stable-alpine
      - name: app
        image: registry.example.com/myapp:v2
      - name: db
        image: mysql

Note that Avassa does not have a default registry, if no registry address is specified one also has to configure a default remote registry, using the following configuration under image-registry remote-registries.

default-remote-registry: registry.example.com

I.e. using the above application specification and the default definition the image: mysql image would refer to the image registry.example.com/mysql:latest.

Getting images into the Control Tower registry​

When an application specification is configured, the system will immediately try to fetch the images for all the containers in the application specification and install them in the Control Tower registry. This is called "automatic pull" and is the default behavior. If for some reason an image can not be fetched (missing credentials, no default remote registry, a non-existing image, et.c.) the system will retry until it succeeds.

There are two other ways of getting an image into the Control Tower registry: manual pull, and manual push. To manually pull an image into the Control Tower registry the image-registry pull command can be used (see the Registry and Images How-to for examples), and to push an image you can use for example the docker push command.

Once all the images that are part of an application specification are present, the application can be deployed. As part of the deployment, the images are distributed to the sites that the application will be deployed to.

Distributing images to sites​

When an application is deployed to a site, the exact version (i.e. digest) of that image is determined, and any further reference to this image will be using the digest (to avoid the problem that a tag could refer to different versions of an image on different sites).

Image Handling