From 21381d1ecfeffdf7b887dfd33acb6b45cf549640 Mon Sep 17 00:00:00 2001 From: Jordan Brockopp Date: Mon, 5 Apr 2021 09:10:08 -0500 Subject: [PATCH] chore: update parameters and samples in docs (#31) --- DOCS.md | 194 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 110 insertions(+), 84 deletions(-) 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 ```