cloud-image-uploader: Add initial sections for AWS, GCP, containers

Also includes updates to reflect the new deployment style, and a brief
guide on testing in staging.

Signed-off-by: Jeremy Cline <jeremycline@linux.microsoft.com>

modules/sysadmin_guide/pages/cloud-image-uploader.adoc

@@ -23,9 +23,7 @@ cloud-image-uploader is an AMQP message consumer (run via `fedora-messaging
 consume`) that processes Pungi compose messages published on the
 `org.fedoraproject.*.pungi.compose.status.change` AMQP topic. When a compose
 enters the `FINISHED` or `FINISHED_INCOMPLETE` states, the service downloads
-any images in the compose and uploads it to the relevant cloud provider by
+any images in the compose and uploads it to the relevant cloud provider.
-running an Ansible playbook. Consult the `playbooks` directory in the source
-repository or Python package to see the playbooks.
 
 The service does not accept any incoming connections and only depends on the
 RabbitMQ message broker and the relevant cloud provider's APIs.
@@ -41,13 +39,23 @@ https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/cloud-im
 application definition]. The playbook to create the OpenShift application is
 located at `playbooks/openshift-apps/cloud-image-uploader.yml`.
 
-Within the container image, configuration is provided via
+The Ansible playbook creates multiple fedora-messaging configuration files from
-`/etc/fedora-messaging/config.toml`. Additionally, secrets may be provided via
+the `config.toml` template. All application configuration is either in the
-environment variables and are noted in the relevant cloud sections.
+fedora-messaging configuration file or in environment variables. The
+environment variables are used for secrets and vary based on which service the
+container handles.
+
+The fedora-messaging configuration file in use by a container is defined in the
+`FEDORA_MESSAGING_CONF` environment variable.
 
 == Deploying
 
-The service contains a single image and one pod in its deployment configuration.
+The OpenShift deployment consists a single image and multiple containers using
+that image, one container for each content type (containers, azure, aws, and
+gcp). The only variation between the containers is the secrets volumes mounted,
+secrets injected via environment variables, and the `FEDORA_MESSAGING_CONF`
+environment variable which points to one of the fedora-messaging configurations
+in `/etc/fedora-messaging/`.
 
 === Staging
 
@@ -55,9 +63,20 @@ The staging BuildConfig builds a container from
 https://pagure.io/cloud-image-uploader/tree/main[the main branch]. You need to
 trigger a build manually, either from the web UI or the CLI.
 
+Although composes are not done in staging, it's still possible to test in
+staging manually. First, start a debug terminal to enter a running container.
+Next, find an AMQP message for a
+https://apps.fedoraproject.org/datagrepper/v2/search?topic=org.fedoraproject.prod.pungi.compose.status.change[production
+compose] in the `FINISHED` or `FINISHED_INCOMPLETE` state. You can trigger the
+fedora-messaging consumer to process the message by running:
+
+....
+FEDORA_MESSAGING_CONF=/etc/fedora-messaging/service-config.toml fedora-messaging reconsume <message-id>
+....
+
 === Production
 
-The staging BuildConfig builds a container from
+The production BuildConfig builds a container from
 https://pagure.io/cloud-image-uploader/tree/prod[the prod branch]. Just like
 staging, you need to trigger a build manually. After deploying to staging, the
 main branch can be merged into the production branch to "promote" it:
@@ -72,10 +91,8 @@ Images are uploaded whenever a compose that contains `vhd-compressed` images.
 Images are first uploaded to a container in the storage account and then
 imported into an Image Gallery.
 
-Credentials for Azure are provided using environment variables. The credentials
+Credentials for Azure are provided using environment variables and are
-are used by the
+discovered by the Azure Python SDK automatically.
-https://docs.ansible.com/ansible/latest/collections/azure/azcollection/index.html[Azure
-Ansible collection].
 
 ==== Image Cleanup
 
@@ -155,6 +172,7 @@ with additional permission.
 ==== Credential rotation
 
 At the moment, credentials are set to expire and will need to be periodically rotated. To do so via the CLI:
+
 ....
 $ az ad app list -o table  # Find the application to issue new secrets for and set CLIENT_ID to its "Id" field
 $ touch azure_secret
@@ -162,3 +180,80 @@ $ chmod 600 azure_secret
 $ SECRET_NAME="Some useful name for the secret"
 $ az ad app credential reset --id $CLIENT_ID --append --display-name $SECRET_NAME --years 1 --query password --output tsv > azure_secret
 ....
+
+=== AWS
+
+AWS images are uploaded by this service to the Fedora AWS account. Cleanup is
+handled by the general Fedora AWS resource cleaner and uses the tags applied to
+a resource to determine when to remove them.
+
+Images are first uploaded to the `fedora-s3-bucket-fedimg` S3 bucket, and then
+imported as EC2 snapshots to the region configured in the `base_region` setting
+of the `consumer_config.aws` section. The snapshot is then replicated to all
+the regions listed in the `ami_regions` setting.
+
+==== New Regions
+
+In the event that a new region becomes available and users want Fedora Cloud
+images there, simply add the new region to the `ami_regions` list.
+
+
+=== Containers
+
+Containers are pushed to the `registry.fedoraproject.org` and `quay.io/fedora/`
+registries. These include the Fedora Toolbox, Fedora and Fedora Minimal, ELN,
+and Atomic Desktop images.
+
+==== Adding New Container Images
+
+The configuration contains a mapping of variants to registry repositories in
+the `consumer_config.container.repos` configuration section. In order to handle
+a new container image, a new mapping should be added to this dictionary.
+
+=== Google Cloud Engine
+
+Google Cloud Engine images are published under the `fedora-cloud` project in
+Google Cloud Platform. The flow is similar to other clouds, as the tarball is
+uploaded to the `fedora-cloud-image-upload` bucket and then imported as a
+machine image. The bucket has a lifecycle configuration to delete an object 3
+days after it has been created so old tarballs are cleaned up automatically
+after being imported.
+
+==== Credentials
+
+The service uses the
+`fedora-image-uploader@fedora-cloud.iam.gserviceaccount.com` service account.
+New credentials can be issued for that account under the IAM & Admin panel,
+although the current credentials do not expire.
+
+==== Permissions
+
+The service account is assigned the `Fedora Image Uploader` role which should
+grant it the minimal permissions required to manage images. The current
+permission list is as follows:
+
+  - compute.globalOperations.get
+  - compute.images.create
+  - compute.images.createTagBinding
+  - compute.images.delete
+  - compute.images.deleteTagBinding
+  - compute.images.deprecate
+  - compute.images.get
+  - compute.images.getFromFamily
+  - compute.images.list
+  - compute.images.listEffectiveTags
+  - compute.images.listTagBindings
+  - compute.images.setLabels
+  - compute.images.update
+  - compute.images.useReadOnly
+  - resourcemanager.projects.get
+
+In the event that the application requires new permissions, edit the `Fedora
+Image Uploader` role to include the new permissions.
+
+==== Cleanup
+
+Machine images are labeled to include their `end-of-life` date. After this date
+is reached, the image is removed. Images are uploaded as "deprecated" by
+default. Every two weeks an image in an Image Family is promoted and marked as
+not deprecated. Deprecated images are removed after two weeks.