Images tree

Add your images definition into Stevedore’s images-tree and create a relationship among them

The images-tree is a data structure that contains the definitions of the images, as well as the relationships between them. It is defined in a YAML format containing a main key named images, which is a map of maps data structure.

Under the images block, you place all the image names, and each image’s name is a first-level key. For each image name, you have to define a second level of keys that identifies the image versions. The value of each version is the image definition for that specific name and version.

Note that in case an image name or image version contains a . (dot), you must quote it to avoid the YAML parser failing. This is a common issue that can be easily solved by wrapping the name or version in quotes.

Images can be related to each other, and these relationships are defined using their name and version. The relationships can be established from the image to its parents or its children. The images reference guide provides more information about how to set the images’ relationship.

To know which images can be built, Stevedore searches for the images-tree in the file specified on the images_tree configuration parameter, or in a directory specified by the same parameter. In the latter case, Stevedore loads the image definitions found within all the files in the directory.

Example

The following example specifies an images-tree that provides multiple image definitions for the busybox, php-fpm, php-cli and my-app images.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
images:
  root:
    latest:
      persistent_labels:
        created_at: "{{ .DateRFC3339Nano }}"

  busybox:
    "1.35":
      builder: global-infr-builder
      parents:
        root:
          - latest
    "1.36":
      builder: global-infr-builder
      parents:
        root:
          - latest
  php-fpm:
    "8.0":
      version: "{{ .Version }}-{{ .Parent.Version }}"
      builder:
        driver: docker
        context:
          path: php-fpm
      parents:
        busybox:
          - "1.35"
    "8.1":
      version: "{{ .Version }}-{{ .Parent.Version }}"
      builder:
        driver: docker
        context:
          path: php-fpm
      parents:
        busybox:
          - "1.35"
          - "1.36"
  php-cli:
    "8.1":
      version: "{{ .Version }}-{{ .Parent.Version }}"
      builder:
        driver: docker
        context:
          path: php-cli
      parents:
        busybox:
          - "1.35"
          - "1.36"
  my-app:
    "*":
      version: "{{ .Version }}-{{ .Parent.Version }}"
      builder:
        driver: docker
        context:
          git:
            repository: git@gitserver.stevedore.test:/git/repos/my-app.git
            reference: "{{ .Version }}"
            auth:
              credentials_id: mygit.stevedore.test
      parents:
        php-fpm:
          - "8.1"

You can check the previously defined images-tree by executing stevedore get images --tree.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ stevedore get images --tree
├─── root:latest
│  ├─── busybox:1.35
│  │  ├─── php-fpm:8.0-1.35
│  │  ├─── php-fpm:8.1-1.35
│  │  │  ├─── my-app:{{ .Version }}-{{ .Parent.Version }}
│  │  ├─── php-cli:8.1-1.35
│  ├─── busybox:1.36
│  │  ├─── php-fpm:8.1-1.36
│  │  ├─── php-cli:8.1-1.36

Last modified April 22, 2023: review documentation v0.11.0 (440cf9a)