Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve --use-new-run help text, update README with missing flags #1405

Merged
merged 3 commits into from
Sep 8, 2020
Merged

Improve --use-new-run help text, update README with missing flags #1405

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f79492b
Make --use-new-run flag help easier to understand
tstromberg Aug 29, 2020
c0b88a0
Add missing flags/options to README, sort them
tstromberg Aug 29, 2020
3012551
Run doctoc
tstromberg Aug 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 95 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ _If you are interested in contributing to kaniko, see [DEVELOPMENT.md](DEVELOPME
- [kaniko Build Contexts](#kaniko-build-contexts)
- [Using Azure Blob Storage](#using-azure-blob-storage)
- [Using Private Git Repository](#using-private-git-repository)
- [Using Standard Input](#using-standard-input)
- [Running kaniko](#running-kaniko)
- [Running kaniko in a Kubernetes cluster](#running-kaniko-in-a-kubernetes-cluster)
- [Kubernetes secret](#kubernetes-secret)
Expand All @@ -52,30 +53,35 @@ _If you are interested in contributing to kaniko, see [DEVELOPMENT.md](DEVELOPME
- [--cache](#--cache)
- [--cache-dir](#--cache-dir)
- [--cache-repo](#--cache-repo)
- [--cache-ttl duration](#--cache-ttl-duration)
- [--cleanup](#--cleanup)
- [--context-sub-path](#--context-sub-path)
- [--digest-file](#--digest-file)
- [--oci-layout-path](#--oci-layout-path)
- [--insecure-registry](#--insecure-registry)
- [--skip-tls-verify-registry](#--skip-tls-verify-registry)
- [--cleanup](#--cleanup)
- [--force](#--force)
- [--git](#--git)
- [--image-name-with-digest-file](#--image-name-with-digest-file)
- [--insecure](#--insecure)
- [--insecure-pull](#--insecure-pull)
- [--insecure-registry](#--insecure-registry)
- [--label](#--label)
- [--log-format](#--log-format)
- [--log-timestamp](#--log-timestamp)
- [--no-push](#--no-push)
- [--oci-layout-path](#--oci-layout-path)
- [--registry-certificate](#--registry-certificate)
- [--registry-mirror](#--registry-mirror)
- [--reproducible](#--reproducible)
- [--single-snapshot](#--single-snapshot)
- [--skip-tls-verify](#--skip-tls-verify)
- [--skip-tls-verify-pull](#--skip-tls-verify-pull)
- [--skip-tls-verify-registry](#--skip-tls-verify-registry)
- [--skip-unused-stages](#--skip-unused-stages)
- [--snapshotMode](#--snapshotmode)
- [--target](#--target)
- [--tarPath](#--tarpath)
- [--target](#--target)
- [--use-new-run](#--use-new-run)
- [--verbosity](#--verbosity)
- [--whitelist-var-run](#--whitelist-var-run)
- [--label](#--label)
- [--skip-unused-stages](#--skip-unused-stages)
- [Debug Image](#debug-image)
- [Security](#security)
- [Comparison with Other Tools](#comparison-with-other-tools)
Expand Down Expand Up @@ -157,15 +163,15 @@ gsutil cp context.tar.gz gs://<bucket name>

When running kaniko, use the `--context` flag with the appropriate prefix to specify the location of your build context:

| Source | Prefix | Example |
|---------|---------|---------|
| Local Directory | dir://[path to a directory in the kaniko container] | `dir:///workspace` |
| Local Tar Gz | tar://[path to a .tar.gz in the kaniko container] | `tar://path/to/context.tar.gz` |
| Standard Input | tar://[stdin] | `tar://stdin` |
| GCS Bucket | gs://[bucket name]/[path to .tar.gz] | `gs://kaniko-bucket/path/to/context.tar.gz` |
| S3 Bucket | s3://[bucket name]/[path to .tar.gz] | `s3://kaniko-bucket/path/to/context.tar.gz` |
| Azure Blob Storage| https://[account].[azureblobhostsuffix]/[container]/[path to .tar.gz] | `https://myaccount.blob.core.windows.net/container/path/to/context.tar.gz` |
| Git Repository | git://[repository url][#reference][#commit-id] | `git://github.com/acme/myproject.git#refs/heads/mybranch#<desired-commit-id>` |
| Source | Prefix | Example |
| ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Local Directory | dir://[path to a directory in the kaniko container] | `dir:///workspace` |
| Local Tar Gz | tar://[path to a .tar.gz in the kaniko container] | `tar://path/to/context.tar.gz` |
| Standard Input | tar://[stdin] | `tar://stdin` |
| GCS Bucket | gs://[bucket name]/[path to .tar.gz] | `gs://kaniko-bucket/path/to/context.tar.gz` |
| S3 Bucket | s3://[bucket name]/[path to .tar.gz] | `s3://kaniko-bucket/path/to/context.tar.gz` |
| Azure Blob Storage | https://[account].[azureblobhostsuffix]/[container]/[path to .tar.gz] | `https://myaccount.blob.core.windows.net/container/path/to/context.tar.gz` |
| Git Repository | git://[repository url][#reference][#commit-id] | `git://github.com/acme/myproject.git#refs/heads/mybranch#<desired-commit-id>` |

If you don't specify a prefix, kaniko will assume a local directory.
For example, to use a GCS bucket called `kaniko-bucket`, you would pass in `--context=gs://kaniko-bucket/path/to/context.tar.gz`.
Expand Down Expand Up @@ -440,12 +446,12 @@ Run kaniko with the `config.json` inside `/kaniko/.docker/config.json`
To create a credentials to authenticate to Google Cloud Registry, follow these steps:
1. Create a [service account](https://console.cloud.google.com/iam-admin/serviceaccounts) or in the Google Cloud Console project you want to push the final image to with `Storage Admin` permissions.
2. Download a JSON key for this service account
3. (optional) Rename the key to `kaniko-secret.json`, if you don't rename, you have to change the name used the command(in the volume part)
4. Run the container adding the path in GOOGLE_APPLICATION_CREDENTIALS env var
3. (optional) Rename the key to `kaniko-secret.json`, if you don't rename, you have to change the name used the command(in the volume part)
4. Run the container adding the path in GOOGLE_APPLICATION_CREDENTIALS env var

```shell
docker run -ti --rm -e GOOGLE_APPLICATION_CREDENTIALS=/kaniko/config.json \
-v `pwd`:/workspace -v `pwd`/kaniko-secret.json:/kaniko/config.json:ro gcr.io/kaniko-project/executor:latest \
-v `pwd`:/workspace -v `pwd`/kaniko-secret.json:/kaniko/config.json:ro gcr.io/kaniko-project/executor:latest \
--dockerfile=Dockerfile --destination=yourimagename
```

Expand Down Expand Up @@ -535,6 +541,14 @@ 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._

#### --cache-ttl duration

Cache timeout in hours. Defaults to two weeks.

#### --cleanup

Set this flag to clean the filesystem at the end of the build.

#### --context-sub-path

Set a sub path within the given `--context`.
Expand All @@ -553,55 +567,74 @@ will write the digest to that file, which is picked up by
Kubernetes automatically as the `{{.state.terminated.message}}`
of the container.

#### --oci-layout-path
#### --force

Set this flag to specify a directory in the container where the OCI image
layout of a built image will be placed. This can be used to automatically
track the exact image built by Kaniko.
Force building outside of a container

For example, to surface the image digest built in a
[Tekton task](https://github.com/tektoncd/pipeline/blob/v0.6.0/docs/resources.md#surfacing-the-image-digest-built-in-a-task),
this flag should be set to match the image resource `outputImageDir`.
#### --git

_Note: Depending on the built image, the media type of the image manifest might be either
`application/vnd.oci.image.manifest.v1+json` or `application/vnd.docker.distribution.manifest.v2+json`._
Branch to clone if build context is a git repository (default branch=,single-branch=false,recurse-submodules=false)

#### --insecure-registry
#### --image-name-with-digest-file

Set this flag to use plain HTTP requests when accessing a registry. It is supposed to be used for testing purposes only and should not be used in production!
You can set it multiple times for multiple registries.
Specify a file to save the image name w/ digest of the built image to.

#### --skip-tls-verify-registry
#### --insecure

Set this flag to skip TLS certificate validation when accessing a registry. It is supposed to be used for testing purposes only and should not be used in production!
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!

#### --insecure-registry

Set this flag to use plain HTTP requests when accessing a registry. It is supposed to be used for testing purposes only and should not be used in production!
You can set it multiple times for multiple registries.

#### --cleanup
#### --label

Set this flag to clean the filesystem at the end of the build.
Set this flag as `--label key=value` to set some metadata to the final image. This is equivalent as using the `LABEL` within the Dockerfile.

#### --insecure
#### --log-format

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!
Set this flag as `--log-format=<text|color|json>` to set the log format. Defaults to `color`.

#### --insecure-pull
#### --log-timestamp

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!
Set this flag as `--log-timestamp=<true|false>` to add timestamps to `<text|color>` log format. Defaults to `false`.

#### --no-push

Set this flag if you only want to build the image, without pushing to a registry.

#### --oci-layout-path

Set this flag to specify a directory in the container where the OCI image
layout of a built image will be placed. This can be used to automatically
track the exact image built by Kaniko.

For example, to surface the image digest built in a
[Tekton task](https://github.com/tektoncd/pipeline/blob/v0.6.0/docs/resources.md#surfacing-the-image-digest-built-in-a-task),
this flag should be set to match the image resource `outputImageDir`.

_Note: Depending on the built image, the media type of the image manifest might be either
`application/vnd.oci.image.manifest.v1+json` or `application/vnd.docker.distribution.manifest.v2+json`._


#### --registry-certificate

Set this flag to provide a certificate for TLS communication with a given registry.

Expected format is `my.registry.url=/path/to/the/certificate.cert`


#### --registry-mirror

Set this flag if you want to use a registry mirror instead of default `index.docker.io`.



#### --reproducible

Set this flag to strip timestamps out of the built image and make it reproducible.
Expand All @@ -610,6 +643,7 @@ Set this flag to strip timestamps out of the built image and make it reproducibl

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 pushing to a registry. It is supposed to be used for testing purposes only and should not be used in production!
Expand All @@ -618,46 +652,48 @@ Set this flag to skip TLS certificate validation when pushing to a registry. It

Set this flag to skip TLS certificate validation when pulling from a registry. It is supposed to be used for testing purposes only and should not be used in production!

#### --skip-tls-verify-registry

Set this flag to skip TLS certificate validation when accessing a registry. It is supposed to be used for testing purposes only and should not be used in production!
You can set it multiple times for multiple registries.

#### --skip-unused-stages

This flag builds only used stages if defined to `true`.
Otherwise it builds by default all stages, even the unnecessaries ones until it reaches the target stage / end of Dockerfile

#### --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)).
You can set the `--snapshotMode=<full (default), redo, time>` flag to set how kaniko will snapshot the filesystem.

#### --target
* If `--snapshot=full` is set, the full file contents and metadata are considered when snapshotting. This is the least performant option, but also the most robust.

Set this flag to indicate which build stage is the target build stage.
* If `--snapshotMode=redo` is set, the file mtime, size, mode, owner uid and gid will be considered when snapshotting. This may be up to 50% faster than "full", particularly if your project has a large number files.

* If `--snapshotMode=time` is set, only file mtime will be considered when snapshotting (see
[limitations related to mtime](#mtime-and-snapshotting)).

#### --tarPath

Set this flag as `--tarPath=<path>` to save the image as a tarball at path instead of pushing the image.
You need to set `--destination` as well (for example `--destination=image`).

#### --verbosity
#### --target

Set this flag as `--verbosity=<panic|fatal|error|warn|info|debug|trace>` to set the logging level. Defaults to `info`.
Set this flag to indicate which build stage is the target build stage.

#### --log-format
#### --use-new-run

Set this flag as `--log-format=<text|color|json>` to set the log format. Defaults to `color`.
Use the experimental run implementation for detecting changes without requiring file system snapshots. In some cases, this may improve build performance by 75%.

#### --log-timestamp
#### --verbosity

Set this flag as `--log-timestamp=<true|false>` to add timestamps to `<text|color>` log format. Defaults to `false`.
Set this flag as `--verbosity=<panic|fatal|error|warn|info|debug|trace>` to set the logging level. Defaults to `info`.

#### --whitelist-var-run

Ignore /var/run when taking image snapshot. Set it to false to preserve /var/run/* in destination image. (Default true).

#### --label

Set this flag as `--label key=value` to set some metadata to the final image. This is equivalent as using the `LABEL` within the Dockerfile.

#### --skip-unused-stages

This flag builds only used stages if defined to `true`.
Otherwise it builds by default all stages, even the unnecessaries ones until it reaches the target stage / end of Dockerfile

### Debug Image

The kaniko executor image is based on scratch and doesn't contain a shell.
Expand Down
2 changes: 1 addition & 1 deletion cmd/executor/cmd/root.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ func addKanikoOptionsFlags() {
RootCmd.PersistentFlags().BoolVarP(&opts.IgnoreVarRun, "whitelist-var-run", "", true, "Ignore /var/run directory when taking image snapshot. Set it to false to preserve /var/run/ in destination image. (Default true).")
RootCmd.PersistentFlags().VarP(&opts.Labels, "label", "", "Set metadata for an image. Set it repeatedly for multiple labels.")
RootCmd.PersistentFlags().BoolVarP(&opts.SkipUnusedStages, "skip-unused-stages", "", false, "Build only used stages if defined to true. Otherwise it builds by default all stages, even the unnecessaries ones until it reaches the target stage / end of Dockerfile")
RootCmd.PersistentFlags().BoolVarP(&opts.RunV2, "use-new-run", "", false, "Experimental run command to detect file system changes. This new run command does no rely on snapshotting to detect changes.")
RootCmd.PersistentFlags().BoolVarP(&opts.RunV2, "use-new-run", "", false, "Use the experimental run implementation for detecting changes without requiring file system snapshots.")
RootCmd.PersistentFlags().Var(&opts.Git, "git", "Branch to clone if build context is a git repository")
}

Expand Down