Air-gapped clusters

This document walks you through the process of installing Portworx into an air-gapped environment. First, you must fetch the required container images from the public container registries on the internet. Then, you can load these images directly onto your nodes or upload them into your private container registry. Once you’ve loaded the Portworx images, you will continue with the standard installation procedure.

Step 1: Download the air-gapped bootstrap script

  1. Export your Kubernetes version by entering the following command:

    KBVER=$(kubectl version --short | awk -F'[v+_-]' '/Server Version: / {print $3}')

    If the current node doesn’t have kubectl installed, you can set the KBVER variable manually by running export KBVER=<YOUR_KUBERNETES_VERSION>. For example, if your Kubernetes version is 1.19.3, run the following command:

  2. Download the air-gapped-install bootstrap script by entering the following curl command:

    curl -o -L "$KBVER"

Step 2: Pull the container images

Pull the container images by running the px-ag-install script with the pull option:

sh pull

Step 3: Make container images available to your nodes

There are two ways in which you can make the Portworx container images available to your nodes:

  • Follow Step 3a if your company uses private container registry
  • Otherwise, follow Step 3b to push directly to your nodes

Step 3a: Push to a local registry server, accessible by the air-gapped nodes

NOTE: For details about how you can use a private registry, see the Using a Private Registry section of the Kubernetes documentation.
  1. Push the images to the registry by running the px-ag-install script with the push option and your registry location:


    For example:

    sh push

    alternatively you can put all images in the same repository:

    sh push
  2. Once you’ve loaded the images into your registry, continue with Step 4: Install Portworx. When you install Portworx, specify your custom registry in the Customize section of the spec generator:

    Screenshot showing the customize section

Step 3b: Push directly to your nodes

Load container images onto your nodes individually by running the px-ag-install script with the load option and your intranet host locations:

sh load <intranet-host> [<host2> <host3>...]

For <intranet-host>, use the hostname or IP-address of your node.


  • The command above uses ssh to load the images on the nodes on intranet. You can customize or replace the ssh command with the -e command switch. For example, -e "sshpass -p 5ecr3t ssh -l root" uses the sshpass(1) command to automatically pass root’s password when logging into the intranet host.
  • If you’re using this method, you can specify Image Pull Policy as IfNotPresent or Never on the “Registry and Image Settings” page when generating the Portworx spec.

Step 4: Install Portworx

Once you have loaded the Portworx images into your registry or nodes, you’re ready to create an install spec using the spec generator. Determine whether you need to specify the PX_HTTP_PROXY environment variable during installation:

Specify the PX_HTTP_PROXY environment variable

SharedV4 volumes require that your host run dependent services. If your host does not already have dependent services installed, Portworx will attempt to install them automatically. However, installation may fail if the hosts are not configured properly. For example: if your host is air-gapped and does not have dependent packages on intranet-accessible package repositories, or doesn’t have package management configured to use the HTTP proxy server.

If your air-gapped environment doesn’t have a system-wide HTTP proxy, you must specify the PX_HTTP_PROXY=... variable in the environment variables tab of the spec generator to define the HTTP proxy for Portworx installation, including the automated installation of NFS service on the host.

Create an install spec

Using the Portworx spec generator, create an install spec, making sure to enable sharedV4 support and specify the PX_HTTP_PROXY environment variable if you need to.

Refer to the following installation topics for more installation information:

Air-gapped install bootstrap script reference

./ [image-commands] [options] '[arguments...]'
NOTE: The script name reflects the default name specified in the installation instructions, but can be whatever you named the script file when you downloaded it.

Image commands

Command Description Required?
pull Pulls the Portworx container images locally
push <registry[/repo]> Pushes the Portworx images into remote container registry server
load node1 [node2 [...]] Loads the images tarball to remote nodes (note: ssh-access required)


Option Description Required?
--help Displays help output
-I, --include <image> Specify additional images to include
-E, --exclude <glob> Specify images to EXCLUDE (e.g. -E ‘csi’)
-n, --dry-run Show commands instead of running
-V, --version Print version of the script
-v Verbose output

Load-specific options

Option Description Required?
-e, --rsh <command> specify the remote shell to use (default ssh)
-L, --load-cmd <command> specify the remote container-load command to use (default auto)
-t <prefix> specify temporary tarball filename (default px-agtmp.tar)
--pks assume PKS environment; transfer images using ‘bosh’ command


  • Pull images from default container registries, push them to custom registry server (default repositories) pull push
  • Pull images from default container registries, push them to custom registry server and portworx repository pull push
  • Push images to password-protected remote registry, then import docker/podman configuration as kuberentes secret

    docker login pull push import-secrets
  • Pull images, then load to given nodes using ssh pull load node1 node2 node33 node444
  • Pull images, then load to given nodes using ssh and root-account -e "ssh -l root" pull load node1 node2 node33 node444
  • Load images to given nodes using ssh and password ‘5ecr3t’ -e "sshpass -p 5ecr3t ssh" load node1 node2 node33 node444
  • Pull ONLY busybox image, load it to given nodes -E '*' -I pull load node1 node2 node33 node444

Last edited: Wednesday, Dec 16, 2020