artifacts: Add docs for file/artifact promotion

Signed-off-by: Stephen Augustus <foo@auggie.dev>

artifacts/README.md

@@ -0,0 +1,127 @@
+# Kubernetes Artifacts
+
+This directory contains manifests that are used to perform artifact/file
+promotion for the Kubernetes project.
+
+- [Ownership](#ownership)
+- [Staging buckets](#staging-buckets)
+  - [Creating staging projects](#creating-staging-projects)
+    - [Create a Google Group](#create-a-google-group)
+    - [Create initial manifests](#create-initial-manifests)
+    - [Add to infra tracking](#add-to-infra-tracking)
+    - [Actuation](#actuation)
+- [Enabling automatic builds](#enabling-automatic-builds)
+- [Artifact promotion](#artifact-promotion)
+
+## Ownership
+
+The artifact promoter (and process documentation) is maintained by the
+[Release Engineering subproject](https://git.k8s.io/community/sig-release#release-engineering) of SIG Release.
+
+Feedback should be directed to their communication channels.
+
+## Staging buckets
+
+Each "project" (as defined by SIGs/subprojects) that require access to perform
+file/artifact promotion to artifacts.k8s.io must have a staging GCP project, as
+well as a GCS bucket within that GCP project.
+
+Each staging bucket is governed by a Google Group, which grants push access to
+that bucket.
+
+Project owners can push to their staging repository and use the artifact
+promoter ([`kpromo`][kpromo]) to promote images to the production serving bucket.
+
+### Creating staging projects
+
+#### Create a Google Group
+
+Follow the instructions [here][google-groups] to create a Google Group to
+delegate access to your staging project.
+
+#### Create initial manifests
+
+Create two files:
+
+- `filestores/k8s-staging-<project-name>/filepromoter-manifest.yaml`
+- `manifests/k8s-staging-<project-name>/OWNERS`
+
+The `filepromoter-manifest.yaml` file will house the credentials and other
+filestore/bucket metadata.
+
+(Look at the existing staging configurations and below for examples.)
+
+```yaml
+# google group for gcr.io/k8s-staging-cri-tools is
+# k8s-infra-staging-cri-tools@kubernetes.io
+filestores:
+# STAGING PROJECT
+- base: gs://k8s-staging-cri-tools/releases/
+  # DESIGNATE THE STAGING PROJECT AS THE PROMOTION SOURCE
+  src: true
+# PRODUCTION DIRECTORY TO PROMOTE TO
+- base: gs://k8s-artifacts-prod/binaries/cri-tools/
+  # GCP SERVICE ACCOUNT TO USE FOR PROMOTION
+  service-account: k8s-infra-promoter@k8s-artifacts-prod.iam.gserviceaccount.com
+```
+
+The separation between `filepromoter-manifest.yaml` and the file manifests that
+will exist in the `manifests/` directory is to prevent a single PR from
+modifying the source registry information as well as the artifact/file/release
+information.
+
+Any changes to the `filestores/` directory is expected to be one-time only
+during project setup.
+
+Be sure to add the project owners to the
+`manifests/k8s-staging-<project-name>/OWNERS` file to increase the number of
+people who can approve new artifacts for promotion on behalf of your project.
+
+#### Add to infra tracking
+
+Add the project name to the `infra.staging.projects` list defined in
+[`infra/gcp/infra.yaml`][infra.yaml]
+
+#### Actuation
+
+Once your PR merges:
+
+- a postsubmit job will create the necessary Google Group
+- whoever approved your PR will run [the necessary bash script(s)][staging-bash]
+  to create the staging repo
+
+## Enabling automatic builds
+
+TBD
+
+## Artifact promotion
+
+To promote a set of artifacts, follow these steps:
+
+1. Push the artifacts to staging bucket that was created e.g.,
+   `gs://k8s-staging-kops`
+2. Fork this git repo
+3. Follow the instructions [here][generate-manifest] to generate a file
+   promotion manifest, which should be placed in
+   `manifests/k8s-staging-<project-name>/<manifest-name>.yaml`. A simple
+   convention to follow is using the release's tag as the manifest filename
+   e.g., `manifests/k8s-staging-<project-name>/<release-version>.yaml`
+4. Create a PR to this git repo for your changes.
+5. The PR should trigger a [`pull-k8sio-file-promo` presubmit job][presubmit]
+   which will validate and dry-run your changes; check that the `k8s-ci-robot`
+   responds 'Job succeeded' for it.
+6. Merge the PR. The artifacts will be promoted by one of two jobs
+   1. [`post-k8sio-file-promo`][postsubmit] is a postsubmit job that runs
+      immediately after merge
+   1. [`ci-k8sio-file-promo`][periodic] is a periodic job that runs on a
+      schedule (currently every 4 hours)
+7. Published artifacts will appear artifacts.k8s.io
+
+[generate-manifest]: https://sigs.k8s.io/k8s-container-image-promoter/cmd/kpromo#generating-a-file-promotion-manifest
+[google-groups]: /groups/README.md
+[infra.yaml]: /infra/gcp/infra.yaml
+[kpromo]: https://sigs.k8s.io/k8s-container-image-promoter/cmd/kpromo
+[periodic]: https://prow.k8s.io/job-history/gs/kubernetes-jenkins/logs/ci-k8sio-file-promo
+[postsubmit]: https://prow.k8s.io/job-history/gs/kubernetes-jenkins/logs/post-k8sio-file-promo
+[presubmit]: https://prow.k8s.io/job-history/gs/kubernetes-jenkins/pr-logs/directory/pull-k8sio-file-promo
+[staging-bash]: /infra/gcp/bash/ensure-staging-storage.sh

groups/README.md

@@ -1,12 +1,27 @@
 # Automation of Google Groups maintenance for k8s-infra permissions
 
+- [Making changes](#making-changes)
+  - [Staging access groups](#staging-access-groups)
+- [Manual deploy](#manual-deploy)
+
 ## Making changes
 
 - Edit `groups.yaml` and `restrictions.yaml` to add a new group or update an existing group
 - Use `make test` to ensure the changes meet conventions
 - Open a pull request
 - When the pull request merges, the [post-k8sio-groups] job will deploy the changes
 
+### Staging access groups
+
+Google Groups for granting push access to container repositories and/or buckets
+must be of the form:
+
+```console
+k8s-infra-staging-<project-name>@kubernetes.io`
+```
+
+`<project-name>` can have a maximum of 18 characters.
+
 ## Manual deploy
 
 - Must be run by someone who is a member of the k8s-infra-group-admins@kubernetes.io group

k8s.gcr.io/README.md

@@ -3,6 +3,11 @@
 This directory is for tools and things that are used to administer the GCR
 repositories used to publish official container images for Kubernetes.
 
+- [Staging repos](#staging-repos)
+  - [Creating staging repos](#creating-staging-repos)
+  - [Enabling automatic builds](#enabling-automatic-builds)
+  - [Image Promoter](#image-promoter)
+
 ## Staging repos
 
 Each "project" (as decided by people) that feeds into Kubernetes' main
@@ -15,11 +20,7 @@ to promote images to the main serving repository.
 
 ### Creating staging repos
 
-1. Create a google group for granting push access by adding an email
-alias for it in [groups.yaml] and [restrictions.yaml]. The email alias should be of the form
-`k8s-infra-staging-<project-name>@kubernetes.io`. The project name
-can have a maximum of 18 characters.
-
+1. [Create a Google Group][google-groups]
 2. Create 3 files:
     - `images/k8s-staging-<project-name>/OWNERS`
     - `images/k8s-staging-<project-name>/images.yaml`
@@ -32,7 +33,7 @@ look at the existing staging repos for examples.
 NOTE: For `images/k8s-staging-<project-name>/images.yaml`, if you have no images
 to upload at this time, you must still create a blank file, like this:
 
-```
+```yaml
 # No images yet
 ```
 
@@ -84,6 +85,7 @@ To promote an image, follow these steps:
 Essentially, in order to get images published to a production repo, you have to
 use the image promotion (PR creation) process defined above.
 
+[google-groups]: /groups/README.md
 [image-pushing-readme]: https://git.k8s.io/test-infra/config/jobs/image-pushing/README.md
 [groups.yaml]: /groups/groups.yaml
 [restrictions.yaml]: /groups/restrictions.yaml