Merge pull request #950 from alphagov/refresh/dockerfile

Updated Dockerfile reference and updated Dockerfile to match guidance

.github/dependabot.yml

@@ -6,3 +6,8 @@ updates:
     interval: weekly
     time: "03:00"
   open-pull-requests-limit: 10
+- package-ecosystem: docker
+  directory: "/"
+  schedule:
+    interval: weekly
+    time: "03:00"

Dockerfile

@@ -1,4 +1,5 @@
-FROM ruby:3.1.3-buster
+ # 3.1.3-buster
+FROM ruby@sha256:55cd5fab4140db7a04f46921eafcd941be95f6c5687b01154d43e75479ba0fe9
 
 EXPOSE 4567:4567
 EXPOSE 35729:35729

source/manuals/programming-languages/docker.html.md.erb

@@ -11,36 +11,21 @@ This style guide:
 * provides some conventions for creating production-ready Dockerfiles at GDS
 * supplements the official [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
 
-## Using tags and digests in FROM instructions
-
-The `FROM` instruction specifies the starting image for your Docker image build.
+## Why we use Dockerfile
 
-A tag is a short label you can use to reference an image.
+The [Open Container Initiative](https://opencontainers.org/) started in June 2015, and is an open governance structure for creating open standards around container formats.
+Docker were one of the first movers in this space. Their documentation defined the de facto standard and then delegated to the OCI.
 
-For example:
-
-```
-FROM alpine:3.9
-```
+The [OCI's documentation on Containerfile](https://github.com/containers/common/blob/main/docs/Containerfile.5.md) is derived from Docker's Dockerfile documentation.
 
-where:
+## Using tags and digests in FROM instructions
 
-* `alpine` is the image name
-* `3.9` is the tag
+The `FROM` instruction specifies the starting image for your Docker image build.
 
-As you cannot rely on the tag pointing to the exact same image over time, you
-should instead use a digest, which identifies the image by a hash of its
-contents. This makes sure that you are always referencing the image that you
-expect.
+A tag is a short label you can use to reference an image, often referencing a version number.
 
-For example:
-
-```
-FROM alpine@sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
-```
-
-Where `sha256@769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6`
-is the unique digest representing the particular variant of the image.
+As you cannot rely on the tag pointing to the exact same image over time, you should instead use a digest, which identifies the image by a hash of its contents.
+This makes sure that you are always referencing the image that you expect.
 
 To get the digest, run `docker pull <tag>`. For example:
 
@@ -51,10 +36,26 @@ Digest: sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
 Status: Image is up-to-date for alpine:3.9
 ```
 
-As [Dependabot](https://dependabot.com) has [support for updating `FROM` lines
-which use digests](https://github.com/dependabot/dependabot-core/pull/100),
+As [Dependabot](https://dependabot.com) has
+[support for updating `FROM` lines which use digests](https://github.com/dependabot/dependabot-core/pull/100),
 you can still use Dependabot to keep your images up-to-date.
 
+If you specify both the tag and the digest, then the digest takes precedence.
+The standard implies that you may only specify one or the other.  Do not specify
+both as the behaviour may vary across different platforms.
+
+Instead, the recommended way to keep track of the intended version is to add it in a line above FROM as a comment.
+For example:
+
+```
+# alpine:3.9
+FROM alpine@sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
+...
+```
+
+Please double-check that the digest and the commented version are consistent each time you upgrade, as Dependabot does not have perfect capability at either identifying the magnitude of the upgrade.
+It will also not update the comment automatically, so this will need modifying on any dependabot-raised pull requests.
+
 ## Using multi-stage builds
 
 Using [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) enables the drastic
@@ -65,13 +66,16 @@ used in the compilation steps.
 As an example;
 
 ```
-FROM golang:1.16 AS builder
+# golang:bullseye
+FROM golang@sha256:ecb3fe70e1fd6cef4c5c74246a7525c3b7d59c48ea0589bbb0e57b1b37321fb9 AS builder
 WORKDIR /go/src/github.com/alphagov/paas-aiven-broker/
 RUN git clone https://github.com/alphagov/paas-aiven-broker.git .
 RUN go mod download
 RUN go build
 
-FROM alpine:latest
+# alpine:3.9
+FROM alpine@sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
+
 RUN apk --no-cache add ca-certificates
 WORKDIR /root/
 COPY --from=builder /go/src/github.com/alphagov/paas-aiven-broker/paas-aiven-broker .

source/standards/source-code/use-github.html.md.erb

@@ -60,12 +60,14 @@ Consider creating a Workflow Template in the [alphagov workflow folder](https://
 If using GitHub-owned actions, [pin to a specific version](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions) and [configure Dependabot to keep your actions up to date](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot#example-dependabotyml-file-for-github-actions) by adding a comment on the same line with the tag the commitsha represents. For example:
 
 ```
-- uses: actions/checkout@01aecccf739ca6ff86c0539fbc67a7a5007bbc81 #v2.1.0
+- uses: actions/checkout@01aecccf739ca6ff86c0539fbc67a7a5007bbc81 # v2.1.0
 ```
 
 Pinned versions should include the semver version in a comment next to the SHA, helping humans understand which versions we are pinned to.
 Where possible, allow automated dependency management tools to scan these version comments and suggest updates.
 
+Please double-check that the digest and the commented version are consistent each time you upgrade, as dependabot does not have perfect capability at either identifying the magnitude of the upgrade, or necessarily updating the commented pin.
+
 Third-party actions should only be used if:
 
 - The provider is verified by GitHub (for example, [aws-actions](https://github.com/aws-actions))