Kubernetes
Description
The kubernetes crawler looks recursively for every .yaml and .yml file from a root directory, and updates the container images declared in any Kubernetes pod specification it recognises.
Multi-document YAML files are supported, and each document is addressed by index in the generated manifest.
This crawler is enabled by default, so it can be used either automatically by running updatecli diff from a directory containing the files to update, or by providing a manifest.
The automatic discovery behavior can be tuned by providing a YAML manifest with a kubernetes crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.
Supported resources
Images are read from containers and initContainers at any of these locations:
spec.containers/spec.initContainers- barePodspec.template.spec.…-Deployment,DaemonSet,StatefulSet,Job, and anything else built on a pod templatespec.jobTemplate.spec.template.spec.…-CronJob
Matching is structural: apiVersion and kind are not checked, so any document exposing one of those paths is processed.
Generated manifests
Each image produces a dockerimage source for the latest tag and a yaml target that rewrites the image reference in place. When digest pinning is enabled, a dockerdigest source is added and the digest is written alongside the tag.
digest defaults to true. Set digest: false to track the tag only.
Authentication
Use auths to reach private registries, keyed by registry URL without a scheme, accepting either a token or a username/password pair. When it is empty Updatecli falls back to the ambient OCI credentials, such as those written by docker login.
Version filtering
If unspecified, the version filter defaults to kind semver with pattern *.
The pattern is then narrowed per image using the tag currently in the file: an image on 3.18 is filtered with >=3.18, and a tagfilter regex derived from the shape of that tag is added so unrelated tag conventions are not considered.
More details on the "Version Filtering" page.
Limitations
Kustomize
images:transformers in akustomization.yamlare not supported. Plain Kubernetes manifests living inside a kustomize tree are picked up normally, because they carry a standard pod specification.filespatterns are matched against the file name only, not against the path. Use.yaml, notmanifests/.yaml.An image whose value contains a template expression, such as
"{{ .Values.image.repository }}:{{ .Values.image.tag }}", cannot be resolved to a tag. A digest-only manifest is generated for it, which is rarely actionable (useignoreto exclude these).
Manifest
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| auths | object | auths provides a map of registry credentials where the key is the registry URL without scheme if empty, updatecli relies on OCI credentials such as the one used by Docker. example: | |
| password | string | password specifies the container registry password to use for authentication. Not compatible with token compatible: * source * condition * target default:
by default credentials are fetch from the local environment such as remark: Not compatible with token | |
| token | string | token specifies the container registry token to use for authentication. compatible: * source * condition * target default:
by default credentials are fetch from the local environment such as remark: Not compatible with username/password | |
| username | string | username specifies the container registry username to use for authentication. compatible: * source * condition * target default:
by default credentials are fetch from the local environment such as remark: Not compatible with token | |
| digest | boolean | digest provides parameters to specify if the generated manifest should use a digest on top of the tag. | |
| files | array | Files allows to specify a list of Files to analyze. The pattern syntax is: Match requires pattern to match all of name, not just a substring. The only possible returned error is ErrBadPattern, when pattern is malformed. On Windows, escaping is disabled. Instead, | |
| ignore | array | Ignore allows to specify rule to ignore autodiscovery a specific Kubernetes manifest based on a rule | |
| images | array | Images specifies the list of container image to check | |
| path | string | Path specifies a Fleet bundle path pattern, the pattern requires to match all of name, not just a subpart of the path. | |
| only | array | Only allows to specify rule to only autodiscover manifest for a specific Kubernetes manifest based on a rule | |
| images | array | Images specifies the list of container image to check | |
| path | string | Path specifies a Fleet bundle path pattern, the pattern requires to match all of name, not just a subpart of the path. | |
| rootdir | string | RootDir defines the root directory used to recursively search for Kubernetes files | |
| versionfilter | object |
kind - semver
versionfilter of kind kind - regex
versionfilter of kind example: and its type like regex, semver, or just latest. More examples can be found at https://www.updatecli.io/docs/core/versionfilter/ | |
| kind | string | specifies the version kind such as semver, regex, or latest | |
| pattern | string | specifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format | |
| regex | string | specifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used. | |
| replaceall | object | replaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction. | |
| pattern | string | Pattern specifies the regex pattern to match for replacement | |
| replacement | string | Replacement specifies the replacement string (supports $1, $2, etc. for captured groups) | |
| strict | boolean | strict enforce strict versioning rule. Only used for semantic versioning at this time |
Example
# updatecli.d/default.yaml
name: "Kubernetes autodiscovery"
scms:
default:
kind: git
spec:
url: "https://github.com/jenkins-infra/release.git"
branch: master
autodiscovery:
scmid: default
crawlers:
kubernetes:
digest: true
versionfilter:
kind: semver
pattern: minoronly
## To ignore specific path
#ignore:
# - images:
# - "mcr.microsoft.com/dotnet/framework/sdk"
only:
- images:
- "mcr.microsoft.com/dotnet/framework/sdk"