diff --git a/site/config.yaml b/site/config.yaml index 33bf45d15..a11f76bcd 100644 --- a/site/config.yaml +++ b/site/config.yaml @@ -43,15 +43,16 @@ params: name: kbld short_name: kbld root_link: /kbld/ - latest_docs_link: /kbld/docs/v0.36.0/ + latest_docs_link: /kbld/docs/v0.37.x/ github_url: https://github.com/carvel-dev/kbld search: true search_index_name: carvel-kbld search_api_key: a38560864c2e9128ae57d5734df438ff versioning: true - version_latest: v0.36.0 + version_latest: v0.37.x versions: - develop + - v0.37.x - v0.36.0 - v0.35.0 - v0.34.0 diff --git a/site/content/kbld/docs/v0.36.0/_index.md b/site/content/kbld/docs/v0.36.0/_index.md index 9bd58912c..80ac7aa7d 100644 --- a/site/content/kbld/docs/v0.36.0/_index.md +++ b/site/content/kbld/docs/v0.36.0/_index.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/] + title: "About kbld" toc: "false" cascade: diff --git a/site/content/kbld/docs/v0.36.0/auth.md b/site/content/kbld/docs/v0.36.0/auth.md index f1df9f1b5..95b47b7d6 100644 --- a/site/content/kbld/docs/v0.36.0/auth.md +++ b/site/content/kbld/docs/v0.36.0/auth.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/auth] + title: Authentication --- diff --git a/site/content/kbld/docs/v0.36.0/building.md b/site/content/kbld/docs/v0.36.0/building.md index afd16045c..897a5a9c5 100644 --- a/site/content/kbld/docs/v0.36.0/building.md +++ b/site/content/kbld/docs/v0.36.0/building.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/building] + title: Building images --- diff --git a/site/content/kbld/docs/v0.36.0/cnab-image-relocation.md b/site/content/kbld/docs/v0.36.0/cnab-image-relocation.md index 152de7a64..2c7b5a644 100644 --- a/site/content/kbld/docs/v0.36.0/cnab-image-relocation.md +++ b/site/content/kbld/docs/v0.36.0/cnab-image-relocation.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/cnab-image-relocation] + title: CNAB Image Maps --- diff --git a/site/content/kbld/docs/v0.36.0/config.md b/site/content/kbld/docs/v0.36.0/config.md index 4a07efd49..97422cd1c 100644 --- a/site/content/kbld/docs/v0.36.0/config.md +++ b/site/content/kbld/docs/v0.36.0/config.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/config] + title: Configuration --- diff --git a/site/content/kbld/docs/v0.36.0/install.md b/site/content/kbld/docs/v0.36.0/install.md index 4b15fb2bd..dd85f3937 100644 --- a/site/content/kbld/docs/v0.36.0/install.md +++ b/site/content/kbld/docs/v0.36.0/install.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/install] + title: Install --- diff --git a/site/content/kbld/docs/v0.36.0/packaging.md b/site/content/kbld/docs/v0.36.0/packaging.md index 95d65a0bd..0c2ca04bd 100644 --- a/site/content/kbld/docs/v0.36.0/packaging.md +++ b/site/content/kbld/docs/v0.36.0/packaging.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/packaging] + title: Packaging and Relocation --- diff --git a/site/content/kbld/docs/v0.36.0/resolving.md b/site/content/kbld/docs/v0.36.0/resolving.md index 97b932f9e..85728b9df 100644 --- a/site/content/kbld/docs/v0.36.0/resolving.md +++ b/site/content/kbld/docs/v0.36.0/resolving.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/resolving] + title: Resolving images --- diff --git a/site/content/kbld/docs/v0.36.0/security.md b/site/content/kbld/docs/v0.36.0/security.md index 0888a2254..437ba2873 100644 --- a/site/content/kbld/docs/v0.36.0/security.md +++ b/site/content/kbld/docs/v0.36.0/security.md @@ -1,5 +1,5 @@ --- -aliases: [/kbld/docs/latest/security] + title: Security --- diff --git a/site/content/kbld/docs/v0.37.x/_index.md b/site/content/kbld/docs/v0.37.x/_index.md new file mode 100644 index 000000000..b42ab7926 --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/_index.md @@ -0,0 +1,30 @@ +--- +aliases: [/kbld/docs/latest/] +title: "About kbld" +toc: "false" +cascade: + version: v0.37.x + toc: "true" + type: docs + layout: docs +--- + +`kbld` (pronounced: `kei·bild`) seamlessly incorporates image building and image pushing into your development and deployment workflows. + +Features: + +- Orchestrates image builds (delegates to tools like Docker, pack, kubectl-buildkit) and registry pushes +- Works with local Docker daemon and remote registries, for development and production cases +- Records metadata about image sources in annotation on Kubernetes resources (see examples below) +- Resolves image references to their digest (immutable) form +- Not specific to Kubernetes, but works really well with Kubernetes configuration files + +See [building and deploying simple Go application to Kubernetes example](/blog/deploying-apps-with-ytt-kbld-kapp/#building-container-images-locally) that uses kbld. + +## Why digest references? + +Docker images can be referenced by their name (`nginx`), name-tag pair (`nginx:1.14`), or a digest (`nginx@sha256:c398dc3f2...`). One can avoid potential deployment inconsistencies by using digest references as they are immutable, and therefore always points to an exact image. kbld helps Kubernetes users convert image references to their digest form to make sure exact image is used during deploys. + +## Blog posts + +- [Deploying Kubernetes Applications with ytt, kbld, and kapp](/blog/deploying-apps-with-ytt-kbld-kapp) diff --git a/site/content/kbld/docs/v0.37.x/auth.md b/site/content/kbld/docs/v0.37.x/auth.md new file mode 100644 index 000000000..f1df9f1b5 --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/auth.md @@ -0,0 +1,88 @@ +--- +aliases: [/kbld/docs/latest/auth] +title: Authentication +--- + +## Via Docker config + +Even though `kbld` commands use registry APIs directly, by default it uses credentials stored in `~/.docker/config.json` which are typically generated via `docker login` command. + +Example generated `~/.docker/config.json`: + +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "dXNlcjpwYXNzd29yZA==" + }, + }, + "HttpHeaders": { + "User-Agent": "Docker-Client/18.09.6 (darwin)" + } +} +``` + +where `dXNlcjpwYXNzd29yZA==` is `base64("username:password")`. + +## Via Environment Variables + +As of v0.23.0+, kbld can also use following environment variables: + +- `KBLD_REGISTRY_HOSTNAME` to specify registry hostname (e.g. gcr.io, docker.io) +- `KBLD_REGISTRY_USERNAME` to specify registry username +- `KBLD_REGISTRY_PASSWORD` to specify registry password + +Since you may need to provide multiple registry credentials, above environment variables multiple times with a suffix like so `KBLD_REGISTRY_HOSTNAME_0` (suffix can be 1+ alphanumeric characters). Use same suffix for hostname, username and password. + +Currently credentials provided via environment variables do not apply when building images with Docker. Continue using `docker login` to authenticate Docker daemon. + +## gcr.io + +- Create service account with "Storage Admin" for push access + - See [Permissions and Roles](https://cloud.google.com/container-registry/docs/access-control#permissions_and_roles) +- Download JSON service account key and place it somewhere on filesystem (e.g. `/tmp/key`) + - See [Advanced authentication](https://cloud.google.com/container-registry/docs/advanced-authentication#json_key_file) +- Run `cat /tmp/key | docker login -u _json_key --password-stdin https://gcr.io` to authenticate + +## AWS ECR + +- Create ECR repository +- Create IAM user with ECR policy that allows to read/write + - See [Amazon ECR Policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html) +- Run `aws configure` and specify access key ID, secret access key and region + - To install on Ubuntu, run `apt-get install pip3` and `pip3 install awscli` + - See [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) +- Run `eval $(aws ecr get-login --no-include-email)` to authenticate + - See [get-login command](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html) + +Example ECR policy from https://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ecr:GetAuthorizationToken", + "ecr:BatchCheckLayerAvailability", + "ecr:GetDownloadUrlForLayer", + "ecr:GetRepositoryPolicy", + "ecr:DescribeRepositories", + "ecr:ListImages", + "ecr:DescribeImages", + "ecr:BatchGetImage", + "ecr:InitiateLayerUpload", + "ecr:UploadLayerPart", + "ecr:CompleteLayerUpload", + "ecr:PutImage" + ], + "Resource": "*" + } + ] +} +``` + +## Harbor + +You may have to provide `--registry-ca-cert-path` flag with a path to a CA certificate file for Harbor Registry API. diff --git a/site/content/kbld/docs/v0.37.x/building.md b/site/content/kbld/docs/v0.37.x/building.md new file mode 100644 index 000000000..afd16045c --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/building.md @@ -0,0 +1,152 @@ +--- +aliases: [/kbld/docs/latest/building] +title: Building images +--- + +## Building images from source + +kbld can be used to orchestrate build tools such as [Docker](https://docs.docker.com/engine/reference/commandline/cli/) and [pack](https://github.com/buildpacks/pack) to build images from source and record resulting image reference in a YAML file. This is especially convenient during local development when working with one or more changing applications. + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: simple-app #! <-- unresolved image ref +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test2 +spec: + selector: + matchLabels: + app: kbld-test2 + template: + metadata: + labels: + app: kbld-test2 + spec: + containers: + - name: my-app + image: another-simple-app #! <-- unresolved image ref +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: simple-app + path: src/simple-app +- image: another-simple-app + path: src/another-simple-app +``` + +(See [Configuration](config.md) for more details about `Sources`.) + +Running above example via `kbld -f file.yml` will start two `docker build` processes and produce following output + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: kbld:1556053998479026000-simple-app #! <-- resolved image ref +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test2 +spec: + selector: + matchLabels: + app: kbld-test2 + template: + metadata: + labels: + app: kbld-test2 + spec: + containers: + - name: my-app + image: kbld:1556053998479039000-another-simple-app #! <--resolved image ref +``` + +Note that because we are using Docker daemon for local images and are not pushing them into a remote registry we cannot unfortunately use digest reference form (a limitation of Docker daemon); however, tags generated by kbld uniquely identify produced images. As soon as images are pushed to a remote registry, tags are converted into digest references. + +**Hint**: [Minikube](https://kubernetes.io/docs/setup/minikube/) comes with Docker daemon inside its VM. You can expose by running `eval $(minikube docker-env)` before executing kbld. + +## Pushing images + +As long as building tool has proper push access (run `docker login` for Docker), kbld can push out built images to specified repositories. Just add following configuration: + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +destinations: +- image: simple-app + newImage: docker.io/dkalinin/simple-app +- image: another-simple-app + newImage: docker.io/dkalinin/another-simple-app +``` + +With addition of above configuration, kbld will produce following YAML: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: index.docker.io/dkalinin/simple-app@sha256:f7988fb6c02e... #! <-- pushed image ref +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test2 +spec: + selector: + matchLabels: + app: kbld-test2 + template: + metadata: + labels: + app: kbld-test2 + spec: + containers: + - name: my-app + image: index.docker.io/dkalinin/another-simple-app@sha256:a7355fb1007e... #! <-- pushed image ref +``` diff --git a/site/content/kbld/docs/v0.37.x/cnab-image-relocation.md b/site/content/kbld/docs/v0.37.x/cnab-image-relocation.md new file mode 100644 index 000000000..152de7a64 --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/cnab-image-relocation.md @@ -0,0 +1,65 @@ +--- +aliases: [/kbld/docs/latest/cnab-image-relocation] +title: CNAB Image Maps +--- + +CNAB spec mentions [Image Relocation](https://github.com/cnabio/cnab-spec/blob/master/103-bundle-runtime.md#image-relocation) as part of bundle runtime. + +kbld supports applying `relocation-mapping.json` on top of YAML configuration via `kbld --image-map-file /cnab/app/relocation-mapping.json ...`. For example: + +/cnab/app/relocation-mapping.json: + +```json +{ + "gabrtv/microservice@sha256:cca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120687": "my.registry/microservice@sha256:cca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120687", + "technosophos/helloworld:0.1.0": "my.registry/helloworld:0.1.0" +} +``` + +and kbld input: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: gabrtv/microservice@sha256:cca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120687 + - name: my-app2 + image: technosophos/helloworld:0.1.0 +``` + +would result in: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: my.registry/microservice@sha256:cca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120687 + - name: my-app2 + image: my.registry/helloworld:0.1.0 +``` diff --git a/site/content/kbld/docs/v0.37.x/config.md b/site/content/kbld/docs/v0.37.x/config.md new file mode 100644 index 000000000..4a07efd49 --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/config.md @@ -0,0 +1,538 @@ +--- +aliases: [/kbld/docs/latest/config] +title: Configuration +--- + +## Overview + +Customize how `kbld`: +- searches for image references, +- resolves image names, +- builds images from source, and +- pushes built images to container registries. + +This is done by supplying one or more configuration files. These files are in the Kubernetes resource format (i.e. has `apiVersion` and `kind`). `kbld` consumes and removes such files from its output. + +A `kbld` configuration file is structured like so: + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +minimumRequiredVersion: 0.31.0 + +searchRules: ... +overrides: ... +sources: ... +destinations: ... +``` + +where: +- `minimumRequiredVersion` (optional; semver) — specifies the minimum required version of `kbld` needed to work with this configuration. + +and any combination of the follow four sections: +- `searchRules` — a list of [Search Rules](#search-rules) that `kbld` follows to locate container image references within the input files. +- `overrides` — a list of [Overrides](#overrides) that `kbld` applies to found container image references before it attempts to resolve or build the actual image. +- `sources` — a list of [Sources](#sources), each of which describes where to find the source that makes up the contents of a given image _and_ which build tool to use to construct it. +- `destinations` — a list of [Destinations](#destinations), each of which describes where (i.e. to which container registry) to publish a given image. + +_(Note: prior to v0.28.0, different types of configuration were supplied in different `kind` of files: `kind: Sources`, `kind: ImageDestinations`, `kind: ImageOverrides`, `kind: ImageKeys`. Since v0.28.0, all such configuration can be specified in one kind of file: `kind: Config`; this is recommended.)_ + +--- +## Search Rules + +`kbld` scans input files for references to container images. Search rules describe how `kbld` should identify those references and how to process them. + +A search rule has two parts: +- conditions for matching (either by key, by value, or both), and +- a strategy for how to parse and update a matched item. + +A search rule is expressed like this: + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +searchRules: +- keyMatcher: ... + valueMatcher: ... + updateStrategy: ... +``` + +where a rule consists of one or both of the following... +- `keyMatcher` a [Key Matcher](#key-matcher) — identifies container image references based on an item's key. +- `valueMatcher` a [Value Matcher](#value-matcher) — identifies container image references based on an item's value. + +_(If both are specified, their results are "and'ed" together.)_ + +...and optionally, +- `updateStrategy` an [Update Strategy](#update-strategy) — what `kbld` should do with the matched container image reference. + +**Multiple Matching search rules** \ +If multiple search rules match the same item, the rule that was defined first is applied. + +Note: `kbld` includes its own [Default Search Rules](#default-search-rules) + +### Key Matcher + +Specifies whether a given key indicates that its corresponding value is an image reference. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +searchRules: +- keyMatcher: + name: + path: +``` + +where: +- `name` (string) specifies the key name (e.g. `sidecarImage`) +- `path` (array) specifies key path from the root of the YAML document.\ + Each path part can be one of: + - the literal key name. (e.g. `[data, sidecarImage]` maps to `data.sidecarImage`) + - an array indexing tactic (choose one): + - `index:` (int) — search one element in the array at the (zero-based) index given. \ + (example: `[spec, template, spec, containers, {index: 0}, image]`) + - `allIndexes:` (bool) — search all elements in the array. \ + (example: `[spec, images, {allIndexes: true}]`) + +### Value Matcher + +Specifies whether a given value contains an image reference. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +searchRules: +- valueMatcher: + ( image | imageRepo ): +``` +where (choose one): +- `image` (string) value to match exactly +- `imageRepo` (string) of values in the format (`[registry]repo[:tag]\[@sha256:...]`), the value of the `repo` portion. \ + (example: `imageRepo: gcr.io/project/app` \ + matches `gcr.io/projects/app:v1.1` and `gcr.io/projects/app@sha256:f33e111...` \ + but not `gcr.io/projects/app_v1`) + +### Update Strategy + +Given a container image reference identified by one or more matchers, an Update Strategy describes how to update that value (v0.21.0+). + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +searchRules: +- ( keyMatcher | valueMatcher ): ... + updateStrategy: + yaml: + searchRules: ... + json: + searchRules: ... + none: {} + entireValue: {} +``` + +where (choose one): +- `yaml` parses YAML and identifies image refs by specified search rules + - `searchRules` — one or more [Search Rules](#search-rules), scoped to the parsed content. +- `json` parses JSON and identifies image refs by specified search rules + - `searchRules` — one or more [Search Rules](#search-rules), scoped to the parsed content. +- `none` (empty) excludes value from processing (v0.22.0+) +- `entireValue` (empty; default) uses the exact value as the image reference. + +#### Example for `updateStrategy` that parses YAML + +```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 +``` + +Note that in the `ConfigMap`, that `/data/data.yml` holds a multi-line string. That string happens to also be in YAML format. When _that_ YAML is parsed, the `image` key holds a container image reference. + + +### Default Search Rules + +After custom search rules have been processed, `kbld` appends the following search rule: + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +searchRules: +- keyMatcher: + name: image + updateStrategy: + entireValue: {} +``` + +--- +## Overrides + +After `kbld` searches for container image references, it applies a set of "overrides" which effectively rewrite those references. It does this _before_ attempting to build the corresponding image or resolve it to a digest reference. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +overrides: +- image: + newImage: + preresolved: + tagSelection: ... + platformSelection: ... +``` + +where: +- `image` (required; string) exact value found while searching for container image references. +- `newImage` (required; string) value with which to replace/override. This ought to be an image reference in the format `[registry]repo[:tag]\[@sha256:...]`. \ + Examples: + - `nginx` + - `quay.io/bitnami/nginx` + - `nginx:1.21.1` + - `nginx@sha256:a05b0cd...` + - `index.docker.io/library/nginx@sha256:a05b0cd...` +- `preresolved` (optional; bool) specifies if `newImage` should be used as is (rather than be [re]resolved to a digest reference). +- `tagSelection` (optional; [VersionSelection](/vendir/docs/latest/versions/#versionselection-type)) when `newImage` _is_ being resolved, specifies how to select the tag part of the reference before resolving to a digest reference. (Available as of v0.28.0+) + - In this case, `newImage` must not have a tag or digest part (e.g. `gcr.io/my-corp/app`). +- `platformSelection` (optional; map) specifies a way to select particular image within an image index. Available in 0.35.0+. + - `architecture` (string) selects via CPU architecture. ex: `amd64` + - `os` (string) selects via OS name. ex: `linux` + - `os.version` (string) selects via OS version (commonly used for Windows). ex: `10.0.10586` + - `os.features` (string array) selects via OS features (commonly used for Windows). ex: `["win32k"]` + - `variant` (string) selects via architecture variant. ex: `armv6l` + - `features` (string array) selects via architecture features. ex: `["sse4"]` + +**Example: Static Rewrite** + +With the following configuration, any container image reference of the value `"unknown"` will get rewritten to `"docker.io/library/nginx:1.14.2"` before being resolved to a digest reference. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +overrides: +- image: unknown + newImage: docker.io/library/nginx:1.14.2 +``` + +**Example: Preresolved** + +This configuration replaces references of `"unknown"` with `"docker.io/library/nginx:1.14.2"`. It short-circuits any building, resolution, or even connecting to a registry to obtain metadata about the image reference. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +overrides: +- image: unknown + newImage: docker.io/library/nginx:1.14.2 + preresolved: true +``` + +**Example: Dynamic Tag Selection** + +This configuration first rewrites references of `"unknown"` with `"docker.io/library/nginx"`. It then queries the registry to locate the latest version just prior to 1.15.0 (which turns out to be 1.14.2). + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +overrides: +- image: unknown + newImage: docker.io/library/nginx + tagSelection: + semver: + constraints: "<1.15.0" +``` + + +--- +## Sources + +Rather than resolve an image reference, `kbld` can build the image from source. More precisely, `kbld` can be configured to use one of the many image building tools it integrates with to construct the image from source. For an overview, see [Building Images](building.md). + +Such integration is enabled by configuring a "Source": + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: image1 + path: src/ + ( docker | pack | kubectlBuildkit | ko | bazel ): ... +``` + +where: +- `image` (required; string) exact value found while searching for container image references. +- `path` (required; string) filesystem path to the source for the to-be-built image. + This path also acts as the container file context; therefore, any paths in the + container file (when one is present) must be relative to the value of the field + `path`. +- a builder configuration (optional; choose one) — name/configure a specific image builder tool: + - `docker:` (default) use [Docker](#docker) or [Docker buildx](#docker-buildx) to build from source. + - `pack:` use [Pack](#pack) to build the image via buildpacks from source. + - `kubectlBuildkit:` use [Buildkit CLI for kubectl](#buildkit-cli-for-kubectl) to build the image via a Kubernetes cluster form source. + - `ko:` use [ko](#ko) to build the image from Go source. + - `bazel:` use [Bazel](#bazel) to build the image via Bazel Container Image Rules. + + +### Docker + +Using this integration requires: +- Docker — https://docs.docker.com/get-docker + +The [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) must be on the `$PATH`. + +To configure an image to be built via Docker, include a `docker:`-flavored [Source](#sources): +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: image1 + path: src/ + docker: + build: + target: some-target + pull: true + noCache: true + file: hack/Dockerfile.dev + buildkit: true + rawOptions: ["--squash", "--build-arg", "ARG_IN_DOCKERFILE=value"] +``` +where (all options are optional): +- `target` (string): the target build stage to build (no default) +- `pull` (bool): always attempt to pull a newer version of the image (default is false) +- `noCache` (bool): do not use cache when building the image (default is false) +- `file` (string): name of the Dockerfile (default is Dockerfile) +- `buildkit` (bool): enable [Builtkit](https://docs.docker.com/develop/develop-images/build_enhancements) for this build. (Also see [Docker buildx](#docker-buildx) integration.) +- `rawOptions` ([]string): Refer to [`docker build` reference](https://docs.docker.com/engine/reference/commandline/build/) for all available options + +### Docker buildx + +Available as of v0.34.0+ + +Using this integration requires: +- Docker - https://docs.docker.com/get-docker +- Docker buildx plugin + +The [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) must be on the `$PATH`. + +To configure an image to be built via Docker buildx, include a `docker:`-flavored [Source](#sources): +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: image1 + path: src/ + docker: + buildx: + target: some-target + pull: true + noCache: true + file: hack/Dockerfile.dev + rawOptions: ["--platform=linux/amd64,linux/arm64,linux/arm/v7"] +``` +where (all options are optional): +- `target` (string): the target build stage to build (no default) +- `pull` (bool): always attempt to pull a newer version of the image (default is false) +- `noCache` (bool): do not use cache when building the image (default is false) +- `file` (string): name of the Dockerfile (default is Dockerfile) +- `rawOptions` ([]string): Refer to [`docker buildx build` reference](https://docs.docker.com/engine/reference/commandline/buildx_build/) for all available options + +### Pack + +Using this integration requires: +- Docker — https://docs.docker.com/get-docker +- Pack — https://buildpacks.io/docs/tools/pack/ + +The [Pack CLI](https://buildpacks.io/docs/tools/pack/cli/pack/) must be on the `$PATH`. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: image1 + path: src/ + pack: + build: + builder: cloudfoundry/cnb:bionic +``` +where (all options are optional): +- `builder` (string): Set builder image (required) +- `buildpacks` ([]string): Set list of buildpacks to be used (no default) +- `clearCache` (bool): Clear cache before building image (default is false) +- `rawOptions` ([]string): Refer to `pack build -h` for all available flags + +### BuildKit CLI for kubectl + +Available as of v0.28.0+ + +Using this integration requires: +- `kubectl` — https://kubernetes.io/docs/tasks/tools/ +- Buildkit for kubectl — https://github.com/vmware-tanzu/buildkit-cli-for-kubectl#installing-the-tarball \ + _(`kbld` v0.28.0+ is tested with buildkit-for-kubectl v0.1.0, but may work well with other versions.)_ + +The [`kubectl` CLI](https://kubernetes.io/docs/reference/kubectl/kubectl/) must be on the `$PATH`. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: image1 + path: src/ + kubectlBuildkit: + build: + target: "some-target" + pull: true + noCache: true + file: "hack/Dockefile.dev" + rawOptions: ["--platform=..."] +``` + +where (all options are optional): +- `target` (string): Set the target build stage to build (no default) +- `pull` (bool): Always attempt to pull a newer version of the image (default is false) +- `noCache` (bool): Do not use cache when building the image (default is false) +- `file` (string): Name of the Dockerfile (default is Dockerfile) +- `rawOptions` ([]string): Refer to `kubectl buildkit build -h` for all available options + +#### Authenticating to Registry for Pushing Images + +To provide registry credentials to the builder, create a Kubernetes `docker-registry` 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](https://github.com/vmware-tanzu/buildkit-cli-for-kubectl). + +### ko + +Available as of v0.28.0+ + +Using this integration requires: +- `ko` — https://github.com/google/ko \ + (`kbld` v0.28.0+ is tested with `ko` v0.8.0, but may work well with other versions.) + +The `ko` CLI must be on the `$PATH`. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: image1 + path: ./src/ + ko: + build: + rawOptions: ["--disable-optimizations"] +``` + +where: +- `rawOptions` (optional; []string): Refer to `ko publish -h` for all available options. + +By default `kbld` provides the `--local` flag + +### Bazel + +Available as of v0.31.0+ + +Using this integration requires: +- Docker — https://docs.docker.com/get-docker +- Bazel — https://docs.bazel.build/versions/main/install.html \ + _(`kbld` v0.31.0+ is tested with Bazel v4.2.0 and [Container Image Rules](https://github.com/bazelbuild/rules_docker/tree/v0.18.0) v0.18.0, but may work well with other versions.)_ + +The `bazel` CLI must be on the `$PATH`. + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: + - image: image1 + path: ./src/ + bazel: + run: + target: :image1-go-container + rawOptions: ["--platforms=@io_bazel_rules_go//go/toolchain:linux_amd64"] +``` + +where: +- `target` (string): bazel build target; when passed to `bazel run` will build and load the desired image. +- `rawOptions` ([]string): Refer to https://docs.bazel.build/versions/main/user-manual.html for all available options. + +#### Using Language-specific Container Rules + +This integration invokes the `bazel run` command (as opposed to the `bazel build` command). + +Typically, when configuring the Bazel integration with `kbld`, the specified target is one of the [Container Image Rules](https://github.com/bazelbuild/rules_docker/tree/master#bazel-container-image-rules). + +With such rules, the `bazel build` command _produces_ the artifacts that make up all images described in the `BUILD`, but stops short of loading any image into the Docker daemon. In order for an image to be pushed to a registry (i.e. published), it must first be loaded into the local Docker daemon. The `bazel run` command takes that additional step to execute the script that performs that `docker load` _for the named target, only_. + +For so-called [`lang_image` rules](https://github.com/bazelbuild/rules_docker/tree/master#language-rules), this also results in launching a container from that image (i.e. `docker run` the built image). For our purposes, this is undesirable because it effectively halts the build. + +To skip this that launching step, append the args `-- --norun` via the `rawOptions:` key: + +```yaml +... + bazel: + run: + target: :image1-go-container + rawOptions: ["--", "--norun"] +``` + +See also https://github.com/bazelbuild/rules_docker#using-with-docker-locally. + +--- +## Destinations + +Once `kbld` has processed the found container image references (either resolved or built them), it can publish those images to a different registry (on an image-by-image basis). + +Pushing images to registries through this configuration requires: +- Docker — https://docs.docker.com/get-docker + +(In the case where all published images are built through [BuildKit CLI for kubectl](#buildkit-cli-for-kubectl), Docker is not required; publishing happens from within the Kubernetes cluster). + +Do this by configuring one or more "destinations": + +```yaml +--- +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +destinations: +- image: adservice + newImage: docker.io/dkalinin/microservices-demo-adservice + tags: [latest, tag2] +``` + +where: +- `image` (required; string) exact value found while searching for container image references. +- `newImage` (required; string) image destination (i.e. fully qualified registry location for the image) +- `tags` (optional; array of strings) tags to apply to pushed images (v0.26.0+) diff --git a/site/content/kbld/docs/v0.37.x/install.md b/site/content/kbld/docs/v0.37.x/install.md new file mode 100644 index 000000000..4b15fb2bd --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/install.md @@ -0,0 +1,58 @@ +--- +aliases: [/kbld/docs/latest/install] +title: Install +--- + +## Via script (macOS or Linux) + +(Note that `install.sh` script installs other Carvel tools as well.) + +Install binaries into specific directory: + +```bash +$ mkdir local-bin/ +$ curl -L https://carvel.dev/install.sh | K14SIO_INSTALL_BIN_DIR=local-bin bash + +$ export PATH=$PWD/local-bin/:$PATH +$ kbld version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ kbld version +``` + +## Via Homebrew (macOS or Linux) + +Based on [github.com/vmware-tanzu/homebrew-carvel](https://github.com/vmware-tanzu/homebrew-carvel). + +```bash +$ brew tap vmware-tanzu/carvel +$ brew install kbld +$ kbld version +``` + +## Specific version from a GitHub release + +To download, click on one of the assets in a [chosen GitHub release](https://github.com/vmware-tanzu/carvel-kbld/releases), for example for 'kbld-darwin-amd64'. + +```bash +# **Compare binary checksum** against what's specified in the release notes +# (if checksums do not match, binary was not successfully downloaded) +$ shasum -a 256 ~/Downloads/kbld-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/kbld-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/kbld-darwin-amd64 /usr/local/bin/kbld + +# Make binary executable +$ chmod +x /usr/local/bin/kbld + +# Check its version +$ kbld version +``` diff --git a/site/content/kbld/docs/v0.37.x/packaging.md b/site/content/kbld/docs/v0.37.x/packaging.md new file mode 100644 index 000000000..95d65a0bd --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/packaging.md @@ -0,0 +1,190 @@ +--- +aliases: [/kbld/docs/latest/packaging] +title: Packaging and Relocation +--- + +### Deprecation +This functionality was deprecated in `kbld` starting from version v0.30.0 and will be removed soon. +These features are now available on [imgpkg](https://carvel.dev/imgpkg). + +## Overview + +kbld provides a way to relocate (i.e. copy) images between multiple registries. Two approaches are available: + +- `kbld relocate` (available v0.23.0+) allows to efficiently copy images between registries as long as running `relocate` command has connectivity to both registries. +- `kbld package` and `kbld unpackage` allows to export images into a single tarball, and later import them from given tarball into a different (or same) registry. This approach does _not_ require connectivity to source registry during the `pkg unpackage` time. + +Use cases: + +- packaging applications for fully offline environments with a private registry +- copying images from one registry to another +- backing up images + +There are two approaches to do this: + +- With lock file (recommended) +- Directly against configuration + +## With lock file + +For example, to package referenced images into a single tarball: + +1. Produce lock file for referenced images in configuration + + ```bash + $ cat /tmp/manifest + images: + - image: nginx + - image: haproxy + + $ kbld -f /tmp/manifest --lock-output /tmp/manifest.lock + ... + + $ cat /tmp/manifest.lock + apiVersion: kbld.k14s.io/v1alpha1 + kind: Config + minimumRequiredVersion: 0.21.0 + overrides: + - image: haproxy + newImage: index.docker.io/library/haproxy@sha256:e6f9faf0c2a0cf2d2d5a53307351fa896d90ca9ccd62817c24026460d97dde92 + preresolved: true + - image: nginx + newImage: index.docker.io/library/nginx@sha256:86ae264c3f4acb99b2dee4d0098c40cb8c46dcf9e1148f05d3a51c4df6758c12 + preresolved: true + ``` + +1. Feed `/tmp/manifest.lock` to `kbld pkg` command to download images and pack them into a single tarball `/tmp/packaged-images.tar`: + + ```bash + $ kbld pkg -f /tmp/manifest.lock --output /tmp/packaged-images.tar + package | exporting 2 images... + package | will export index.docker.io/library/nginx@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + package | will export index.docker.io/library/haproxy@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + package | exported 2 images + + $ ls -lah /tmp/packaged-images.tar + -rw-r--r-- 1 root root 314M May 3 18:59 /tmp/packaged-images.tar + ``` + + Note: Depending on your internet connection this may be slow. + +To import packaged images from a tarball: + +1. Specify new repository location `docker.io/dkalinin/app1` and provide tarball: + + ```bash + $ kbld unpkg -f /tmp/manifest.lock --input /tmp/packaged-images.tar --repository docker.io/dkalinin/app1 --lock-output /tmp/manifest.lock.copied + unpackage | importing 2 images... + unpackage | importing index.docker.io/library/nginx@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c -> docker.io/dkalinin/app1@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c... + unpackage | importing index.docker.io/library/haproxy@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 -> docker.io/dkalinin/app1@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5... + unpackage | imported 2 images + ``` + + Images will be imported under a single new repository `docker.io/dkalinin/app1`. **You are guaranteed that images are exactly same as they are referenced by the same digests in produced YAML configuration (though under a different repository name)**. + +1. **Alternatively**, using `relocate` command against a lock file: + + ```bash + $ kbld relocate -f /tmp/manifest.lock --repository docker.io/dkalinin/app1 --lock-output /tmp/manifest.lock.copied + relocate | ... + ``` + +1. Use newely generated lock file with configuration to get updated results + + ```bash + $ kbld -f /tmp/manifest -f /tmp/manifest.lock.copied + images: + - image: docker.io/dkalinin/app1@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + - image: docker.io/dkalinin/app1@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + ``` + +--- +## Directly against configuration + +For example, to package referenced images into a single tarball: + +1. First make sure all image references are in their digest form + + ```bash + $ cat /tmp/manifest + images: + - image: nginx + - image: haproxy + + $ kbld -f /tmp/manifest > /tmp/resolved-manifest + resolve | final: haproxy -> index.docker.io/library/haproxy@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + resolve | final: nginx -> index.docker.io/library/nginx@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + + $ cat /tmp/resolved-manifest + images: + - image: index.docker.io/library/nginx@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + - image: index.docker.io/library/haproxy@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + ``` + +1. Feed `/tmp/resolved-manifest` to `kbld pkg` command to download images and pack them into a single tarball `/tmp/packaged-images.tar`: + + ```bash + $ kbld pkg -f /tmp/resolved-manifest --output /tmp/packaged-images.tar + package | exporting 2 images... + package | will export index.docker.io/library/nginx@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + package | will export index.docker.io/library/haproxy@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + package | exported 2 images + + $ ls -lah /tmp/packaged-images.tar + -rw-r--r-- 1 root root 314M May 3 18:59 /tmp/packaged-images.tar + ``` + + Note: Depending on your internet connection this may be slow. + +To import packaged images from a tarball: + +1. Specify new repository location `docker.io/dkalinin/app1` and provide tarball: + + ```bash + $ kbld unpkg -f /tmp/resolved-manifest --input /tmp/packaged-images.tar --repository docker.io/dkalinin/app1 + unpackage | importing 2 images... + unpackage | importing index.docker.io/library/nginx@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c -> docker.io/dkalinin/app1@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c... + unpackage | importing index.docker.io/library/haproxy@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 -> docker.io/dkalinin/app1@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5... + unpackage | imported 2 images + images: + - image: docker.io/dkalinin/app1@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + - image: docker.io/dkalinin/app1@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + ``` + + Images will be imported under a single new repository `docker.io/dkalinin/app1`. **You are guaranteed that images are exactly same as they are referenced by the same digests in produced YAML configuration (though under a different repository name)**. + +1. **Alternatively**, using `relocate` command: + + ```bash + $ kbld relocate -f /tmp/resolved-manifest --repository docker.io/dkalinin/app1 + relocate | ... + images: + - image: docker.io/dkalinin/app1@sha256:e71b1bf4281f25533cf15e6e5f9be4dac74d2328152edf7ecde23abc54e16c1c + - image: docker.io/dkalinin/app1@sha256:6dae9c8674e2e5f418c3dd040041a05f6b490597315139c0bcacadf65a46cfd5 + ``` + +--- +## Authentication + +See general authentication steps in [Authentication doc](auth.md). + +## Using with gcr.io + +- Run `kbld unpkg -f /tmp/resolved-manifest --input /tmp/packaged-images.tar --repository gcr.io/{project-id}/app1` to import images (e.g. project id is `dkalinin`) + +## Using with AWS ECR + +**Note**: AWS ECR does not support manifest list media types from Docker Registry v2 API. Manifest lists are used for images that are built against multiple architectures and platforms and are referenced through a single digest or tag. Most user-built images do not use manifest lists (as it's a single image); however, common Docker Hub library images are represented by manifest lists and will fail upon import into AWS ECR. You will see following error: `Writing image index: Retried 5 times: uploading manifest2: UNSUPPORTED: Invalid parameter at 'imageTag' failed to satisfy constraint: 'must satisfy regular expression '[a-zA-Z0-9-_.]+'`. Related [AWS feature request](https://forums.aws.amazon.com/thread.jspa?threadID=292294)). + +- Run `kbld unpkg -f /tmp/resolved-manifest --input /tmp/packaged-images.tar --repository {uri}` to import images (e.g. uri is `823869848626.dkr.ecr.us-east-1.amazonaws.com/k14s/kbld-test`) + +## Using with Harbor + +You may have to provide `--registry-ca-cert-path` flag with a path to a CA certificate file for Harbor Registry API. + +## Notes + +- Produced tarball does not have duplicate image layers, as they are named by their digest (see `tar tvf /tmp/packaged-images.tar`). +- If digest reference points to an image index, all children (images and other image indexes) will be included in the export. Saving only a portion of contents would of course change the digest. +- Only Docker v2 and OCI images and indexes are supported. Docker v1 format is not supported, hence, not all images out there could be exported and only registries supporting v2 format can be used for imports. +- Images that once were in different repositories are imported into the same repository to make it easier to manage them in bulk. diff --git a/site/content/kbld/docs/v0.37.x/resolving.md b/site/content/kbld/docs/v0.37.x/resolving.md new file mode 100644 index 000000000..97b932f9e --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/resolving.md @@ -0,0 +1,202 @@ +--- +aliases: [/kbld/docs/latest/resolving] +title: Resolving images +--- + +## Resolving image references to digests + +kbld looks for `image` keys within YAML documents and tries to resolve image reference to its full digest form. + +For example, following + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: nginx:1.14.2 + #! ^-- image reference in its tag form +``` + +will be transformed to + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: index.docker.io/library/nginx@sha256:f7988fb6c02e0ce69257d9bd9cf37ae20a60f1df7563c3a2a6abe24160306b8d + #! ^-- resolved image reference to its digest form +``` + +via + +```bash +kbld -f file.yml +``` + +Few other variations + +```bash +pbpaste | kbld -f- +kbld -f . +kbld -f file.yml -f config2.yml +``` + +### Resolving image references to digests + +Available in 0.35.0+ + +Use `--platform` flag to resolve image indexes (a type of OCI artifact) to their particular child image based on a platform (architecture, OS, OS variant) associated with an image. If platform flag is specified and image is not an image index, no special resolution is performed. + +Examples: + +- `kbld -f ... --platform linux/386` selects based on an OS (`linux`) and an architecture (`386`) +- `kbld -f ... --platform linux/arm/v6` selects based on an OS (`linux`), architecture (`arm`) and variant (`v6`) + +### Generating resolution `imgpkg` lock output + +Available in 0.28.0+ + +Using the `--imgpkg-lock-output` flag, users are able to create an [ImagesLock](https://github.com/vmware-tanzu/carvel-imgpkg/blob/develop/docs/resources.md#imageslock) file that can be used as input for the packaging and distribution tool: [`imgpkg`](https://github.com/vmware-tanzu/carvel-imgpkg) + +For example, the command `kbld -f input.yml --imgpkg-lock-output /tmp/imgpkg.lock.yml` with `input.yml`: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: nginx:1.14.2 + #! ^-- image reference in its tag form +``` + +will produce `/tmp/imgpkg.lock.yml`: + +```yaml +apiVersion: imgpkg.carvel.dev/v1alpha1 +kind: ImagesLock +images: +- image: index.docker.io/library/nginx@sha256:f7988fb6c02e0ce69257d9bd9cf37ae20a60f1df7563c3a2a6abe24160306b8d + annotations: + kbld.carvel.dev/id: nginx:1.14.2 +``` + +An ImagesLock can be included with configuration via `-f` to produce same resolved configuration, for example, `kbld -f input.yml -f /tmp/imgpkg.lock.yml` produces: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: index.docker.io/library/nginx@sha256:f7988fb6c02e0ce69257d9bd9cf37ae20a60f1df7563c3a2a6abe24160306b8d +``` + +### Generating resolution lock output + +In some cases recording resolution results may be useful. To do so add `--lock-output /path-to-file` to the `kbld` command. + +For example, command `kbld -f input.yml --lock-output /tmp/kbld.lock.yml` with `input.yml`: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: nginx:1.14.2 + #! ^-- image reference in its tag form +``` + +will produce `/tmp/kbld.lock.yml`: + +```yaml +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +minimumRequiredVersion: 0.17.0 +overrides: +- image: nginx:1.14.2 + newImage: index.docker.io/library/nginx@sha256:f7988fb6c02e0ce69257d9bd9cf37ae20a60f1df7563c3a2a6abe24160306b8d + preresolved: true +``` + +Lock content can be included with configuration via `-f` to produce same resolved configuration, for example, `kbld -f input.yml -f /tmp/kbld.lock.yml` produces: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kbld-test1 +spec: + selector: + matchLabels: + app: kbld-test1 + template: + metadata: + labels: + app: kbld-test1 + spec: + containers: + - name: my-app + image: index.docker.io/library/nginx@sha256:f7988fb6c02e0ce69257d9bd9cf37ae20a60f1df7563c3a2a6abe24160306b8d +``` diff --git a/site/content/kbld/docs/v0.37.x/security.md b/site/content/kbld/docs/v0.37.x/security.md new file mode 100644 index 000000000..0888a2254 --- /dev/null +++ b/site/content/kbld/docs/v0.37.x/security.md @@ -0,0 +1,8 @@ +--- +aliases: [/kbld/docs/latest/security] +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `kbld`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). diff --git a/site/data/kbld/docs/kbld-v0-37-x-toc.yml b/site/data/kbld/docs/kbld-v0-37-x-toc.yml new file mode 100644 index 000000000..39a840900 --- /dev/null +++ b/site/data/kbld/docs/kbld-v0-37-x-toc.yml @@ -0,0 +1,33 @@ +toc: + - title: Introduction + subfolderitems: + - page: About kbld + url: / + - page: Install + url: /install + - title: Usage + subfolderitems: + - page: Resolving images + url: /resolving + - page: Building images + url: /building + - page: Packaging & Relocation + url: /packaging + - page: CNAB Image Mappings + url: /cnab-image-relocation + - title: Reference + subfolderitems: + - page: Configuration + url: /config + - page: Authentication + url: /auth + - title: FAQ + subfolderitems: + - page: Code of Conduct + shared_url: /code-of-conduct + - page: Contributing + shared_url: /contributing + - page: Carvel Development Guidelines + shared_url: /development_guidelines + - page: Security + shared_url: /security-policy diff --git a/site/data/kbld/docs/toc-mapping.yml b/site/data/kbld/docs/toc-mapping.yml index 20dcf6d27..a0565e118 100644 --- a/site/data/kbld/docs/toc-mapping.yml +++ b/site/data/kbld/docs/toc-mapping.yml @@ -4,3 +4,4 @@ v0.33.0: kbld-v0-33-0-toc v0.34.0: kbld-v0-34-0-toc v0.35.0: kbld-v0-35-0-toc v0.36.0: kbld-v0-36-0-toc +v0.37.x: kbld-v0-37-x-toc