# Edge Release

## Overview

The Edge Release package serves two functions:

1. The creation of an `edge-release` OCI Artifact that contains references to pallets pinned at specific tags/shas
  - This artifact serves as a record of pallets that are available at a given Edge infra release
  - An `EdgeRelease` consists of a set of `Pallet`s and metadata about the release
2. 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

## Creating an `EdgeRelease`

The declarative method for creating an `EdgeRelease` is to create a release configuration in yaml. 
Required members of the config are:

- A `source_repository` member that points to a repository containing pallet images with the required fields
- A `destination_repository` member pointing to the repository where the release artifact will be written
- A `pallets` list containing the names of the pallets to include in the release
- The version of the release is defaulted to the semver in the `.version` file, but an optional field `current_version` can override that value

Example config:

```yaml
# optional field
# current_version: "0.21.4"
# required field
source_repository:
  name: "warehouse"
  location: "us-east1"
  project: "ret-edge-pltf-infra"
# required field
destination_repository:
  name: "warehouse"
  location: "us-east1"
  project: "ret-edge-pltf-infra"
# required field
pallets:
  # Cloud infra (latest) Pallets
  - "foreman"
  - "banner-infra-cluster"
  - "cluster-infra"
  - "basic-store"
  - "couchdb-masters"
  - "couchdb-bannerinfra"
  # Versioned Pallets
  - "store"
  - "lumper-controller"
  - "external-secrets-operator"
  - "fluxcd-operators"
  - "nodeagent"
  - "spegel"
  - "k8s-admission-controller"
  - "descheduler"
  - "distributed-storage"
  - "multi-interface"
  - "couchdb-repl-secret"
  - "virtual-machines"
  - "data-sync"
  - "metrics"
  - "bsl-shims"
  - "edge-iam"
```

To create an `EdgeRelease` and view the resulting JSON, run:
`bazel run cmd/f8n/warehouse/release -- build -c path/to/your/release_config.yaml -ojson`

To create an `EdgeRelease` and push to the destination repository, run:
`bazel run cmd/f8n/warehouse/release -- build -c path/to/your/release_config.yaml -p`
(You can still pass `-ojson` if you'd like to see the release artifact in the terminal)

## Consuming `EdgeRelease` Artifacts in an Environment

### Declaring an Environment

`EdgeRelease` artifacts are consumed by declaring an environment and the required releases available in that environment.

- The `source_repository` field declares the repository where the `edge-release` artifact is sourced
- The `current` field declares which release is the current version and applies the `latest` tag
- The `additional` field declares any additional releases that should be made available in the environment

For Example:

```yaml
# required field
source_repository:
  name: "warehouse"
  location: "us-east1"
  project: "ret-edge-pltf-infra"
# required field
current: "0.21.4"
# optional field
additional:
  - "0.20.19"
  - "0.19.11"
```

### Locking an Environment

Once 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.

To create the lock file, run:
`bazel run cmd/f8n/warehouse/release -- lock -c path/to/your/environment_config.yaml`

This produces a lock file with an abbreviated example below:
```yaml
packages:
- name: banner-infra-cluster
  versions:
  - digest: sha256:e5edd7732b571285f6221edaf65e4eda90edb2b21b1ec1a565c74d5adf0e23a3
    tags:
    - 0.21.4
    - "0.21"
    - latest
  - digest: sha256:af72dc6bbbf2da9a5fd25f28c42dfdb8da9549292e4fff5f6191a1bb25732114
    tags:
    - 0.20.19
    - "0.20"
  - digest: sha256:f03f9f3fd7e5dd23f77637b312cdcb51c2a56555b53ebcf98bc4fac6da105ecd
    tags:
    - 0.19.11
    - "0.19"
- name: basic-store
  versions:
  - digest: sha256:daa3229f59132ea4e1d5c5bba9c47ef49be0b7616454fbdee7c6b2e5bff2d8e6
    tags:
    - 0.21.4
    - "0.21"
    - latest
  - digest: sha256:af4869fd505856d7b077446a229a668db7d95cfe2cd8751778b634bc61e8f525
    tags:
    - 0.20.19
    - "0.20"
  - digest: sha256:47d95cb964ffa306ea765c7a2ff41ab8e3d846d1c7d0b4ee104ebd3c64f72e37
    tags:
    - 0.19.11
    - "0.19"
- name: data-sync
  versions:
  - digest: sha256:5736fcb5f7327020dc406851618a0c72f91b19479b80ffd56d38ffeeb50d6038
    tags:
    - 0.21.4
    - "0.21"
    - latest
  - digest: sha256:388728b762fa52df905a3f53b206c152493b555ffb0b1b2411b22dcbf3a5cad4
    tags:
    - 0.20.19
    - "0.20"
```

Of particular note is the `data-sync` pallet. This pallet is not avaiable in Edge infra releases older
than `0.20`, so the `0.19`/`0.19.11` tag is not present.

Creating a lock file with an environment config allows the forwarder to forward image references as it does
currently.