Configuration
Overview ¶
You can configure kbld by adding configuration resources (they follow Kubernetes resource format, but are removed from kbld output). Configuration resources may be specified multiple times.
Schema ¶
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
minimumRequiredVersion: 0.15.0
sources:
- image: adservice
path: src/
destinations:
- image: adservice
newImage: docker.io/dkalinin/microservices-demo-adservice
searchRules:
- keyMatcher:
name: sidecarImage
- valueMatcher:
image: exact-image
imageRepo: gcr.io/some/repo
overrides:
- image: nginx
newImage: docker.io/library/nginx:1.14.2
minimumRequiredVersion
(optional) specify minimume required version of kbld needed to work with this configurationsources
(optional; array) allows to specify how to build certain images. See details in sections below.destinations
(optional; array) allows to specify one or more destination where images should be pushedimage
(optional) image matchernewImage
(optional) image destination (e.g. docker.io/dkalinin/app-demo)tags
(optional; array of strings) tags to apply to pushed images (e.g.[latest, tag2]
) (v0.26.0+)
searchRules
(optional; array) allows to specify one or more matchers for finding image references. Key and value matchers could be specified together or separately. If key and value matchers are specified together, both matchers must succeed. This functionality supersedesImageKeys
kind.keyMatcher
(optional) key matchername
(optional; string) specifies key name (e.g.sidecarImage
)path
(optional; array) specifies key path from the root of the YAML document (e.g.[data, sidecarImage]
,[spec, images, {allIndexes: true}]
)
valueMatcher
(optional) value matcherimage
(optional; string) matches values exactlyimageRepo
(optional; string) matches values that follow image reference format ([registry]repo[:tag]\[@sha256:...]
) and expectsrepo
portion to match (e.g.gcr.io/project/app
)
updateStrategy
(optional) strategy for finding and updating image references within value (v0.21.0+)none
(optional) excludes value from processing (v0.22.0+)entireString
(optional; default) uses entire value as an image refjson
(optional) parses JSON and identifies image refs by specified search rulessearchRules
… (recursive)
yaml
(optional) parses YAML and identifies image refs by specified search rulessearchRules
… (recursive)
overrides
(optional; array) configures kbld to rewrite image location before trying to build image or resolve it to a digest.image
(optional) image matchernewImage
(optional) could be image without tag/digest, image tag ref, or image digest refpreresolved
(optional; bool) specifies ifnewImage
should be used as istagSelection
(optional; VersionSelection) specifies how to resolve tag fornewImage
.newImage
in this case is expected to not specify tag or digest (e.g.gcr.io/my-corp/app
) without a tag. SeeVersionSelection
type details. Available as of v0.28.0+
Sources ¶
Sources configure kbld to execute image building operation based on specified path.
(Note: We recommend using Config
kind with sources
key instead of Sources
kind. sources
key in both kind Config
and Sources
has same functionality.)
Currently supported builders:
docker
: Docker CLI (default)pack
: Pack CLI (https://github.com/buildpacks/pack)kubectlBuildkit
: BuildKit CLI for kubectl
Docker ¶
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
sources:
- image: image1
path: src/
docker:
# all options shown; none are required
build:
target: "some-target"
pull: true
noCache: true
file: "hack/Dockefile.dev"
rawOptions: ["--squash"]
docker.build.target
(string): Set the target build stage to build (no default)docker.build.pull
(bool): Always attempt to pull a newer version of the image (default is false)docker.build.noCache
(bool): Do not use cache when building the image (default is false)docker.build.file
(string): Name of the Dockerfile (default is Dockerfile)docker.build.rawOptions
([]string): Refer to https://docs.docker.com/engine/reference/commandline/build/ for all available options
Pack ¶
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
sources:
- image: image1
path: src/
pack:
build:
builder: cloudfoundry/cnb:bionic
pack.build.builder
(string): Set builder image (required)pack.build.buildpacks
([]string): Set list of buildpacks to be used (no default)pack.build.clearCache
(bool): Clear cache before building image (default is false)pack.build.rawOptions
([]string): Refer topack build -h
for all available flags
BuildKit CLI for kubectl ¶
Available as of v0.28.0+
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
sources:
- image: image1
path: src/
kubectlBuildkit:
# all options shown; none are required
build:
target: "some-target"
pull: true
noCache: true
file: "hack/Dockefile.dev"
rawOptions: ["--platform=..."]
kubectlBuildkit.build.target
(string): Set the target build stage to build (no default)kubectlBuildkit.build.pull
(bool): Always attempt to pull a newer version of the image (default is false)kubectlBuildkit.build.noCache
(bool): Do not use cache when building the image (default is false)kubectlBuildkit.build.file
(string): Name of the Dockerfile (default is Dockerfile)kubectlBuildkit.build.rawOptions
([]string): Refer tokubectl buildkit build -h
for all available options
To provide registry credentials to the builder, create a Kubernetes docker secret:
kubectl create secret docker-registry buildkit --docker-server=https://index.docker.io/v1/ --docker-username=my-user --docker-password=my-password
See project site for details: buildkit-cli-for-kubectl.
Destinations ¶
Destinations configure kbld to push built images to specified location.
Currently images are pushed via Docker daemon for both Docker and pack built images (since pack also uses Docker daemon).
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
destinations:
- image: adservice
newImage: docker.io/dkalinin/microservices-demo-adservice
As of v0.26.0+, additional tags could be specified to be associated with pushed image (applied via registry API):
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
destinations:
- image: adservice
newImage: docker.io/dkalinin/microservices-demo-adservice
tags:
- v0.10.3
- latest-staging
ImageDestinations ¶
We recommend using Config
kind with destinations
key instead of ImageDestinations
kind. destinations
key in both kind Config
and ImageDestinations
has same functionality.
Overrides ¶
Overrides configure kbld to rewrite image location before trying to build it or resolve it to a digest.
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
overrides:
- image: unknown
newImage: docker.io/library/nginx:1.14.2
It can also hold preresolved
new image, so no building or resolution happens (for preresolved images, kbld will not connect to registry to obtain any metadata):
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
overrides:
- image: unknown
newImage: docker.io/library/nginx:1.14.2
preresolved: true
tagSelection
can be used for dynamic selection of a tag based on various strategies. Currently only semver
strategy is available.
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
overrides:
- image: unknown
newImage: docker.io/library/nginx
tagSelection:
semver:
constraints: "<1.15.0"
ImageOverrides ¶
We recommend using Config
kind with overrides
key instead of ImageOverrides
kind. overrides
key in both kind Config
and ImageOverrides
has same functionality.
Example for updateStrategy
that parses YAML ¶
kind: ConfigMap
metadata:
name: config
data:
data.yml: |
name: nginx
image: nginx # <-- below config finds and updates this image
---
apiVersion: kbld.k14s.io/v1alpha1
kind: Config
minimumRequiredVersion: 0.15.0
searchRules:
- keyMatcher:
name: data.yml
updateStrategy:
yaml:
searchRules:
- keyMatcher:
name: image
Matching images ¶
Available as of 0.15.0+
Sources
, ImageDestinations
, and ImageOverrides
have ability to match images in following ways:
- via
image
to match exact content- e.g.
image: image1
which would only matchimage1
- e.g.
- via
imageRepo
to match only by registry+repo combination- e.g.
imageRepo: gcr.io/org/app1
which would matchgcr.io/org/app1:latest
orgcr.io/org/app1@sha256:...
or justgcr.io/org/app1
- e.g.