diff --git a/DOCS.md b/DOCS.md
index 6c7574c..6244ea4 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -8,9 +8,24 @@ Registry: https://hub.docker.com/r/target/vela-docker
## Usage
-**NOTE: It is not recommended to use `latest` as the tag for the Docker image. Users should use a semantically versioned tag instead.**
+> **NOTE:**
+>
+> Users should refrain from using latest as the tag for the Docker image.
+>
+> It is recommended to use a semantically versioned tag instead.
-Sample of building and publishing an image:
+Samples of building and publishing an image:
+
+```yaml
+steps:
+ - name: publish_hello-world
+ image: target/vela-docker:latest
+ pull: always
+ parameters:
+ registry: index.docker.io
+ repo: octocat/hello-world
+ tags: [ latest ]
+```
```yaml
steps:
@@ -22,6 +37,8 @@ steps:
tags: [ index.docker.io/octocat/hello-world:latest ]
```
+> **NOTE:** The two above samples are functionally equivalent.
+
Sample of building an image without publishing:
```diff
@@ -30,9 +47,10 @@ steps:
image: target/vela-docker:latest
pull: always
parameters:
- registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world:latest ]
+ dry_run: true
+ registry: index.docker.io
+ repo: octocat/hello-world
+ tags: [ latest ]
```
Sample of building and publishing an image with custom tags:
@@ -44,9 +62,11 @@ steps:
pull: always
parameters:
registry: index.docker.io
+ repo: octocat/hello-world
+- tags: [ latest ]
+ tags:
-+ - index.docker.io/octocat/hello-world:latest
-+ - index.docker.io/octocat/hello-world:1
++ - latest
++ - octocat/hello-world:1
+ - index.docker.io/octocat/hello-world:foobar
```
@@ -58,10 +78,11 @@ steps:
image: target/vela-docker:latest
pull: always
parameters:
- registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world ]
+ build_args:
+ - FOO=bar
+ registry: index.docker.io
+ repo: octocat/hello-world
+ tags: [ latest ]
```
Sample of building and publishing an image with image caching:
@@ -72,9 +93,10 @@ steps:
image: target/vela-docker:latest
pull: always
parameters:
- registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world:latest ]
+ cache_from: index.docker.io/octocat/hello-world
+ registry: index.docker.io
+ repo: octocat/hello-world
+ tags: [ latest ]
```
Sample of building and publishing with custom daemon settings:
@@ -85,10 +107,11 @@ steps:
image: target/vela-docker:latest
pull: always
parameters:
- registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world:latest ]
+ daemon:
-+ registry_mirror: mirror.index.docker.io
++ registry_mirrors: mirror.index.docker.io
+ registry: index.docker.io
+ repo: octocat/hello-world
+ tags: [ latest ]
```
## Secrets
@@ -107,7 +130,8 @@ steps:
+ secrets: [ docker_username, docker_password ]
parameters:
registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world:latest ]
+ repo: octocat/hello-world
+ tags: [ latest ]
- username: octocat
- password: superSecretPassword
```
@@ -135,7 +159,8 @@ steps:
pull: always
parameters:
registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world:latest ]
+ repo: octocat/hello-world
+ tags: [ latest ]
- username: octocat
- password: superSecretPassword
```
@@ -150,97 +175,97 @@ steps:
> Any values set from a file take precedence over values set from the environment.
>
> By default [build kit](https://docs.docker.com/develop/develop-images/build_enhancements/) is on; it can be turned off by setting `DOCKER_BUILDKIT=0` in the environment.
->
-> `key.key` syntax signifies a new yaml object within the definition.
+>
+> The `key.key` syntax signifies a new yaml object within the definition.
The following parameters are used to configure the image:
-| Name | Description | Required | Default | Environment Variables |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------- |
-| `add_hosts` | enables adding a custom host-to-IP mapping - format (host:ip) | `false` | N/A | `PARAMETER_ADD_HOSTS`
`DOCKER_ADD_HOSTS` |
-| `build_args` | enables setting build-time variables | `false` | N/A | `PARAMETER_BUILD_ARGS`
`DOCKER_BUILD_ARGS` |
-| `cache_from` | enables setting images to consider as cache sources | `false` | N/A | `PARAMETER_CACHE_FROM`
`DOCKER_CACHE_FROM` |
-| `cgroup_parent` | enables setting an optional parent cgroup for the container | `false` | N/A | `PARAMETER_CGROUP_PARENT`
`DOCKER_CGROUP_PARENT` |
-| `compress` | enables setting compression the build context using gzip | `false` | N/A | `PARAMETER_COMPRESS`
`DOCKER_COMPRESS` |
-| `context` | enables setting the build context | `true` | `.` | `PARAMETER_CONTEXT`
`DOCKER_CONTEXT` |
-| `cpu` | enables setting the cpu parameter, see [cpu](#cpu) settings below | `false` | N/A | `PARAMETER_CPU`
`DOCKER_CPU` |
-| `daemon` | enables setting the daemon parameter, see [daemon](#daemon) settings below | `false` | N/A | `PARAMETER_DAEMON`
`DOCKER_DAEMON` |
-| `disable_content_trust` | enables skipping image verification | `false` | N/A | `PARAMETER_DISABLE_CONTENT_TRUST`
`DOCKER_DISABLE_CONTENT_TRUST` |
-| `dry_run` | enables building the image without publishing | `false` | `false` | `PARAMETER_DRY_RUN`
`DOCKER_DRY_RUN` |
-| `file` | enables setting the name of the Dockerfile | `false` | N/A | `PARAMETER_FILE`
`DOCKER_FILE` |
-| `force_rm` | enables setting always remove on intermediate containers | `false` | N/A | `PARAMETER_FORCE_RM`
`DOCKER_FORCE_RM` |
-| `image_id_file` | enables setting writing the image ID to the file | `false` | N/A | `PARAMETER_IMAGE_ID_FILE`
`DOCKER_IMAGE_ID_FILE` |
-| `isolation` | enables container isolation technology | `false` | N/A | `PARAMETER_ISOLATION`
`DOCKER_ISOLATION` |
-| `labels` | enables setting metadata for an image | `false` | N/A | `PARAMETER_LABELS`
`DOCKER_LABELS` |
-| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`DOCKER_LOG_LEVEL` |
-| `memory` | enables setting a memory limit | `false` | N/A | `PARAMETER_MEMORY`
`DOCKER_MEMORY` |
-| `memory_swaps` | enables setting a swap limit equal to memory plus swap: '-1' to enable unlimited swap | `false` | N/A | `PARAMETER_MEMORY_SWAPS`
`DOCKER_MEMORY_SWAPS` |
-| `network` | enables setting the networking mode for the RUN instructions during build | `false` | N/A | `PARAMETER_NETWORK`
`DOCKER_NETWORK` |
-| `no_cache` | enables setting not use cache when building the image | `false` | N/A | `PARAMETER_NO_CACHE`
`DOCKER_NO_CACHE` |
-| `outputs` | enables setting an output destination - format (type=local,dest=path) | `false` | N/A | `PARAMETER_OUTPUTS`
`DOCKER_OUTPUTS` |
-| `password` | password for communication with the registry | `true` | N/A | `PARAMETER_PASSWORD`
`DOCKER_PASSWORD` |
-| `platform` | enables setting a platform if server is multi-platform capable | `false` | N/A | `PARAMETER_PLATFORM`
`DOCKER_PLATFORM` |
-| `progress` | enables setting type of progress output - options (auto\|plain\|tty) | `false` | N/A | `PARAMETER_PROGRESS`
`DOCKER_PROGRESS` |
-| `pull` | enables always attempting to pull a newer version of the image | `false` | N/A | `PARAMETER_PULL`
`DOCKER_PULL` |
-| `quiet` | enables suppressing the build output and print image ID on success | `false` | N/A | `PARAMETER_QUIET`
`DOCKER_QUIET` |
-| `registry` | Docker registry address to communicate with | `true` | `index.docker.io` | `PARAMETER_REGISTRY`
`DOCKER_REGISTRY` |
-| `remove` | enables removing the intermediate containers after a successful build | `false` | N/A | `PARAMETER_REMOVE`
`DOCKER_REMOVE` |
-| `repo` | Docker repository for the image | `false` | N/A | `PARAMETER_REPO`
`DOCKER_REPO` |
-| `secrets` | enables setting a secret file to expose to the build - format (id=mysecret,src=/local/secret) | `false` | N/A | `PARAMETER_SECRETS`
`DOCKER_SECRETS` |
-| `security_opts` | enables setting security options | `false` | N/A | `PARAMETER_SECURITY_OPTS`
`DOCKER_SECURITY_OPTS` |
-| `shm_sizes` | enables setting the size of /dev/shm | `false` | N/A | `PARAMETER_SHM_SIZES`
`DOCKER_SHM_SIZES` |
-| `squash` | enables setting squash newly built layers into a single new layer | `false` | N/A | `PARAMETER_SQUASH`
`DOCKER_SQUASH` |
-| `ssh_components` | enables setting an ssh agent socket or keys to expose to the build - format (default\|[=\|[,]]) | `false` | N/A | `PARAMETER_SSH_COMPONENTS`
`DOCKER_SSH_COMPONENTS` |
-| `stream` | enables streaming attaches to server to negotiate build context | `false` | N/A | `PARAMETER_STREAM`
`DOCKER_STREAM` |
-| `tags` | enables naming and optionally a tagging - format (name:tag) | `true` | N/A | `PARAMETER_TAGS`
`DOCKER_TAGS` |
-| `target` | enables setting the target build stage to build. | `false` | N/A | `PARAMETER_TARGET`
`DOCKER_TARGET` |
-| `ulimits` | enables setting ulimit options | `false` | N/A | `PARAMETER_ULIMITS`
`DOCKER_ULIMITS` |
-| `username` | user name for communication with the registry | `true` | N/A | `PARAMETER_USERNAME`
`DOCKER_USERNAME` |
+| Name | Description | Required | Default | Environment Variables |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------- |
+| `add_hosts` | set a custom host-to-IP mapping - format (host:ip) | `false` | N/A | `PARAMETER_ADD_HOSTS`
`DOCKER_ADD_HOSTS` |
+| `build_args` | set variables to pass to the image at build-time | `false` | N/A | `PARAMETER_BUILD_ARGS`
`DOCKER_BUILD_ARGS` |
+| `cache_from` | set of images to consider as cache sources | `false` | N/A | `PARAMETER_CACHE_FROM`
`DOCKER_CACHE_FROM` |
+| `cgroup_parent` | set a parent cgroup for the container | `false` | N/A | `PARAMETER_CGROUP_PARENT`
`DOCKER_CGROUP_PARENT` |
+| `compress` | enable compressing the build context using gzip | `false` | `false` | `PARAMETER_COMPRESS`
`DOCKER_COMPRESS` |
+| `context` | set of files and/or directory to build the image from | `true` | `.` | `PARAMETER_CONTEXT`
`DOCKER_CONTEXT` |
+| `cpu` | set the cpu parameter, see [cpu](#cpu) settings below | `false` | N/A | `PARAMETER_CPU`
`DOCKER_CPU` |
+| `daemon` | set the daemon parameter, see [daemon](#daemon) settings below | `false` | N/A | `PARAMETER_DAEMON`
`DOCKER_DAEMON` |
+| `disable_content_trust` | enable skipping verification of the image | `false` | `true` | `PARAMETER_DISABLE_CONTENT_TRUST`
`DOCKER_DISABLE_CONTENT_TRUST` |
+| `dry_run` | enable building the image without publishing | `false` | `false` | `PARAMETER_DRY_RUN`
`DOCKER_DRY_RUN` |
+| `file` | set the name of the Dockerfile | `false` | N/A | `PARAMETER_FILE`
`DOCKER_FILE` |
+| `force_rm` | enable always removing the intermediate containers after a successful build | `false` | `false` | `PARAMETER_FORCE_RM`
`DOCKER_FORCE_RM` |
+| `image_id_file` | set the file to write the image ID to | `false` | N/A | `PARAMETER_IMAGE_ID_FILE`
`DOCKER_IMAGE_ID_FILE` |
+| `isolation` | set container isolation technology | `false` | N/A | `PARAMETER_ISOLATION`
`DOCKER_ISOLATION` |
+| `labels` | set metadata for an image | `false` | N/A | `PARAMETER_LABELS`
`DOCKER_LABELS` |
+| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`DOCKER_LOG_LEVEL` |
+| `memory` | set memory limit | `false` | N/A | `PARAMETER_MEMORY`
`DOCKER_MEMORY` |
+| `memory_swaps` | set the swap limit equal to memory plus swap: '-1' to enable unlimited swap | `false` | N/A | `PARAMETER_MEMORY_SWAPS`
`DOCKER_MEMORY_SWAPS` |
+| `network` | set the networking mode for the RUN instructions during build | `false` | N/A | `PARAMETER_NETWORK`
`DOCKER_NETWORK` |
+| `no_cache` | disable caching when building the image | `false` | `false` | `PARAMETER_NO_CACHE`
`DOCKER_NO_CACHE` |
+| `output` | set the output destination - format (type=local,dest=path) | `false` | N/A | `PARAMETER_OUTPUTS`
`DOCKER_OUTPUTS` |
+| `password` | set password for communication with the registry | `true` | N/A | `PARAMETER_PASSWORD`
`DOCKER_PASSWORD` |
+| `platform` | set a platform if server is multi-platform capable | `false` | N/A | `PARAMETER_PLATFORM`
`DOCKER_PLATFORM` |
+| `progress` | set type of progress output - options (auto\|plain\|tty) | `false` | N/A | `PARAMETER_PROGRESS`
`DOCKER_PROGRESS` |
+| `pull` | enable always attempting to pull a newer version of the image | `false` | `false` | `PARAMETER_PULL`
`DOCKER_PULL` |
+| `quiet` | enable suppressing the build output and print image ID on success | `false` | `false` | `PARAMETER_QUIET`
`DOCKER_QUIET` |
+| `registry` | set Docker registry address to communicate with | `true` | `index.docker.io` | `PARAMETER_REGISTRY`
`DOCKER_REGISTRY` |
+| `remove` | enable removing the intermediate containers after a successful build | `false` | `true` | `PARAMETER_REMOVE`
`DOCKER_REMOVE` |
+| `repo` | set Docker repository for the image | `false` | N/A | `PARAMETER_REPO`
`DOCKER_REPO` |
+| `secret` | set secret file to expose to the build (only if BuildKit enabled) - format (id=mysecret,src=/local/secret) | `false` | N/A | `PARAMETER_SECRETS`
`DOCKER_SECRETS` |
+| `security_opts` | set options for security | `false` | N/A | `PARAMETER_SECURITY_OPTS`
`DOCKER_SECURITY_OPTS` |
+| `shm_sizes` | set the size of /dev/shm | `false` | N/A | `PARAMETER_SHM_SIZES`
`DOCKER_SHM_SIZES` |
+| `squash` | enable squashing newly built layers into a single new layer | `false` | `false` | `PARAMETER_SQUASH`
`DOCKER_SQUASH` |
+| `ssh_components` | set SSH agent socket or keys to expose to the build (only if BuildKit enabled) - format (default\|[=\|[,]]) | `false` | N/A | `PARAMETER_SSH_COMPONENTS`
`DOCKER_SSH_COMPONENTS` |
+| `stream` | enable stream attaching to the server to negotiate build context | `false` | `false` | `PARAMETER_STREAM`
`DOCKER_STREAM` |
+| `tags` | set the tags for the Docker image - format (name:tag) | `true` | N/A | `PARAMETER_TAGS`
`DOCKER_TAGS` |
+| `target` | set the target build stage to build | `false` | N/A | `PARAMETER_TARGET`
`DOCKER_TARGET` |
+| `ulimits` | set options for ulimits | `false` | N/A | `PARAMETER_ULIMITS`
`DOCKER_ULIMITS` |
+| `username` | set user name for communication with the registry | `true` | N/A | `PARAMETER_USERNAME`
`DOCKER_USERNAME` |
### CPU
The following settings are used to configure the `cpu` parameter:
-| Name | Description | Required | Default |
-| ---------- | ------------------------------------------------------------------------ | -------- | ------- |
-| `period` | enables setting limits on the CPU CFS (Completely Fair Scheduler) period | `false` | N/A |
-| `quota` | enables setting limit on the CPU CFS (Completely Fair Scheduler) quota | `false` | N/A |
-| `shares` | enables setting CPU shares (relative weight) | `false` | N/A |
-| `set_cpus` | enables setting CPUs in which to allow execution (0-3, 0,1) | `false` | N/A |
-| `set_mems` | enables setting MEMs in which to allow execution (0-3, 0,1) | `false` | N/A |
+| Name | Description | Required | Default |
+| ---------- | ----------------------------------------------------------- | -------- | ------- |
+| `period` | set limit on the CPU CFS (Completely Fair Scheduler) period | `false` | N/A |
+| `quota` | set limit on the CPU CFS (Completely Fair Scheduler) quota | `false` | N/A |
+| `shares` | set CPU shares (relative weight) | `false` | N/A |
+| `set_cpus` | set CPUs in which to allow execution (0-3, 0,1) | `false` | N/A |
+| `set_mems` | set MEMs in which to allow execution (0-3, 0,1) | `false` | N/A |
### Daemon
The following settings are used to configure the `daemon` parameter:
-| Name | Description | Required | Default |
-| --------------------- | ---------------------------------------------------------------------------- | -------- | ------- |
-| `bip` | enables specifying a network bridge IP | `false` | N/A |
-| `dns` | enables setting the DNS settings, see [dns](#dns) settings below | `false` | N/A |
-| `experimental` | enables experimental features | `false` | N/A |
-| `insecure_registries` | enables insecure registry communication | `false` | N/A |
-| `ipv6` | enables IPv6 networking | `false` | N/A |
-| `mtu` | enables setting the containers network MTU | `false` | N/A |
-| `registry_mirrors` | enables setting a preferred Docker registry mirror | `false` | N/A |
-| `storage` | enables setting the storage settings, see [storage](#storage) settings below | `false` | N/A |
+| Name | Description | Required | Default |
+| --------------------- | ---------------------------------------------------------------- | -------- | ------- |
+| `bip` | set a network bridge IP | `false` | N/A |
+| `dns` | set the DNS settings, see [dns](#dns) settings below | `false` | N/A |
+| `experimental` | enable experimental features | `false` | N/A |
+| `insecure_registries` | set the insecure Docker registries | `false` | N/A |
+| `ipv6` | enable IPv6 networking | `false` | N/A |
+| `mtu` | set the network MTU for the contain | `false` | N/A |
+| `registry_mirrors` | set the Docker registry mirrors | `false` | N/A |
+| `storage` | set the storage settings, see [storage](#storage) settings below | `false` | N/A |
### DNS
The following settings are used to configure the `dns daemon` setting:
-| Name | Description | Required | Default |
-| ---------- | --------------------------------------------- | -------- | ------- |
-| `servers` | enables setting the DNS server to use | `false` | N/A |
-| `searches` | enables setting the DNS search domains to use | `false` | N/A |
+| Name | Description | Required | Default |
+| ---------- | -------------------------- | -------- | ------- |
+| `servers` | set the DNS nameservers | `false` | N/A |
+| `searches` | set the DNS search domains | `false` | N/A |
### Storage
The following settings are used to configure the `storage daemon` setting:
-| Name | Description | Required | Default |
-| --------- | ------------------------------------------------------- | -------- | ------- |
-| `drivers` | enables setting an alternate storage driver | `false` | N/A |
-| `opts` | enables setting options on the alternate storage driver | `false` | N/A |
+| Name | Description | Required | Default |
+| -------- | -------------------------------------- | -------- | ------- |
+| `driver` | set the storage driver for the daemon | `false` | N/A |
+| `opts` | set the storage options for the daemon | `false` | N/A |
## Template
@@ -257,7 +282,8 @@ steps:
pull: always
parameters:
registry: index.docker.io
- tags: [ index.docker.io/octocat/hello-world:latest ]
+ repo: octocat/hello-world
+ tags: [ latest ]
+ log_level: trace
```