From ce5b4545918759c32a2370a08ab3bd662da76a59 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Mon, 17 Sep 2018 19:00:46 -0700 Subject: [PATCH 1/8] initial draft of ha air gap install --- .../ha-air-gap-installation/_index.md | 246 ++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md new file mode 100644 index 00000000000..040a2ba0b36 --- /dev/null +++ b/content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md @@ -0,0 +1,246 @@ +--- +title: High Availability Air Gap Installation +weight: +draft: true +--- + +You can install Rancher in an air gap environment in a high availability configuration. + +## HA Air Gap Install Outline + +Deployment of Rancher in a high-availability configuration within an air gap environment is a multistep process. + + + + +- [1—Gather Images](#1gather-images) +- [2—Populate the Registry](#2populate-the-registry) +- [3—Run RKE with Private Registry Options](#3run-rke-with-private-registry-options) +- [4—Install Helm (tiller)](#4install-helm-tiller) +- [5—Install Rancher](#5install-rancher) + + + +## 1—Gather Images + +To get started with an HA install within an air gap environment, download the software and files that you'll use for installation. + +1. Download the four images required to populate your private Docker registry, which will be used to launch Rancher Server. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DownloadDescription
RKE + A list of RKE images that are required can be compiled by running the following command. + 
rke config --system-images
+
rancher-images.txt Rancher has additional images it uses when installing clusters. These images are listed in rancher-images.txt, which can be found at GitHub Releases page for rancher/rancher.
Helm tiller Image + You can discover the tiller image compatible with your installed version of helm with the command below. + 
helm init --dry-run --debug | grep image: | awk '{print $2}'
+
cert-manager ImageRancher uses the cert-manager project to issue self-singed certificates for Rancher GUI/Agent access. You can inspect the cert-manager chart values.yaml to find the latest image and tag. + 
 helm inspect values stable/cert-manager
+        ...
+        image:
+          repository: quay.io/jetstack/cert-manager-controller
+          tag: v0.4.1
+        ...
+
+ +1. From a system with internet access, use the shell script below to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. + + ```bash + #!/bin/bash + set -e + + # Collect images for Air Gap/Private Registry install + # Requires: + # rke - https://rancher.com/docs/rke/v0.1.x/en/installation/ + # helm - https://docs.helm.sh/using_helm/#installing-helm + # curl + # jq + + echo "RKE Images" + rke config --system-images 2>/dev/null > tmp-images.txt + + echo "Helm Tiller Image" + helm init --dry-run --debug | grep image: | awk '{print $2}' >> tmp-images.txt + + echo "Rancher Images" + latest_url=$(curl -sS "https://api.github.com/repos/rancher/rancher/releases/latest" | jq -r '.assets[]|select(.name=="rancher-images.txt")|.browser_download_url') + curl -sSL ${latest_url} >> tmp-images.txt + + echo "Cert-Manager Image" + cm_repo=$(helm inspect values stable/cert-manager | grep repository: | awk '{print $2}') + cm_tag=$(helm inspect values stable/cert-manager | grep tag: | awk '{print $2}') + echo "${cm_repo}:${cm_tag}" >> tmp-images.txt + + echo "Sort and uniq the images list" + cat tmp-images.txt | sort -u | uniq > images.txt + + # cleanup tmp file + rm tmp-images.txt + ``` + +## 2—Populate the Registry + +Each image in the list needs to be pulled from public registries, tagged with your private registry URL/path, and then pushed up to your private registry. + +1. Pull the images from public registries using the following command: + + ```plain + docker pull rancher/coreos-etcd:v3.1.12 + ``` + +1. Tag the images with your private registry URL and path: + + ```plain + docker tag rancher/coreos-etcd:v3.1.12 /rancher/coreos-etcd:v3.1.12 + ``` +1. Push the images to your private registry: + + ```plain + docker push /rancher/coreos-etcd:v3.1.12 + ``` + +1. Use the shell script below to to populate the private registry. This shell script can be used with a list of images (`images.txt`). To use this script, the system needs access to both the Internet and the private registry. + + ```bash + #!/bin/bash + + # Usage: + # ./populate-images.sh --registry my_registry.example.com --images ./images.txt + + POSITIONAL=() + while [[ $# -gt 0 ]] + do + key="$1" + + case $key in + -r|--registry) + reg="$2" + shift # past argument + shift # past value + ;; + -i|--images) + images="$2" + shift + shift + ;; + esac + done + + if [[ -z $reg ]]; then + echo "-r|--registry is required" + exit 1 + fi + + if [[ -z $images ]]; then + echo "-i|--images file is required" + exit 1 + fi + + echo "Log into Docker registry ${reg}" + docker login ${reg} + + for i in $(cat ${images}); do + docker pull ${i} + docker tag ${i} ${reg}/${i} + docker push ${reg}/${i} + done + ``` + +## 3—Run RKE with Private Registry Options + +Edit your `cluster.yaml` file, specifying your cluster nodes and your private registry. + +1. Edit `cluster.yaml`, specifying the nodes you created. Include the `private_registries:` block. Set `is_default: true` for the registry that you pushed the images to. + + nodes: + - address: 18.222.121.187 + internal_address: 172.31.7.22 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 18.220.193.254 + internal_address: 172.31.13.132 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 13.59.83.89 + internal_address: 172.31.3.216 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + private_registries: + - url: my_registry.example.com + user: rancher + password: "*********" + is_default: true + + +1. Run RKE to set up your cluster using your private registry. + + ``` + rke up + ``` + +## 4—Install Helm (tiller) + +Install the Helm package manager. You'll use this software to install Rancher on the Kubernetes cluster you just set up. + +1. The `tiller` serviceAccount that the tiller deployment uses needs credentials to access your private registry. Set up the serviceAccount and RBAC permissions as depicted below. Then patch the service account to add the credentials. + + ``` + kubectl -n kube-system create serviceaccount tiller + kubectl create clusterrolebinding tiller \ + --clusterrole cluster-admin \ + --serviceaccount=kube-system:tiller + ``` + +1. Initialize Helm with the `tiller` image in your private registry. + + ``` + helm init --service-account tiller \ + --tiller-image user-ag-2-registry.rancher.space/gcr.io/kubernetes-helm/tiller:v2.10.0 + ``` + +## 5—Install Rancher + +Finally, we're ready to install Rancher. + +1. Install cert-manager, which automatically creates and handles certificates for your Rancher deployment. + + ``` + helm install stable/cert-manager --name cert-manager --namespace kube-system \ + --set image.repository=user-ag-2-registry.rancher.space/quay.io/jetstack/cert-manager-controller + ``` + +1. Install Rancher, setting the image source and imagePullSecrets options. + + ```plain + helm install rancher-stable/rancher --name rancher --namespace cattle-system \ + --set hostname=user-ag-2.rancher.space \ + --set rancherImage=user-ag-2-registry.rancher.space/rancher/rancher + ``` From e3bfc0cc45ece94219387e8db37710885c8e4b8c Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Mon, 17 Sep 2018 22:24:18 -0700 Subject: [PATCH 2/8] moving ha stuff into OG air gap file --- .../air-gap-installation/_index.md | 241 +++++++++++++++++ .../ha-air-gap-installation/_index.md | 246 ------------------ 2 files changed, 241 insertions(+), 246 deletions(-) delete mode 100644 content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md index 63e5add3d4d..9605122ce8a 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md @@ -96,3 +96,244 @@ docker run -d --restart=unless-stopped \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ /rancher/rancher:v2.0.0 ``` + +You can install Rancher in an air gap environment in a high availability configuration. + +## HA Air Gap Install Outline + +Deployment of Rancher in a high-availability configuration within an air gap environment is a multistep process. + + + + +- [1—Gather Images](#1gather-images) +- [2—Populate the Registry](#2populate-the-registry) +- [3—Run RKE with Private Registry Options](#3run-rke-with-private-registry-options) +- [4—Install Helm (tiller)](#4install-helm-tiller) +- [5—Install Rancher](#5install-rancher) + + + +## 1—Gather Images + +To get started with an HA install within an air gap environment, download the software and files that you'll use for installation. + +1. Download the four images required to populate your private Docker registry, which will be used to launch Rancher Server. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DownloadDescription
RKE + A list of RKE images that are required can be compiled by running the following command. + 
rke config --system-images
+
rancher-images.txt Rancher has additional images it uses when installing clusters. These images are listed in rancher-images.txt, which can be found at GitHub Releases page for rancher/rancher.
Helm tiller Image + You can discover the tiller image compatible with your installed version of helm with the command below. + 
helm init --dry-run --debug | grep image: | awk '{print $2}'
+
cert-manager ImageRancher uses the cert-manager project to issue self-singed certificates for Rancher GUI/Agent access. You can inspect the cert-manager chart values.yaml to find the latest image and tag. + 
 helm inspect values stable/cert-manager
+        ...
+        image:
+          repository: quay.io/jetstack/cert-manager-controller
+          tag: v0.4.1
+        ...
+
+ +1. From a system with internet access, use the shell script below to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. + + ```bash + #!/bin/bash + set -e + + # Collect images for Air Gap/Private Registry install + # Requires: + # rke - https://rancher.com/docs/rke/v0.1.x/en/installation/ + # helm - https://docs.helm.sh/using_helm/#installing-helm + # curl + # jq + + echo "RKE Images" + rke config --system-images 2>/dev/null > tmp-images.txt + + echo "Helm Tiller Image" + helm init --dry-run --debug | grep image: | awk '{print $2}' >> tmp-images.txt + + echo "Rancher Images" + latest_url=$(curl -sS "https://api.github.com/repos/rancher/rancher/releases/latest" | jq -r '.assets[]|select(.name=="rancher-images.txt")|.browser_download_url') + curl -sSL ${latest_url} >> tmp-images.txt + + echo "Cert-Manager Image" + cm_repo=$(helm inspect values stable/cert-manager | grep repository: | awk '{print $2}') + cm_tag=$(helm inspect values stable/cert-manager | grep tag: | awk '{print $2}') + echo "${cm_repo}:${cm_tag}" >> tmp-images.txt + + echo "Sort and uniq the images list" + cat tmp-images.txt | sort -u | uniq > images.txt + + # cleanup tmp file + rm tmp-images.txt + ``` + +## 2—Populate the Registry + +Each image in the list needs to be pulled from public registries, tagged with your private registry URL/path, and then pushed up to your private registry. + +1. Pull the images from public registries using the following command: + + ```plain + docker pull rancher/coreos-etcd:v3.1.12 + ``` + +1. Tag the images with your private registry URL and path: + + ```plain + docker tag rancher/coreos-etcd:v3.1.12 /rancher/coreos-etcd:v3.1.12 + ``` +1. Push the images to your private registry: + + ```plain + docker push /rancher/coreos-etcd:v3.1.12 + ``` + +1. Use the shell script below to to populate the private registry. This shell script can be used with a list of images (`images.txt`). To use this script, the system needs access to both the Internet and the private registry. + + ```bash + #!/bin/bash + + # Usage: + # ./populate-images.sh --registry my_registry.example.com --images ./images.txt + + POSITIONAL=() + while [[ $# -gt 0 ]] + do + key="$1" + + case $key in + -r|--registry) + reg="$2" + shift # past argument + shift # past value + ;; + -i|--images) + images="$2" + shift + shift + ;; + esac + done + + if [[ -z $reg ]]; then + echo "-r|--registry is required" + exit 1 + fi + + if [[ -z $images ]]; then + echo "-i|--images file is required" + exit 1 + fi + + echo "Log into Docker registry ${reg}" + docker login ${reg} + + for i in $(cat ${images}); do + docker pull ${i} + docker tag ${i} ${reg}/${i} + docker push ${reg}/${i} + done + ``` + +## 3—Run RKE with Private Registry Options + +Edit your `cluster.yaml` file, specifying your cluster nodes and your private registry. + +1. Edit `cluster.yaml`, specifying the nodes you created. Include the `private_registries:` block. Set `is_default: true` for the registry that you pushed the images to. + + nodes: + - address: 18.222.121.187 + internal_address: 172.31.7.22 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 18.220.193.254 + internal_address: 172.31.13.132 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 13.59.83.89 + internal_address: 172.31.3.216 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + private_registries: + - url: my_registry.example.com + user: rancher + password: "*********" + is_default: true + + +1. Run RKE to set up your cluster using your private registry. + + ``` + rke up + ``` + +## 4—Install Helm (tiller) + +Install the Helm package manager. You'll use this software to install Rancher on the Kubernetes cluster you just set up. + +1. The `tiller` serviceAccount that the tiller deployment uses needs credentials to access your private registry. Set up the serviceAccount and RBAC permissions as depicted below. Then patch the service account to add the credentials. + + ``` + kubectl -n kube-system create serviceaccount tiller + kubectl create clusterrolebinding tiller \ + --clusterrole cluster-admin \ + --serviceaccount=kube-system:tiller + ``` + +1. Initialize Helm with the `tiller` image in your private registry. + + ``` + helm init --service-account tiller \ + --tiller-image user-ag-2-registry.rancher.space/gcr.io/kubernetes-helm/tiller:v2.10.0 + ``` + +## 5—Install Rancher + +Finally, we're ready to install Rancher. + +1. Install cert-manager, which automatically creates and handles certificates for your Rancher deployment. + + ``` + helm install stable/cert-manager --name cert-manager --namespace kube-system \ + --set image.repository=user-ag-2-registry.rancher.space/quay.io/jetstack/cert-manager-controller + ``` + +1. Install Rancher, setting the image source and imagePullSecrets options. + + ```plain + helm install rancher-stable/rancher --name rancher --namespace cattle-system \ + --set hostname=user-ag-2.rancher.space \ + --set rancherImage=user-ag-2-registry.rancher.space/rancher/rancher + ``` diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md deleted file mode 100644 index 040a2ba0b36..00000000000 --- a/content/rancher/v2.x/en/installation/air-gap-installation/ha-air-gap-installation/_index.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -title: High Availability Air Gap Installation -weight: -draft: true ---- - -You can install Rancher in an air gap environment in a high availability configuration. - -## HA Air Gap Install Outline - -Deployment of Rancher in a high-availability configuration within an air gap environment is a multistep process. - - - - -- [1—Gather Images](#1gather-images) -- [2—Populate the Registry](#2populate-the-registry) -- [3—Run RKE with Private Registry Options](#3run-rke-with-private-registry-options) -- [4—Install Helm (tiller)](#4install-helm-tiller) -- [5—Install Rancher](#5install-rancher) - - - -## 1—Gather Images - -To get started with an HA install within an air gap environment, download the software and files that you'll use for installation. - -1. Download the four images required to populate your private Docker registry, which will be used to launch Rancher Server. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DownloadDescription
RKE - A list of RKE images that are required can be compiled by running the following command. - 
rke config --system-images
-
rancher-images.txt Rancher has additional images it uses when installing clusters. These images are listed in rancher-images.txt, which can be found at GitHub Releases page for rancher/rancher.
Helm tiller Image - You can discover the tiller image compatible with your installed version of helm with the command below. - 
helm init --dry-run --debug | grep image: | awk '{print $2}'
-
cert-manager ImageRancher uses the cert-manager project to issue self-singed certificates for Rancher GUI/Agent access. You can inspect the cert-manager chart values.yaml to find the latest image and tag. - 
 helm inspect values stable/cert-manager
-        ...
-        image:
-          repository: quay.io/jetstack/cert-manager-controller
-          tag: v0.4.1
-        ...
-
- -1. From a system with internet access, use the shell script below to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. - - ```bash - #!/bin/bash - set -e - - # Collect images for Air Gap/Private Registry install - # Requires: - # rke - https://rancher.com/docs/rke/v0.1.x/en/installation/ - # helm - https://docs.helm.sh/using_helm/#installing-helm - # curl - # jq - - echo "RKE Images" - rke config --system-images 2>/dev/null > tmp-images.txt - - echo "Helm Tiller Image" - helm init --dry-run --debug | grep image: | awk '{print $2}' >> tmp-images.txt - - echo "Rancher Images" - latest_url=$(curl -sS "https://api.github.com/repos/rancher/rancher/releases/latest" | jq -r '.assets[]|select(.name=="rancher-images.txt")|.browser_download_url') - curl -sSL ${latest_url} >> tmp-images.txt - - echo "Cert-Manager Image" - cm_repo=$(helm inspect values stable/cert-manager | grep repository: | awk '{print $2}') - cm_tag=$(helm inspect values stable/cert-manager | grep tag: | awk '{print $2}') - echo "${cm_repo}:${cm_tag}" >> tmp-images.txt - - echo "Sort and uniq the images list" - cat tmp-images.txt | sort -u | uniq > images.txt - - # cleanup tmp file - rm tmp-images.txt - ``` - -## 2—Populate the Registry - -Each image in the list needs to be pulled from public registries, tagged with your private registry URL/path, and then pushed up to your private registry. - -1. Pull the images from public registries using the following command: - - ```plain - docker pull rancher/coreos-etcd:v3.1.12 - ``` - -1. Tag the images with your private registry URL and path: - - ```plain - docker tag rancher/coreos-etcd:v3.1.12 /rancher/coreos-etcd:v3.1.12 - ``` -1. Push the images to your private registry: - - ```plain - docker push /rancher/coreos-etcd:v3.1.12 - ``` - -1. Use the shell script below to to populate the private registry. This shell script can be used with a list of images (`images.txt`). To use this script, the system needs access to both the Internet and the private registry. - - ```bash - #!/bin/bash - - # Usage: - # ./populate-images.sh --registry my_registry.example.com --images ./images.txt - - POSITIONAL=() - while [[ $# -gt 0 ]] - do - key="$1" - - case $key in - -r|--registry) - reg="$2" - shift # past argument - shift # past value - ;; - -i|--images) - images="$2" - shift - shift - ;; - esac - done - - if [[ -z $reg ]]; then - echo "-r|--registry is required" - exit 1 - fi - - if [[ -z $images ]]; then - echo "-i|--images file is required" - exit 1 - fi - - echo "Log into Docker registry ${reg}" - docker login ${reg} - - for i in $(cat ${images}); do - docker pull ${i} - docker tag ${i} ${reg}/${i} - docker push ${reg}/${i} - done - ``` - -## 3—Run RKE with Private Registry Options - -Edit your `cluster.yaml` file, specifying your cluster nodes and your private registry. - -1. Edit `cluster.yaml`, specifying the nodes you created. Include the `private_registries:` block. Set `is_default: true` for the registry that you pushed the images to. - - nodes: - - address: 18.222.121.187 - internal_address: 172.31.7.22 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - - address: 18.220.193.254 - internal_address: 172.31.13.132 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - - address: 13.59.83.89 - internal_address: 172.31.3.216 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - private_registries: - - url: my_registry.example.com - user: rancher - password: "*********" - is_default: true - - -1. Run RKE to set up your cluster using your private registry. - - ``` - rke up - ``` - -## 4—Install Helm (tiller) - -Install the Helm package manager. You'll use this software to install Rancher on the Kubernetes cluster you just set up. - -1. The `tiller` serviceAccount that the tiller deployment uses needs credentials to access your private registry. Set up the serviceAccount and RBAC permissions as depicted below. Then patch the service account to add the credentials. - - ``` - kubectl -n kube-system create serviceaccount tiller - kubectl create clusterrolebinding tiller \ - --clusterrole cluster-admin \ - --serviceaccount=kube-system:tiller - ``` - -1. Initialize Helm with the `tiller` image in your private registry. - - ``` - helm init --service-account tiller \ - --tiller-image user-ag-2-registry.rancher.space/gcr.io/kubernetes-helm/tiller:v2.10.0 - ``` - -## 5—Install Rancher - -Finally, we're ready to install Rancher. - -1. Install cert-manager, which automatically creates and handles certificates for your Rancher deployment. - - ``` - helm install stable/cert-manager --name cert-manager --namespace kube-system \ - --set image.repository=user-ag-2-registry.rancher.space/quay.io/jetstack/cert-manager-controller - ``` - -1. Install Rancher, setting the image source and imagePullSecrets options. - - ```plain - helm install rancher-stable/rancher --name rancher --namespace cattle-system \ - --set hostname=user-ag-2.rancher.space \ - --set rancherImage=user-ag-2-registry.rancher.space/rancher/rancher - ``` From 4e3dc421baca7d12fd93327489ff939435058e27 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Tue, 18 Sep 2018 17:59:32 -0700 Subject: [PATCH 3/8] initial check in of HA air gap install docs --- .../air-gap-installation/_index.md | 341 +----------------- .../config-rancher-for-private-reg/_index.md | 32 ++ .../install-rancher/_index.md | 91 +++++ .../prepare-private-reg/_index.md | 147 ++++++++ 4 files changed, 284 insertions(+), 327 deletions(-) create mode 100644 content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md create mode 100644 content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md create mode 100644 content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md index 9605122ce8a..19d83c0038e 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md @@ -1,339 +1,26 @@ --- -title: Preparing for Air Gap Install +title: Air Gap Install weight: 300 --- -Rancher supports installing from a private registry. In every [release](https://github.com/rancher/rancher/releases), we provide you with the needed Docker images and scripts to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. +In environments where security is high priority, you can set up Rancher in an air gap configuration. Air gap installs are more secure than standard single-node or HA deployments because the network that runs Rancher is disconnected from the Internet, reducing your security surface area. ->**Prerequisite:** It is assumed you either have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/). +## Prerequisites ->**Note:** In Rancher v2.0.x, registries with authentication are not supported for installing from a private registry. The Docker images can only be pulled from a registry without authentication enabled. This limitation only applies to Docker images. +Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/). -## Release Files +In every [release](https://github.com/rancher/rancher/releases), we provide you with the needed Docker images and scripts to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. -* **rancher-images.txt**: Contains all images needed for that release. -* **rancher-save-images.sh**: This script will pull all needed images from DockerHub, and save all of the images as a compressed file called `rancher-images.tar.gz`. This file can be transferred to your on-premise host that can access your private registry. -* **rancher-load-images.sh**: This script will load images from rancher-images.tar.gz and push them to your private registry. You have to supply the hostname of your private registry as first argument to the script.
`rancher-load-images.sh registry.yourdomain.com:5000` +## Caveats -## Making the Rancher Images Available +In Rancher v2.0.x, registries with authentication are not supported for installing from a private registry. The Docker images can only be pulled from a registry without authentication enabled. This limitation only applies to Docker images. -We will cover two scenarios: +## Air Gap Installation Outline -* **Scenario 1**: You have a node that can access DockerHub to pull and save the images, and a separate node(s) that access your private registry to push the images. -* **Scenario 2**: You have node(s) that can access both DockerHub and your private registry. +While installing Rancher in an air gap configuration, you'll complete several different tasks. -### Scenario 1: A Node that Can Access DockerHub, Separate Node(s) That Can Access the Private Registry +- [1—Preparing the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/) +- [2—Installing Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/) +- [3—Configuring Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/) -![Scenario1]({{< baseurl >}}/img/rancher/airgap/privateregistry.svg) - -1. Browse to the release page of your version of Rancher (e.g. `https://github.com/rancher/rancher/releases/tag/v2.0.0`) and download `rancher-save-images.sh` and `rancher-load-images.sh`. - -2. Transfer and run `rancher-save-images.sh` on the host the can access DockerHub. This will require at least 20GB of disk space. - -3. Transfer the output file from step 2 (`rancher-images.tar.gz`) to the host that can access the private registry. - -4. Transfer and run `rancher-load-images.sh` on the host that can access the private registry. It should be run in the same directory as `rancher-images.tar.gz`. - -### Scenario 2: You have node(s) that can access both DockerHub and your private registry. - -![Scenario2]({{< baseurl >}}/img/rancher/airgap/privateregistrypushpull.svg) - -1. Browse to the release page of your version of Rancher (e.g. `https://github.com/rancher/rancher/releases/tag/v2.0.0`) and download `rancher-images.txt`. - -2. Pull all the images present in `rancher-images.txt`, re-tag each image with the location of your registry, and push the image to the registry. This will require at least 20GB of disk space. See an example script below: - ``` - #!/bin/sh - IMAGES=`curl -s -L https://github.com/rancher/rancher/releases/download/v2.0.0/rancher-images.txt` - for IMAGE in $IMAGES; do - until docker inspect $IMAGE > /dev/null 2>&1; do - docker pull $IMAGE - done - docker tag $IMAGE /$IMAGE - docker push /$IMAGE - done - ``` - -## Completing the Rancher Installation - -After your private registry is setup on all node(s) for your Rancher installation, complete your Rancher installation. - -### Single Node Install - -Complete installation of Rancher using the instructions in [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). - ->**Note:** -> When completing [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/), prepend your private registry URL to the image when running the `docker run` command. -> -> Example: -> ``` -> docker run -d --restart=unless-stopped \ -> -p 80:80 -p 443:443 \ -> /rancher/rancher:latest - ``` - -## Configuring Rancher to Use the Private Registry - -Rancher needs to be configured to use the private registry as source for the needed images. - -1. Go into the **Settings** view. - - ![Settings]({{< baseurl >}}/img/rancher/airgap/settings.png) - -2. Look for the setting called `system-default-registry` and choose **Edit**. - - ![Edit]({{< baseurl >}}/img/rancher/airgap/edit-system-default-registry.png) - -3. 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) - - ->**Note:** If you want to configure the setting when starting the rancher/rancher container, you can use the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. -> -> Example: -> ``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ - /rancher/rancher:v2.0.0 -``` - -You can install Rancher in an air gap environment in a high availability configuration. - -## HA Air Gap Install Outline - -Deployment of Rancher in a high-availability configuration within an air gap environment is a multistep process. - - - - -- [1—Gather Images](#1gather-images) -- [2—Populate the Registry](#2populate-the-registry) -- [3—Run RKE with Private Registry Options](#3run-rke-with-private-registry-options) -- [4—Install Helm (tiller)](#4install-helm-tiller) -- [5—Install Rancher](#5install-rancher) - - - -## 1—Gather Images - -To get started with an HA install within an air gap environment, download the software and files that you'll use for installation. - -1. Download the four images required to populate your private Docker registry, which will be used to launch Rancher Server. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DownloadDescription
RKE - A list of RKE images that are required can be compiled by running the following command. - 
rke config --system-images
-
rancher-images.txt Rancher has additional images it uses when installing clusters. These images are listed in rancher-images.txt, which can be found at GitHub Releases page for rancher/rancher.
Helm tiller Image - You can discover the tiller image compatible with your installed version of helm with the command below. - 
helm init --dry-run --debug | grep image: | awk '{print $2}'
-
cert-manager ImageRancher uses the cert-manager project to issue self-singed certificates for Rancher GUI/Agent access. You can inspect the cert-manager chart values.yaml to find the latest image and tag. - 
 helm inspect values stable/cert-manager
-        ...
-        image:
-          repository: quay.io/jetstack/cert-manager-controller
-          tag: v0.4.1
-        ...
-
- -1. From a system with internet access, use the shell script below to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. - - ```bash - #!/bin/bash - set -e - - # Collect images for Air Gap/Private Registry install - # Requires: - # rke - https://rancher.com/docs/rke/v0.1.x/en/installation/ - # helm - https://docs.helm.sh/using_helm/#installing-helm - # curl - # jq - - echo "RKE Images" - rke config --system-images 2>/dev/null > tmp-images.txt - - echo "Helm Tiller Image" - helm init --dry-run --debug | grep image: | awk '{print $2}' >> tmp-images.txt - - echo "Rancher Images" - latest_url=$(curl -sS "https://api.github.com/repos/rancher/rancher/releases/latest" | jq -r '.assets[]|select(.name=="rancher-images.txt")|.browser_download_url') - curl -sSL ${latest_url} >> tmp-images.txt - - echo "Cert-Manager Image" - cm_repo=$(helm inspect values stable/cert-manager | grep repository: | awk '{print $2}') - cm_tag=$(helm inspect values stable/cert-manager | grep tag: | awk '{print $2}') - echo "${cm_repo}:${cm_tag}" >> tmp-images.txt - - echo "Sort and uniq the images list" - cat tmp-images.txt | sort -u | uniq > images.txt - - # cleanup tmp file - rm tmp-images.txt - ``` - -## 2—Populate the Registry - -Each image in the list needs to be pulled from public registries, tagged with your private registry URL/path, and then pushed up to your private registry. - -1. Pull the images from public registries using the following command: - - ```plain - docker pull rancher/coreos-etcd:v3.1.12 - ``` - -1. Tag the images with your private registry URL and path: - - ```plain - docker tag rancher/coreos-etcd:v3.1.12 /rancher/coreos-etcd:v3.1.12 - ``` -1. Push the images to your private registry: - - ```plain - docker push /rancher/coreos-etcd:v3.1.12 - ``` - -1. Use the shell script below to to populate the private registry. This shell script can be used with a list of images (`images.txt`). To use this script, the system needs access to both the Internet and the private registry. - - ```bash - #!/bin/bash - - # Usage: - # ./populate-images.sh --registry my_registry.example.com --images ./images.txt - - POSITIONAL=() - while [[ $# -gt 0 ]] - do - key="$1" - - case $key in - -r|--registry) - reg="$2" - shift # past argument - shift # past value - ;; - -i|--images) - images="$2" - shift - shift - ;; - esac - done - - if [[ -z $reg ]]; then - echo "-r|--registry is required" - exit 1 - fi - - if [[ -z $images ]]; then - echo "-i|--images file is required" - exit 1 - fi - - echo "Log into Docker registry ${reg}" - docker login ${reg} - - for i in $(cat ${images}); do - docker pull ${i} - docker tag ${i} ${reg}/${i} - docker push ${reg}/${i} - done - ``` - -## 3—Run RKE with Private Registry Options - -Edit your `cluster.yaml` file, specifying your cluster nodes and your private registry. - -1. Edit `cluster.yaml`, specifying the nodes you created. Include the `private_registries:` block. Set `is_default: true` for the registry that you pushed the images to. - - nodes: - - address: 18.222.121.187 - internal_address: 172.31.7.22 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - - address: 18.220.193.254 - internal_address: 172.31.13.132 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - - address: 13.59.83.89 - internal_address: 172.31.3.216 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - private_registries: - - url: my_registry.example.com - user: rancher - password: "*********" - is_default: true - - -1. Run RKE to set up your cluster using your private registry. - - ``` - rke up - ``` - -## 4—Install Helm (tiller) - -Install the Helm package manager. You'll use this software to install Rancher on the Kubernetes cluster you just set up. - -1. The `tiller` serviceAccount that the tiller deployment uses needs credentials to access your private registry. Set up the serviceAccount and RBAC permissions as depicted below. Then patch the service account to add the credentials. - - ``` - kubectl -n kube-system create serviceaccount tiller - kubectl create clusterrolebinding tiller \ - --clusterrole cluster-admin \ - --serviceaccount=kube-system:tiller - ``` - -1. Initialize Helm with the `tiller` image in your private registry. - - ``` - helm init --service-account tiller \ - --tiller-image user-ag-2-registry.rancher.space/gcr.io/kubernetes-helm/tiller:v2.10.0 - ``` - -## 5—Install Rancher - -Finally, we're ready to install Rancher. - -1. Install cert-manager, which automatically creates and handles certificates for your Rancher deployment. - - ``` - helm install stable/cert-manager --name cert-manager --namespace kube-system \ - --set image.repository=user-ag-2-registry.rancher.space/quay.io/jetstack/cert-manager-controller - ``` - -1. Install Rancher, setting the image source and imagePullSecrets options. - - ```plain - helm install rancher-stable/rancher --name rancher --namespace cattle-system \ - --set hostname=user-ag-2.rancher.space \ - --set rancherImage=user-ag-2-registry.rancher.space/rancher/rancher - ``` + +### [Next: Prepare the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md new file mode 100644 index 00000000000..0a794b85f81 --- /dev/null +++ b/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md @@ -0,0 +1,32 @@ +--- +title: 3—Configuring Rancher for the Private Registry +weight: 75 +aliases: +--- + +Rancher needs to be configured to use the private registry as source for the needed images. + +1. Go into the **Settings** view. + + ![Settings]({{< baseurl >}}/img/rancher/airgap/settings.png) + +2. Look for the setting called `system-default-registry` and choose **Edit**. + + ![Edit]({{< baseurl >}}/img/rancher/airgap/edit-system-default-registry.png) + +3. 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) + + +>**Note:** If you want to configure the setting when starting the rancher/rancher container, you can use the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. +> +> Example: +> ``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ + /rancher/rancher:v2.0.0 +``` + + diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md new file mode 100644 index 00000000000..011c59ab297 --- /dev/null +++ b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md @@ -0,0 +1,91 @@ +--- +title: 2—Installing Rancher +weight: 50 +aliases: +--- + +After your private registry is setup for your Rancher installation, complete that installation. Follow one of the procedures below based on the configuration in which you want to run Rancher. + + + +- [Single Node Install](#single-node-install) +- [High Availability Install](#high-availability-install) + + + +## Single Node Install + +To deploy Rancher on a single node in an air gap environment, follow the instructions in [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). Parts of the install where you must complete a special action for air gap are flagged with a substitute step, which is listed in the subheading below. + + +### Add Private Registry URL to Run Command + +When you get [Choose an SSL Option and Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#2-choose-an-ssl-option-and-install-rancher), regardless of which install option you choose, prepend your Rancher image tag with your private registry URL (``), as shown in the example below. + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + /rancher/rancher:latest +``` + +## High Availability Install + +To install Rancher in a high availability configuration within an air gap environment, follow the instructions in [High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). Parts of the install where you must complete a special action for air gap are flagged with substitute steps, which are listed in the subheadings below. + +### Add Private Registry to RKE YAML + +When you get to [Create the rancher-cluster.yml File]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/#create-the-rancher-cluster-yml-file), replace its code sample with the one below, which adds the `private registries` block: + +```yaml +nodes: + - address: 18.222.121.187 + internal_address: 172.31.7.22 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 18.220.193.254 + internal_address: 172.31.13.132 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 13.59.83.89 + internal_address: 172.31.3.216 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + private_registries: + - url: my_registry.example.com + user: rancher + password: "*********" + is_default: true +``` + +### Initialize Helm Using Private Registry + +When you get to [Helm Init]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/#helm-init), add your private registry in the step to initialize Helm, as shown below: + +``` +helm init --service-account tiller \ +--tiller-image user-ag-2-registry.rancher.space/gcr.io/kubernetes-helm/tiller:v2.10.0 +``` + +### Install cert-manager Using Private Registry + +When you get to [Install cert-manager]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#install-cert-manager), replace the install commands provided with the one below: + +``` +helm install stable/cert-manager --name cert-manager --namespace kube-system \ +--set image.repository=user-ag-2-registry.rancher.space/quay.io/jetstack/cert-manager-controller +``` + +### Install Rancher Using Private Registry + +When you get to [Choose Your SSL Configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#choose-your-ssl-configuration), set your `hostname` and `rancherImage`, adding your private registry's URL, as shown below: + +```plain +helm install rancher-stable/rancher --name rancher --namespace cattle-system \ +--set hostname=user-ag-2.rancher.space \ +--set rancherImage=user-ag-2-registry.rancher.space/rancher/rancher +``` + +### [Next: Configuring Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md new file mode 100644 index 00000000000..f17a2d6d909 --- /dev/null +++ b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md @@ -0,0 +1,147 @@ +--- +title: 1—Preparing the Private Registry +weight: 25 +aliases: +--- + +For the first part of your air gap install, you'll prepare your private registry for Rancher installation by downloading the Rancher release files, and then pushing them to your private registry. + +1. Browse to the [Rancher releases page](https://github.com/rancher/rancher/releases) and download the following files from the build with the `Latest release` tag. + + | Release File | Description | + | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `rancher-images.txt` | Contains all images needed to deploy the release. | + | `rancher-load-images.sh` | This script loads images from `rancher-images.tar.gz` and pushes them to your private registry. You have to supply the hostname of your private registry as first argument to the script.
`rancher-load-images.sh registry.yourdomain.com:5000` | + | `rancher-save-images.sh` | This script pulls all needed images from DockerHub and saves all of the images as a compressed file called `rancher-images.tar.gz`. This file can be transferred to your on-premise host that can access your private registry. | + + +1. **High Availablity Installs Only:** You need some additional software to complete installation in an air gap environment. Download the software in the table below. + + | Software | Description | + |----------|-------------| + | RKE | Rancher Kubernetes Engine (RKE) is Rancher's fast, light-weight Kubernetes installer. | + | Helm Image (tiller) | You can discover the tiller image compatible with your installed version of Helm. + | cert-manager | Rancher uses the [cert-manager](https://github.com/jetstack/cert-manager) project to issue self-singed certificates for Rancher GUI/Agent access. + +1. From a system with internet access, use the shell script below to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. + + ```bash + #!/bin/bash + set -e + + # Collect images for Air Gap/Private Registry install + # Requires: + # rke - https://rancher.com/docs/rke/v0.1.x/en/installation/ + # helm - https://docs.helm.sh/using_helm/#installing-helm + # curl + # jq + + echo "RKE Images" + rke config --system-images 2>/dev/null > tmp-images.txt + + echo "Helm Tiller Image" + helm init --dry-run --debug | grep image: | awk '{print $2}' >> tmp-images.txt + + echo "Rancher Images" + latest_url=$(curl -sS "https://api.github.com/repos/rancher/rancher/releases/latest" | jq -r '.assets[]|select(.name=="rancher-images.txt")|.browser_download_url') + curl -sSL ${latest_url} >> tmp-images.txt + + echo "Cert-Manager Image" + cm_repo=$(helm inspect values stable/cert-manager | grep repository: | awk '{print $2}') + cm_tag=$(helm inspect values stable/cert-manager | grep tag: | awk '{print $2}') + echo "${cm_repo}:${cm_tag}" >> tmp-images.txt + + echo "Sort and uniq the images list" + cat tmp-images.txt | sort -u | uniq > images.txt + + # cleanup tmp file + rm tmp-images.txt + ``` +
+1. Use the Rancher release that you just downloaded to populate your private registry with Rancher images. Use the scenario that best matches your use case. +
+{{% tabs %}} +{{% tab "Scenario 1" %}} +
+You have a node that can access DockerHub to pull and save the images, and a separate node(s) that access your private registry to push the images. + +![Scenario1]({{< baseurl >}}/img/rancher/airgap/privateregistry.svg) + +1. Browse to the release page of your version of Rancher (e.g. `https://github.com/rancher/rancher/releases/tag/v2.0.0`) and download `rancher-save-images.sh` and `rancher-load-images.sh`. + +2. Transfer and run `rancher-save-images.sh` on the host the can access DockerHub. This will require at least 20GB of disk space. + +3. Transfer the output file from step 2 (`rancher-images.tar.gz`) to the host that can access the private registry. + +4. Transfer and run `rancher-load-images.sh` on the host that can access the private registry. It should be run in the same directory as `rancher-images.tar.gz`. +{{% /tab %}} +{{% tab "Scenario 2" %}} +
+You have node(s) that can access both DockerHub and your private registry. +![Scenario2]({{< baseurl >}}/img/rancher/airgap/privateregistrypushpull.svg) + +1. Browse to the release page of your version of Rancher (e.g. `https://github.com/rancher/rancher/releases/tag/v2.0.0`) and download `rancher-images.txt`. + +2. Pull all the images present in `rancher-images.txt`, re-tag each image with the location of your registry, and push the image to the registry. This will require at least 20GB of disk space. See an example script below: + ``` + #!/bin/sh + IMAGES=`curl -s -L https://github.com/rancher/rancher/releases/download/v2.0.0/rancher-images.txt` + for IMAGE in $IMAGES; do + until docker inspect $IMAGE > /dev/null 2>&1; do + docker pull $IMAGE + done + docker tag $IMAGE /$IMAGE + docker push /$IMAGE + done + ``` +{{% /tab %}} +{{% /tabs %}} + +1. Use the shell script below to to populate the private registry. This shell script can be used with a list of images (`images.txt`). To use this script, the system needs access to both the Internet and the private registry. + + ```bash + #!/bin/bash + + # Usage: + # ./populate-images.sh --registry my_registry.example.com --images ./images.txt + + POSITIONAL=() + while [[ $# -gt 0 ]] + do + key="$1" + + case $key in + -r|--registry) + reg="$2" + shift # past argument + shift # past value + ;; + -i|--images) + images="$2" + shift + shift + ;; + esac + done + + if [[ -z $reg ]]; then + echo "-r|--registry is required" + exit 1 + fi + + if [[ -z $images ]]; then + echo "-i|--images file is required" + exit 1 + fi + + echo "Log into Docker registry ${reg}" + docker login ${reg} + + for i in $(cat ${images}); do + docker pull ${i} + docker tag ${i} ${reg}/${i} + docker push ${reg}/${i} + done + ``` + +### [Next: Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/) \ No newline at end of file From 9aee0adaf46a025444743da83c78c2a7a93bb799 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Tue, 18 Sep 2018 19:29:26 -0700 Subject: [PATCH 4/8] making edits for air gap --- .../prepare-private-reg/_index.md | 53 +++++++++++++------ .../installation/ha/create-nodes-lb/_index.md | 2 +- .../en/installation/ha/helm-init/_index.md | 2 + .../en/installation/ha/helm-rancher/_index.md | 7 +++ .../installation/ha/kubernetes-rke/_index.md | 24 +++++---- .../en/installation/single-node/_index.md | 8 +++ .../single-node-install-external-lb/_index.md | 5 ++ 7 files changed, 74 insertions(+), 27 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md index f17a2d6d909..4275a3a8136 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md @@ -5,15 +5,21 @@ aliases: --- For the first part of your air gap install, you'll prepare your private registry for Rancher installation by downloading the Rancher release files, and then pushing them to your private registry. + -1. Browse to the [Rancher releases page](https://github.com/rancher/rancher/releases) and download the following files from the build with the `Latest release` tag. +1. Browse to the [Rancher releases page](https://github.com/rancher/rancher/releases) and download the following files from the version of Rancher tagged with `Latest release`. | Release File | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `rancher-images.txt` | Contains all images needed to deploy the release. | - | `rancher-load-images.sh` | This script loads images from `rancher-images.tar.gz` and pushes them to your private registry. You have to supply the hostname of your private registry as first argument to the script.
`rancher-load-images.sh registry.yourdomain.com:5000` | + | `rancher-images.txt` | This file contains all images needed to deploy the release. | + | `rancher-load-images.sh` | This script loads images from `rancher-images.tar.gz` and pushes them to your private registry. You must supply the hostname of your private registry as first argument to the script.
`rancher-load-images.sh registry.yourdomain.com:5000` | | `rancher-save-images.sh` | This script pulls all needed images from DockerHub and saves all of the images as a compressed file called `rancher-images.tar.gz`. This file can be transferred to your on-premise host that can access your private registry. | + >**Installing on a single node?** + > + >The next two steps don't apply to you. Skip to [step 4](#pop-reg). + + 1. **High Availablity Installs Only:** You need some additional software to complete installation in an air gap environment. Download the software in the table below. @@ -22,8 +28,9 @@ For the first part of your air gap install, you'll prepare your private registry | RKE | Rancher Kubernetes Engine (RKE) is Rancher's fast, light-weight Kubernetes installer. | | Helm Image (tiller) | You can discover the tiller image compatible with your installed version of Helm. | cert-manager | Rancher uses the [cert-manager](https://github.com/jetstack/cert-manager) project to issue self-singed certificates for Rancher GUI/Agent access. - -1. From a system with internet access, use the shell script below to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. + + +1. **High Availablity Installs Only:** From a system with internet access, paste the sample below into an empty file and save it as a shell script. Run the script to compile the images required by the latest Rancher release and write them to `images.txt` in the local directory. ```bash #!/bin/bash @@ -57,32 +64,48 @@ For the first part of your air gap install, you'll prepare your private registry # cleanup tmp file rm tmp-images.txt ``` -
-1. Use the Rancher release that you just downloaded to populate your private registry with Rancher images. Use the scenario that best matches your use case. + +1. Use the Rancher release files that you downloaded in [step 1](#step-1) to populate your private registry with Rancher images. Use the scenario that best matches your use case.
{{% tabs %}} {{% tab "Scenario 1" %}}
-You have a node that can access DockerHub to pull and save the images, and a separate node(s) that access your private registry to push the images. +The architecture for this scenario is: + +- A host that can access DockerHub, which pulls and saves Rancher images from the Internet. + +- An on-premise host that acts as an intermediary between: + + - The host that can access DockerHub. + + - Your private registry. + +- An on-premise private registry, which you'll use to deploy Rancher in your air gap environment. +
+
![Scenario1]({{< baseurl >}}/img/rancher/airgap/privateregistry.svg) -1. Browse to the release page of your version of Rancher (e.g. `https://github.com/rancher/rancher/releases/tag/v2.0.0`) and download `rancher-save-images.sh` and `rancher-load-images.sh`. +1. From the host that can access DockerHub, run `rancher-save-images.sh`. This will require at least 20GB of disk space. -2. Transfer and run `rancher-save-images.sh` on the host the can access DockerHub. This will require at least 20GB of disk space. +1. Transfer the output file from the previous step (`rancher-images.tar.gz`) to the on-premise host that can access the private registry. -3. Transfer the output file from step 2 (`rancher-images.tar.gz`) to the host that can access the private registry. - -4. Transfer and run `rancher-load-images.sh` on the host that can access the private registry. It should be run in the same directory as `rancher-images.tar.gz`. +1. Transfer and run `rancher-load-images.sh` on the host that can access the private registry. It should be run in the same directory as `rancher-images.tar.gz`. {{% /tab %}} {{% tab "Scenario 2" %}}
-You have node(s) that can access both DockerHub and your private registry. +The architecture for this scenario is: + +- A host that can access both DockerHub and your private registry + +- An on-premise private registry, which you'll use to deploy Rancher in your air gap environment. +
+
![Scenario2]({{< baseurl >}}/img/rancher/airgap/privateregistrypushpull.svg) -1. Browse to the release page of your version of Rancher (e.g. `https://github.com/rancher/rancher/releases/tag/v2.0.0`) and download `rancher-images.txt`. 2. Pull all the images present in `rancher-images.txt`, re-tag each image with the location of your registry, and push the image to the registry. This will require at least 20GB of disk space. See an example script below: + ``` #!/bin/sh IMAGES=`curl -s -L https://github.com/rancher/rancher/releases/download/v2.0.0/rancher-images.txt` diff --git a/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md index bec3e28dd4c..389b0e89f68 100644 --- a/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md @@ -1,5 +1,5 @@ --- -title: 1 - Create Nodes and Load Balancer +title: 1—Create Nodes and Load Balancer weight: 185 --- diff --git a/content/rancher/v2.x/en/installation/ha/helm-init/_index.md b/content/rancher/v2.x/en/installation/ha/helm-init/_index.md index af3db4243f6..20d057843bb 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-init/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-init/_index.md @@ -13,6 +13,8 @@ Helm installs the `tiller` service on your cluster to manage charts. Since RKE e * Create the `ClusterRoleBinding` to give the `tiller` account access to the cluster. * Finally use `helm` to initialize the `tiller` service +>**Using Air Gap?** [Add the private registry's FQDN]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#initialize-helm-using-private-registry) to the command. + ``` kubectl -n kube-system create serviceaccount tiller kubectl create clusterrolebinding tiller \ diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index 0e0c7cc90a6..310e0cc12ef 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -23,6 +23,9 @@ Rancher relies on [cert-manager](https://github.com/kubernetes/charts/tree/maste Install `cert-manager` from the Helm stable catalog. +>**Using Air Gap?** [Add the private registry's FQDN]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#install-cert-manager-using-private-registry) to the command. + + ``` helm install stable/cert-manager \ --name cert-manager \ @@ -47,6 +50,8 @@ The default is for Rancher to generate a CA and use the `cert-manager` to issue The only requirement is to set the `hostname` to the DNS name you pointed at your Load Balancer. +>**Using Air Gap?** [Set the `rancherImage` option]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#install-rancher-using-private-registry) in your command, pointing toward your private registry. + ``` helm install rancher-stable/rancher \ --name rancher \ @@ -60,6 +65,8 @@ Use [LetsEncrypt](https://letsencrypt.org/)'s free service to issue trusted SSL Set `hostname`, `ingress.tls.source=letEncrypt` and LetsEncrypt options. +>**Using Air Gap?** [Set the `rancherImage` option]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#install-rancher-using-private-registry) in your command, pointing toward your private registry. + ``` helm install rancher-stable/rancher \ --name rancher \ diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md index 1fb6b0a6a48..c7353e5a176 100644 --- a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md @@ -1,15 +1,19 @@ --- -title: 2 - Install Kubernetes with RKE +title: 2—Install Kubernetes with RKE weight: 190 --- -Use RKE to install Kubernetes with a high-availability etcd configuration. +Use RKE to install Kubernetes with a high availability etcd configuration. -### Create the rancher-cluster.yml file +### Create the `rancher-cluster.yml` File Using the sample below create the `rancher-cluster.yml` file. Replace the IP Addresses in the `nodes` list with the IP address or DNS names of the 3 Nodes you created. -> **Note:** If your node has public and internal addresses, it is recommended to set the `internal_address:` so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the `internal_address:` if you want to use self-referencing security groups or firewalls. +> **Notes:** +> +>- Air Gap User? [Add a private registry section]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-to-rke-yaml) to the sample below. +>- If your node has public and internal addresses, it is recommended to set the `internal_address:` so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the `internal_address:` if you want to use self-referencing security groups or firewalls. + ```yaml nodes: @@ -24,7 +28,7 @@ nodes: role: [controlplane,worker,etcd] ``` -#### Common RKE nodes: options +#### Common RKE Nodes: Options | Option | Description | | --- | --- | @@ -34,9 +38,7 @@ nodes: | `ssh_key_path` | (optional) Path to SSH private key used to authenticate to the node | | `user` | (required) A user that can run docker commands | -
- -#### Advanced configurations +#### Advanced Configurations RKE has many configuration options for customizing the install to suit your specific environment. @@ -48,7 +50,7 @@ Please see the [RKE Documentation]({{< baseurl >}}/rke/v0.1.x/en/) for the full rke up --config ./rancher-cluster.yml ``` -### Testing your cluster +### Testing Your Cluster RKE should have created a file `kube_config_rancher-cluster.yml`. This file has the credentials for `kubectl` and `helm`. @@ -69,7 +71,7 @@ NAME STATUS ROLES AGE VER 165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1 ``` -### Check the health of your cluster pods +### Check the Health of Your Cluster Pods Check that all the required pods and containers are healthy are ready to continue. @@ -96,7 +98,7 @@ kube-system rke-metrics-addon-deploy-job-7ljkc 0/1 Completed kube-system rke-network-plugin-deploy-job-6pbgj 0/1 Completed 0 30s ``` -### Save your files +### Save Your Files Save a copy of the `kube_config_rancher-cluster.yml` and `rancher-cluster.yml` files. You will need these files to maintain and upgrade your Rancher instance. diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index 3aa2179099d..3b458f3ff80 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -33,10 +33,13 @@ If you are installing Rancher in a development or testing environment where iden Log into your Linux host, and then run the minimum installation command below. +>**Air Gap User?** [Add your private registry URL]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-url-to-run-command) before the `rancher/rancher` image tag. + docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ rancher/rancher:latest + {{% /accordion %}} {{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Self-Signed" %}} In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. @@ -52,6 +55,8 @@ After creating your certificate, run the Docker command below to install Rancher - Replace `` with the directory path to your certificate file. - Replace ``,``, and `` with your certificate names. +>**Air Gap User?** [Add your private registry URL]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-url-to-run-command) before the `rancher/rancher` image tag. + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -76,6 +81,8 @@ After obtaining your certificate, run the Docker command below. - Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. +>**Air Gap User?** [Add your private registry URL]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-url-to-run-command) before the `rancher/rancher` image tag. + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -97,6 +104,7 @@ For production environments, you also have the options of using [Let's Encrypt]( After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command. Replace `` with your your domain. +>**Air Gap User?** [Add your private registry URL]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-url-to-run-command) before the `rancher/rancher` image tag. docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index 4ac255820ec..e24cefd9cd5 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -47,6 +47,9 @@ If you elect to use a self-signed certificate to encrypt communication, you must 1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file. + >**Air Gap User?** [Add your private registry URL]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-url-to-run-command) before the `rancher/rancher` image tag. + + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -68,6 +71,8 @@ If you use a certificate signed by a recognized CA, installing your certificate 1. Enter the following command. + >**Air Gap User?** [Add your private registry URL]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-url-to-run-command) before the `rancher/rancher` image tag. + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ From bb3c98f726355943817d43f025373c32da6b3e24 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 19 Sep 2018 14:07:14 -0700 Subject: [PATCH 5/8] added content for setting up a bastion host and declaring external IP addresses --- .../air-gap-installation/_index.md | 6 +- .../install-rancher/_index.md | 59 +++++++++++++++++++ .../en/installation/ha/helm-rancher/_index.md | 2 +- .../installation/ha/kubernetes-rke/_index.md | 2 +- 4 files changed, 65 insertions(+), 4 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md index 19d83c0038e..c929ba3a2b9 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md @@ -6,9 +6,11 @@ In environments where security is high priority, you can set up Rancher in an ai ## Prerequisites -Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/). +- Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/). -In every [release](https://github.com/rancher/rancher/releases), we provide you with the needed Docker images and scripts to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. + In every [release](https://github.com/rancher/rancher/releases), we provide you with the needed Docker images and scripts to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. + +- **Installation Option:** Before beginning your air gap installation, choose whether your want it to be a [single-node install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node) or a [high availability install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). View your chosen configuration's introduction notes along with Rancher's [node requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements). ## Caveats diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md index 011c59ab297..48fab2f5320 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md @@ -36,6 +36,8 @@ To install Rancher in a high availability configuration within an air gap enviro When you get to [Create the rancher-cluster.yml File]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/#create-the-rancher-cluster-yml-file), replace its code sample with the one below, which adds the `private registries` block: +>**Note:** When declaring the `address` for each of your air gap nodes, use its external IP address. + ```yaml nodes: - address: 18.222.121.187 @@ -60,6 +62,63 @@ nodes: is_default: true ``` +#### Optional: Run RKE Through Bastion Host + +When setting up an air gap environment, it may be useful to run RKE through a [bastion host]({{< baseurl >}}/rke/v0.1.x/en/config-options/bastion-host/). This configuration can be helpful if you want to keep your RKE config (`rancher-cluster.yml`) or SSH keys on your local machine. Use of a bastion host requires it to be accessible from both the Internet and your air gap nodes over port 22. + +**Port Requirements:** + +| Port | Outgoing Host | Incoming Host | +| ------ | -------------- | ----------------- | +| 22 TCP | local RKE host | bastion host | +| 22 TCP | bastion host | each air gap node | + +To enable running RKE through a bastion server, add the following sample to `rancher-cluster.yml`: + +```yaml +bastion_host: + address: 18.224.54.35 # public IP of the bastion server + user: rancher + port: 22 + ssh_key_path: /path/to/ssh/key +``` + +>**Note:** When declaring the `address` for each of your air gap nodes and bastion host, use its external IP address. + + +**Example in context:** + +```yaml +bastion_host: + address: 18.224.54.35 # public IP of the bastion server + user: rancher + port: 22 + ssh_key_path: /home/user/.ssh/id_rsa +nodes: + - address: 18.222.121.187 + internal_address: 172.31.7.22 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 18.220.193.254 + internal_address: 172.31.13.132 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + - address: 13.59.83.89 + internal_address: 172.31.3.216 + user: rancher + role: [ "controlplane", "etcd", "worker" ] + ssh_key_file: /home/user/.ssh/id_rsa + private_registries: + - url: my_registry.example.com + user: rancher + password: "*********" + is_default: true +``` + +After adding the bastion host to `rancher-cluster.yml`, running `rke up` provisions the Kubernetes cluster through the bastion server, and provides the resulting `kube_config`. However, it's important to note that as your nodes are not accessible by public IP, the machine from which you run `kubectl` in later steps must be able to access your air gapped nodes at the addresses provided. Due to this requirement, you may need to move the resulting `kube_config` after its creation. + ### Initialize Helm Using Private Registry When you get to [Helm Init]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/#helm-init), add your private registry in the step to initialize Helm, as shown below: diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index 310e0cc12ef..8787f4fd931 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -42,7 +42,7 @@ There are three options for the source of the certificate. 2. `letsEncrypt` - Use [LetsEncrypt](https://letsencrypt.org/) to issue a cert. 3. `secret` - Configure a Kubernetes Secret with your certificate files. - +
#### (Default) Rancher Generated Certificates diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md index c7353e5a176..63815a7f85d 100644 --- a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md @@ -11,7 +11,7 @@ Using the sample below create the `rancher-cluster.yml` file. Replace the IP Add > **Notes:** > ->- Air Gap User? [Add a private registry section]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-to-rke-yaml) to the sample below. +>- Air Gap User? [Add a private registry section]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-to-rke-yaml) to the sample below. Optionally, if you want to run RKE through a bastion host you have set up, you can [add one]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#optional-run-rke-through-bastion-host) to `rancher-cluster.yml`. >- If your node has public and internal addresses, it is recommended to set the `internal_address:` so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the `internal_address:` if you want to use self-referencing security groups or firewalls. From 0954d63f87f7daffc47d96aa459da544d76ca911 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Thu, 20 Sep 2018 10:48:04 -0700 Subject: [PATCH 6/8] removed references to bastion host --- .../install-rancher/_index.md | 102 ++++++------------ .../installation/ha/kubernetes-rke/_index.md | 2 +- 2 files changed, 33 insertions(+), 71 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md index 48fab2f5320..948a71e526a 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md @@ -28,100 +28,60 @@ docker run -d --restart=unless-stopped \ /rancher/rancher:latest ``` +>**Note:** If you want to skip [3—Configuring Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/) later, you can complete it now by setting the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. +> +> Example: +> ``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ + /rancher/rancher:v2.0.0 +``` + ## High Availability Install To install Rancher in a high availability configuration within an air gap environment, follow the instructions in [High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). Parts of the install where you must complete a special action for air gap are flagged with substitute steps, which are listed in the subheadings below. ### Add Private Registry to RKE YAML -When you get to [Create the rancher-cluster.yml File]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/#create-the-rancher-cluster-yml-file), replace its code sample with the one below, which adds the `private registries` block: +When you get to [Create the rancher-cluster.yml File]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/#create-the-rancher-cluster-yml-file), replace its code sample with the one below, which adds the `private registries` block. Replace each `address`, `internal_address`, and `url` with the with the address information for each of your hosts. + +Replace values in the code sample according to the table below. + +| Directive Replacement | Description | +| ----------------------- | --------------------------------------------------------------------- | +| `address` | The IP address for each of your air gap nodes outside of the cluster. | +| `internal address` | The IP address for each of your air gap nodes within the cluster. | +| `url` | The URL for your private registry. | ->**Note:** When declaring the `address` for each of your air gap nodes, use its external IP address. ```yaml nodes: - - address: 18.222.121.187 - internal_address: 172.31.7.22 + - address: 18.222.121.187 # air gap node external IP + internal_address: 172.31.7.22 # air gap node internal IP user: rancher role: [ "controlplane", "etcd", "worker" ] ssh_key_file: /home/user/.ssh/id_rsa - - address: 18.220.193.254 - internal_address: 172.31.13.132 + - address: 18.220.193.254 # air gap node external IP + internal_address: 172.31.13.132 # air gap node internal IP user: rancher role: [ "controlplane", "etcd", "worker" ] ssh_key_file: /home/user/.ssh/id_rsa - - address: 13.59.83.89 - internal_address: 172.31.3.216 + - address: 13.59.83.89 # air gap node external IP + internal_address: 172.31.3.216 # air gap node internal IP user: rancher role: [ "controlplane", "etcd", "worker" ] ssh_key_file: /home/user/.ssh/id_rsa private_registries: - - url: my_registry.example.com + - url: my_registry.example.com # private registry url user: rancher password: "*********" is_default: true ``` -#### Optional: Run RKE Through Bastion Host - -When setting up an air gap environment, it may be useful to run RKE through a [bastion host]({{< baseurl >}}/rke/v0.1.x/en/config-options/bastion-host/). This configuration can be helpful if you want to keep your RKE config (`rancher-cluster.yml`) or SSH keys on your local machine. Use of a bastion host requires it to be accessible from both the Internet and your air gap nodes over port 22. - -**Port Requirements:** - -| Port | Outgoing Host | Incoming Host | -| ------ | -------------- | ----------------- | -| 22 TCP | local RKE host | bastion host | -| 22 TCP | bastion host | each air gap node | - -To enable running RKE through a bastion server, add the following sample to `rancher-cluster.yml`: - -```yaml -bastion_host: - address: 18.224.54.35 # public IP of the bastion server - user: rancher - port: 22 - ssh_key_path: /path/to/ssh/key -``` - ->**Note:** When declaring the `address` for each of your air gap nodes and bastion host, use its external IP address. - - -**Example in context:** - -```yaml -bastion_host: - address: 18.224.54.35 # public IP of the bastion server - user: rancher - port: 22 - ssh_key_path: /home/user/.ssh/id_rsa -nodes: - - address: 18.222.121.187 - internal_address: 172.31.7.22 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - - address: 18.220.193.254 - internal_address: 172.31.13.132 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - - address: 13.59.83.89 - internal_address: 172.31.3.216 - user: rancher - role: [ "controlplane", "etcd", "worker" ] - ssh_key_file: /home/user/.ssh/id_rsa - private_registries: - - url: my_registry.example.com - user: rancher - password: "*********" - is_default: true -``` - -After adding the bastion host to `rancher-cluster.yml`, running `rke up` provisions the Kubernetes cluster through the bastion server, and provides the resulting `kube_config`. However, it's important to note that as your nodes are not accessible by public IP, the machine from which you run `kubectl` in later steps must be able to access your air gapped nodes at the addresses provided. Due to this requirement, you may need to move the resulting `kube_config` after its creation. - ### Initialize Helm Using Private Registry -When you get to [Helm Init]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/#helm-init), add your private registry in the step to initialize Helm, as shown below: +When you get to [Helm Init]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/#helm-init), add your private registry in the step to initialize Helm, as shown below. Replace `user-ag-2-registry.rancher.space` with your registry's hostname and domain. ``` helm init --service-account tiller \ @@ -130,7 +90,8 @@ helm init --service-account tiller \ ### Install cert-manager Using Private Registry -When you get to [Install cert-manager]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#install-cert-manager), replace the install commands provided with the one below: +When you get to [Install cert-manager]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#install-cert-manager), replace the install commands provided with the one below. Replace `user-ag-2-registry.rancher.space` with your registry's hostname and domain. + ``` helm install stable/cert-manager --name cert-manager --namespace kube-system \ @@ -139,9 +100,10 @@ helm install stable/cert-manager --name cert-manager --namespace kube-system \ ### Install Rancher Using Private Registry -When you get to [Choose Your SSL Configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#choose-your-ssl-configuration), set your `hostname` and `rancherImage`, adding your private registry's URL, as shown below: +When you get to [Choose Your SSL Configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#choose-your-ssl-configuration), set your `hostname` and `rancherImage`, replacing `user-ag-2-registry.rancher.space` with your registry's hostname and domain. -```plain + +``` helm install rancher-stable/rancher --name rancher --namespace cattle-system \ --set hostname=user-ag-2.rancher.space \ --set rancherImage=user-ag-2-registry.rancher.space/rancher/rancher diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md index 63815a7f85d..c7353e5a176 100644 --- a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md @@ -11,7 +11,7 @@ Using the sample below create the `rancher-cluster.yml` file. Replace the IP Add > **Notes:** > ->- Air Gap User? [Add a private registry section]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-to-rke-yaml) to the sample below. Optionally, if you want to run RKE through a bastion host you have set up, you can [add one]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#optional-run-rke-through-bastion-host) to `rancher-cluster.yml`. +>- Air Gap User? [Add a private registry section]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#add-private-registry-to-rke-yaml) to the sample below. >- If your node has public and internal addresses, it is recommended to set the `internal_address:` so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the `internal_address:` if you want to use self-referencing security groups or firewalls. From 7a6725a0f30fe84b468d2560ce6ec095e6323f84 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Thu, 20 Sep 2018 16:28:04 -0700 Subject: [PATCH 7/8] added draft flags --- .../config-rancher-for-private-reg/_index.md | 2 +- .../installation/air-gap-installation/install-rancher/_index.md | 2 +- .../air-gap-installation/prepare-private-reg/_index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md index 0a794b85f81..7e1b61ec13f 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md @@ -1,7 +1,7 @@ --- title: 3—Configuring Rancher for the Private Registry weight: 75 -aliases: +draft: true --- Rancher needs to be configured to use the private registry as source for the needed images. diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md index 948a71e526a..9ff6c453b72 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md @@ -1,7 +1,7 @@ --- title: 2—Installing Rancher weight: 50 -aliases: +draft: true --- After your private registry is setup for your Rancher installation, complete that installation. Follow one of the procedures below based on the configuration in which you want to run Rancher. diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md index 4275a3a8136..0c895d4ee4f 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md @@ -1,7 +1,7 @@ --- title: 1—Preparing the Private Registry weight: 25 -aliases: +draft: true --- For the first part of your air gap install, you'll prepare your private registry for Rancher installation by downloading the Rancher release files, and then pushing them to your private registry. From bcf346bf586f73ffe5191d68aaa6055f37d887ab Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Fri, 21 Sep 2018 11:56:13 -0700 Subject: [PATCH 8/8] cleaned up typos --- .../air-gap-installation/_index.md | 6 ++--- .../config-rancher-for-private-reg/_index.md | 6 +++-- .../install-rancher/_index.md | 25 +++++++++---------- .../prepare-private-reg/_index.md | 6 ++--- 4 files changed, 22 insertions(+), 21 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md index c929ba3a2b9..72e3c5e9c57 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md @@ -6,11 +6,11 @@ In environments where security is high priority, you can set up Rancher in an ai ## Prerequisites -- Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/). +- Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation](https://docs.docker.com/registry/). - In every [release](https://github.com/rancher/rancher/releases), we provide you with the needed Docker images and scripts to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. + For each Rancher [release](https://github.com/rancher/rancher/releases), we provide the Docker images and scripts needed to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. -- **Installation Option:** Before beginning your air gap installation, choose whether your want it to be a [single-node install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node) or a [high availability install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). View your chosen configuration's introduction notes along with Rancher's [node requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements). +- **Installation Option:** Before beginning your air gap installation, choose whether you want ~~a~~ [single-node install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node) or a [high availability install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). View your chosen configuration's introduction notes along with Rancher's [node requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements). ## Caveats diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md index 7e1b61ec13f..4084d537d00 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/_index.md @@ -6,15 +6,17 @@ draft: true Rancher needs to be configured to use the private registry as source for the needed images. +1. Log into Rancher and configure the default admin password. + 1. Go into the **Settings** view. ![Settings]({{< baseurl >}}/img/rancher/airgap/settings.png) -2. Look for the setting called `system-default-registry` and choose **Edit**. +1. Look for the setting called `system-default-registry` and choose **Edit**. ![Edit]({{< baseurl >}}/img/rancher/airgap/edit-system-default-registry.png) -3. Change the value to your registry (e.g. `registry.yourdomain.com:port`). Do not prefix the registry with `http://` or `https://`. +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) diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md index 9ff6c453b72..3578650b56e 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/install-rancher/_index.md @@ -8,19 +8,18 @@ After your private registry is setup for your Rancher installation, complete tha -- [Single Node Install](#single-node-install) -- [High Availability Install](#high-availability-install) +- [Single Node Air Gap Install](#single-node-air-gap-install) +- [High Availability Air Gap Install](#high-availability-air-gap-install) +## Single Node Air Gap Install -## Single Node Install - -To deploy Rancher on a single node in an air gap environment, follow the instructions in [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). Parts of the install where you must complete a special action for air gap are flagged with a substitute step, which is listed in the subheading below. +To deploy Rancher on a single node in an air gap environment, follow the instructions in the standard [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). Parts of the install where you must complete a special action for air gap are flagged with a substitute step, which is listed in the subheading below. ### Add Private Registry URL to Run Command -When you get [Choose an SSL Option and Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#2-choose-an-ssl-option-and-install-rancher), regardless of which install option you choose, prepend your Rancher image tag with your private registry URL (``), as shown in the example below. +When you get to the section [Choose an SSL Option and Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#2-choose-an-ssl-option-and-install-rancher), regardless of which install option you choose, prepend your Rancher image tag with your private registry URL (``), as shown in the example below. ``` docker run -d --restart=unless-stopped \ @@ -31,16 +30,16 @@ docker run -d --restart=unless-stopped \ >**Note:** If you want to skip [3—Configuring Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/config-rancher-for-private-reg/) later, you can complete it now by setting the environment variable `CATTLE_SYSTEM_DEFAULT_REGISTRY`. > > Example: -> ``` +``` docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ - /rancher/rancher:v2.0.0 + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ + /rancher/rancher:v2.0.0 ``` -## High Availability Install +## High Availability Air Gap Install -To install Rancher in a high availability configuration within an air gap environment, follow the instructions in [High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). Parts of the install where you must complete a special action for air gap are flagged with substitute steps, which are listed in the subheadings below. +To install Rancher in a high availability configuration within an air gap environment, follow the instructions in the standard [High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha). Parts of the install where you must complete a special action for air gap are flagged with substitute steps, which are listed in the subheadings below. ### Add Private Registry to RKE YAML @@ -51,7 +50,7 @@ Replace values in the code sample according to the table below. | Directive Replacement | Description | | ----------------------- | --------------------------------------------------------------------- | | `address` | The IP address for each of your air gap nodes outside of the cluster. | -| `internal address` | The IP address for each of your air gap nodes within the cluster. | +| `internal_address` | The IP address for each of your air gap nodes within the cluster. | | `url` | The URL for your private registry. | diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md index 0c895d4ee4f..b86f31d5150 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/_index.md @@ -88,7 +88,7 @@ The architecture for this scenario is: 1. From the host that can access DockerHub, run `rancher-save-images.sh`. This will require at least 20GB of disk space. -1. Transfer the output file from the previous step (`rancher-images.tar.gz`) to the on-premise host that can access the private registry. +1. Transfer the output file from the previous step (`rancher-images.tar.gz`) to the host that can access the private registry. 1. Transfer and run `rancher-load-images.sh` on the host that can access the private registry. It should be run in the same directory as `rancher-images.tar.gz`. {{% /tab %}} @@ -96,7 +96,7 @@ The architecture for this scenario is:
The architecture for this scenario is: -- A host that can access both DockerHub and your private registry +- A host that can access both DockerHub and your private registry. - An on-premise private registry, which you'll use to deploy Rancher in your air gap environment.
@@ -104,7 +104,7 @@ The architecture for this scenario is: ![Scenario2]({{< baseurl >}}/img/rancher/airgap/privateregistrypushpull.svg) -2. Pull all the images present in `rancher-images.txt`, re-tag each image with the location of your registry, and push the image to the registry. This will require at least 20GB of disk space. See an example script below: +2. Pull all the images present in `rancher-images.txt`, re-tag each image with the location of your registry, and push the image to the registry. This action requires at least 20GB of disk space. See an example script below: ``` #!/bin/sh