{"id":15033519,"url":"https://github.com/googlecontainertools/kaniko","last_synced_at":"2025-05-12T16:12:43.494Z","repository":{"id":37270486,"uuid":"119419195","full_name":"GoogleContainerTools/kaniko","owner":"GoogleContainerTools","description":"Build Container Images In Kubernetes","archived":false,"fork":false,"pushed_at":"2025-05-05T02:24:08.000Z","size":63440,"stargazers_count":15488,"open_issues_count":756,"forks_count":1465,"subscribers_count":142,"default_branch":"main","last_synced_at":"2025-05-05T14:10:03.669Z","etag":null,"topics":["containers","developer-tools","docker","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleContainerTools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-29T17:53:54.000Z","updated_at":"2025-05-05T14:09:49.000Z","dependencies_parsed_at":"2023-02-19T03:46:00.986Z","dependency_job_id":"916e4990-4b9f-45df-b242-1e109fca715f","html_url":"https://github.com/GoogleContainerTools/kaniko","commit_stats":{"total_commits":1707,"total_committers":325,"mean_commits":5.252307692307692,"dds":0.8224956063268893,"last_synced_commit":"942fbe65e8d9186a85e6fb6c2e303b32457d7e93"},"previous_names":["googlecloudplatform/kaniko"],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleContainerTools%2Fkaniko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleContainerTools%2Fkaniko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleContainerTools%2Fkaniko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleContainerTools%2Fkaniko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleContainerTools","download_url":"https://codeload.github.com/GoogleContainerTools/kaniko/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253774007,"owners_count":21962198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","developer-tools","docker","kubernetes"],"created_at":"2024-09-24T20:21:33.273Z","updated_at":"2025-05-12T16:12:43.446Z","avatar_url":"https://github.com/GoogleContainerTools.png","language":"Go","readme":"# kaniko - Build Images In Kubernetes\n\n## 🚨NOTE: kaniko is not an officially supported Google product🚨\n\n[![Unit tests](https://github.com/GoogleContainerTools/kaniko/actions/workflows/unit-tests.yaml/badge.svg)](https://github.com/GoogleContainerTools/kaniko/actions/workflows/unit-tests.yaml)\n[![Integration tests](https://github.com/GoogleContainerTools/kaniko/actions/workflows/integration-tests.yaml/badge.svg)](https://github.com/GoogleContainerTools/kaniko/actions/workflows/integration-tests.yaml)\n[![Build images](https://github.com/GoogleContainerTools/kaniko/actions/workflows/images.yaml/badge.svg)](https://github.com/GoogleContainerTools/kaniko/actions/workflows/images.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/GoogleContainerTools/kaniko)](https://goreportcard.com/report/github.com/GoogleContainerTools/kaniko)\n\n![kaniko logo](logo/Kaniko-Logo.png)\n\nkaniko is a tool to build container images from a Dockerfile, inside a container\nor Kubernetes cluster.\n\nkaniko doesn't depend on a Docker daemon and executes each command within a\nDockerfile completely in userspace. This enables building container images in\nenvironments that can't easily or securely run a Docker daemon, such as a\nstandard Kubernetes cluster.\n\nkaniko is meant to be run as an image: `gcr.io/kaniko-project/executor`. We do\n**not** recommend running the kaniko executor binary in another image, as it\nmight not work as you expect - see [Known Issues](#known-issues).\n\nWe'd love to hear from you! Join us on\n[#kaniko Kubernetes Slack](https://kubernetes.slack.com/messages/CQDCHGX7Y/)\n\n:mega: **Please fill out our\n[quick 5-question survey](https://forms.gle/HhZGEM33x4FUz9Qa6)** so that we can\nlearn how satisfied you are with kaniko, and what improvements we should make.\nThank you! :dancers:\n\n_If you are interested in contributing to kaniko, see\n[DEVELOPMENT.md](DEVELOPMENT.md) and [CONTRIBUTING.md](CONTRIBUTING.md)._\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n**Table of Contents** _generated with\n[DocToc](https://github.com/thlorenz/doctoc)_\n\n- [kaniko - Build Images In Kubernetes](#kaniko---build-images-in-kubernetes)\n  - [🚨NOTE: kaniko is not an officially supported Google product🚨](#note-kaniko-is-not-an-officially-supported-google-product)\n  - [Community](#community)\n  - [How does kaniko work?](#how-does-kaniko-work)\n  - [Known Issues](#known-issues)\n  - [Demo](#demo)\n  - [Tutorial](#tutorial)\n  - [Using kaniko](#using-kaniko)\n    - [kaniko Build Contexts](#kaniko-build-contexts)\n    - [Using Azure Blob Storage](#using-azure-blob-storage)\n    - [Using Private Git Repository](#using-private-git-repository)\n    - [Using Standard Input](#using-standard-input)\n    - [Running kaniko](#running-kaniko)\n      - [Running kaniko in a Kubernetes cluster](#running-kaniko-in-a-kubernetes-cluster)\n        - [Kubernetes secret](#kubernetes-secret)\n      - [Running kaniko in gVisor](#running-kaniko-in-gvisor)\n      - [Running kaniko in Google Cloud Build](#running-kaniko-in-google-cloud-build)\n      - [Running kaniko in Docker](#running-kaniko-in-docker)\n    - [Caching](#caching)\n      - [Caching Layers](#caching-layers)\n      - [Caching Base Images](#caching-base-images)\n    - [Pushing to Different Registries](#pushing-to-different-registries)\n      - [Pushing to Docker Hub](#pushing-to-docker-hub)\n      - [Pushing to Google GCR](#pushing-to-google-gcr)\n      - [Pushing to GCR using Workload Identity](#pushing-to-gcr-using-workload-identity)\n      - [Pushing to Amazon ECR](#pushing-to-amazon-ecr)\n      - [Pushing to Azure Container Registry](#pushing-to-azure-container-registry)\n      - [Pushing to JFrog Container Registry or to JFrog Artifactory](#pushing-to-jfrog-container-registry-or-to-jfrog-artifactory)\n    - [Additional Flags](#additional-flags)\n      - [Flag `--build-arg`](#flag---build-arg)\n      - [Flag `--cache`](#flag---cache)\n      - [Flag `--cache-dir`](#flag---cache-dir)\n      - [Flag `--cache-repo`](#flag---cache-repo)\n      - [Flag `--cache-copy-layers`](#flag---cache-copy-layers)\n      - [Flag `--cache-run-layers`](#flag---cache-run-layers)\n      - [Flag `--cache-ttl duration`](#flag---cache-ttl-duration)\n      - [Flag `--cleanup`](#flag---cleanup)\n      - [Flag `--compressed-caching`](#flag---compressed-caching)\n      - [Flag `--context-sub-path`](#flag---context-sub-path)\n      - [Flag `--custom-platform`](#flag---custom-platform)\n      - [Flag `--digest-file`](#flag---digest-file)\n      - [Flag `--dockerfile`](#flag---dockerfile)\n      - [Flag `--force`](#flag---force)\n      - [Flag `--git`](#flag---git)\n      - [Flag `--image-name-with-digest-file`](#flag---image-name-with-digest-file)\n      - [Flag `--image-name-tag-with-digest-file`](#flag---image-name-tag-with-digest-file)\n      - [Flag `--insecure`](#flag---insecure)\n      - [Flag `--insecure-pull`](#flag---insecure-pull)\n      - [Flag `--insecure-registry`](#flag---insecure-registry)\n      - [Flag `--label`](#flag---label)\n      - [Flag `--log-format`](#flag---log-format)\n      - [Flag `--log-timestamp`](#flag---log-timestamp)\n      - [Flag `--no-push`](#flag---no-push)\n      - [Flag `--no-push-cache`](#flag---no-push-cache)\n      - [Flag `--oci-layout-path`](#flag---oci-layout-path)\n      - [Flag `--push-retry`](#flag---push-retry)\n      - [Flag `--registry-certificate`](#flag---registry-certificate)\n      - [Flag `--registry-client-cert`](#flag---registry-client-cert)\n      - [Flag `--registry-map`](#flag---registry-map)\n      - [Flag `--registry-mirror`](#flag---registry-mirror)\n      - [Flag `--skip-default-registry-fallback`](#flag---skip-default-registry-fallback)\n      - [Flag `--reproducible`](#flag---reproducible)\n      - [Flag `--single-snapshot`](#flag---single-snapshot)\n      - [Flag `--skip-push-permission-check`](#flag---skip-push-permission-check)\n      - [Flag `--skip-tls-verify`](#flag---skip-tls-verify)\n      - [Flag `--skip-tls-verify-pull`](#flag---skip-tls-verify-pull)\n      - [Flag `--skip-tls-verify-registry`](#flag---skip-tls-verify-registry)\n      - [Flag `--skip-unused-stages`](#flag---skip-unused-stages)\n      - [Flag `--snapshot-mode`](#flag---snapshot-mode)\n      - [Flag `--tar-path`](#flag---tar-path)\n      - [Flag `--target`](#flag---target)\n      - [Flag `--use-new-run`](#flag---use-new-run)\n      - [Flag `--verbosity`](#flag---verbosity)\n      - [Flag `--ignore-var-run`](#flag---ignore-var-run)\n      - [Flag `--ignore-path`](#flag---ignore-path)\n      - [Flag `--image-fs-extract-retry`](#flag---image-fs-extract-retry)\n      - [Flag `--image-download-retry`](#flag---image-download-retry)\n    - [Debug Image](#debug-image)\n  - [Security](#security)\n    - [Verifying Signed Kaniko Images](#verifying-signed-kaniko-images)\n  - [Kaniko Builds - Profiling](#kaniko-builds---profiling)\n  - [Creating Multi-arch Container Manifests Using Kaniko and Manifest-tool](#creating-multi-arch-container-manifests-using-kaniko-and-manifest-tool)\n    - [General Workflow](#general-workflow)\n    - [Limitations and Pitfalls](#limitations-and-pitfalls)\n    - [Example CI Pipeline (GitLab)](#example-ci-pipeline-gitlab)\n      - [Building the Separate Container Images](#building-the-separate-container-images)\n      - [Merging the Container Manifests](#merging-the-container-manifests)\n      - [On the Note of Adding Versioned Tags](#on-the-note-of-adding-versioned-tags)\n  - [Comparison with Other Tools](#comparison-with-other-tools)\n  - [Community](#community-1)\n  - [Limitations](#limitations)\n    - [mtime and snapshotting](#mtime-and-snapshotting)\n  - [References](#references)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Community\n\nWe'd love to hear from you! Join\n[#kaniko on Kubernetes Slack](https://kubernetes.slack.com/messages/CQDCHGX7Y/)\n\n## How does kaniko work?\n\nThe kaniko executor image is responsible for building an image from a Dockerfile\nand pushing it to a registry. Within the executor image, we extract the\nfilesystem of the base image (the FROM image in the Dockerfile). We then execute\nthe commands in the Dockerfile, snapshotting the filesystem in userspace after\neach one. After each command, we append a layer of changed files to the base\nimage (if there are any) and update image metadata.\n\n## Known Issues\n\n- kaniko does not support building Windows containers.\n- Running kaniko in any Docker image other than the official kaniko image is not\n  supported due to implementation details.\n  - This includes copying the kaniko executables from the official image into\n    another image (e.g. a Jenkins CI agent).\n  - In particular, it cannot use chroot or bind-mount because its container must\n    not require privilege, so it unpacks directly into its own container root\n    and may overwrite anything already there.\n- kaniko does not support the v1 Registry API\n  ([Registry v1 API Deprecation](https://www.docker.com/blog/registry-v1-api-deprecation/))\n\n## Demo\n\n![Demo](/docs/demo.gif)\n\n## Tutorial\n\nFor a detailed example of kaniko with local storage, please refer to a\n[getting started tutorial](./docs/tutorial.md).\n\nPlease see [References](#References) for more docs \u0026 video tutorials\n\n## Using kaniko\n\nTo use kaniko to build and push an image for you, you will need:\n\n1. A [build context](#kaniko-build-contexts), aka something to build\n2. A [running instance of kaniko](#running-kaniko)\n\n### kaniko Build Contexts\n\nkaniko's build context is very similar to the build context you would send your\nDocker daemon for an image build; it represents a directory containing a\nDockerfile which kaniko will use to build your image. For example, a `COPY`\ncommand in your Dockerfile should refer to a file in the build context.\n\nYou will need to store your build context in a place that kaniko can access.\nRight now, kaniko supports these storage solutions:\n\n- GCS Bucket\n- S3 Bucket\n- Azure Blob Storage\n- Local Directory\n- Local Tar\n- Standard Input\n- Git Repository\n\n_Note about Local Directory: this option refers to a directory within the kaniko\ncontainer. If you wish to use this option, you will need to mount in your build\ncontext into the container as a directory._\n\n_Note about Local Tar: this option refers to a tar gz file within the kaniko\ncontainer. If you wish to use this option, you will need to mount in your build\ncontext into the container as a file._\n\n_Note about Standard Input: the only Standard Input allowed by kaniko is in\n`.tar.gz` format._\n\nIf using a GCS or S3 bucket, you will first need to create a compressed tar of\nyour build context and upload it to your bucket. Once running, kaniko will then\ndownload and unpack the compressed tar of the build context before starting the\nimage build.\n\nTo create a compressed tar, you can run:\n\n```shell\ntar -C \u003cpath to build context\u003e -zcvf context.tar.gz .\n```\n\nThen, copy over the compressed tar into your bucket. For example, we can copy\nover the compressed tar to a GCS bucket with gsutil:\n\n```shell\ngsutil cp context.tar.gz gs://\u003cbucket name\u003e\n```\n\nWhen running kaniko, use the `--context` flag with the appropriate prefix to\nspecify the location of your build context:\n\n| Source             | Prefix                                                                | Example                                                                       |\n| ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| Local Directory    | dir://[path to a directory in the kaniko container]                   | `dir:///workspace`                                                            |\n| Local Tar Gz       | tar://[path to a .tar.gz in the kaniko container]                     | `tar:///path/to/context.tar.gz`                                               |\n| Standard Input     | tar://[stdin]                                                         | `tar://stdin`                                                                 |\n| GCS Bucket         | gs://[bucket name]/[path to .tar.gz]                                  | `gs://kaniko-bucket/path/to/context.tar.gz`                                   |\n| S3 Bucket          | s3://[bucket name]/[path to .tar.gz]                                  | `s3://kaniko-bucket/path/to/context.tar.gz`                                   |\n| Azure Blob Storage | https://[account].[azureblobhostsuffix]/[container]/[path to .tar.gz] | `https://myaccount.blob.core.windows.net/container/path/to/context.tar.gz`    |\n| Git Repository     | git://[repository url][#reference][#commit-id]                        | `git://github.com/acme/myproject.git#refs/heads/mybranch#\u003cdesired-commit-id\u003e` |\n\nIf you don't specify a prefix, kaniko will assume a local directory. For\nexample, to use a GCS bucket called `kaniko-bucket`, you would pass in\n`--context=gs://kaniko-bucket/path/to/context.tar.gz`.\n\n### Using Azure Blob Storage\n\nIf you are using Azure Blob Storage for context file, you will need to pass\n[Azure Storage Account Access Key](https://docs.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string?toc=%2fazure%2fstorage%2fblobs%2ftoc.json)\nas an environment variable named `AZURE_STORAGE_ACCESS_KEY` through Kubernetes\nSecrets\n\n### Using Private Git Repository\n\nYou can use `Personal Access Tokens` for Build Contexts from Private\nRepositories from\n[GitHub](https://blog.github.com/2012-09-21-easier-builds-and-deployments-using-git-over-https-and-oauth/).\n\nYou can either pass this in as part of the git URL (e.g.,\n`git://TOKEN@github.com/acme/myproject.git#refs/heads/mybranch`) or using the\nenvironment variable `GIT_TOKEN`.\n\nYou can also pass `GIT_USERNAME` and `GIT_PASSWORD` (password being the token)\nif you want to be explicit about the username.\n\n### Using Standard Input\n\nIf running kaniko and using Standard Input build context, you will need to add\nthe docker or kubernetes `-i, --interactive` flag. Once running, kaniko will\nthen get the data from `STDIN` and create the build context as a compressed tar.\nIt will then unpack the compressed tar of the build context before starting the\nimage build. If no data is piped during the interactive run, you will need to\nsend the EOF signal by yourself by pressing `Ctrl+D`.\n\nComplete example of how to interactively run kaniko with `.tar.gz` Standard\nInput data, using docker:\n\n```shell\necho -e 'FROM alpine \\nRUN echo \"created from standard input\"' \u003e Dockerfile | tar -cf - Dockerfile | gzip -9 | docker run \\\n  --interactive -v $(pwd):/workspace gcr.io/kaniko-project/executor:latest \\\n  --context tar://stdin \\\n  --destination=\u003cgcr.io/$project/$image:$tag\u003e\n```\n\nComplete example of how to interactively run kaniko with `.tar.gz` Standard\nInput data, using Kubernetes command line with a temporary container and\ncompletely dockerless:\n\n```shell\necho -e 'FROM alpine \\nRUN echo \"created from standard input\"' \u003e Dockerfile | tar -cf - Dockerfile | gzip -9 | kubectl run kaniko \\\n--rm --stdin=true \\\n--image=gcr.io/kaniko-project/executor:latest --restart=Never \\\n--overrides='{\n  \"apiVersion\": \"v1\",\n  \"spec\": {\n    \"containers\": [\n      {\n        \"name\": \"kaniko\",\n        \"image\": \"gcr.io/kaniko-project/executor:latest\",\n        \"stdin\": true,\n        \"stdinOnce\": true,\n        \"args\": [\n          \"--dockerfile=Dockerfile\",\n          \"--context=tar://stdin\",\n          \"--destination=gcr.io/my-repo/my-image\"\n        ],\n        \"volumeMounts\": [\n          {\n            \"name\": \"cabundle\",\n            \"mountPath\": \"/kaniko/ssl/certs/\"\n          },\n          {\n            \"name\": \"docker-config\",\n            \"mountPath\": \"/kaniko/.docker/\"\n          }\n        ]\n      }\n    ],\n    \"volumes\": [\n      {\n        \"name\": \"cabundle\",\n        \"configMap\": {\n          \"name\": \"cabundle\"\n        }\n      },\n      {\n        \"name\": \"docker-config\",\n        \"configMap\": {\n          \"name\": \"docker-config\"\n        }\n      }\n    ]\n  }\n}'\n```\n\n### Running kaniko\n\nThere are several different ways to deploy and run kaniko:\n\n- [In a Kubernetes cluster](#running-kaniko-in-a-kubernetes-cluster)\n- [In gVisor](#running-kaniko-in-gvisor)\n- [In Google Cloud Build](#running-kaniko-in-google-cloud-build)\n- [In Docker](#running-kaniko-in-docker)\n\n#### Running kaniko in a Kubernetes cluster\n\nRequirements:\n\n- Standard Kubernetes cluster (e.g. using\n  [GKE](https://cloud.google.com/kubernetes-engine/))\n- [Kubernetes Secret](#kubernetes-secret)\n- A [build context](#kaniko-build-contexts)\n\n##### Kubernetes secret\n\nTo run kaniko in a Kubernetes cluster, you will need a standard running\nKubernetes cluster and a Kubernetes secret, which contains the auth required to\npush the final image.\n\nTo create a secret to authenticate to Google Cloud Registry, follow these steps:\n\n1. Create a service account in the Google Cloud Console project you want to push\n   the final image to with `Storage Admin` permissions.\n2. Download a JSON key for this service account\n3. Rename the key to `kaniko-secret.json`\n4. To create the secret, run:\n\n```shell\nkubectl create secret generic kaniko-secret --from-file=\u003cpath to kaniko-secret.json\u003e\n```\n\n_Note: If using a GCS bucket in the same GCP project as a build context, this\nservice account should now also have permissions to read from that bucket._\n\nThe Kubernetes Pod spec should look similar to this, with the args parameters\nfilled in:\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: kaniko\nspec:\n  containers:\n    - name: kaniko\n      image: gcr.io/kaniko-project/executor:latest\n      args:\n        - \"--dockerfile=\u003cpath to Dockerfile within the build context\u003e\"\n        - \"--context=gs://\u003cGCS bucket\u003e/\u003cpath to .tar.gz\u003e\"\n        - \"--destination=\u003cgcr.io/$PROJECT/$IMAGE:$TAG\u003e\"\n      volumeMounts:\n        - name: kaniko-secret\n          mountPath: /secret\n      env:\n        - name: GOOGLE_APPLICATION_CREDENTIALS\n          value: /secret/kaniko-secret.json\n  restartPolicy: Never\n  volumes:\n    - name: kaniko-secret\n      secret:\n        secretName: kaniko-secret\n```\n\nThis example pulls the build context from a GCS bucket. To use a local directory\nbuild context, you could consider using configMaps to mount in small build\ncontexts.\n\n#### Running kaniko in gVisor\n\nRunning kaniko in [gVisor](https://github.com/google/gvisor) provides an\nadditional security boundary. You will need to add the `--force` flag to run\nkaniko in gVisor, since currently there isn't a way to determine whether or not\na container is running in gVisor.\n\n```shell\ndocker run --runtime=runsc -v $(pwd):/workspace -v ~/.config:/root/.config \\\ngcr.io/kaniko-project/executor:latest \\\n--dockerfile=\u003cpath to Dockerfile\u003e --context=/workspace \\\n--destination=gcr.io/my-repo/my-image --force\n```\n\nWe pass in `--runtime=runsc` to use gVisor. This example mounts the current\ndirectory to `/workspace` for the build context and the `~/.config` directory\nfor GCR credentials.\n\n#### Running kaniko in Google Cloud Build\n\nRequirements:\n\n- A [build context](#kaniko-build-contexts)\n\nTo run kaniko in GCB, add it to your build config as a build step:\n\n```yaml\nsteps:\n  - name: gcr.io/kaniko-project/executor:latest\n    args:\n      [\n        \"--dockerfile=\u003cpath to Dockerfile within the build context\u003e\",\n        \"--context=dir://\u003cpath to build context\u003e\",\n        \"--destination=\u003cgcr.io/$PROJECT/$IMAGE:$TAG\u003e\",\n      ]\n```\n\nkaniko will build and push the final image in this build step.\n\n#### Running kaniko in Docker\n\nRequirements:\n\n- [Docker](https://docs.docker.com/install/)\n\nWe can run the kaniko executor image locally in a Docker daemon to build and\npush an image from a Dockerfile.\n\nFor example, when using gcloud and GCR you could run kaniko as follows:\n\n```shell\ndocker run \\\n    -v \"$HOME\"/.config/gcloud:/root/.config/gcloud \\\n    -v /path/to/context:/workspace \\\n    gcr.io/kaniko-project/executor:latest \\\n    --dockerfile /workspace/Dockerfile \\\n    --destination \"gcr.io/$PROJECT_ID/$IMAGE_NAME:$TAG\" \\\n    --context dir:///workspace/\n```\n\nThere is also a utility script [`run_in_docker.sh`](./run_in_docker.sh) that can\nbe used as follows:\n\n```shell\n./run_in_docker.sh \u003cpath to Dockerfile\u003e \u003cpath to build context\u003e \u003cdestination of final image\u003e\n```\n\n_NOTE: `run_in_docker.sh` expects a path to a Dockerfile relative to the\nabsolute path of the build context._\n\nAn example run, specifying the Dockerfile in the container directory\n`/workspace`, the build context in the local directory\n`/home/user/kaniko-project`, and a Google Container Registry as a remote image\ndestination:\n\n```shell\n./run_in_docker.sh /workspace/Dockerfile /home/user/kaniko-project gcr.io/$PROJECT_ID/$TAG\n```\n\n### Caching\n\n#### Caching Layers\n\nkaniko can cache layers created by `RUN`(configured by flag\n`--cache-run-layers`) and `COPY` (configured by flag `--cache-copy-layers`)\ncommands in a remote repository. Before executing a command, kaniko checks the\ncache for the layer. If it exists, kaniko will pull and extract the cached layer\ninstead of executing the command. If not, kaniko will execute the command and\nthen push the newly created layer to the cache.\n\nNote that kaniko cannot read layers from the cache after a cache miss: once a\nlayer has not been found in the cache, all subsequent layers are built locally\nwithout consulting the cache.\n\nUsers can opt into caching by setting the `--cache=true` flag. A remote\nrepository for storing cached layers can be provided via the `--cache-repo`\nflag. If this flag isn't provided, a cached repo will be inferred from the\n`--destination` provided.\n\n#### Caching Base Images\n\nkaniko can cache images in a local directory that can be volume mounted into the\nkaniko pod. To do so, the cache must first be populated, as it is read-only. We\nprovide a kaniko cache warming image at `gcr.io/kaniko-project/warmer`:\n\n```shell\ndocker run -v $(pwd):/workspace gcr.io/kaniko-project/warmer:latest --cache-dir=/workspace/cache --image=\u003cimage to cache\u003e --image=\u003canother image to cache\u003e\ndocker run -v $(pwd):/workspace gcr.io/kaniko-project/warmer:latest --cache-dir=/workspace/cache --dockerfile=\u003cpath to dockerfile\u003e\ndocker run -v $(pwd):/workspace gcr.io/kaniko-project/warmer:latest --cache-dir=/workspace/cache --dockerfile=\u003cpath to dockerfile\u003e --build-arg version=1.19\n```\n\n`--image` can be specified for any number of desired images. `--dockerfile` can\nbe specified for the path of dockerfile for cache.These command will combined to\ncache those images by digest in a local directory named `cache`. Once the cache\nis populated, caching is opted into with the same `--cache=true` flag as above.\nThe location of the local cache is provided via the `--cache-dir` flag,\ndefaulting to `/cache` as with the cache warmer. See the `examples` directory\nfor how to use with kubernetes clusters and persistent cache volumes.\n\n### Pushing to Different Registries\n\nkaniko uses Docker credential helpers to push images to a registry.\n\nkaniko comes with support for GCR, Docker `config.json` and Amazon ECR, but\nconfiguring another credential helper should allow pushing to a different\nregistry.\n\n#### Pushing to Docker Hub\n\nGet your docker registry user and password encoded in base64\n\n    echo -n USER:PASSWORD | base64\n\nCreate a `config.json` file with your Docker registry url and the previous\ngenerated base64 string\n\n**Note:** Please use v1 endpoint. See #1209 for more details\n\n```json\n{\n  \"auths\": {\n    \"https://index.docker.io/v1/\": {\n      \"auth\": \"xxxxxxxxxxxxxxx\"\n    }\n  }\n}\n```\n\nRun kaniko with the `config.json` inside `/kaniko/.docker/config.json`\n\n```shell\ndocker run -ti --rm -v `pwd`:/workspace -v `pwd`/config.json:/kaniko/.docker/config.json:ro gcr.io/kaniko-project/executor:latest --dockerfile=Dockerfile --destination=yourimagename\n```\n\n#### Pushing to Google GCR\n\nTo create a credentials to authenticate to Google Cloud Registry, follow these\nsteps:\n\n1. Create a\n   [service account](https://console.cloud.google.com/iam-admin/serviceaccounts)\n   or in the Google Cloud Console project you want to push the final image to\n   with `Storage Admin` permissions.\n2. Download a JSON key for this service account\n3. (optional) Rename the key to `kaniko-secret.json`, if you don't rename, you\n   have to change the name used the command(in the volume part)\n4. Run the container adding the path in GOOGLE_APPLICATION_CREDENTIALS env var\n\n```shell\ndocker run -ti --rm -e GOOGLE_APPLICATION_CREDENTIALS=/kaniko/config.json \\\n-v `pwd`:/workspace -v `pwd`/kaniko-secret.json:/kaniko/config.json:ro gcr.io/kaniko-project/executor:latest \\\n--dockerfile=Dockerfile --destination=yourimagename\n```\n\n#### Pushing to GCR using Workload Identity\n\nIf you have enabled Workload Identity on your GKE cluster then you can use the\nworkload identity to push built images to GCR without adding a\n`GOOGLE_APPLICATION_CREDENTIALS` in your kaniko pod specification.\n\nLearn more on how to\n[enable](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#enable_on_cluster)\nand\n[migrate existing apps](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#migrate_applications_to)\nto workload identity.\n\nTo authenticate using workload identity you need to run the kaniko pod using the\nKubernetes Service Account (KSA) bound to Google Service Account (GSA) which has\n`Storage.Admin` permissions to push images to Google Container registry.\n\nPlease follow the detailed steps\n[here](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#authenticating_to)\nto create a Kubernetes Service Account, Google Service Account and create an IAM\npolicy binding between the two to allow the Kubernetes Service account to act as\nthe Google service account.\n\nTo grant the Google Service account the right permission to push to GCR, run the\nfollowing GCR command\n\n```\ngcloud projects add-iam-policy-binding $PROJECT \\\n  --member=serviceAccount:[gsa-name]@${PROJECT}.iam.gserviceaccount.com \\\n  --role=roles/storage.objectAdmin\n```\n\nPlease ensure, kaniko pod is running in the namespace and with a Kubernetes\nService Account.\n\n#### Pushing to Amazon ECR\n\nThe Amazon ECR\n[credential helper](https://github.com/awslabs/amazon-ecr-credential-helper) is\nbuilt into the kaniko executor image.\n\n1. Configure credentials\n\n   1. You can use instance roles when pushing to ECR from a EC2 instance or from\n      EKS, by\n      [configuring the instance role permissions](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_EKS.html)\n      (the AWS managed policy\n      `EC2InstanceProfileForImageBuilderECRContainerBuilds` provides broad\n      permissions to upload ECR images and may be used as configuration\n      baseline). Additionally, set `AWS_SDK_LOAD_CONFIG=true` as environment\n      variable within the kaniko pod. If running on an EC2 instance with an\n      instance profile, you may also need to set\n      `AWS_EC2_METADATA_DISABLED=true` for kaniko to pick up the correct\n      credentials.\n\n   2. Or you can create a Kubernetes secret for your `~/.aws/credentials` file\n      so that credentials can be accessed within the cluster. To create the\n      secret, run:\n      `shell kubectl create secret generic aws-secret --from-file=\u003cpath to .aws/credentials\u003e `\n\nThe Kubernetes Pod spec should look similar to this, with the args parameters\nfilled in. Note that `aws-secret` volume mount and volume are only needed when\nusing AWS credentials from a secret, not when using instance roles.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: kaniko\nspec:\n  containers:\n    - name: kaniko\n      image: gcr.io/kaniko-project/executor:latest\n      args:\n        - \"--dockerfile=\u003cpath to Dockerfile within the build context\u003e\"\n        - \"--context=s3://\u003cbucket name\u003e/\u003cpath to .tar.gz\u003e\"\n        - \"--destination=\u003caws_account_id.dkr.ecr.region.amazonaws.com/my-repository:my-tag\u003e\"\n      volumeMounts:\n        # when not using instance role\n        - name: aws-secret\n          mountPath: /root/.aws/\n  restartPolicy: Never\n  volumes:\n    # when not using instance role\n    - name: aws-secret\n      secret:\n        secretName: aws-secret\n```\n\n#### Pushing to Azure Container Registry\n\nAn ACR\n[credential helper](https://github.com/chrismellard/docker-credential-acr-env)\nis built into the kaniko executor image, which can be used to authenticate with\nwell-known Azure environmental information.\n\nTo configure credentials, you will need to do the following:\n\n1. Update the `credStore` section of `config.json`:\n\n```json\n{ \"credsStore\": \"acr\" }\n```\n\nA downside of this approach is that ACR authentication will be used for all\nregistries, which will fail if you also pull from DockerHub, GCR, etc. Thus, it\nis better to configure the credential tool only for your ACR registries by using\n`credHelpers` instead of `credsStore`:\n\n```json\n{ \"credHelpers\": { \"mycr.azurecr.io\": \"acr-env\" } }\n```\n\nYou can mount in the new config as a configMap:\n\n```shell\nkubectl create configmap docker-config --from-file=\u003cpath to config.json\u003e\n```\n\n2. Configure credentials\n\nYou can create a Kubernetes secret with environment variables required for\nService Principal authentication and expose them to the builder container.\n\n```\nAZURE_CLIENT_ID=\u003cclientID\u003e\nAZURE_CLIENT_SECRET=\u003cclientSecret\u003e\nAZURE_TENANT_ID=\u003ctenantId\u003e\n```\n\nIf the above are not set then authentication falls back to managed service\nidentities and the MSI endpoint is attempted to be contacted which will work in\nvarious Azure contexts such as App Service and Azure Kubernetes Service where\nthe MSI endpoint will authenticate the MSI context the service is running under.\n\nThe Kubernetes Pod spec should look similar to this, with the args parameters\nfilled in. Note that `azure-secret` secret is only needed when using Azure\nService Principal credentials, not when using a managed service identity.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: kaniko\nspec:\n  containers:\n    - name: kaniko\n      image: gcr.io/kaniko-project/executor:latest\n      args:\n        - \"--dockerfile=\u003cpath to Dockerfile within the build context\u003e\"\n        - \"--context=s3://\u003cbucket name\u003e/\u003cpath to .tar.gz\u003e\"\n        - \"--destination=mycr.azurecr.io/my-repository:my-tag\"\n      envFrom:\n        # when authenticating with service principal\n        - secretRef:\n            name: azure-secret\n      volumeMounts:\n        - name: docker-config\n          mountPath: /kaniko/.docker/\n  volumes:\n    - name: docker-config\n      configMap:\n        name: docker-config\n  restartPolicy: Never\n```\n\n#### Pushing to JFrog Container Registry or to JFrog Artifactory\n\nKaniko can be used with both\n[JFrog Container Registry](https://www.jfrog.com/confluence/display/JFROG/JFrog+Container+Registry)\nand JFrog Artifactory.\n\nGet your JFrog Artifactory registry user and password encoded in base64\n\n    echo -n USER:PASSWORD | base64\n\nCreate a `config.json` file with your Artifactory Docker local registry URL and\nthe previous generated base64 string\n\n```json\n{\n  \"auths\": {\n    \"artprod.company.com\": {\n      \"auth\": \"xxxxxxxxxxxxxxx\"\n    }\n  }\n}\n```\n\nFor example, for Artifactory cloud users, the docker registry should be:\n`\u003ccompany\u003e.\u003clocal-repository-name\u003e.io`.\n\nRun kaniko with the `config.json` inside `/kaniko/.docker/config.json`\n\n    docker run -ti --rm -v `pwd`:/workspace -v `pwd`/config.json:/kaniko/.docker/config.json:ro gcr.io/kaniko-project/executor:latest --dockerfile=Dockerfile --destination=yourimagename\n\nAfter the image is uploaded, using the JFrog CLI, you can\n[collect](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-PushingDockerImagesUsingKaniko)\nand\n[publish](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-PublishingBuild-Info)\nthe build information to Artifactory and trigger\n[build vulnerabilities scanning](https://www.jfrog.com/confluence/display/JFROG/Declarative+Pipeline+Syntax#DeclarativePipelineSyntax-ScanningBuildswithJFrogXray)\nusing JFrog Xray.\n\nTo collect and publish the image's build information using the Jenkins\nArtifactory plugin, see instructions for\n[scripted pipeline](https://www.jfrog.com/confluence/display/JFROG/Scripted+Pipeline+Syntax#ScriptedPipelineSyntax-UsingKaniko)\nand\n[declarative pipeline](https://www.jfrog.com/confluence/display/JFROG/Declarative+Pipeline+Syntax#DeclarativePipelineSyntax-UsingKaniko).\n\n### Additional Flags\n\n#### Flag `--build-arg`\n\nThis flag allows you to pass in ARG values at build time, similarly to Docker.\nYou can set it multiple times for multiple arguments.\n\nNote that passing values that contain spaces is not natively supported - you\nneed to ensure that the IFS is set to null before your executor command. You can\nset this by adding `export IFS=''` before your executor call. See the following\nexample\n\n```bash\nexport IFS=''\n/kaniko/executor --build-arg \"MY_VAR='value with spaces'\" ...\n```\n\n#### Flag `--cache`\n\nSet this flag as `--cache=true` to opt into caching with kaniko.\n\n#### Flag `--cache-dir`\n\nSet this flag to specify a local directory cache for base images. Defaults to\n`/cache`.\n\n_This flag must be used in conjunction with the `--cache=true` flag._\n\n#### Flag `--cache-repo`\n\nSet this flag to specify a remote repository that will be used to store cached\nlayers.\n\nIf this flag is not provided, a cache repo will be inferred from the\n`--destination` flag. If `--destination=gcr.io/kaniko-project/test`, then cached\nlayers will be stored in `gcr.io/kaniko-project/test/cache`.\n\n_This flag must be used in conjunction with the `--cache=true` flag._\n\n#### Flag `--cache-copy-layers`\n\nSet this flag to cache copy layers.\n\n#### Flag `--cache-run-layers`\n\nSet this flag to cache run layers (default=true).\n\n#### Flag `--cache-ttl duration`\n\nCache timeout in hours. Defaults to two weeks.\n\n#### Flag `--cleanup`\n\nSet this flag to clean the filesystem at the end of the build.\n\n#### Flag `--compressed-caching`\n\nSet this to false in order to prevent tar compression for cached layers. This\nwill increase the runtime of the build, but decrease the memory usage especially\nfor large builds. Try to use `--compressed-caching=false` if your build fails\nwith an out of memory error. Defaults to true.\n\n#### Flag `--context-sub-path`\n\nSet a sub path within the given `--context`.\n\nIts particularly useful when your context is, for example, a git repository, and\nyou want to build one of its subfolders instead of the root folder.\n\n#### Flag `--custom-platform`\n\nAllows to build with another default platform than the host, similarly to docker\nbuild --platform xxx the value has to be on the form\n`--custom-platform=linux/arm`, with acceptable values listed here:\n[GOOS/GOARCH](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63).\n\nIt's also possible specifying CPU variants adding it as a third parameter (like\n`--custom-platform=linux/arm/v5`). Currently CPU variants are only known to be\nused for the ARM architecture as listed here:\n[GOARM](https://go.dev/wiki/GoArm#supported-architectures)\n\n_The resulting images cannot provide any metadata about CPU variant due to a\nlimitation of the OCI-image specification._\n\n_This is not virtualization and cannot help to build an architecture not\nnatively supported by the build host. This is used to build i386 on an amd64\nHost for example, or arm32 on an arm64 host._\n\n#### Flag `--digest-file`\n\nSet this flag to specify a file in the container. This file will receive the\ndigest of a built image. This can be used to automatically track the exact image\nbuilt by kaniko.\n\nFor example, setting the flag to `--digest-file=/dev/termination-log` will write\nthe digest to that file, which is picked up by Kubernetes automatically as the\n`{{.state.terminated.message}}` of the container.\n\n#### Flag `--dockerfile`\n\nPath to the dockerfile to be built. (default \"Dockerfile\")\n\n#### Flag `--force`\n\nForce building outside of a container\n\n#### Flag `--git`\n\nBranch to clone if build context is a git repository (default\nbranch=,single-branch=false,recurse-submodules=false,insecure-skip-tls=false)\n\n#### Flag `--image-name-with-digest-file`\n\nSpecify a file to save the image name w/ digest of the built image to.\n\n#### Flag `--image-name-tag-with-digest-file`\n\nSpecify a file to save the image name w/ image tag and digest of the built image\nto.\n\n#### Flag `--insecure`\n\nSet this flag if you want to push images to a plain HTTP registry. It is\nsupposed to be used for testing purposes only and should not be used in\nproduction!\n\n#### Flag `--insecure-pull`\n\nSet this flag if you want to pull images from a plain HTTP registry. It is\nsupposed to be used for testing purposes only and should not be used in\nproduction!\n\n#### Flag `--insecure-registry`\n\nYou can set `--insecure-registry \u003cregistry-name\u003e` to use plain HTTP requests\nwhen accessing the specified registry. It is supposed to be used for testing\npurposes only and should not be used in production! You can set it multiple\ntimes for multiple registries.\n\n#### Flag `--label`\n\nSet this flag as `--label key=value` to set some metadata to the final image.\nThis is equivalent as using the `LABEL` within the Dockerfile.\n\n#### Flag `--log-format`\n\nSet this flag as `--log-format=\u003ctext|color|json\u003e` to set the log format.\nDefaults to `color`.\n\n#### Flag `--log-timestamp`\n\nSet this flag as `--log-timestamp=\u003ctrue|false\u003e` to add timestamps to\n`\u003ctext|color\u003e` log format. Defaults to `false`.\n\n#### Flag `--no-push`\n\nSet this flag if you only want to build the image, without pushing to a\nregistry. This can also be defined through `KANIKO_NO_PUSH` environment\nvariable.\n\nNOTE: this will still push cache layers to the repo, to disable pushing cache layers use `--no-push-cache`\n\n#### Flag `--no-push-cache`\n\nSet this flag if you do not want to push cache layers to a\nregistry.  Can be used in addition to `--no-push` to push no layers to a registry.\n\n#### Flag `--oci-layout-path`\n\nSet this flag to specify a directory in the container where the OCI image layout\nof a built image will be placed. This can be used to automatically track the\nexact image built by kaniko.\n\nFor example, to surface the image digest built in a\n[Tekton task](https://github.com/tektoncd/pipeline/blob/v0.6.0/docs/resources.md#surfacing-the-image-digest-built-in-a-task),\nthis flag should be set to match the image resource `outputImageDir`.\n\n_Note: Depending on the built image, the media type of the image manifest might\nbe either `application/vnd.oci.image.manifest.v1+json` or\n`application/vnd.docker.distribution.manifest.v2+json`._\n\n#### Flag `--push-ignore-immutable-tag-errors`\n\nSet this boolean flag to `true` if you want the Kaniko process to exit with\nsuccess when a push error related to tag immutability occurs.\n\nThis is useful for example if you have parallel builds pushing the same tag\nand do not care which one actually succeeds.\n\nDefaults to `false`.\n\n#### Flag `--push-retry`\n\nSet this flag to the number of retries that should happen for the push of an\nimage to a remote destination. Defaults to `0`.\n\n#### Flag `--registry-certificate`\n\nSet this flag to provide a certificate for TLS communication with a given\nregistry.\n\nExpected format is `my.registry.url=/path/to/the/certificate.cert`\n\n#### Flag `--registry-client-cert`\n\nSet this flag to provide a certificate/key pair for mutual TLS (mTLS)\ncommunication with a given\n[registry that requires mTLS](https://docs.docker.com/engine/security/certificates/)\nfor authentication.\n\nExpected format is\n`my.registry.url=/path/to/client/cert.crt,/path/to/client/key.key`\n\n#### Flag `--registry-map`\n\nSet this flag if you want to remap registries references. Usefull for air gap\nenvironement for example. You can use this flag more than once, if you want to\nset multiple mirrors for a given registry. You can mention several remap in a\nsingle flag too, separated by semi-colon. If an image is not found on the first\nmirror, Kaniko will try the next mirror(s), and at the end fallback on the\noriginal registry.\n\nRegistry maps can also be defined through `KANIKO_REGISTRY_MAP` environment\nvariable.\n\nExpected format is\n`original-registry=remapped-registry[;another-reg=another-remap[;...]]` for\nexample.\n\nNote that you **can** specify a URL with scheme for this flag. Some valid options\nare:\n\n- `index.docker.io=mirror.gcr.io`\n- `gcr.io=127.0.0.1`\n- `quay.io=192.168.0.1:5000`\n- `index.docker.io=docker-io.mirrors.corp.net;index.docker.io=mirror.gcr.io;gcr.io=127.0.0.1`\n  will try `docker-io.mirrors.corp.net` then `mirror.gcr.io` for\n  `index.docker.io` and `127.0.0.1` for `gcr.io`\n- `docker.io=harbor.provate.io/theproject`\n\n#### Flag `--registry-mirror`\n\nSet this flag if you want to use a registry mirror instead of the default\n`index.docker.io`. You can use this flag more than once, if you want to set\nmultiple mirrors. If an image is not found on the first mirror, Kaniko will try\nthe next mirror(s), and at the end fallback on the default registry.\n\nMirror can also be defined through `KANIKO_REGISTRY_MIRROR` environment\nvariable.\n\nExpected format is `mirror.gcr.io` or `mirror.gcr.io/path` for example.\n\nNote that you **can** specify a URL with scheme for this flag. Some valid options\nare:\n\n- `mirror.gcr.io`\n- `127.0.0.1`\n- `192.168.0.1:5000`\n- `mycompany-docker-virtual.jfrog.io`\n- `harbor.provate.io/theproject`\n\n#### Flag `--skip-default-registry-fallback`\n\nSet this flag if you want the build process to fail if none of the mirrors\nlisted in flag [registry-mirror](#flag---registry-mirror) can pull some image.\nThis should be used with mirrors that implements a whitelist or some image\nrestrictions.\n\nIf [registry-mirror](#flag---registry-mirror) is not set or is empty, this flag\nis ignored.\n\n#### Flag `--reproducible`\n\nSet this flag to strip timestamps out of the built image and make it\nreproducible.\n\n#### Flag `--single-snapshot`\n\nThis flag takes a single snapshot of the filesystem at the end of the build, so\nonly one layer will be appended to the base image.\n\n#### Flag `--skip-push-permission-check`\n\nSet this flag to skip push permission check. This can be useful to delay Kanikos\nfirst request for delayed network-policies.\n\n#### Flag `--skip-tls-verify`\n\nSet this flag to skip TLS certificate validation when pushing to a registry. It\nis supposed to be used for testing purposes only and should not be used in\nproduction!\n\n#### Flag `--skip-tls-verify-pull`\n\nSet this flag to skip TLS certificate validation when pulling from a registry.\nIt is supposed to be used for testing purposes only and should not be used in\nproduction!\n\n#### Flag `--skip-tls-verify-registry`\n\nYou can set `--skip-tls-verify-registry \u003cregistry-name\u003e` to skip TLS certificate\nvalidation when accessing the specified registry. It is supposed to be used for\ntesting purposes only and should not be used in production! You can set it\nmultiple times for multiple registries.\n\n#### Flag `--skip-unused-stages`\n\nThis flag builds only used stages if defined to `true`. Otherwise it builds by\ndefault all stages, even the unnecessary ones until it reaches the target stage\n/ end of Dockerfile\n\n#### Flag `--snapshot-mode`\n\nYou can set the `--snapshot-mode=\u003cfull (default), redo, time\u003e` flag to set how\nkaniko will snapshot the filesystem.\n\n- If `--snapshot-mode=full` is set, the full file contents and metadata are\n  considered when snapshotting. This is the least performant option, but also\n  the most robust.\n\n- If `--snapshot-mode=redo` is set, the file mtime, size, mode, owner uid and\n  gid will be considered when snapshotting. This may be up to 50% faster than\n  \"full\", particularly if your project has a large number files.\n\n- If `--snapshot-mode=time` is set, only file mtime will be considered when\n  snapshotting (see [limitations related to mtime](#mtime-and-snapshotting)).\n\n#### Flag `--tar-path`\n\nSet this flag as `--tar-path=\u003cpath\u003e` to save the image as a tarball at path. You\nneed to set `--destination` as well (for example `--destination=image`). If you\nwant to save the image as tarball only you also need to set `--no-push`.\n\n#### Flag `--target`\n\nSet this flag to indicate which build stage is the target build stage.\n\n#### Flag `--use-new-run`\n\nUsing this flag enables an experimental implementation of the Run command which\ndoes not rely on snapshotting at all. In this approach, in order to compute\nwhich files were changed, a marker file is created before executing the Run\ncommand. Then the entire filesystem is walked (takes ~1-3 seconds for 700Kfiles)\nto find all files whose ModTime is greater than the marker file. With this new\nrun command implementation, the total build time is reduced seeing performance\nimprovements in the range of ~75%. This new run mode trades off\naccuracy/correctness in some cases (potential for missed files in a \"snapshot\")\nfor improved performance by avoiding the full filesystem snapshots.\n\n#### Flag `--verbosity`\n\nSet this flag as `--verbosity=\u003cpanic|fatal|error|warn|info|debug|trace\u003e` to set\nthe logging level. Defaults to `info`.\n\n#### Flag `--ignore-var-run`\n\nIgnore /var/run when taking image snapshot. Set it to false to preserve\n/var/run/\\* in destination image. (Default true).\n\n#### Flag `--ignore-path`\n\nSet this flag as `--ignore-path=\u003cpath\u003e` to ignore path when taking an image\nsnapshot. Set it multiple times for multiple ignore paths.\n\n#### Flag `--image-fs-extract-retry`\n\nSet this flag to the number of retries that should happen for the extracting an\nimage filesystem. Defaults to `0`.\n\n#### Flag `--image-download-retry`\n\nSet this flag to the number of retries that should happen when downloading the\nremote image. Consecutive retries occur with exponential backoff and an initial\ndelay of 1 second. Defaults to 0`.\n\n### Debug Image\n\nThe kaniko executor image is based on scratch and doesn't contain a shell. We\nprovide `gcr.io/kaniko-project/executor:debug`, a debug image which consists of\nthe kaniko executor image along with a busybox shell to enter.\n\nYou can launch the debug image with a shell entrypoint:\n\n```shell\ndocker run -it --entrypoint=/busybox/sh gcr.io/kaniko-project/executor:debug\n```\n\n## Security\n\nkaniko by itself **does not** make it safe to run untrusted builds inside your\ncluster, or anywhere else.\n\nkaniko relies on the security features of your container runtime to provide\nbuild security.\n\nThe minimum permissions kaniko needs inside your container are governed by a few\nthings:\n\n- The permissions required to unpack your base image into its container\n- The permissions required to execute the RUN commands inside the container\n\nIf you have a minimal base image (SCRATCH or similar) that doesn't require\npermissions to unpack, and your Dockerfile doesn't execute any commands as the\nroot user, you can run kaniko without root permissions. It should be noted that\nDocker runs as root by default, so you still require (in a sense) privileges to\nuse kaniko.\n\nYou may be able to achieve the same default seccomp profile that Docker uses in\nyour Pod by setting\n[seccomp](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#seccomp)\nprofiles with annotations on a\n[PodSecurityPolicy](https://cloud.google.com/kubernetes-engine/docs/how-to/pod-security-policies)\nto create or update security policies on your cluster.\n\n### Verifying Signed Kaniko Images\n\nkaniko images are signed for versions \u003e= 1.5.2 using\n[cosign](https://github.com/sigstore/cosign)!\n\nTo verify a public image, install [cosign](https://github.com/sigstore/cosign)\nand use the provided [public key](cosign.pub):\n\n```\n$ cat cosign.pub\n-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9aAfAcgAxIFMTstJUv8l/AMqnSKw\nP+vLu3NnnBDHCfREQpV/AJuiZ1UtgGpFpHlJLCNPmFkzQTnfyN5idzNl6Q==\n-----END PUBLIC KEY-----\n\n$ cosign verify -key ./cosign.pub gcr.io/kaniko-project/executor:latest\n```\n\n## Kaniko Builds - Profiling\n\nIf your builds are taking long, we recently added support to analyze kaniko\nfunction calls using [Slow Jam](https://github.com/google/slowjam) To start\nprofiling,\n\n1. Add an environment variable `STACKLOG_PATH` to your\n   [pod definition](https://github.com/GoogleContainerTools/kaniko/blob/master/examples/pod-build-profile.yaml#L15).\n2. If you are using the kaniko `debug` image, you can copy the file in the\n   `pre-stop` container lifecycle hook.\n\n## Creating Multi-arch Container Manifests Using Kaniko and Manifest-tool\n\nWhile Kaniko itself currently does not support creating multi-arch manifests\n(contributions welcome), one can use tools such as\n[manifest-tool](https://github.com/estesp/manifest-tool) to stitch multiple\nseparate builds together into a single container manifest.\n\n### General Workflow\n\nThe general workflow for creating multi-arch manifests is as follows:\n\n1. Build separate container images using Kaniko on build hosts matching your\n   target architecture and tag them with the appropriate ARCH tag.\n2. Push the separate images to your container registry.\n3. Manifest-tool identifies the separate manifests in your container registry,\n   according to a given template.\n4. Manifest-tool pushes a combined manifest referencing the separate manifests.\n\n![Workflow Multi-arch](docs/images/multi-arch.drawio.svg)\n\n### Limitations and Pitfalls\n\nThe following conditions must be met:\n\n1. You need access to build-machines running the desired architectures (running\n   Kaniko in an emulator, e.g. QEMU should also be possible but goes beyond the\n   scope of this documentation). This is something to keep in mind when using\n   SaaS build tools such as github.com or gitlab.com, of which at the time of\n   writing neither supports any non-x86_64 SaaS runners\n   ([GitHub](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources),[GitLab](https://docs.gitlab.com/ee/ci/runners/saas/linux_saas_runner.html#machine-types-available-for-private-projects-x86-64)),\n   so be prepared to bring your own machines\n   ([GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners),[GitLab](https://docs.gitlab.com/runner/register/).\n2. Kaniko needs to be able to run on the desired architectures. At the time of\n   writing, the official Kaniko container supports\n   [linux/amd64, linux/arm64, linux/s390x and linux/ppc64le (not on \\*-debug images)](https://github.com/GoogleContainerTools/kaniko/blob/main/.github/workflows/images.yaml).\n3. The container registry of your choice must be OCIv1 or Docker v2.2\n   compatible.\n\n### Example CI Pipeline (GitLab)\n\nIt is up to you to find an automation tool that suits your needs best. We\nrecommend using a modern CI/CD system such as GitHub workflows or GitLab CI. As\nwe (the authors) happen to use GitLab CI, the following examples are tailored to\nthis specific platform but the underlying principles should apply anywhere else\nand the examples are kept simple enough, so that you should be able to follow\nalong, even without any previous experiences with this specific platform. When\nin doubt, visit the\n[gitlab-ci.yml reference page](https://docs.gitlab.com/ee/ci/yaml/index.html)\nfor a comprehensive overview of the GitLab CI keywords.\n\n#### Building the Separate Container Images\n\ngitlab-ci.yml:\n\n```yaml\n# define a job for building the containers\nbuild-container:\n  stage: container-build\n  # run parallel builds for the desired architectures\n  parallel:\n    matrix:\n      - ARCH: amd64\n      - ARCH: arm64\n  tags:\n    # run each build on a suitable, preconfigured runner (must match the target architecture)\n    - runner-${ARCH}\n  image:\n    name: gcr.io/kaniko-project/executor:debug\n    entrypoint: [\"\"]\n  script:\n    # build the container image for the current arch using kaniko\n    - \u003e-\n      /kaniko/executor --context \"${CI_PROJECT_DIR}\" --dockerfile\n      \"${CI_PROJECT_DIR}/Dockerfile\" # push the image to the GitLab container\n      registry, add the current arch as tag. --destination\n      \"${CI_REGISTRY_IMAGE}:${ARCH}\"\n```\n\n#### Merging the Container Manifests\n\ngitlab-ci.yml:\n\n```yaml\n# define a job for creating and pushing a merged manifest\nmerge-manifests:\n  stage: container-build\n  # all containers must be build before merging them\n  # alternatively the job may be configured to run in a later stage\n  needs:\n    - job: container-build\n      artifacts: false\n  tags:\n    # may run on any architecture supported by manifest-tool image\n    - runner-xyz\n  image:\n    name: mplatform/manifest-tool:alpine\n    entrypoint: [\"\"]\n  script:\n    - \u003e-\n      manifest-tool # authorize against your container registry\n      --username=${CI_REGISTRY_USER} --password=${CI_REGISTRY_PASSWORD} push\n      from-args # define the architectures you want to merge --platforms\n      linux/amd64,linux/arm64 # \"ARCH\" will be automatically replaced by\n      manifest-tool # with the appropriate arch from the platform definitions\n      --template ${CI_REGISTRY_IMAGE}:ARCH # The name of the final, combined\n      image which will be pushed to your registry --target ${CI_REGISTRY_IMAGE}\n```\n\n#### On the Note of Adding Versioned Tags\n\nFor simplicity's sake we deliberately refrained from using versioned tagged\nimages (all builds will be tagged as \"latest\") in the previous examples, as we\nfeel like this adds to much platform and workflow specific code.\n\nNethertheless, for anyone interested in how we handle (dynamic) versioning in\nGitLab, here is a short rundown:\n\n- If you are only interested in building tagged releases, you can simply use the\n  [GitLab predefined](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)\n  `CI_COMMIT_TAG` variable when running a tag pipeline.\n- When you (like us) want to additionally build container images outside of\n  releases, things get a bit messier. In our case, we added a additional job\n  which runs before the build and merge jobs (don't forget to extend the `needs`\n  section of the build and merge jobs accordingly), which will set the tag to\n  `latest` when running on the default branch, to the commit hash when run on\n  other branches and to the release tag when run on a tag pipeline.\n\ngitlab-ci.yml:\n\n```yaml\ncontainer-get-tag:\n  stage: pre-container-build-stage\n  tags:\n    - runner-xyz\n  image: busybox\n  script:\n    # All other branches are tagged with the currently built commit SHA hash\n    - |\n      # If pipeline runs on the default branch: Set tag to \"latest\"\n      if test \"$CI_COMMIT_BRANCH\" == \"$CI_DEFAULT_BRANCH\"; then\n        tag=\"latest\"\n      # If pipeline is a tag pipeline, set tag to the git commit tag\n      elif test -n \"$CI_COMMIT_TAG\"; then\n        tag=\"$CI_COMMIT_TAG\"\n      # Else set the tag to the git commit sha\n      else\n        tag=\"$CI_COMMIT_SHA\"\n      fi\n    - echo \"tag=$tag\" \u003e build.env\n  # parse tag to the build and merge jobs.\n  # See: https://docs.gitlab.com/ee/ci/variables/#pass-an-environment-variable-to-another-job\n  artifacts:\n    reports:\n      dotenv: build.env\n```\n\n## Comparison with Other Tools\n\nSimilar tools include:\n\n- [BuildKit](https://github.com/moby/buildkit)\n- [img](https://github.com/genuinetools/img)\n- [orca-build](https://github.com/cyphar/orca-build)\n- [umoci](https://github.com/openSUSE/umoci)\n- [buildah](https://github.com/containers/buildah)\n- [FTL](https://github.com/GoogleCloudPlatform/runtimes-common/tree/master/ftl)\n- [Bazel rules_docker](https://github.com/bazelbuild/rules_docker)\n\nAll of these tools build container images with different approaches.\n\nBuildKit (and `img`) can perform as a non-root user from within a container but\nrequires seccomp and AppArmor to be disabled to create nested containers.\n`kaniko` does not actually create nested containers, so it does not require\nseccomp and AppArmor to be disabled. BuildKit supports \"cross-building\"\nmulti-arch containers by leveraging QEMU.\n\n`orca-build` depends on `runc` to build images from Dockerfiles, which can not\nrun inside a container (for similar reasons to `img` above). `kaniko` doesn't\nuse `runc` so it doesn't require the use of kernel namespacing techniques.\nHowever, `orca-build` does not require Docker or any privileged daemon (so\nbuilds can be done entirely without privilege).\n\n`umoci` works without any privileges, and also has no restrictions on the root\nfilesystem being extracted (though it requires additional handling if your\nfilesystem is sufficiently complicated). However, it has no `Dockerfile`-like\nbuild tooling (it's a slightly lower-level tool that can be used to build such\nbuilders -- such as `orca-build`).\n\n`Buildah` specializes in building OCI images. Buildah's commands replicate all\nof the commands that are found in a Dockerfile. This allows building images with\nand without Dockerfiles while not requiring any root privileges. Buildah’s\nultimate goal is to provide a lower-level coreutils interface to build images.\nThe flexibility of building images without Dockerfiles allows for the\nintegration of other scripting languages into the build process. Buildah follows\na simple fork-exec model and does not run as a daemon but it is based on a\ncomprehensive API in golang, which can be vendored into other tools.\n\n`FTL` and `Bazel` aim to achieve the fastest possible creation of Docker images\nfor a subset of images. These can be thought of as a special-case \"fast path\"\nthat can be used in conjunction with the support for general Dockerfiles kaniko\nprovides.\n\n## Community\n\n[kaniko-users](https://groups.google.com/forum/#!forum/kaniko-users) Google\ngroup\n\nTo Contribute to kaniko, see [DEVELOPMENT.md](DEVELOPMENT.md) and\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Limitations\n\n### mtime and snapshotting\n\nWhen taking a snapshot, kaniko's hashing algorithms include (or in the case of\n[`--snapshot-mode=time`](#--snapshotmode), only use) a file's\n[`mtime`](https://en.wikipedia.org/wiki/Inode#POSIX_inode_description) to\ndetermine if the file has changed. Unfortunately, there is a delay between when\nchanges to a file are made and when the `mtime` is updated. This means:\n\n- With the time-only snapshot mode (`--snapshot-mode=time`), kaniko may miss\n  changes introduced by `RUN` commands entirely.\n- With the default snapshot mode (`--snapshot-mode=full`), whether or not kaniko\n  will add a layer in the case where a `RUN` command modifies a file **but the\n  contents do not** change is theoretically non-deterministic. This _does not\n  affect the contents_ which will still be correct, but it does affect the\n  number of layers.\n\n_Note that these issues are currently theoretical only. If you see this issue\noccur, please\n[open an issue](https://github.com/GoogleContainerTools/kaniko/issues)._\n\n### Dockerfile commands `--chown` support\nKaniko currently supports `COPY --chown` and `ADD --chown` Dockerfile command. It does not support `RUN --chown`.\n\n## References\n\n- [Kaniko - Building Container Images In Kubernetes Without Docker](https://youtu.be/EgwVQN6GNJg).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecontainertools%2Fkaniko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglecontainertools%2Fkaniko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecontainertools%2Fkaniko/lists"}