From 889a3f51017dccbabb80ea93ae62e0d20aea6972 Mon Sep 17 00:00:00 2001 From: galal-hussein Date: Mon, 20 Jan 2020 21:40:16 +0200 Subject: [PATCH 1/3] Private registries --- .../installation/private-registry/_index.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 content/k3s/latest/en/installation/private-registry/_index.md diff --git a/content/k3s/latest/en/installation/private-registry/_index.md b/content/k3s/latest/en/installation/private-registry/_index.md new file mode 100644 index 00000000000..87a19513347 --- /dev/null +++ b/content/k3s/latest/en/installation/private-registry/_index.md @@ -0,0 +1,134 @@ +--- +title: "Private Registry Configuration" +weight: 55 +--- +​ +Containerd can be configured to connect to private registries and use them to pull private images on the node, private registry configuration feature was added in k3s v1.0.0. +​ +Upon startup, K3s will check to see if a `registries.yaml` file exists at `/etc/rancher/k3s/` and instruct containerd to use any registries defined in the file. If you wish to use a private registry, then you will need to create this file as root on each node that will be using the registry. +​ +Note that server nodes are scheduleable by default. If you have not tainted the server nodes and will be running workloads on them please ensure you also create the registires.yaml file on each server as well. +​ +Configuration in Containerd can be used to connect to private registry with TLS connection and with registries that enable authentication as well, the following section will explain the registries.yaml file and give different examples of using private registry configuration in k3s. +​ +### Registries Configuration file + +The file consists of two main sections: + +- mirrors +- configs + +#### Mirrors + +Mirrors is a directive that define the names and endpoints of the private registries, for example: + +``` +mirrors: + mycustomreg.com:5000 + endpoint: + - "https://mycustomreg.com:5000" +``` + +Each mirror must have a name and set of endpoints, when pulling an image from a registry, containerd will try these endpoint URLs one by one, and use the first working one. + +### Configs + +Configs section define the TLS and credential configuration for each mirror, for each mirror you can define `auth` and/or `tls`, the tls part consists of: + +- cert_file: which defines the client certificate path that will be used to authenticate with the registry. +- key_file: which defines the client key path that will be used to authenticate with the registry. +- ca_file: which defines the ca certificate path to be used to verify the registry's server cert file. + +The `cred` part consists of either username/password or authentication token: + +- username: user name of the private registry basic auth +- password: user password of the private registry basic auth +- auth: authentication token of the private registry basic auth + +Below are basic examples of using private registries in different modes: + +### With TLS +​ +Below are examples showing how you may configure `/etc/rancher/k3s/registires.yaml` on each node when using TLS. +​ +{{% tabs %}} +{{% tab "With Authentication" %}} +​ +With Auth Content here: +​ +``` +mirrors: + mycustomreg.com:5000 + endpoint: + - "https://mycustomreg.com:5000" +configs: + mycustomreg:5000 + auth: + username: xxxxxx # this is the registry username + password: xxxxxx # this is the registry password + tls: + cert_file: # path to the cert file used in the registry + key_file: # path to the key file used in the registry + ca_file: # path to the ca file used in the registry +``` +​ +{{% /tab %}} +{{% tab "Without Authentication" %}} +​ +Without Auth content: +​ +``` +mirrors: + mycustomreg.com:5000 + endpoint: + - "https://mycustomreg.com:5000" +configs: + mycustomreg:5000 + tls: + cert_file: # path to the cert file used in the registry + key_file: # path to the key file used in the registry + ca_file: # path to the ca file used in the registry +``` + +{{% /tab %}} +{{% /tabs %}} + +### Without TLS +​ +Below are examples showing how you may configure `/etc/rancher/k3s/registries.yaml` on each node when _not_ using TLS. +​ +{{% tabs %}} +{{% tab "With Authentication" %}} +​ +With Auth content: + +``` +mirrors: + mycustomreg.com:5000 + endpoint: + - "http://mycustomreg.com:5000" +configs: + mycustomreg:5000 + auth: + username: xxxxxx # this is the registry username + password: xxxxxx # this is the registry password +``` +​ +{{% /tab %}} +{{% tab "Without Authentication" %}} +​ +Without Auth content: + +``` +mirrors: + mycustomreg.com:5000 + endpoint: + - "http://mycustomreg.com:5000" +``` +​ +{{% /tab %}} +{{% /tabs %}} +​ +Note that in case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https. + +In order for containerd to take an effect you need to restart K3s on each node in order to leverage the private registry. From dfd70db30c860cf271e37daa6b468bdbc31d36ac Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 20 Jan 2020 15:14:03 -0700 Subject: [PATCH 2/3] Copy edit K3s private registry doc --- .../installation/private-registry/_index.md | 47 ++++++++++--------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/content/k3s/latest/en/installation/private-registry/_index.md b/content/k3s/latest/en/installation/private-registry/_index.md index 87a19513347..c0133bc2df9 100644 --- a/content/k3s/latest/en/installation/private-registry/_index.md +++ b/content/k3s/latest/en/installation/private-registry/_index.md @@ -2,25 +2,26 @@ title: "Private Registry Configuration" weight: 55 --- -​ -Containerd can be configured to connect to private registries and use them to pull private images on the node, private registry configuration feature was added in k3s v1.0.0. -​ +_Available as of v1.0.0_ + +Containerd can be configured to connect to private registries and use them to pull private images on the node. + Upon startup, K3s will check to see if a `registries.yaml` file exists at `/etc/rancher/k3s/` and instruct containerd to use any registries defined in the file. If you wish to use a private registry, then you will need to create this file as root on each node that will be using the registry. -​ -Note that server nodes are scheduleable by default. If you have not tainted the server nodes and will be running workloads on them please ensure you also create the registires.yaml file on each server as well. -​ -Configuration in Containerd can be used to connect to private registry with TLS connection and with registries that enable authentication as well, the following section will explain the registries.yaml file and give different examples of using private registry configuration in k3s. -​ -### Registries Configuration file + +Note that server nodes are schedulable by default. If you have not tainted the server nodes and will be running workloads on them, please ensure you also create the registires.yaml file on each server as well. + +Configuration in Containerd can be used to connect to a private registry with a TLS connection and with registries that enable authentication as well. The following section will explain the `registries.yaml` file and give different examples of using private registry configuration in K3s. + +# Registries Configuration File The file consists of two main sections: - mirrors - configs -#### Mirrors +### Mirrors -Mirrors is a directive that define the names and endpoints of the private registries, for example: +Mirrors is a directive that defines the names and endpoints of the private registries, for example: ``` mirrors: @@ -29,17 +30,19 @@ mirrors: - "https://mycustomreg.com:5000" ``` -Each mirror must have a name and set of endpoints, when pulling an image from a registry, containerd will try these endpoint URLs one by one, and use the first working one. +Each mirror must have a name and set of endpoints. When pulling an image from a registry, Containerd will try these endpoint URLs one by one, and use the first working one. ### Configs -Configs section define the TLS and credential configuration for each mirror, for each mirror you can define `auth` and/or `tls`, the tls part consists of: +The configs section defines the TLS and credential configuration for each mirror. For each mirror you can define `auth` and/or `tls`. The TLS part consists of: -- cert_file: which defines the client certificate path that will be used to authenticate with the registry. -- key_file: which defines the client key path that will be used to authenticate with the registry. -- ca_file: which defines the ca certificate path to be used to verify the registry's server cert file. +Directive | Description +----------|------------ +`cert_file` | The client certificate path that will be used to authenticate with the registry +`key_file` | The client key path that will be used to authenticate with the registry +`ca_file` | Defines the CA certificate path to be used to verify the registry's server cert file -The `cred` part consists of either username/password or authentication token: +The credentials consist of either username/password or authentication token: - username: user name of the private registry basic auth - password: user password of the private registry basic auth @@ -49,7 +52,7 @@ Below are basic examples of using private registries in different modes: ### With TLS ​ -Below are examples showing how you may configure `/etc/rancher/k3s/registires.yaml` on each node when using TLS. +Below are examples showing how you may configure `/etc/rancher/k3s/registries.yaml` on each node when using TLS. ​ {{% tabs %}} {{% tab "With Authentication" %}} @@ -125,10 +128,10 @@ mirrors: endpoint: - "http://mycustomreg.com:5000" ``` -​ + {{% /tab %}} {{% /tabs %}} -​ -Note that in case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https. + +> In case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https. -In order for containerd to take an effect you need to restart K3s on each node in order to leverage the private registry. +In order for Containerd to take an effect, you need to restart K3s on each node in order to leverage the private registry. From 05d93b2dcee43dd5c2bf2d9f35c6a783430cfb1a Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 21 Jan 2020 13:20:27 -0700 Subject: [PATCH 3/3] Respond to feedback on K3s private registry doc --- .../installation/private-registry/_index.md | 30 +++++++------------ 1 file changed, 11 insertions(+), 19 deletions(-) diff --git a/content/k3s/latest/en/installation/private-registry/_index.md b/content/k3s/latest/en/installation/private-registry/_index.md index c0133bc2df9..d315656d4d4 100644 --- a/content/k3s/latest/en/installation/private-registry/_index.md +++ b/content/k3s/latest/en/installation/private-registry/_index.md @@ -10,7 +10,7 @@ Upon startup, K3s will check to see if a `registries.yaml` file exists at `/etc/ Note that server nodes are schedulable by default. If you have not tainted the server nodes and will be running workloads on them, please ensure you also create the registires.yaml file on each server as well. -Configuration in Containerd can be used to connect to a private registry with a TLS connection and with registries that enable authentication as well. The following section will explain the `registries.yaml` file and give different examples of using private registry configuration in K3s. +Configuration in containerd can be used to connect to a private registry with a TLS connection and with registries that enable authentication as well. The following section will explain the `registries.yaml` file and give different examples of using private registry configuration in K3s. # Registries Configuration File @@ -30,7 +30,7 @@ mirrors: - "https://mycustomreg.com:5000" ``` -Each mirror must have a name and set of endpoints. When pulling an image from a registry, Containerd will try these endpoint URLs one by one, and use the first working one. +Each mirror must have a name and set of endpoints. When pulling an image from a registry, containerd will try these endpoint URLs one by one, and use the first working one. ### Configs @@ -51,14 +51,12 @@ The credentials consist of either username/password or authentication token: Below are basic examples of using private registries in different modes: ### With TLS -​ + Below are examples showing how you may configure `/etc/rancher/k3s/registries.yaml` on each node when using TLS. -​ + {{% tabs %}} {{% tab "With Authentication" %}} -​ -With Auth Content here: -​ + ``` mirrors: mycustomreg.com:5000 @@ -74,12 +72,10 @@ configs: key_file: # path to the key file used in the registry ca_file: # path to the ca file used in the registry ``` -​ + {{% /tab %}} {{% tab "Without Authentication" %}} -​ -Without Auth content: -​ + ``` mirrors: mycustomreg.com:5000 @@ -97,13 +93,11 @@ configs: {{% /tabs %}} ### Without TLS -​ + Below are examples showing how you may configure `/etc/rancher/k3s/registries.yaml` on each node when _not_ using TLS. -​ + {{% tabs %}} {{% tab "With Authentication" %}} -​ -With Auth content: ``` mirrors: @@ -116,11 +110,9 @@ configs: username: xxxxxx # this is the registry username password: xxxxxx # this is the registry password ``` -​ + {{% /tab %}} {{% tab "Without Authentication" %}} -​ -Without Auth content: ``` mirrors: @@ -134,4 +126,4 @@ mirrors: > In case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https. -In order for Containerd to take an effect, you need to restart K3s on each node in order to leverage the private registry. +In order for the registry changes to take effect, you need to restart K3s on each node.