retagger

A tool to handle the retagging of third-party docker images and make them available in their own registries.

What does retagger do, exactly?

retagger is first and foremost a CircleCI workflow that runs every day at 21:30 UTC and on every merge to the main branch. It utilizes skopeo and custom golang code to take upstream docker images, rename them if necessary, and push them to Giant Swarm's container registries: gsoci.azurecr.io and giantswarm-registry.cn-shanghai.cr.aliyuncs.com. It is capable of working with v1, v2, and OCI registries, as well as retagging multi-architecture images.

💡Please note it is not responsible for pushing images to neither docker.io/giantswarm, nor azurecr.io/giantswarm container registries.

How to add your image to the job

You've come to the right place. Pick one of the following methods. For both methods, ensure that the repository exists in the desired container registry first.

Plain copy

You do not need any customizations. Great!

1. Find a skopeo-*.yaml file in images matching your upstream container registry's name. Create a new one, if necessary.
2. Add a tag, SHA, or a semantic version constraint for your image. Refer to Skopeo section or existing files for format definition.
3. If you haven't created a new file, that's it. You're set. Otherwise, continue following the steps.
4. Open CircleCI config and add your file to both retag-registry steps under matrix.parameters.images_file.

Manual copy

You need to copy a few tags, it's a one-off situation. You can use docker pull/docker tag/docker push combination or the below skopeo snippet:

$ skopeo sync --src docker --dest docker --all --keep-going crossplane/crossplane:v1.11.0 docker.io/giantswarm/

Image list formats

Skopeo

The basic file format looks as follows: images/skopeo-registry-example-com.yaml

registry.example.com:
    images:
        redis:
            - "1.0"
            - "2.0"
            - "sha256:0000000000000000000000000000000011111111111111111111111111111111"
    images-by-semver:
        alpine: ">= 3.17"

The full specification is available in upstream skopeo-sync docs. Semantic version constraint documentation is available in Masterminds/semver docs.

Custom image builds

Custom container image builds were moved to: https://github.com/giantswarm/custom-container-images.

Renamed images

Renamed images are represented as an array of RenamedImages objects. Please see the definition below:

type RenamedImage struct {
	// Image is the full name of the image to pull.
	// Example: "alpine", "docker.io/giantswarm/app-operator", or
	// "ghcr.io/fluxcd/kustomize-controller"
	Image string `yaml:"image"`
	// TagOrPattern is used to filter image tags. All tags matching the pattern
	// will be retagged. Required if SHA is specified.
	// Example: "v1.[234].*" or ".*-stable"
	TagOrPattern string `yaml:"tag_or_pattern,omitempty"`
	// SHA is used to filter image tags. If SHA is specified, it will take
	// precedence over TagOrPattern. However TagOrPattern is still required!
	// Example: 234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0
	SHA string `yaml:"sha,omitempty"`
	// Semver is used to filter image tags by semantic version constraints. All
	// tags satisfying the constraint will be retagged.
	Semver string `yaml:"semver,omitempty"`
	// Filter is a regexp pattern used to extract a part of the tag for Semver
	// comparison. First matched group will be supplied for semver comparison.
	// Example:
	//   Filter: "(.+)-alpine"  ->  Image tag: "3.12-alpine" -> Comparison: "3.12>=3.10"
	//   Semver: ">= 3.10"          Extracted group: "3.12"
	Filter string `yaml:"filter,omitempty"`
	// AddTagSuffix is an extra string to append to the tag.
	// Example: "giantswarm", the tag would become "<tag>-giantswarm"
	AddTagSuffix string `yaml:"add_tag_suffix,omitempty"`
	// OverrideRepoName allows user to rewrite the name of the image entirely.
	// Example: "alpinegit", so "alpine" would become
	// "gsoci.azurecr.io/giantswarm/alpinegit"
	OverrideRepoName string `yaml:"override_repo_name,omitempty"`
	// StripSemverPrefix removes the initial 'v' in 'v1.2.3' if enabled. Works
	// only when Semver is defined.
	StripSemverPrefix bool `yaml:"strip_semver_prefix,omitempty"`
}

Contributing

Please refer to CONTRIBUTING.md.