gsadmin/renovate
1
0
Fork 0
mirror of https://github.com/renovatebot/renovate.git synced 2026-11-01 10:09:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(docker): rewrite sections (#16083)

Browse Source
This commit is contained in:
HonkingGoose
2022-06-15 13:48:25 +02:00
committed by GitHub
parent 87f85951a2
commit 9fd3db7280
1 changed files with 15 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/usage/docker.md
+15 -16
View File
@@ -75,43 +75,42 @@ See the docs for `versioning` for documentation and examples of `regex` versioni
## Digest Pinning
We recommend that you pin your Docker images to an exact digest.
By pinning to a digest you ensure your Docker builds are **immutable**: every time you do a `pull` you get the same content.
By pinning to a digest you make your Docker builds immutable, every time you do a `pull` you get the same content.
If you have experience with the way dependency versioning is handled in the JavaScript/npm ecosystem, you might be used to exact versions being immutable.
e.g. if you specify a version like `2.0.1`, you and your colleagues always get the exact same "code".
If you work with dependencies in the JavaScript/npm ecosystem, you may be used to exact versions being immutable.
For example, if you set a version like `2.0.1`, you and your colleagues always get the exact same "code".
What you may not know is that Docker's tags are not immutable versions, even if they look like a version.
e.g. you probably expect `myimage:1` and `myimage:1.2` to change over time, but you might incorrectly assume that `myimage:1.2.0` never changes.
Docker's tags are not immutable versions, even if tags _look_ like a version.
You probably expect `myimage:1` and `myimage:1.2` to change over time, but you might incorrectly assume that `myimage:1.2.0` never changes.
Although it probably _shouldn't_, the reality is that any Docker image tag _can_ change content, and potentially break.
Using a Docker digest as the image's primary identifier instead of using a Docker tag will achieve immutability.
It's not easy to work with strings like `FROM node@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
By replacing Docker tags with Docker digests as the image's primary identifier you'll get immutable builds.
It's hard to work with strings like `FROM node@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
Luckily Renovate can update the digests for you, so you don't have to.
To keep things simple, Renovate retains the Docker tag in the `FROM` line, e.g. `FROM node:14.15.1@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
Read on to see how Renovate updates Docker digests.
To keep things simple, Renovate keeps the Docker tag in the `FROM` line, like this: `FROM node:14.15.1@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
## Digest Updating
If you follow our advice to go from a simple tag like `node:14` to using a pinned digest `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub.
If you follow our advice to replace a simple tag like `node:14` with a pinned digest `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub.
Previously this update would have been "invisible" to you - one day you pull code that represents `node:14.15.0` and the next day you get code that represents `node:14.15.1`.
Previously this update would have been "invisible" to you - one day you pull code that represents `node:14.15.0` and the next day you pull code that represents `node:14.15.1`.
But you can never be sure, especially as Docker caches.
Perhaps some of your colleagues or worse still your build machine are stuck on an older version with a security vulnerability.
Maybe some of your colleagues, or worse still your build machine, are stuck on an older version with a security vulnerability.
By pinning to a digest instead, you will get these updates via Pull Requests, or even committed directly to your repository if you enable branch automerge for convenience.
This ensures everyone on the team uses the latest versions and is in sync.
This makes sure everyone on your team uses the latest versions.
## Version Upgrading
Renovate also supports _upgrading_ versions in Docker tags, e.g. from `myimage:1.2.0` to `myimage:1.2.1` or `myimage:1.2` to `myimage:1.3`.
If a tag looks like a version, Renovate will upgrade it like a version.
We recommend you use the major.minor.patch tagging scheme e.g. change from `myimage:1` to `myimage:1.1.1`.
We recommend you use the major.minor.patch tagging scheme, e.g. change from `myimage:1` to `myimage:1.1.1`.
This way it's easy to see what the Renovate PR is going to change.
You can see the difference between a PR that upgrades `myimage` from `1.1.1` to `1.1.2`. and a PR that changes the contents of the version you already use (`1.1.1`).
You can see the difference between a PR that upgrades `myimage` from `1.1.1` to `1.1.2` and a PR that changes the contents of the version you already use (`1.1.1`).
Currently, Renovate will upgrade minor/patch versions (e.g. from `1.2.0` to `1.2.1`) by default, but not upgrade major versions.
By default, Renovate will upgrade minor/patch versions (like from `1.2.0` to `1.2.1`), but not upgrade major versions.
If you wish to enable major versions then add the preset `docker:enableMajor` to your `extends` array in your `renovate.json`.
Renovate has some Docker-specific intelligence when it comes to versions.