mirror of https://github.com/fluxcd/flux2.git
Separate image tags howto from migration howto
The Flux v1 migration how-to flows better if the section on how to set builds up to tag images in the right way is its own document. It's a lot to skim past when you don't need it, and (since it's a different layer of yak hair) something you might want to figure out first if you do need it. Signed-off-by: Michael Bridgen <michael@weave.works>pull/806/head
Michael Bridgen
4 years ago
committed by
Hidde Beydals
parent
15f8e6369b
commit
2a3a4456c1
@ -0,0 +1,150 @@
|
|||||||
|
<!-- -*- fill-column: 100 -*- -->
|
||||||
|
# How to make sortable image tags to use with automation
|
||||||
|
|
||||||
|
Flux v2 does not support selecting the lastest image by build time. Obtaining the build time needs
|
||||||
|
the container config for each image, and fetching that is subject to strict rate limiting by image
|
||||||
|
registries (e.g., by [DockerHub][dockerhub-rates]).
|
||||||
|
|
||||||
|
This guide explains how to construct image tags so that the most recent image has the tag that comes
|
||||||
|
last in alphabetical order. The technique suggested is to put a timestamp or serial number in each
|
||||||
|
image tag.
|
||||||
|
|
||||||
|
## Formats and alternatives
|
||||||
|
|
||||||
|
The important properties for sorting alphabetically are that the parts of the timestamp go from most
|
||||||
|
significant to least (e.g., the year down to the second), and that the output is always the same
|
||||||
|
number of characters.
|
||||||
|
|
||||||
|
Image tags are often shown in user interfaces, so readability matters. Here are some alternatives:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ # seconds-since-epoch (used in the example above)
|
||||||
|
$ date +%s
|
||||||
|
1611840548
|
||||||
|
$ # date and time (remember ':' is not allowed in a tag)
|
||||||
|
$ date +%F.%H%M%S
|
||||||
|
2021-01-28.133158
|
||||||
|
```
|
||||||
|
|
||||||
|
Alternatively, you can use a stable serial number as part of the tag. Some CI platforms will
|
||||||
|
provide a build number in an environment variable, but that may not be reliable to use as a serial
|
||||||
|
number -- check the platform documentation.
|
||||||
|
|
||||||
|
A commit count can be a reasonable stand-in for a serial number, if you build an image per commit,
|
||||||
|
and you don't rewrite the branch in question.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ # commits in branch
|
||||||
|
$ git --rev-list --count HEAD
|
||||||
|
1504
|
||||||
|
```
|
||||||
|
|
||||||
|
Beware: this will not give a useful number if you have a shallow clone.
|
||||||
|
|
||||||
|
### Other things to include in the image tag
|
||||||
|
|
||||||
|
It is also handy to quickly trace an image to the branch and commit of its source code. Including
|
||||||
|
the branch also means you can filter for images from a particular branch.
|
||||||
|
|
||||||
|
In sum, a useful tag format is
|
||||||
|
|
||||||
|
<branch>-<sha1>-<timestamp>
|
||||||
|
|
||||||
|
The branch and tag will usually be made available in a CI platform as environment variables. See
|
||||||
|
|
||||||
|
- [CircleCI's built-in variables `CIRCLE_BRANCH` and `CIRCLE_SHA1`][circle-ci-env]
|
||||||
|
- [GitHub Actions' `GITHUB_REF` and `GITHUB_SHA`][github-actions-env]
|
||||||
|
- [Travis CI's `TRAVIS_BRANCH` and `TRAVIS_COMMIT`][travis-env].
|
||||||
|
|
||||||
|
## Example of a build process with timestamp tagging
|
||||||
|
|
||||||
|
Here is an example of a [GitHub Actions job][gha-syntax] that creates a "build ID" with the git
|
||||||
|
branch, SHA1, and a timestamp, and uses it as a tag when building an image:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
build-push:
|
||||||
|
env:
|
||||||
|
IMAGE: org/my-app
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
|
||||||
|
- name: Generate build ID
|
||||||
|
id: prep
|
||||||
|
run: |
|
||||||
|
branch=${GITHUB_REF##*/}
|
||||||
|
sha=${GITHUB_SHA::8}
|
||||||
|
ts=$(date +%s)
|
||||||
|
echo "::set-output name=BUILD_ID::${branch}-${sha}-${ts}"
|
||||||
|
|
||||||
|
# These are prerequisites for the docker build step
|
||||||
|
- name: Set up QEMU
|
||||||
|
uses: docker/setup-qemu-action@v1
|
||||||
|
- name: Set up Docker Buildx
|
||||||
|
uses: docker/setup-buildx-action@v1
|
||||||
|
- name: Login to DockerHub
|
||||||
|
uses: docker/login-action@v1
|
||||||
|
with:
|
||||||
|
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||||
|
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||||
|
|
||||||
|
- name: Build and publish container image with tag
|
||||||
|
uses: docker/build-push-action@v2
|
||||||
|
with:
|
||||||
|
push: true
|
||||||
|
context: .
|
||||||
|
file: ./Dockerfile
|
||||||
|
tags: |
|
||||||
|
${{ env.IMAGE }}:${{ steps.prep.outputs.BUILD_ID }}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using in an `ImagePolicy` object
|
||||||
|
|
||||||
|
When creating an `ImagePolicy` object, you will need to extract just the timestamp part of the tag,
|
||||||
|
using the `tagFilter` field. You can filter for a particular branch to restrict images to only those
|
||||||
|
built from that branch.
|
||||||
|
|
||||||
|
Here is an example that filters for only images built from `main` branch, and selects the most
|
||||||
|
recent according the timestamp (created with `date +%s`):
|
||||||
|
|
||||||
|
```
|
||||||
|
apiVersion: image.toolkit.fluxcd.io/v1alpha1
|
||||||
|
kind: ImagePolicy
|
||||||
|
metadata:
|
||||||
|
name: image-repo-policy
|
||||||
|
namespace: flux-system
|
||||||
|
spec:
|
||||||
|
imageRepositoryRef:
|
||||||
|
name: image-repo
|
||||||
|
filterTags:
|
||||||
|
pattern: '^main-[a-f0-9]+-(?P<ts>[0-9]+)'
|
||||||
|
extract: '$ts'
|
||||||
|
policy:
|
||||||
|
alphabetical:
|
||||||
|
order: asc
|
||||||
|
```
|
||||||
|
|
||||||
|
If you don't care about the branch, that part can be a wildcard in the pattern:
|
||||||
|
|
||||||
|
```
|
||||||
|
apiVersion: image.toolkit.fluxcd.io/v1alpha1
|
||||||
|
kind: ImagePolicy
|
||||||
|
metadata:
|
||||||
|
name: image-repo-policy
|
||||||
|
namespace: flux-system
|
||||||
|
spec:
|
||||||
|
imageRepositoryRef:
|
||||||
|
name: image-repo
|
||||||
|
filterTags:
|
||||||
|
pattern: '^.+-[a-f0-9]+-(?P<ts>[0-9]+)'
|
||||||
|
extract: '$ts'
|
||||||
|
policy:
|
||||||
|
alphabetical:
|
||||||
|
order: asc
|
||||||
|
```
|
||||||
|
|
||||||
|
[circle-ci-env]: https://circleci.com/docs/2.0/env-vars/#built-in-environment-variables
|
||||||
|
[github-actions-env]: https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables
|
||||||
|
[travis-env]: https://docs.travis-ci.com/user/environment-variables/#default-environment-variables
|
||||||
|
[dockerhub-rates]: https://docs.docker.com/docker-hub/billing/faq/#pull-rate-limiting-faqs
|
||||||
|
[gha-syntax]: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
|
||||||
Loading…
Reference in New Issue