Add some documentation

README.md

@@ -3,7 +3,72 @@
 This repo is dedicated to mirror images from other organizations into Rancher.
 There are no packaging changes or changes in the layers of these images.
 
-## Mirroring images
+> [!IMPORTANT]
+> This repository is currently undergoing an overhaul in order to accomplish the
+> goals laid out in
+> [EDR 005](https://docs.google.com/document/d/1IVu4Lq13yKiSs0gl_tIJ3vuidVmt0FIkO2mlZXTRAH4/edit?pli=1&tab=t.0#heading=h.k15gkmaregsk).
+> The bespoke scripts that are used to mirror images are being replaced by
+> [`regsync`](https://github.com/regclient/regclient/blob/main/docs/regsync.md).
+> Generation of `regsync` config, among other automations, is being written in Go.
+> As this migration takes place, no disruption to regular image mirroring
+> will occur - you may continue to use the old tooling while the new
+> tooling is built. Documentation for the new setup is under [New Documentation](#new-documentation).
+> Documentation for the old setup is under [Old Documentation](#old-documentation).
+
+## New Documentation
+
+### Overview
+
+`regsync` is used for mirroring images from one repository to another. `regsync`
+is configured via `regsync.yaml`. `regsync.yaml` is generated by running:
+```
+go run main.go generate-regsync
+```
+The `generate-regsync` subcommand is configured via `config.yaml`.
+
+Once `regsync.yaml` has been updated, you may run `regsync` via the command
+```
+regsync once --verbosity error --config regsync.yaml --missing
+```
+
+### `config.yaml` Fields
+
+#### `Repositories`
+
+`Repositories` describes the repositories that image-mirror interfaces with.
+This section roughly correlates to the `creds` section of `regsync.yaml`.
+
+| Field | Required | Description |
+| ------------- | ------------- |------------- |
+| `EnvVarPrefix` | yes | The prefix added to the environment variables used to set username, password and registry in `regsync.yaml`.
+| `BaseUrl` | yes | The base URL for the repository. Appending `/` plus an image name should be a valid image reference.
+| `Target` | no | When `true`, denotes a target repository. This means that all images will be mirrored to this repository.
+
+
+#### `Images`
+
+`Images` describes the images that we want to mirror to each target
+repository.
+
+| Field | Required | Description |
+| ------------- | ------------- |------------- |
+| `SourceImage` | yes | The source image. If there is no host, the image is assumed to be from Docker Hub.
+| `Tags` | yes | The tags to mirror.
+| `TargetImageName` | no | By default, the target image name is derived from the source image, and is of the format `mirrored-<org>-<name>`. For example, `banzaicloud/logging-operator` becomes `mirrored-banzaicloud-logging-operator`. However, there are some images that do not follow this convention - this field exists for these cases. New images should not set this field.
+
+
+## Old Documentation
+
+The following documentation describes the old way of mirroring images.
+It pertains to files like:
+- `images-list`
+- `images-list-daily`
+- `retrieve-image-tags/`
+- `Dockerfile.dapper`
+- `entrypoint.sh`
+- `scripts/`
+
+### Mirroring images
 
 The list is maintained in the `images-list` file, which is structured with the following format...
 
@@ -18,19 +83,19 @@ banzaicloud/logging-operator rancher/mirrored-banzaicloud-logging-operator 3.7.0
 
 Images are mirrored using the `scripts/image-mirror.sh` script.
 
-## Adding New Images
+### Adding New Images
 
 When adding new images to the repo, please indicate so in the pull request.
 
 An EIO team member or manager will need to create the repo in DockerHub as well as add the `automatedcipublisher` as a team member in DockerHub with `write` access in order for the images to be automatically pushed.
 
-## Updating Existing Images
+### Updating Existing Images
 
 **Do not** update the tag in the `images-list` file for an updated image to be pulled/pushed. Add an additional entry with the new tag.
 
-## Adding new tags to existing images
+### Adding new tags to existing images
 
-### Scheduled
+#### Scheduled
 
 There is also a scheduled workflow called [Retrieve image tags](https://github.com/rancher/image-mirror/actions/workflows/retrieve-image-tags.yml) that can be used if you have images that needs new tags added automatically. It will check a configurable source for available tags, and use the found tags to dispatch the workflow [Add tag to existing image
 ](https://github.com/rancher/image-mirror/actions/workflows/add-tag-to-existing-image.yml). The configuration lives in [`config.json`](https://github.com/rancher/image-mirror/blob/master/retrieve-image-tags/config.json). The basic structure is having a descriptive key (pick your own), and specify the list of images for which the available tag(s) need to be looked up (`versionSource`), and an optional SemVer constraint if you need to limit what tags are used. The current datasources are:
@@ -260,26 +325,26 @@ See example configuration for `helm-directory`:
 
 If you want to manually test your configuration changes to check if the correct tags are found, you can use the following commands depending on your available runtime:
 
-#### Docker 
+##### Docker 
 
 ```
 docker run -v $PWD:/code -w /code/retrieve-image-tags python:3.10-alpine sh -c "apk -qU add helm && pip install --disable-pip-version-check --root-user-action=ignore -qr requirements.txt && python retrieve-image-tags.py"
 ```
 
-#### podman
+##### podman
 
 ```
 podman run -v $PWD:/code -w /code/retrieve-image-tags python:3.10-alpine sh -c "apk -qU add helm && pip install --disable-pip-version-check --root-user-action=ignore -qr requirements.txt && python retrieve-image-tags.py"
 ```
 
-#### containerd
+##### containerd
 
 ```
 ctr images pull docker.io/library/python:3.10-alpine
 ctr run -t --net-host --mount type=bind,src=$PWD,dst=/code,options=rbind:ro --cwd /code/retrieve-image-tags --rm docker.io/library/python:3.10-alpine workflow-test sh -c "apk -qU add helm && pip install --disable-pip-version-check --root-user-action=ignore -qr requirements.txt && python retrieve-image-tags.py"
 ```
 
-### Using scripts
+#### Using scripts
 
 You can use the following commands/scripts to add a tag to an **existing** image. Make sure the `IMAGES` environment variable is set to the image(s) you want to add a tag to, and the `TAGS` environment variable is set to the tags you want to add to the images. The script will check:
 
@@ -310,7 +375,7 @@ Optionally, you can also check if the newly added image tag exists (this will al
 make check-new-images-exist.sh
 ```
 
-### Using GitHub Actions workflow
+#### Using GitHub Actions workflow
 
 You can use the [Add tag to existing image](https://github.com/rancher/image-mirror/actions/workflows/add-tag-to-existing-image.yml) workflow to provide a comma separated list of existing images and to be added tags, and it will create a pull request automatically with the changes. See [Using scripts](#using-scripts) what this does in detail.