Merge branch 'acunskis-doc-update-readme' into 'master'

Update readme with latest build flow

See merge request https://gitlab.com/gitlab-org/gitlab-build-images/-/merge_requests/595

Merged-by: Balasankar 'Balu' C <balasankar@gitlab.com>
Approved-by: Stan Hu <stanhu@gmail.com>
Approved-by: Balasankar 'Balu' C <balasankar@gitlab.com>
Co-authored-by: Stan Hu <stanhu@gmail.com>
Co-authored-by: Andrejs Cunskis <acunskis@gitlab.com>

README.md

@@ -19,72 +19,91 @@ There are two methods to adding a new image:
 A bespoke image is one that uses it's own Dockerfile. In the interests of
 avoiding repetition, it's better to use the custom docker build if possible.
 
+Images from a custom Dockerfile are built from job definitions in [custom.images.yml](.gitlab/ci/custom.images.yml)
+
 Assuming the image you want to add is called `new-image`:
 
-1. Add a test task: `new-image test: *test_build`.
+1. Add a new build job:
-1. Add a new build task: `new-image: *build_and_deploy`.
+
+```yml
+new-image:
+  extends: .build_and_deploy
+```
+
 1. Add a Dockerfile: `Dockerfile.new-image`.
 
 ### Use a custom image with versioned features
 
-To add a new image to the build, edit [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/.gitlab-ci.yml).
+To add a new image to the build, create a new images definition file like [`gitlab.images.yml`](.gitlab/ci/gitlab.images.yml).
 
-With custom images, the name of the image is used to define the contents (as opposed to use a bespoke Dockerfile build).
+With custom images, the components and versions define the resulting image name and tag.
 
-For this reason, the name needs to be correctly defined.
+Major components define image path. Base image is defined by `OS` component. Supported base images are:
 
-The name is defined as `[feature]-[version]` pairs, separated by `-`.
+1. `debian:$version`
+1. `ubi:$version`
+
+[Supported major](https://gitlab.com/gitlab-org/gitlab-build-images/-/blob/master/scripts/lib/custom-docker.sh#L4) components are:
+
+1. `OS`
+1. `RUBY`
+1. `GOLANG`
+1. `NODE`
+1. `POSTGRES`
+
+Minor components define tag name. [Supported minor](https://gitlab.com/gitlab-org/gitlab-build-images/-/blob/master/scripts/lib/custom-docker.sh#L5) components are:
+
+1. `BUNDLER`
+1. `RUBYGEMS`
+1. `GIT`
+1. `LFS`
+1. `CHROME`
+1. `YARN`
+1. `GRAPHICSMAGICK`
+1. `BAZELISK`
+1. `DOCKER`
+1. `BUILDX`
+1. `GCLOUD`
+1. `KUBECTL`
+1. `HELM`
+
+The names are defined as `[feature]-[version]` pairs, separated by `-`.
 
 Here are some example build names:
 
-1. `ruby-2.7-golang-1.15-git-2.29`
+1. `debian-bullseye-ruby-2.7-golang-1.15:git-2.29`
-1. `ruby-3.0.0-git-2.29-lfs-2.9-node-14.15-yarn-1.22-graphicsmagick-1.3.34`
+1. `debian-bullseye-ruby-3.0.0-node-14.15:git-2.29-lfs-2.9-yarn-1.22-graphicsmagick-1.3.34`
-1. `ruby-3.0.0.patched-golang-1.14-git-2.29-lfs-2.9-chrome-87-node-14.15-yarn-1.22-postgresql-12-graphicsmagick-1.3.34`
+1. `debian-bullseye-ruby-3.0.0.patched-golang-1.14-postgresql-12:git-2.29-lfs-2.9-chrome-87-node-14.15-yarn-1.22-graphicsmagick-1.3.34`
-
-The first pair represents the base image and version. So `ruby-3.0-...` will use the `ruby:3.0` base image, while
-`golang-1.15` will use the `golang:1.15` base image.
-
-Each of the following parts represents another feature and version. Available
-options are:
-
-1. `bazelisk`
-1. `chrome`
-1. `docker`
-1. `git`
-1. `golang`
-1. `graphicsmagick`
-1. `lfs`
-1. `node`
-1. `postgresql`
-1. `ruby`
-1. `yarn`
 
 #### Adding a new build
 
-As an example, if you want to add new image for Ruby 3.0 with `git` 2.29 and `golang` 1.15,
+As an example, if you want to add new image for Ruby 3.0 with `git` 2.29 and `golang` 1.15 based on `debian` bullseye,
-the name would be `ruby-3.0-golang-1.15-git-2.29`.
+following job definition would have to be created:
 
-1. Add a test task: `ruby-3.0-golang-1.15-git-2.29 test: *test_custom`
+```yml
-1. Add a new build task: `ruby-3.0-golang-1.15-git-2.29 push: *build_and_deploy_custom`
+new_image:
+  extends:
+    - .build_and_push
+  variables:
+    OS: 'debian:bullseye'
+    RUBY: '3.0'
+    GOLANG: '1.15'
+    GIT: '2.29'
+```
 
-Note that the build name is also used for tagging the generated image, which means it cannot be
+Note that tag name is limited to 128 characters so amount of `minor components` an image can have is limited by it.
-longer than 128 characters.
 
 #### Pushing a rebuild image
 
-To build (or rebuild) a given image and push it, you need to enable manual action for a given
+Images are built and pushed automatically after a merge request is merged.
-job after it is merged to master.
-
-By default we don't do it to ensure that an upstream dependency doesn't end up breaking our images
-unexpectedly. For reference, this happened in the past: https://gitlab.com/gitlab-org/gitlab/issues/205192
 
 ## Note regarding Google Chrome
 
 Google has a policy of yanking older versions of Google Chrome from their PPA
 whenever a new major version is released. To help maintain consistent build
-images, there is a CI step that saves the latest Google Chrome .deb into an the
+images, there is a CI step that saves the latest Google Chrome and Chromium .deb into an the
-GitLab package registry. The install for Chrome will attempt to retrieve from the
+GitLab package registry. The install for Chrome will use registry to fetch corresponding packages.
-registry if it cannot find the file in the apt repository.
+Make sure a certain version is cached before updating it in build jobs.
 See `scripts/cache-google-chrome` for more details.
 
 ## Contributing