diff --git a/content/rancher/v2.x/en/installation/air-gap-high-availability/_index.md b/content/rancher/v2.x/en/installation/air-gap-high-availability/_index.md index 6cc0ee32a10..4febd45ac7e 100644 --- a/content/rancher/v2.x/en/installation/air-gap-high-availability/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-high-availability/_index.md @@ -23,7 +23,6 @@ The following CLI tools are required for this install. Make sure these tools are - [2. Collect and Publish Image Sources]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/prepare-private-registry/) - [3. Install Kubernetes with RKE]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/install-kube/) - [4. Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/install-rancher/) -- [5. Configure Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/) -- [6. Configure Rancher System Charts]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/) +- [5. Configure Rancher System Charts]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/) ### [Next: Create Nodes and Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/provision-hosts/) diff --git a/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/_index.md deleted file mode 100644 index 9dc14874cd3..00000000000 --- a/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "5. Configure Rancher for the Private Registry" -weight: 500 -aliases: - ---- - -Rancher needs to be configured to use the private registry in order to provision any [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) or [Rancher tools]({{< baseurl >}}/rancher/v2.x/en/tools/). - ->**Note:** If you want to configure Rancher to use your private registry when starting the rancher/rancher container, you can use the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. - -1. Log into Rancher and configure the default admin password. - -1. Go into the **Settings** view. - - ![Settings]({{< baseurl >}}/img/rancher/airgap/settings.png) - -1. Look for the setting called `system-default-registry` and choose **Edit**. - - ![Edit]({{< baseurl >}}/img/rancher/airgap/edit-system-default-registry.png) - -1. Change the value to your registry (e.g. `registry.yourdomain.com:port`). Do not prefix the registry with `http://` or `https://`. - - ![Save]({{< baseurl >}}/img/rancher/airgap/enter-system-default-registry.png) - -### [Next: Configure Rancher System Charts]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/) diff --git a/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/_index.md b/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/_index.md index 50c2ddd93d1..b0d5e08b85b 100644 --- a/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/_index.md @@ -1,7 +1,8 @@ --- -title: "6. Configure Rancher System Charts" +title: "5. Configure Rancher System Charts" weight: 600 aliases: + - /rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/ --- # A. Prepare System Charts diff --git a/content/rancher/v2.x/en/installation/air-gap-high-availability/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-high-availability/install-rancher/_index.md index 1c060e09aef..b6d09e42324 100644 --- a/content/rancher/v2.x/en/installation/air-gap-high-availability/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-high-availability/install-rancher/_index.md @@ -45,12 +45,14 @@ For HA air gap configurations, there are two recommended options for the source | [Rancher Generated Self-Signed Certificates](#self-signed) | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)
This is the **default** | yes | | [Certificates from Files](#secret) | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s) | no | -## C. Install Rancher +## C. Set Up the Rancher Template Based on the choice your made in [B. Choose your SSL Configuration](#b-optional-install-cert-manager), complete one of the procedures below. +In this section you will configure your cert manager and private registry in the Rancher template. + {{% accordion id="self-signed" label="Option A: Default Self-Signed Certificate" %}} -By default, Rancher generates a CA and uses cert manger to issue the certificate for access to the Rancher server interface. +By default, Rancher generates a CA and uses cert manager to issue the certificate for access to the Rancher server interface. 1. From a system connected to the internet, fetch the latest cert-manager chart available from the [official Helm chart repository](https://github.com/helm/charts/tree/master/stable). @@ -66,23 +68,24 @@ By default, Rancher generates a CA and uses cert manger to issue the certificate --set image.repository=/quay.io/jetstack/cert-manager-controller ``` -1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. - - Placeholder | Description - ------------|------------- - `` | The version number of the output tarball. - `` | The DNS name you pointed at your load balancer. - `` | The DNS name for your private registry.). +1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. To configure Rancher to use your private registry when starting the `rancher/rancher` container, use the `CATTLE_SYSTEM_DEFAULT_REGISTRY` variable. You can set the the extra environment variable `extraEnv` to use the same `name` and `value` keys as the container manifest definitions. Remember to quote the values: - - ```plain + ```plain helm template ./rancher-.tgz --output-dir . \ --name rancher \ --namespace cattle-system \ --set hostname= \ --set rancherImage=/rancher/rancher + --set 'extraEnv[0].name=CATTLE_SYSTEM_DEFAULT_REGISTRY' + --set 'extraEnv[0].value=' ``` + Placeholder | Description + ------------|------------- + `` | The version number of the output tarball. + `` | The DNS name you pointed at your load balancer. + `` | The DNS name for your private registry. This configures Rancher to use your private registry when starting the `rancher/rancher` container. + {{% /accordion %}} {{% accordion id="secret" label="Option B: Certificates for Files (Kubernetes Secret)" %}} @@ -91,16 +94,7 @@ By default, Rancher generates a CA and uses cert manger to issue the certificate > **Note:** The common name for the cert will need to match the `hostname` option or the ingress controller will fail to provision the site for Rancher. -1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. - - Placeholder | Description - ------------|------------- - `` | The version number of the output tarball. - `` | The DNS name you pointed at your load balancer. - `` | The DNS name for your private registry. - - - > **Note:** If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret` +1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. To configure Rancher to use your private registry when starting the `rancher/rancher` container, the `CATTLE_SYSTEM_DEFAULT_REGISTRY` variable. You can set the the extra environment variable `extraEnv` to use the same `name` and `value` keys as the container manifest definitions. Remember to quote the values: ``` helm template ./rancher-.tgz --output-dir . \ @@ -109,7 +103,17 @@ By default, Rancher generates a CA and uses cert manger to issue the certificate --set hostname= \ --set rancherImage=/rancher/rancher \ --set ingress.tls.source=secret -``` + --set 'extraEnv[0].name=CATTLE_SYSTEM_DEFAULT_REGISTRY' + --set 'extraEnv[0].value=' + ``` + + Placeholder | Description + ------------|------------- + `` | The version number of the output tarball. + `` | The DNS name you pointed at your load balancer. + `` | The DNS name for your private registry. This configures Rancher to use your private registry when starting the `rancher/rancher` container. + + > **Note:** If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret` 1. See [Adding TLS Secrets]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them. {{% /accordion %}} @@ -133,4 +137,12 @@ kubectl create namespace cattle-system kubectl -n cattle-system apply -R -f ./rancher ``` -### [Next: Configure Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/) +### Additional Resources + +These resources could be helpful when you install Rancher: + +- [Rancher Helm chart options]({{}}rancher/v2.x/en/installation/ha/helm-rancher/chart-options/) +- [Adding TLS secrets]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) +- [Troubleshooting Rancher HA installations]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/) + +### [Next: Configure Rancher System Charts]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-system-charts/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/air-gap-high-availability/prepare-private-registry/_index.md b/content/rancher/v2.x/en/installation/air-gap-high-availability/prepare-private-registry/_index.md index 68edfac7547..d02f1385b1e 100644 --- a/content/rancher/v2.x/en/installation/air-gap-high-availability/prepare-private-registry/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-high-availability/prepare-private-registry/_index.md @@ -5,6 +5,16 @@ aliases: - /rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/ --- +>**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. + +By default, all system images are being pulled from DockerHub. If you are on a system that does not have access to DockerHub, you will need to create a private registry that is populated with all the required [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/). + +As of RKE v0.1.10, you have to configure your private registry. You can specify this registry as a default registry so that all system images are pulled from the designated private registry. You can use the command `rke config --system-images` to get the list of default system images to populate your private registry. For details, refer to the [RKE documentation on how to set a default registry]({{}}/rke/latest/en/config-options/private-registries/). + +Prior to RKE v0.1.10, you had to configure your private registry **and** update the names of all the [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) in the `cluster.yml` so that the image names would have the private registry URL appended before each image name. + +When configuring your private registry, you only need to provide credentials if your registry requires them. + ## A. Collect Images Start by collecting all the images needed to install Rancher in an air gap environment. You'll collect images from your chosen Rancher release, RKE, and (if you're using a self-signed TLS certificate) Cert-Manager. diff --git a/content/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/_index.md index cbb98837736..d73c0305812 100644 --- a/content/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/_index.md @@ -4,7 +4,21 @@ weight: 400 aliases: --- -Rancher needs to be configured to use the private registry in order to provision any [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) or [Rancher tools]({{< baseurl >}}/rancher/v2.x/en/tools/). +After your private registry is populated with all the required system images, you need to configure Rancher to use the private registry. There are two places you need to use a private registry: + +- When Rancher is installed, to provide the Rancher system images +- After Rancher is installed, to use when deploying clusters + +There are multiple ways to configure private registries in Rancher, depending on whether your private registry requires credentials: + +- If your private registry requires credentials, you need to pass the credentials to Rancher by editing the cluster options for each cluster that needs to pull images from the registry. +- If the private registry doesn't require credentials, you can configure it as a default registry through the **Settings** tab in the global view. + +If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to [pass in the registry credentials through the advanced cluster options](#provisioning-clusters-with-private-registries-that-require-credentials) every time you create a new cluster. + +# Setting a Private Registry with No Credentials as the Default Registry + +>**Note:** If you want to set the default private registry when starting the rancher/rancher container, you can use the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. 1. Log into Rancher and configure the default admin password. @@ -20,6 +34,17 @@ Rancher needs to be configured to use the private registry in order to provision ![Save]({{< baseurl >}}/img/rancher/airgap/enter-system-default-registry.png) ->**Note:** If you want to configure the setting when starting the rancher/rancher container, you can use the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. +**Result:** Rancher will use your private registry to pull system images. + +# Setting a Private Registry with Credentials for Deploying Clusters + +You can follow these steps to configure a private registry when you provision a cluster with Rancher: + +1. When you create a cluster through the Rancher UI, go to the **Cluster Options** section and click **Show Advanced Options.** +1. In the Enable Private Registries section, click **Enabled.** +1. Enter the registry URL and credentials. +1. Click **Save.** + +**Result:** The new cluster will be able to pull images from the private registry. ### [Next: Configure Rancher System Charts]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-system-charts/) diff --git a/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md index bf50909cc44..305725e4ae6 100644 --- a/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md @@ -13,16 +13,15 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher >- Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{< baseurl >}}/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/). >- Record all transactions with the Rancher API? See [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#api-audit-log). - Choose from the following options: - {{% accordion id="option-a" label="Option A-Default Self-Signed Certificate" %}} If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself. Log into your Linux host, and then run the installation command below. Replace `` with your private registry URL and port. Replace `` with release tag of the [Rancher version]({{< baseurl >}}/rancher/v2.x/en/installation/server-tags/) that you want to install. +If your private registry doesn't require credentials, you can set it as default when starting the rancher/rancher container by using the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -48,9 +47,11 @@ Placeholder | Description `` | The path to your full certificate chain. `` | The path to the private key for your certificate. `` | The path to the certificate authority's private key. -`` | Your private registry URL and port. +`` | Your private registry URL and port. This configures Rancher to use your private registry when starting the `rancher/rancher` container. `` | The release tag of the [Rancher version]({{< baseurl >}}/rancher/v2.x/en/installation/server-tags/) that you want to install. +If your private registry doesn't require credentials, you can set it as default when starting the rancher/rancher container by using the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -72,6 +73,8 @@ After obtaining your certificate, run the Docker command below, replacing each p When entering the command, use the table below to replace each placeholder. +If your private registry doesn't require credentials, you can set it as default when starting the rancher/rancher container by using the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. + Placeholder | Description ------------|------------- `` | The path to the directory containing your certificate files. @@ -91,4 +94,4 @@ docker run -d --restart=unless-stopped \ {{% /accordion %}} -### [Next: Configure Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/) +### [Next: Configure Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/air-gap-single-node/prepare-private-registry/_index.md b/content/rancher/v2.x/en/installation/air-gap-single-node/prepare-private-registry/_index.md index f7b74daa966..080568275f2 100644 --- a/content/rancher/v2.x/en/installation/air-gap-single-node/prepare-private-registry/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-single-node/prepare-private-registry/_index.md @@ -4,6 +4,12 @@ weight: 200 aliases: --- +>**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. + +By default, all system images are being pulled from DockerHub. If you are on a system that does not have access to DockerHub, you will need to create a private registry that is populated with all the required [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/). + +When configuring your private registry, you only need to provide credentials if your registry requires them. + ## A. Collect Image Sources Using a computer with internet access, browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher 2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments. @@ -46,4 +52,4 @@ After collecting the release files, publish the images from `rancher-images.txt` ./rancher-load-images.sh --image-list ./rancher-images.txt --registry ``` -### [Next: Choose an SSL Option and Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/) \ No newline at end of file +### [Next: Choose an SSL Option and Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/)