Air-gapped environments

Install the Solo distribution of Istio in an air-gapped environment using a private registry.

Install the Solo distribution of Istio in an environment without public internet access by pulling the required Istio component images on a connected device and transferring them to a private registry that your disconnected cluster can reach.

If you also plan to install the Solo UI, see Install the Solo UI in air-gapped environments after completing this guide.

Before you begin

Make sure that you have the following components set up in your environment accounts before you start the installation.

Connected device: A device with public internet access to pull images and Helm charts from us-docker.pkg.dev.

Disconnected device: The server or cluster in your air-gapped environment where you run the installation.

Private registry: A container registry that is reachable from both devices, such as Sonatype Nexus Repository or JFrog Artifactory. Your connected device pushes images to it, and your disconnected cluster pulls the images from it during installation. You might also need to add registry credentials to your cluster as an image pull secret, such as a global image pull secret on OpenShift.

Step 1: Enumerate Istio images

Complete the following steps on your connected device to identify the images that your installation requires.

Install the required CLIs.
- helm v3.x
- docker or crane

Set environment variables for the Solo distribution of Istio version and image repositories.

export ISTIO_VERSION=1.30.4-patch0
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
export REPO=us-docker.pkg.dev/soloio-img/istio
export HELM_REPO=us-docker.pkg.dev/soloio-img/istio-helm

Create a working directory and pull the Istio Helm charts for ambient mesh.

mkdir istio-charts && cd istio-charts
helm pull oci://${HELM_REPO}/base --version ${ISTIO_VERSION}
helm pull oci://${HELM_REPO}/istiod --version ${ISTIO_VERSION}
helm pull oci://${HELM_REPO}/cni --version ${ISTIO_VERSION}
helm pull oci://${HELM_REPO}/ztunnel --version ${ISTIO_VERSION}

Render each chart to extract the full list of container image references.
```
for chart in *.tgz; do
  helm template release "$chart" \
    --set global.hub=${REPO} \
    --set global.tag=${ISTIO_IMAGE} 2>/dev/null
done | grep 'image:' | sort -u
```
The output lists every image: reference across all ambient mesh components. Use this list in the next step to pull each image.

Note

If you use the Gloo Operator to install Istio, you must also enumerate the operator’s own images. Set GLOO_OPERATOR_VERSION to the operator version you want, pull the oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator chart, and run helm template on it in the same way.

Step 2: Transfer images and charts to your private registry

Complete the following steps on your connected device to pull all images and push them to your private registry.

Set an environment variable for your private registry address.
```
export REGISTRY=<your-private-registry>
```
Pull each image that you identified in the previous section. The following example uses docker pull, but you can substitute crane pull or any compatible tool. If helm template returned any other images that are not listed here, pull those additional images too.
```
docker pull ${REPO}/pilot:${ISTIO_IMAGE}
docker pull ${REPO}/proxyv2:${ISTIO_IMAGE}
docker pull ${REPO}/install-cni:${ISTIO_IMAGE}
docker pull ${REPO}/ztunnel:${ISTIO_IMAGE}
```

Tag and push each image to your private registry.

for img in pilot proxyv2 install-cni ztunnel; do
  docker tag ${REPO}/${img}:${ISTIO_IMAGE} ${REGISTRY}/istio/${img}:${ISTIO_IMAGE}
  docker push ${REGISTRY}/istio/${img}:${ISTIO_IMAGE}
done

Optional: Push the Helm chart tarballs to your private registry as OCI artifacts so that your disconnected cluster can run helm install directly from it.
```
for chart in *.tgz; do
  helm push "$chart" oci://${REGISTRY}/istio-helm
done
```
If you do not push the charts to your registry, copy the tarball files directly to your disconnected device and install from the local path.

Step 3: Install Istio from your private registry

On your disconnected device, run the installation by using the images in your private registry.

Install each Istio ambient component by overriding global.hub to point to the directory in your private registry where you pushed the Istio images.

Note

These sample commands are provided to demonstrate the image and registry fields. For the full set of required Helm values, see the Helm install guide.

# Install Istio base CRDs
helm install istio-base oci://${REGISTRY}/istio-helm/base \
  --version ${ISTIO_VERSION} \
  -n istio-system \
  --create-namespace

# Install istiod
helm install istiod oci://${REGISTRY}/istio-helm/istiod \
  --version ${ISTIO_VERSION} \
  -n istio-system \
  --set global.hub=${REGISTRY}/istio \
  --set global.tag=${ISTIO_IMAGE} \
  --set pilot.env.PILOT_ENABLE_AMBIENT=true

# Install Istio CNI
helm install istio-cni oci://${REGISTRY}/istio-helm/cni \
  --version ${ISTIO_VERSION} \
  -n istio-system \
  --set global.hub=${REGISTRY}/istio \
  --set global.tag=${ISTIO_IMAGE}

# Install ztunnel
helm install ztunnel oci://${REGISTRY}/istio-helm/ztunnel \
  --version ${ISTIO_VERSION} \
  -n istio-system \
  --set hub=${REGISTRY}/istio \
  --set tag=${ISTIO_IMAGE}

Install the Gloo Operator from your private registry, then create a ServiceMeshController that points Istio at your registry.

Install the Gloo Operator by using the Helm chart from your private registry.

export GLOO_OPERATOR_VERSION=0.5.2
helm install gloo-operator oci://${REGISTRY}/gloo-operator-helm/gloo-operator \
  --version ${GLOO_OPERATOR_VERSION} \
  -n gloo-mesh \
  --create-namespace \
  --set manager.image.registry=${REGISTRY} \
  --set manager.env.SOLO_ISTIO_LICENSE_KEY=${SOLO_ISTIO_LICENSE_KEY}

Create an image pull secret with credentials for your private registry in the istio-system namespace. This is the namespace where the Gloo Operator installs Istio by default.

kubectl create namespace istio-system
kubectl create secret docker-registry istio-pull-secret \
  -n istio-system \
  --docker-server=${REGISTRY} \
  --docker-username=<username> \
  --docker-password=<password>

Create a ServiceMeshController that specifies your private registry and the pull secret.

kubectl apply -n gloo-mesh -f - <<EOF
apiVersion: operator.gloo.solo.io/v1
kind: ServiceMeshController
metadata:
  name: managed-istio
spec:
  dataplaneMode: Ambient
  installNamespace: istio-system
  version: ${ISTIO_VERSION}
  image:
    repository: ${REGISTRY}/istio
    secrets:
      - istio-pull-secret
EOF

If you used a different secret name or namespace, update secrets[0] and installNamespace to match. The secret must exist in the namespace specified in installNamespace.

Next steps

Migrate from a sidecar mesh