From b59e29773c31bd173e3e23058fd960c3027da1eb Mon Sep 17 00:00:00 2001 From: Mike Brown Date: Mon, 5 Apr 2021 21:48:35 -0500 Subject: [PATCH 1/4] adds description for hosts.toml Signed-off-by: Mike Brown --- docs/hosts.md | 273 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 docs/hosts.md diff --git a/docs/hosts.md b/docs/hosts.md new file mode 100644 index 000000000..357854796 --- /dev/null +++ b/docs/hosts.md @@ -0,0 +1,273 @@ + +# Registry Configuration - Introduction + +Configuring registries will be done by specifying (optionally) a `hosts.toml` file for +each desired registry host in a configuration directory. **Updates under this directory +do not require restarting the containerd daemon.** + +## Specifying the Configuration Directory + +## Using Host Namespace Configs with CTR + +When pulling via `ctr` use the `--hosts-dir` option: +``` +ctr images pull --hosts-dir "/etc/containerd/certs.d" +``` + +## CRI +_The old CRI config pattern for specifying registry.mirrors and registry.configs has +been **DEPRECATED**._ You should now point your registry `config_path` to path where your +`hosts.toml` files are located. + +Modify your `config.toml` (default location: `/etc/containerd/config.toml`) as follows: +```toml +[plugins."io.containerd.grpc.v1.cri".registry] + config_path = "/etc/containerd/certs.d" +``` + +## Support for Docker's Certificate File Pattern + +If no hosts.toml configuration exists in the host directory, it will fallback to check +certificate files based on [Docker's certificate file pattern](https://docs.docker.com/engine/reference/commandline/dockerd/#insecure-registries) +(".crt" files for CA certificates and ".cert"/".key" files for client certificates). + +## Registry Host Namespace + +A registry host is the location where container images and artifacts are sourced. These +registry hosts may be local or remote and are typically accessed via http/https using the +[OCI distribution specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). +A registry mirror is not a registry host but these mirrors can also be used to pull content. +Registry hosts are typically refered to by their internet domain names, aka. registry +host names. For example, docker.io, quay.io, gcr.io, and ghcr.io. + +A registry host namespace is, for the purpose of containerd registry configuration, a +path to the `hosts.toml` file specified by the registry host name, or ip address, and an +optional port identifier. When makeing a pull request for an image the format is +typically as follows: +``` +pull [registry_host_name|IP address][:port][/v2][/org_path][:tag|@DIGEST] +``` + +The registry host namespace portion is `[registry_host_name|IP address][:port]`. Example +tree for docker.io: + +``` +$ tree /etc/containerd/certs.d +/etc/containerd/certs.d +└── docker.io + └── hosts.toml +``` + +The `/v2` portion of the pull request format shown above refers to the version of the +distribution api. If not included in the pull request, `/v2` is added by default for all +clients compliant to the distribution specification linked above. + +For example when pulling image_name:tag from a private registry named myregistry.io over +port 5000: +``` +pull myregistry.io:5000/image_name:tag +``` +The pull will resolve to `https://myregistry.io:5000/v2/image_name:tag` + +# Registry Configuration - Examples + +### Simple (default) Host Config for Docker +Here is a simple example for a default registry hosts configuration. Set +`config_path = "/etc/containerd/certs.d"` in your config.toml for containerd. +Make a directory tree at the config path that includes `docker.io` as a directory +representing the host namespace to be configured. Then add a `hosts.toml` file +in the `docker.io` to configure the host namespace. It should look like this: + +``` +$ tree /etc/containerd/certs.d +/etc/containerd/certs.d +└── docker.io + └── hosts.toml + +$ cat /etc/containerd/certs.d/docker.io/hosts.toml +server = "https://docker.io" + +[host."https://registry-1.docker.io"] + capabilities = ["pull", "resolve"] +``` + +### Setup a Local Mirror for Docker + +``` +server = "https://registry-1.docker.io" # Exclude this to not use upstream + +[host."https://public-mirror.example.com"] + capabilities = ["pull"] # Requires less trust, won't resolve tag to digest from this host +[host."https://docker-mirror.internal"] + capabilities = ["pull", "resolve"] + ca = "docker-mirror.crt" # Or absolute path /etc/containerd/certs.d/docker.io/docker-mirror.crt +``` + +### Bypass TLS Verification Example + +To bypass the TLS verification for a private registry at `192.168.31.250:5000` + +Create a path and `hosts.toml` text at the path "/etc/containerd/certs.d/docker.io/hosts.toml" with following or similar contents: + +```toml +server = "https://registry-1.docker.io" + +[host."http://192.168.31.250:5000"] + capabilities = ["pull", "resolve", "push"] + skip_verify = true +``` + +# hosts.toml Content Description - Detail + +For each registry host namespace directory in your registry `config_path` you may +include a `hosts.toml` configuration file. The following root level toml fields +apply to the registry host namespace: + +*** Note: All paths specified in the `hosts.toml` file may be absolute or relative +to the `hosts.toml` file. + +## server field +`server` specifies the default server for this registry host namespace. When +`host`(s) are specified, the hosts are tried first in the order listed. +``` +server = "https://docker.io" +``` + +## capabilities field + +`capabilities` is an optional setting for specifying what operations a host is +capable of performing. Include only the values that apply. +``` +capabilities = ["pull", "resolve", "push"] +``` + +capabilities (or Host capabilities) represent the capabilities of the registry host. +This also represents the set of operations for which the registry host may be trusted +to perform. + +For example, pushing is a capability which should only be performed on an upstream +source, not a mirror. + +Resolving (the process of converting a name into a digest) +must be considered a trusted operation and only done by +a host which is trusted (or more preferably by secure process +which can prove the provenance of the mapping). + +A public mirror should never be trusted to do a resolve action. + +| Registry Type | Pull | Resolve | Push | +|------------------|------|---------|------| +| Public Registry | yes | yes | yes | +| Private Registry | yes | yes | yes | +| Public Mirror | yes | no | no | +| Private Mirror | yes | yes | no | + +## ca field + +`ca` (Certificate Authority Certification) can be set to a path or an array of +paths each pointing to a ca file for use in authenticating with the registry +namespace. +``` +ca = "/etc/certs/mirror.pem" +``` +or +``` +ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"] +``` + +## client field + +`client` certificates are configured as follows + +`a path`: +``` +client = "/etc/certs/client.pem" +``` + +`an array of paths`: +``` +client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"] +``` + +`an array of pairs of paths`: +``` +client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]] +``` + +## skip_verify field + +`skip_verify` set this flag to `true` to skip the registry certificate +verification for this registry host namespace. (Defaults to `false`) +``` +skip_verify = false +``` + +## header fields (in the toml table format) + +`[header]` contains some number of keys where each key is to one of a string or + +`an array of strings as follows`: +``` +[header] + x-custom-1 = "custom header" +``` + +`or` +``` +[header] + x-custom-1 = ["custom header part a","part b"] +``` + +`or` +``` +[header] + x-custom-1 = "custom header", + x-custom-1-2 = "another custom header" +``` + +## host field(s) (in the toml table format) + +`[host]."https://namespace"` and `[host].http://namespace` entries in the +`hosts.toml` configuration are registry namespaces used in lieu of the default +registry host namespace. These hosts are sometimes called mirrors because they +may contain a copy of the container images and artifacts you are attempting to +retrieve from the default registry. Each `host`/`mirror` namespace is also +configured in much the same way as the default registry namespace. Notably the +`server` is not specified in the `host` description because it is specified in +the namespace. Here are a few rough examples configuring host mirror namespaces +for this registry host namespace: +``` +[host."https://mirror.registry"] + capabilities = ["pull"] + ca = "/etc/certs/mirror.pem" + skip_verify = false + [host."https://mirror.registry".header] + x-custom-2 = ["value1", "value2"] + +[host."https://mirror-bak.registry/us"] + capabilities = ["pull"] + skip_verify = true + +[host."http://mirror.registry"] + capabilities = ["pull"] + +[host."https://test-1.registry"] + capabilities = ["pull", "resolve", "push"] + ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"] + client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]] + +[host."https://test-2.registry"] + client = "/etc/certs/client.pem" + +[host."https://test-3.registry"] + client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"] +``` + +**Further, recursion is not supported in the specification of host mirror +namespaces in the hosts.toml file. Thus the following is not allowed/supported:** +``` +[host."http://mirror.registry"] + capabilities = ["pull"] + [host."http://double-mirror.registry"] + capabilities = ["pull"] +``` From 0ba7303ee8c34f8f85c4679832f3b00dc36353ea Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Thu, 6 May 2021 09:28:42 -0700 Subject: [PATCH 2/4] Prepare default branch rename Use renamed branch for containerd/project Signed-off-by: Derek McGowan --- .github/workflows/ci.yml | 2 ++ README.md | 8 ++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bc77c9802..2799a780f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,10 +2,12 @@ name: CI on: push: branches: + - main - master - 'release/**' pull_request: branches: + - main - master - 'release/**' diff --git a/README.md b/README.md index 9d2821bf6..755650a5e 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ We are a large inclusive OSS project that is welcoming help of any kind shape or * Documentation help is needed to make the product easier to consume and extend. * We need OSS community outreach / organizing help to get the word out; manage and create messaging and educational content; and to help with social media, community forums/groups, and google groups. -* We are actively inviting new [security advisors](https://github.com/containerd/project/blob/master/GOVERNANCE.md#security-advisors) to join the team. +* We are actively inviting new [security advisors](https://github.com/containerd/project/blob/main/GOVERNANCE.md#security-advisors) to join the team. * New sub-projects are being created, core and non-core that could use additional development help. * Each of the [containerd projects](https://github.com/containerd) has a list of issues currently being worked on or that need help resolving. - If the issue has not already been assigned to someone, or has not made recent progress and you are interested, please inquire. @@ -323,9 +323,9 @@ However, all projects within the repo have common maintainership, governance, an guidelines which are stored in a `project` repository commonly for all containerd projects. Please find all these core project documents, including the: - * [Project governance](https://github.com/containerd/project/blob/master/GOVERNANCE.md), - * [Maintainers](https://github.com/containerd/project/blob/master/MAINTAINERS), - * and [Contributing guidelines](https://github.com/containerd/project/blob/master/CONTRIBUTING.md) + * [Project governance](https://github.com/containerd/project/blob/main/GOVERNANCE.md), + * [Maintainers](https://github.com/containerd/project/blob/main/MAINTAINERS), + * and [Contributing guidelines](https://github.com/containerd/project/blob/main/CONTRIBUTING.md) information in our [`containerd/project`](https://github.com/containerd/project) repository. From 6e249b1aea69f30969ab3452dc19e78300dc3c06 Mon Sep 17 00:00:00 2001 From: Mike Brown Date: Tue, 4 May 2021 04:49:29 -0500 Subject: [PATCH 3/4] adds credentials description Signed-off-by: Mike Brown --- docs/hosts.md | 69 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 15 deletions(-) diff --git a/docs/hosts.md b/docs/hosts.md index 357854796..8df0e98d1 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -2,21 +2,21 @@ # Registry Configuration - Introduction Configuring registries will be done by specifying (optionally) a `hosts.toml` file for -each desired registry host in a configuration directory. **Updates under this directory -do not require restarting the containerd daemon.** +each desired registry host in a configuration directory. **Note**: Updates under this directory +do not require restarting the containerd daemon. ## Specifying the Configuration Directory -## Using Host Namespace Configs with CTR +### Using Host Namespace Configs with CTR When pulling via `ctr` use the `--hosts-dir` option: ``` ctr images pull --hosts-dir "/etc/containerd/certs.d" ``` -## CRI +### CRI _The old CRI config pattern for specifying registry.mirrors and registry.configs has -been **DEPRECATED**._ You should now point your registry `config_path` to path where your +been **DEPRECATED**._ You should now point your registry `config_path` to the path where your `hosts.toml` files are located. Modify your `config.toml` (default location: `/etc/containerd/config.toml`) as follows: @@ -42,7 +42,7 @@ host names. For example, docker.io, quay.io, gcr.io, and ghcr.io. A registry host namespace is, for the purpose of containerd registry configuration, a path to the `hosts.toml` file specified by the registry host name, or ip address, and an -optional port identifier. When makeing a pull request for an image the format is +optional port identifier. When making a pull request for an image the format is typically as follows: ``` pull [registry_host_name|IP address][:port][/v2][/org_path][:tag|@DIGEST] @@ -69,6 +69,45 @@ pull myregistry.io:5000/image_name:tag ``` The pull will resolve to `https://myregistry.io:5000/v2/image_name:tag` +## Specifying Registry Credentials + +### CTR + +When performing image operations via `ctr` use the --help option to get a list of options you can set for specifying credentials: +``` +ctr i pull --help +... +OPTIONS: + --skip-verify, -k skip SSL certificate validation + --plain-http allow connections using plain HTTP + --user value, -u value user[:password] Registry user and password + --refresh value refresh token for authorization server + --hosts-dir value Custom hosts configuration directory + --tlscacert value path to TLS root CA + --tlscert value path to TLS client certificate + --tlskey value path to TLS client key + --http-dump dump all HTTP request/responses when interacting with container registry + --http-trace enable HTTP tracing for registry interactions + --snapshotter value snapshotter name. Empty value stands for the default value. [$CONTAINERD_SNAPSHOTTER] + --label value labels to attach to the image + --platform value Pull content from a specific platform + --all-platforms pull content and metadata from all platforms + --all-metadata Pull metadata for all platforms + --print-chainid Print the resulting image's chain ID + --max-concurrent-downloads value Set the max concurrent downloads for each pull (default: 0) +``` + +## CRI + +Although we have deprecated the old CRI config pattern for specifying registry.mirrors +and registry.configs you can still specify your credentials via +[CRI config](https://github.com/containerd/containerd/blob/master/docs/cri/registry.md#configure-registry-credentials). + +Additionally, the containerd CRI plugin implements/supports the authentication parameters passed in through CRI pull image service requests. +For example, when containerd is the container runtime implementation for `Kubernetes`, the containerd CRI plugin receives +authentication credentials from kubelet as retrieved from +[Kubernetes Image Pull Secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) + # Registry Configuration - Examples ### Simple (default) Host Config for Docker @@ -123,7 +162,7 @@ For each registry host namespace directory in your registry `config_path` you ma include a `hosts.toml` configuration file. The following root level toml fields apply to the registry host namespace: -*** Note: All paths specified in the `hosts.toml` file may be absolute or relative +**Note**: All paths specified in the `hosts.toml` file may be absolute or relative to the `hosts.toml` file. ## server field @@ -179,17 +218,17 @@ ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"] `client` certificates are configured as follows -`a path`: +a path: ``` client = "/etc/certs/client.pem" ``` -`an array of paths`: +an array of paths: ``` client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"] ``` -`an array of pairs of paths`: +an array of pairs of paths: ``` client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]] ``` @@ -206,19 +245,19 @@ skip_verify = false `[header]` contains some number of keys where each key is to one of a string or -`an array of strings as follows`: +an array of strings as follows: ``` [header] x-custom-1 = "custom header" ``` -`or` +or ``` [header] x-custom-1 = ["custom header part a","part b"] ``` -`or` +or ``` [header] x-custom-1 = "custom header", @@ -263,8 +302,8 @@ for this registry host namespace: client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"] ``` -**Further, recursion is not supported in the specification of host mirror -namespaces in the hosts.toml file. Thus the following is not allowed/supported:** +**Note**: Recursion is not supported in the specification of host mirror +namespaces in the hosts.toml file. Thus the following is not allowed/supported: ``` [host."http://mirror.registry"] capabilities = ["pull"] From 4b1b8346be2e8851650823a5e53b53658309f651 Mon Sep 17 00:00:00 2001 From: "Enrico Weigelt, metux IT consult" Date: Wed, 12 May 2021 15:45:31 +0200 Subject: [PATCH 4/4] Makefile: make sure manpages are built before install-man Let install-man depend on man, so manpages are really built before trying to install them. Signed-off-by: Enrico Weigelt, metux IT consult --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index ef7b7606e..b7029bf4e 100644 --- a/Makefile +++ b/Makefile @@ -253,7 +253,7 @@ mkdir -p $(DESTDIR)/man/man$(2); gzip -c $(1) >$(DESTDIR)/man/man$(2)/$(3).gz; endef -install-man: +install-man: man @echo "$(WHALE) $@" $(foreach manpage,$(addprefix man/,$(MANPAGES)), $(call installmanpage,$(manpage),$(subst .,,$(suffix $(manpage))),$(notdir $(manpage))))