Cleanup readme (#386)
- Add newlines after headings and remove whitespace - Use doctoc to update the Table of Contents - Get additional flags in alphabetical order
This commit is contained in:
Achilleas Pipinellis
dlorenc
parent
ade42d9105
commit
097ccb67a7
135
README.md
135
README.md
|
|
@ -12,36 +12,62 @@ This enables building container images in environments that can't easily or secu
|
||||||
kaniko is meant to be run as an image, `gcr.io/kaniko-project/executor`.
|
kaniko is meant to be run as an image, `gcr.io/kaniko-project/executor`.
|
||||||
We do **not** recommend running the kaniko executor binary in another image, as it might not work.
|
We do **not** recommend running the kaniko executor binary in another image, as it might not work.
|
||||||
|
|
||||||
- [Kaniko](#kaniko)
|
_If you are interested in contributing to kaniko, see [DEVELOPMENT.md](DEVELOPMENT.md) and [CONTRIBUTING.md](CONTRIBUTING.md)._
|
||||||
- [How does kaniko work?](#how-does-kaniko-work)
|
|
||||||
- [Known Issues](#known-issues)
|
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||||
|
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||||
|
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
|
||||||
|
|
||||||
|
- [How does kaniko work?](#how-does-kaniko-work)
|
||||||
|
- [Known Issues](#known-issues)
|
||||||
- [Demo](#demo)
|
- [Demo](#demo)
|
||||||
- [Using kaniko](#using-kaniko)
|
- [Using kaniko](#using-kaniko)
|
||||||
- [kaniko Build Contexts](#kaniko-build-contexts)
|
- [kaniko Build Contexts](#kaniko-build-contexts)
|
||||||
- [Running kaniko](#running-kaniko)
|
- [Running kaniko](#running-kaniko)
|
||||||
- [Running kaniko in a Kubernetes cluster](#running-kaniko-in-a-kubernetes-cluster)
|
- [Running kaniko in a Kubernetes cluster](#running-kaniko-in-a-kubernetes-cluster)
|
||||||
|
- [Kubernetes secret](#kubernetes-secret)
|
||||||
- [Running kaniko in gVisor](#running-kaniko-in-gvisor)
|
- [Running kaniko in gVisor](#running-kaniko-in-gvisor)
|
||||||
- [Running kaniko in Google Cloud Build](#running-kaniko-in-google-cloud-build)
|
- [Running kaniko in Google Cloud Build](#running-kaniko-in-google-cloud-build)
|
||||||
- [Running kaniko in Docker](#running-kaniko-in-Docker)
|
- [Running kaniko in Docker](#running-kaniko-in-docker)
|
||||||
- [Caching](#caching)
|
- [Caching](#caching)
|
||||||
|
- [Caching Layers](#caching-layers)
|
||||||
|
- [Caching Base Images](#caching-base-images)
|
||||||
- [Pushing to Different Registries](#pushing-to-different-registries)
|
- [Pushing to Different Registries](#pushing-to-different-registries)
|
||||||
|
- [Pushing to Amazon ECR](#pushing-to-amazon-ecr)
|
||||||
- [Additional Flags](#additional-flags)
|
- [Additional Flags](#additional-flags)
|
||||||
|
- [--build-arg](#--build-arg)
|
||||||
|
- [--cache](#--cache)
|
||||||
|
- [--cache-dir](#--cache-dir)
|
||||||
|
- [--cache-repo](#--cache-repo)
|
||||||
|
- [--cleanup](#--cleanup)
|
||||||
|
- [--insecure](#--insecure)
|
||||||
|
- [--insecure-pull](#--insecure-pull)
|
||||||
|
- [--no-push](#--no-push)
|
||||||
|
- [--reproducible](#--reproducible)
|
||||||
|
- [--single-snapshot](#--single-snapshot)
|
||||||
|
- [--snapshotMode](#--snapshotmode)
|
||||||
|
- [--skip-tls-verify](#--skip-tls-verify)
|
||||||
|
- [--skip-tls-verify-pull](#--skip-tls-verify-pull)
|
||||||
|
- [--target](#--target)
|
||||||
|
- [--tarPath](#--tarpath)
|
||||||
- [Debug Image](#debug-image)
|
- [Debug Image](#debug-image)
|
||||||
- [Security](#security)
|
- [Security](#security)
|
||||||
- [Comparison with Other Tools](#comparison-with-other-tools)
|
- [Comparison with Other Tools](#comparison-with-other-tools)
|
||||||
- [Community](#community)
|
- [Community](#community)
|
||||||
- [Limitations](#limitations)
|
- [Limitations](#limitations)
|
||||||
|
- [mtime and snapshotting](#mtime-and-snapshotting)
|
||||||
|
|
||||||
_If you are interested in contributing to kaniko, see [DEVELOPMENT.md](DEVELOPMENT.md) and [CONTRIBUTING.md](CONTRIBUTING.md)._
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||||
|
|
||||||
### How does kaniko work?
|
## How does kaniko work?
|
||||||
|
|
||||||
The kaniko executor image is responsible for building an image from a Dockerfile and pushing it to a registry.
|
The kaniko executor image is responsible for building an image from a Dockerfile and pushing it to a registry.
|
||||||
Within the executor image, we extract the filesystem of the base image (the FROM image in the Dockerfile).
|
Within the executor image, we extract the filesystem of the base image (the FROM image in the Dockerfile).
|
||||||
We then execute the commands in the Dockerfile, snapshotting the filesystem in userspace after each one.
|
We then execute the commands in the Dockerfile, snapshotting the filesystem in userspace after each one.
|
||||||
After each command, we append a layer of changed files to the base image (if there are any) and update image metadata.
|
After each command, we append a layer of changed files to the base image (if there are any) and update image metadata.
|
||||||
|
|
||||||
### Known Issues
|
## Known Issues
|
||||||
|
|
||||||
kaniko does not support building Windows containers.
|
kaniko does not support building Windows containers.
|
||||||
|
|
||||||
## Demo
|
## Demo
|
||||||
|
|
@ -73,12 +99,14 @@ If using a GCS or S3 bucket, you will first need to create a compressed tar of y
|
||||||
Once running, kaniko will then download and unpack the compressed tar of the build context before starting the image build.
|
Once running, kaniko will then download and unpack the compressed tar of the build context before starting the image build.
|
||||||
|
|
||||||
To create a compressed tar, you can run:
|
To create a compressed tar, you can run:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
tar -C <path to build context> -zcvf context.tar.gz .
|
tar -C <path to build context> -zcvf context.tar.gz .
|
||||||
```
|
```
|
||||||
Then, copy over the compressed tar into your bucket.
|
Then, copy over the compressed tar into your bucket.
|
||||||
For example, we can copy over the compressed tar to a GCS bucket with gsutil:
|
For example, we can copy over the compressed tar to a GCS bucket with gsutil:
|
||||||
```
|
|
||||||
|
```shell
|
||||||
gsutil cp context.tar.gz gs://<bucket name>
|
gsutil cp context.tar.gz gs://<bucket name>
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -222,6 +250,7 @@ A remote repository for storing cached layers can be provided via the `--cache-r
|
||||||
If this flag isn't provided, a cached repo will be inferred from the `--destination` provided.
|
If this flag isn't provided, a cached repo will be inferred from the `--destination` provided.
|
||||||
|
|
||||||
#### Caching Base Images
|
#### Caching Base Images
|
||||||
|
|
||||||
kaniko can cache images in a local directory that can be volume mounted into the kaniko image.
|
kaniko can cache images in a local directory that can be volume mounted into the kaniko image.
|
||||||
To do so, the cache must first be populated, as it is read-only. We provide a kaniko cache warming
|
To do so, the cache must first be populated, as it is read-only. We provide a kaniko cache warming
|
||||||
image at `gcr.io/kaniko-project/warmer`:
|
image at `gcr.io/kaniko-project/warmer`:
|
||||||
|
|
@ -302,57 +331,21 @@ To configure credentials, you will need to do the following:
|
||||||
|
|
||||||
### Additional Flags
|
### Additional Flags
|
||||||
|
|
||||||
#### --snapshotMode
|
|
||||||
|
|
||||||
You can set the `--snapshotMode=<full (default), time>` flag to set how kaniko will snapshot the filesystem.
|
|
||||||
If `--snapshotMode=time` is set, only file mtime will be considered when snapshotting (see
|
|
||||||
[limitations related to mtime](#mtime-and-snapshotting)).
|
|
||||||
|
|
||||||
#### --build-arg
|
#### --build-arg
|
||||||
|
|
||||||
This flag allows you to pass in ARG values at build time, similarly to Docker.
|
This flag allows you to pass in ARG values at build time, similarly to Docker.
|
||||||
You can set it multiple times for multiple arguments.
|
You can set it multiple times for multiple arguments.
|
||||||
|
|
||||||
#### --single-snapshot
|
|
||||||
|
|
||||||
This flag takes a single snapshot of the filesystem at the end of the build, so only one layer will be appended to the base image.
|
|
||||||
|
|
||||||
#### --reproducible
|
|
||||||
|
|
||||||
Set this flag to strip timestamps out of the built image and make it reproducible.
|
|
||||||
|
|
||||||
#### --tarPath
|
|
||||||
|
|
||||||
Set this flag as `--tarPath=<path>` to save the image as a tarball at path instead of pushing the image.
|
|
||||||
|
|
||||||
#### --target
|
|
||||||
|
|
||||||
Set this flag to indicate which build stage is the target build stage.
|
|
||||||
|
|
||||||
#### --no-push
|
|
||||||
|
|
||||||
Set this flag if you only want to build the image, without pushing to a registry.
|
|
||||||
|
|
||||||
#### --insecure
|
|
||||||
|
|
||||||
Set this flag if you want to push images to a plain HTTP registry. It is supposed to be used for testing purposes only and should not be used in production!
|
|
||||||
|
|
||||||
#### --skip-tls-verify
|
|
||||||
|
|
||||||
Set this flag to skip TLS certificate validation when pushing images to a registry. It is supposed to be used for testing purposes only and should not be used in production!
|
|
||||||
|
|
||||||
#### --insecure-pull
|
|
||||||
|
|
||||||
Set this flag if you want to pull images from a plain HTTP registry. It is supposed to be used for testing purposes only and should not be used in production!
|
|
||||||
|
|
||||||
#### --skip-tls-verify-pull
|
|
||||||
|
|
||||||
Set this flag to skip TLS certificate validation when pulling images from a registry. It is supposed to be used for testing purposes only and should not be used in production!
|
|
||||||
|
|
||||||
#### --cache
|
#### --cache
|
||||||
|
|
||||||
Set this flag as `--cache=true` to opt in to caching with kaniko.
|
Set this flag as `--cache=true` to opt in to caching with kaniko.
|
||||||
|
|
||||||
|
#### --cache-dir
|
||||||
|
|
||||||
|
Set this flag to specify a local directory cache for base images. Defaults to `/cache`.
|
||||||
|
|
||||||
|
_This flag must be used in conjunction with the `--cache=true` flag._
|
||||||
|
|
||||||
#### --cache-repo
|
#### --cache-repo
|
||||||
|
|
||||||
Set this flag to specify a remote repository which will be used to store cached layers.
|
Set this flag to specify a remote repository which will be used to store cached layers.
|
||||||
|
|
@ -362,15 +355,43 @@ If `--destination=gcr.io/kaniko-project/test`, then cached layers will be stored
|
||||||
|
|
||||||
_This flag must be used in conjunction with the `--cache=true` flag._
|
_This flag must be used in conjunction with the `--cache=true` flag._
|
||||||
|
|
||||||
#### --cache-dir
|
|
||||||
|
|
||||||
Set this flag to specify a local directory cache for base images. Defaults to `/cache`.
|
|
||||||
|
|
||||||
_This flag must be used in conjunction with the `--cache=true` flag._
|
|
||||||
|
|
||||||
#### --cleanup
|
#### --cleanup
|
||||||
|
|
||||||
Set this flag to cleanup the filesystem at the end, leaving a clean kaniko container (if you want to build multiple images in the same container, using the debug kaniko image)
|
Set this flag if you want to push images to a plain HTTP registry. It is supposed to be used for testing purposes only and should not be used in production!
|
||||||
|
|
||||||
|
#### --insecure-pull
|
||||||
|
|
||||||
|
Set this flag if you want to pull images from a plain HTTP registry. It is supposed to be used for testing purposes only and should not be used in production!
|
||||||
|
|
||||||
|
#### --no-push
|
||||||
|
|
||||||
|
Set this flag if you only want to build the image, without pushing to a registry.
|
||||||
|
|
||||||
|
#### --reproducible
|
||||||
|
|
||||||
|
Set this flag to strip timestamps out of the built image and make it reproducible.
|
||||||
|
|
||||||
|
#### --single-snapshot
|
||||||
|
|
||||||
|
This flag takes a single snapshot of the filesystem at the end of the build, so only one layer will be appended to the base image.
|
||||||
|
|
||||||
|
#### --skip-tls-verify
|
||||||
|
|
||||||
|
Set this flag to skip TLS certificate validation when connecting to a registry. It is supposed to be used for testing purposes only and should not be used in production!
|
||||||
|
|
||||||
|
#### --snapshotMode
|
||||||
|
|
||||||
|
You can set the `--snapshotMode=<full (default), time>` flag to set how kaniko will snapshot the filesystem.
|
||||||
|
If `--snapshotMode=time` is set, only file mtime will be considered when snapshotting (see
|
||||||
|
[limitations related to mtime](#mtime-and-snapshotting)).
|
||||||
|
|
||||||
|
#### --target
|
||||||
|
|
||||||
|
Set this flag to indicate which build stage is the target build stage.
|
||||||
|
|
||||||
|
#### --tarPath
|
||||||
|
|
||||||
|
Set this flag as `--tarPath=<path>` to save the image as a tarball at path instead of pushing the image.
|
||||||
|
|
||||||
### Debug Image
|
### Debug Image
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue