artifacts: Add docs for file/artifact promotion

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

artifacts/README.md

@@ -0,0 +1,92 @@
+# Kubernetes Artifacts
+
+This directory the manifest that are used to perform artifact promotion for
+the Kubernetes project.
+
+- [Staging buckets](#staging-buckets)
+  - [Creating staging repos](#creating-staging-repos)
+- [Enabling automatic builds](#enabling-automatic-builds)
+- [Image Promoter](#image-promoter)
+
+## 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 repos
+
+1. [Create a Google Group][google-groups]
+2. 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 for examples.)
+
+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.
+
+1. Add the project name to the `infra.staging.projects` list defined in
+   [`infra/gcp/infra.yaml`][infra.yaml]
+2. 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
+
+## Image Promoter
+
+To promote an image, follow these steps:
+
+1. Push your image to one of the above staging docker repos. (E.g.,
+   gcr.io/k8s-staging-coredns).
+1. Clone this git repo.
+1. Add the image into the promoter manifest. E.g., if you pushed
+   gcr.io/k8s-staging-coredns/foo:1.3, then add a "foo" image entry into the
+   manifest in `filestores/k8s-staging-coredns/images.yaml`.
+1. Create a PR to this git repo for your changes.
+1. The PR should trigger a `pull-k8sio-cip` job which will validate and dry-run
+   your changes; check that the `k8s-ci-robot` responds 'Job succeeded' for it.
+1. Merge the PR. Your image will be promoted by one of two jobs:
+   - [`post-k8sio-image-promo`][post-promo-job] is a postsubmit that runs immediately after merge
+   - [`ci-k8sio-cip`][ci-promo-job] is a postsubmit that runs immediately after merge
+1. A periodic 
+1. Published images will appear on k8s.gcr.io and can be viewed [here](https://console.cloud.google.com/gcr/filestores/k8s-artifacts-prod).
+
+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
+[infra.yaml]: /infra/gcp/infra.yaml
+[kpromo]: https://sigs.k8s.io/k8s-container-image-promoter/cmd/kpromo
+[staging-bash]: /infra/gcp/bash/ensure-staging-storage.sh
+
+<!-- TODO(releng): DELETE IF UNUSED -->
+
+[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
+[vdf]: /k8s.gcr.io/Vanity-Domain-Flip.md
+[post-promo-job]: https://testgrid.k8s.io/sig-release-releng-blocking#post-k8sio-image-promo
+[ci-promo-job]: https://testgrid.k8s.io/sig-release-releng-blocking#ci-k8sio-image-promo

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