XTesting/kubespray/docs/offline-environment.md

   1 # Offline environment
   2
   3 In case your servers don't have access to internet (for example when deploying on premises with security constraints), you need to setup:
   4
   5 * a HTTP reverse proxy/cache/mirror to serve some static files (zips and binaries)
   6 * an internal Yum/Deb repository for OS packages
   7 * an internal container image registry that need to be populated with all container images used by Kubespray. Exhaustive list depends on your setup
   8 * [Optional] an internal PyPi server for kubespray python packages (only required if your OS doesn't provide all python packages/versions listed in `requirements.txt`)
   9 * [Optional] an internal Helm registry (only required if `helm_enabled=true`)
  10
  11 ## Configure Inventory
  12
  13 Once all artifacts are accessible from your internal network, **adjust** the following variables in [your inventory](/inventory/sample/group_vars/all/offline.yml) to match your environment:
  14
  15 ```yaml
  16 # Registry overrides
  17 kube_image_repo: "{{ registry_host }}"
  18 gcr_image_repo: "{{ registry_host }}"
  19 docker_image_repo: "{{ registry_host }}"
  20 quay_image_repo: "{{ registry_host }}"
  21
  22 kubeadm_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubeadm"
  23 kubectl_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubectl"
  24 kubelet_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubelet"
  25 # etcd is optional if you **DON'T** use etcd_deployment=host
  26 etcd_download_url: "{{ files_repo }}/kubernetes/etcd/etcd-{{ etcd_version }}-linux-amd64.tar.gz"
  27 cni_download_url: "{{ files_repo }}/kubernetes/cni/cni-plugins-linux-{{ image_arch }}-{{ cni_version }}.tgz"
  28 crictl_download_url: "{{ files_repo }}/kubernetes/cri-tools/crictl-{{ crictl_version }}-{{ ansible_system | lower }}-{{ image_arch }}.tar.gz"
  29 # If using Calico
  30 calicoctl_download_url: "{{ files_repo }}/kubernetes/calico/{{ calico_ctl_version }}/calicoctl-linux-{{ image_arch }}"
  31 # If using Calico with kdd
  32 calico_crds_download_url: "{{ files_repo }}/kubernetes/calico/{{ calico_version }}.tar.gz"
  33 # Containerd
  34 containerd_download_url: "{{ files_repo }}/containerd-{{ containerd_version }}-linux-{{ image_arch }}.tar.gz"
  35 runc_download_url: "{{ files_repo }}/runc.{{ image_arch }}"
  36 nerdctl_download_url: "{{ files_repo }}/nerdctl-{{ nerdctl_version }}-{{ ansible_system | lower }}-{{ image_arch }}.tar.gz"
  37 # Insecure registries for containerd
  38 containerd_insecure_registries:
  39   - "{{ registry_host }}"
  40
  41 # CentOS/Redhat/AlmaLinux/Rocky Linux
  42 ## Docker / Containerd
  43 docker_rh_repo_base_url: "{{ yum_repo }}/docker-ce/$releasever/$basearch"
  44 docker_rh_repo_gpgkey: "{{ yum_repo }}/docker-ce/gpg"
  45
  46 # Fedora
  47 ## Docker
  48 docker_fedora_repo_base_url: "{{ yum_repo }}/docker-ce/{{ ansible_distribution_major_version }}/{{ ansible_architecture }}"
  49 docker_fedora_repo_gpgkey: "{{ yum_repo }}/docker-ce/gpg"
  50 ## Containerd
  51 containerd_fedora_repo_base_url: "{{ yum_repo }}/containerd"
  52 containerd_fedora_repo_gpgkey: "{{ yum_repo }}/docker-ce/gpg"
  53
  54 # Debian
  55 ## Docker
  56 docker_debian_repo_base_url: "{{ debian_repo }}/docker-ce"
  57 docker_debian_repo_gpgkey: "{{ debian_repo }}/docker-ce/gpg"
  58 ## Containerd
  59 containerd_debian_repo_base_url: "{{ ubuntu_repo }}/containerd"
  60 containerd_debian_repo_gpgkey: "{{ ubuntu_repo }}/containerd/gpg"
  61 containerd_debian_repo_repokey: 'YOURREPOKEY'
  62
  63 # Ubuntu
  64 ## Docker
  65 docker_ubuntu_repo_base_url: "{{ ubuntu_repo }}/docker-ce"
  66 docker_ubuntu_repo_gpgkey: "{{ ubuntu_repo }}/docker-ce/gpg"
  67 ## Containerd
  68 containerd_ubuntu_repo_base_url: "{{ ubuntu_repo }}/containerd"
  69 containerd_ubuntu_repo_gpgkey: "{{ ubuntu_repo }}/containerd/gpg"
  70 containerd_ubuntu_repo_repokey: 'YOURREPOKEY'
  71 ```
  72
  73 For the OS specific settings, just define the one matching your OS.
  74 If you use the settings like the one above, you'll need to define in your inventory the following variables:
  75
  76 * `registry_host`: Container image registry. If you _don't_ use the same repository path for the container images that the ones defined in [Download's role defaults](https://github.com/kubernetes-sigs/kubespray/blob/master/roles/download/defaults/main.yml), you need to override the `*_image_repo` for these container images. If you want to make your life easier, use the same repository path, you won't have to override anything else.
  77 * `files_repo`: HTTP webserver or reverse proxy that is able to serve the files listed above. Path is not important, you can store them anywhere as long as it's accessible by kubespray. It's recommended to use `*_version` in the path so that you don't need to modify this setting everytime kubespray upgrades one of these components.
  78 * `yum_repo`/`debian_repo`/`ubuntu_repo`: OS package repository depending of your OS, should point to your internal repository. Adjust the path accordingly.
  79
  80 ## Install Kubespray Python Packages
  81
  82 ### Recommended way: Kubespray Container Image
  83
  84 The easiest way is to use [kubespray container image](https://quay.io/kubespray/kubespray) as all the required packages are baked in the image.
  85 Just copy the container image in your private container image registry and you are all set!
  86
  87 ### Manual installation
  88
  89 Look at the `requirements.txt` file and check if your OS provides all packages out-of-the-box (Using the OS package manager). For those missing, you need to either use a proxy that has Internet access (typically from a DMZ) or setup a PyPi server in your network that will host these packages.
  90
  91 If you're using a HTTP(S) proxy to download your python packages:
  92
  93 ```bash
  94 sudo pip install --proxy=https://[username:password@]proxyserver:port -r requirements.txt
  95 ```
  96
  97 When using an internal PyPi server:
  98
  99 ```bash
 100 # If you host all required packages
 101 pip install -i https://pypiserver/pypi -r requirements.txt
 102
 103 # If you only need the ones missing from the OS package manager
 104 pip install -i https://pypiserver/pypi package_you_miss
 105 ```
 106
 107 ## Run Kubespray as usual
 108
 109 Once all artifacts are in place and your inventory properly set up, you can run kubespray with the regular `cluster.yaml` command:
 110
 111 ```bash
 112 ansible-playbook -i inventory/my_airgap_cluster/hosts.yaml -b cluster.yml
 113 ```
 114
 115 If you use [Kubespray Container Image](#recommended-way:-kubespray-container-image), you can mount your inventory inside the container:
 116
 117 ```bash
 118 docker run --rm -it -v path_to_inventory/my_airgap_cluster:inventory/my_airgap_cluster myprivateregisry.com/kubespray/kubespray:v2.14.0 ansible-playbook -i inventory/my_airgap_cluster/hosts.yaml -b cluster.yml
 119 ```