Air-gapped Installation on Kubernetes

The air-gapped installation is almost the same as the online installation except that you must create a local registry to host container images. This tutorial demonstrates how to install Kube AI Hub on Kubernetes in an air-gapped environment.

Before you follow the steps below, read Prerequisites first.

Step 1: Prepare a Private Image Registry

You can use Harbor or any other private image registries. This tutorial uses a generic image registry as an example (if you have your own private image registry, you can skip this step).

Use self-signed certificates

1. Generate your own certificate by executing the following commands:

   mkdir -p certs
   

   openssl req \
   -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
   -x509 -days 36500 -out certs/domain.crt
   

2. Make sure you specify a domain name in the field Common Name when you are generating your own certificate. For instance, the field is set to registry.example.local in this example.

Start the image registry

Run the following commands to start the image registry:

docker run -d \
  --restart=always \
  --name registry \
  -v "$(pwd)"/certs:/certs \
  -v /mnt/registry:/var/lib/registry \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -p 443:443 \
  registry:2

Configure the registry

1. Add an entry to /etc/hosts to map the hostname (i.e. the registry domain name; in this case, it is registry.example.local) to the private IP address of your machine as below.

   # container registry
   192.168.0.2 registry.example.local
   

2. Execute the following commands to copy the certificate to the specified directory and make containerd trust the certificate.

   mkdir -p /etc/containerd/certs.d/registry.example.local
   

   cp certs/domain.crt /etc/containerd/certs.d/registry.example.local/ca.crt
   

   Note

   The path of the certificate is associated with the domain name. When you copy the path, use the actual domain name if it is different from the one set above.

3. To verify whether the private registry is effective, you can copy an image to your local machine first and use ctr or crictl to test it.

Step 2: Prepare Installation Images

When you install Kube AI Hub in an air-gapped environment, you need to prepare an image package containing all necessary images in advance.

1. Obtain the image list file images-list.txt from your delivery channel.

   Note

   This file lists images under ##+modulename based on different modules. You can add your own images to this file following the same rule.

2. Obtain offline-installation-tool.sh from your delivery channel.

3. Make the .sh file executable.

   chmod +x offline-installation-tool.sh
   

4. You can execute the command ./offline-installation-tool.sh -h to see how to use the script:

   Usage:
   
     ./offline-installation-tool.sh [-l IMAGES-LIST] [-d IMAGES-DIR] [-r PRIVATE-REGISTRY] [-v KUBERNETES-VERSION ]
   
   Description:
     -b                     : save kubernetes' binaries.
     -d IMAGES-DIR          : the dir of files (tar.gz) which generated by `docker save`. default: ./kubesphere-images
     -l IMAGES-LIST         : text file with list of images.
     -r PRIVATE-REGISTRY    : target private registry:port.
     -s                     : save model will be applied. Pull the images in the IMAGES-LIST and save images as a tar.gz file.
     -v KUBERNETES-VERSION  : download kubernetes' binaries. default: v1.34.4
     -h                     : usage message
   

5. Pull images in offline-installation-tool.sh.

   ./offline-installation-tool.sh -s -l images-list.txt -d ./kubesphere-images
   

   Note

   You can choose to pull images as needed. For example, you can delete ##k8s-images and related images under it in images-list.txt if you already have a Kubernetes cluster.

Step 3: Push Images to Your Private Registry

Transfer your packaged image file to your local machine and execute the following command to push it to the registry.

./offline-installation-tool.sh -l images-list.txt -d ./kubesphere-images -r registry.example.local

Step 4: Download Deployment Files

Similar to installing Kube AI Hub on an existing Kubernetes cluster in an online environment, you also need to download cluster-configuration.yaml and kubesphere-installer.yaml first.

1. Obtain these two files from your delivery channel and transfer them to your machine serving as the taskbox for installation.

2. Edit cluster-configuration.yaml to add your private image registry. For example, registry.example.local is the registry address in this tutorial, and use it as the value of .spec.local_registry as below.

   spec:
     persistence:
       storageClass: ""
     authentication:
       jwtSecret: ""
     local_registry: registry.example.local # Add this line manually; make sure you use your own registry address.
   

   Note

   You can enable pluggable components in this YAML file to explore more features of Kube AI Hub. Refer to Enable Pluggable Components for details.

3. Save cluster-configuration.yaml after you finish editing it. Replace ks-installer with your own registry address with the following command.

   sed -i "s#^\s*image: kubesphere.*/ks-installer:.*#        image: registry.example.local/kubesphere/ks-installer:v3.4.0#" kubesphere-installer.yaml
   

   Warning

   The registry address is registry.example.local in the command. Please make sure you use your own registry address.

Step 5: Start Installation

After you make sure that all the steps above are completed, you can execute the following command.

kubectl apply -f kubesphere-installer.yaml
kubectl apply -f cluster-configuration.yaml

Step 6: Verify Installation

When the installation finishes, you can see the content as follows:

#####################################################
###              Welcome to Kube AI Hub!           ###
#####################################################

Console: http://192.168.0.2:30880
Account: admin
Password: P@88w0rd

NOTES：
  1. After logging into the console, please check the
     monitoring status of service components in
     the "Cluster Management". If any service is not
     ready, please wait patiently until all components
     are ready.
  2. Please modify the default password after login.

#####################################################

Now, you will be able to access the web console of Kube AI Hub at http://{IP}:30880 with the default account and password admin/P@88w0rd.