1# Edge Release
2
3## Overview
4
5The Edge Release package serves two functions:
6
71. The creation of an `edge-release` OCI Artifact that contains references to pallets pinned at specific tags/shas
8 - This artifact serves as a record of pallets that are available at a given Edge infra release
9 - An `EdgeRelease` consists of a set of `Pallet`s and metadata about the release
102. The ability to create an environment (a set of releases) and make those releases' individual pallets available in the environment by way of the forwarder
11
12## Creating an `EdgeRelease`
13
14The declarative method for creating an `EdgeRelease` is to create a release configuration in yaml.
15Required members of the config are:
16
17- A `source_repository` member that points to a repository containing pallet images with the required fields
18- A `destination_repository` member pointing to the repository where the release artifact will be written
19- A `pallets` list containing the names of the pallets to include in the release
20- The version of the release is defaulted to the semver in the `.version` file, but an optional field `current_version` can override that value
21
22Example config:
23
24```yaml
25# optional field
26# current_version: "0.21.4"
27# required field
28source_repository:
29 name: "warehouse"
30 location: "us-east1"
31 project: "ret-edge-pltf-infra"
32# required field
33destination_repository:
34 name: "warehouse"
35 location: "us-east1"
36 project: "ret-edge-pltf-infra"
37# required field
38pallets:
39 # Cloud infra (latest) Pallets
40 - "foreman"
41 - "banner-infra-cluster"
42 - "cluster-infra"
43 - "basic-store"
44 - "couchdb-masters"
45 - "couchdb-bannerinfra"
46 # Versioned Pallets
47 - "store"
48 - "lumper-controller"
49 - "external-secrets-operator"
50 - "fluxcd-operators"
51 - "nodeagent"
52 - "spegel"
53 - "k8s-admission-controller"
54 - "descheduler"
55 - "distributed-storage"
56 - "multi-interface"
57 - "couchdb-repl-secret"
58 - "virtual-machines"
59 - "data-sync"
60 - "metrics"
61 - "bsl-shims"
62 - "edge-iam"
63```
64
65To create an `EdgeRelease` and view the resulting JSON, run:
66`bazel run cmd/f8n/warehouse/release -- build -c path/to/your/release_config.yaml -ojson`
67
68To create an `EdgeRelease` and push to the destination repository, run:
69`bazel run cmd/f8n/warehouse/release -- build -c path/to/your/release_config.yaml -p`
70(You can still pass `-ojson` if you'd like to see the release artifact in the terminal)
71
72## Consuming `EdgeRelease` Artifacts in an Environment
73
74### Declaring an Environment
75
76`EdgeRelease` artifacts are consumed by declaring an environment and the required releases available in that environment.
77
78- The `source_repository` field declares the repository where the `edge-release` artifact is sourced
79- The `current` field declares which release is the current version and applies the `latest` tag
80- The `additional` field declares any additional releases that should be made available in the environment
81
82For Example:
83
84```yaml
85# required field
86source_repository:
87 name: "warehouse"
88 location: "us-east1"
89 project: "ret-edge-pltf-infra"
90# required field
91current: "0.21.4"
92# optional field
93additional:
94 - "0.20.19"
95 - "0.19.11"
96```
97
98### Locking an Environment
99
100Once the environment is declared, the `release` tool can produce a package lock that resolves all pallets in the releases and serializes their versions and tags.
101
102To create the lock file, run:
103`bazel run cmd/f8n/warehouse/release -- lock -c path/to/your/environment_config.yaml`
104
105This produces a lock file with an abbreviated example below:
106```yaml
107packages:
108- name: banner-infra-cluster
109 versions:
110 - digest: sha256:e5edd7732b571285f6221edaf65e4eda90edb2b21b1ec1a565c74d5adf0e23a3
111 tags:
112 - 0.21.4
113 - "0.21"
114 - latest
115 - digest: sha256:af72dc6bbbf2da9a5fd25f28c42dfdb8da9549292e4fff5f6191a1bb25732114
116 tags:
117 - 0.20.19
118 - "0.20"
119 - digest: sha256:f03f9f3fd7e5dd23f77637b312cdcb51c2a56555b53ebcf98bc4fac6da105ecd
120 tags:
121 - 0.19.11
122 - "0.19"
123- name: basic-store
124 versions:
125 - digest: sha256:daa3229f59132ea4e1d5c5bba9c47ef49be0b7616454fbdee7c6b2e5bff2d8e6
126 tags:
127 - 0.21.4
128 - "0.21"
129 - latest
130 - digest: sha256:af4869fd505856d7b077446a229a668db7d95cfe2cd8751778b634bc61e8f525
131 tags:
132 - 0.20.19
133 - "0.20"
134 - digest: sha256:47d95cb964ffa306ea765c7a2ff41ab8e3d846d1c7d0b4ee104ebd3c64f72e37
135 tags:
136 - 0.19.11
137 - "0.19"
138- name: data-sync
139 versions:
140 - digest: sha256:5736fcb5f7327020dc406851618a0c72f91b19479b80ffd56d38ffeeb50d6038
141 tags:
142 - 0.21.4
143 - "0.21"
144 - latest
145 - digest: sha256:388728b762fa52df905a3f53b206c152493b555ffb0b1b2411b22dcbf3a5cad4
146 tags:
147 - 0.20.19
148 - "0.20"
149```
150
151Of particular note is the `data-sync` pallet. This pallet is not avaiable in Edge infra releases older
152than `0.20`, so the `0.19`/`0.19.11` tag is not present.
153
154Creating a lock file with an environment config allows the forwarder to forward image references as it does
155currently.
View as plain text