Install in air-gapped environments

Enterprise

Install the Solo UI in an air-gapped environment using a private registry.

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

Before you begin

Make sure that you have the following components set up in your environment 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. Your connected device pushes images to it, and your disconnected cluster pulls the images from it during installation.
Complete Install Solo Enterprise for Istio in air-gapped environments to set up your private registry and mirror the Istio images.

Note

Solo.io provides Helm values to install third-party components as a convenience, including ClickHouse and OpenTelemetry collector. These components are not included in the Solo Support policy. For support, contact the respective vendor or open-source project community.

Step 1: Enumerate Solo UI images

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

Install the required CLIs.
- helm v3.x
- docker or crane
Set environment variables for the Solo UI version and your private registry.
```
export SOLO_UI_VERSION=0.5.7
export REGISTRY=<your-private-registry>
```

Pull the Solo UI Helm charts. For multicluster installations, pull both charts. For single-cluster installations, the relay chart is not required.

mkdir solo-ui-charts && cd solo-ui-charts
helm pull oci://us-docker.pkg.dev/solo-public/solo-enterprise-helm/charts/management \
  --version ${SOLO_UI_VERSION}
helm pull oci://us-docker.pkg.dev/solo-public/solo-enterprise-helm/charts/relay \
  --version ${SOLO_UI_VERSION}

Render each chart to extract the full list of container image references. The management chart requires a cluster name and license key placeholder to render without validation errors.

helm template solo-management management-*.tgz \
  --set cluster=placeholder \
  --set licensing.licenseKey=placeholder \
  --set products.mesh.enabled=true \
  2>/dev/null | grep 'image:' | sort -u

helm template solo-relay relay-*.tgz \
  --set cluster=placeholder \
  --set tunnel.fqdn=placeholder \
  --set telemetry.fqdn=placeholder \
  2>/dev/null | grep 'image:' | sort -u

The output lists every image: reference across all Solo UI components, including third-party images for ClickHouse and the OpenTelemetry collector. Use this list in the next step.

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 the Solo image repository and pull the Solo-owned images. Use the third-party image tags returned by helm template in the previous step.

export SOLO_REPO=us-docker.pkg.dev/solo-public/solo-enterprise

# Management chart images
docker pull ${SOLO_REPO}/solo-enterprise-ui-backend:${SOLO_UI_VERSION}
docker pull ${SOLO_REPO}/solo-enterprise-ui-frontend:${SOLO_UI_VERSION}
docker pull ${SOLO_REPO}/solo-enterprise-tunnel-server:${SOLO_UI_VERSION}
docker pull ${SOLO_REPO}/solo-enterprise-autoauth:<idp-tag>

# Relay chart image (multicluster only)
docker pull ${SOLO_REPO}/solo-enterprise-tunnel-client:${SOLO_UI_VERSION}

# Third-party images (use tags from helm template output)
docker pull docker.io/otel/opentelemetry-collector-contrib:<otel-tag>
docker pull clickhouse/clickhouse-server:<clickhouse-tag>

Tag and push each image to your private registry, preserving the same repository path structure.

# Solo-owned images (management chart)
for img in solo-enterprise-ui-backend solo-enterprise-ui-frontend \
            solo-enterprise-tunnel-server; do
  docker tag ${SOLO_REPO}/${img}:${SOLO_UI_VERSION} \
    ${REGISTRY}/solo-enterprise/${img}:${SOLO_UI_VERSION}
  docker push ${REGISTRY}/solo-enterprise/${img}:${SOLO_UI_VERSION}
done

# IDP image (uses its own tag, not SOLO_UI_VERSION)
docker tag ${SOLO_REPO}/solo-enterprise-autoauth:<idp-tag> \
  ${REGISTRY}/solo-enterprise/solo-enterprise-autoauth:<idp-tag>
docker push ${REGISTRY}/solo-enterprise/solo-enterprise-autoauth:<idp-tag>

# Relay chart image (multicluster only)
docker tag ${SOLO_REPO}/solo-enterprise-tunnel-client:${SOLO_UI_VERSION} \
  ${REGISTRY}/solo-enterprise/solo-enterprise-tunnel-client:${SOLO_UI_VERSION}
docker push ${REGISTRY}/solo-enterprise/solo-enterprise-tunnel-client:${SOLO_UI_VERSION}

# OTel collector image
docker tag docker.io/otel/opentelemetry-collector-contrib:<otel-tag> \
  ${REGISTRY}/otel/opentelemetry-collector-contrib:<otel-tag>
docker push ${REGISTRY}/otel/opentelemetry-collector-contrib:<otel-tag>

# ClickHouse image
docker tag clickhouse/clickhouse-server:<clickhouse-tag> \
  ${REGISTRY}/clickhouse/clickhouse-server:<clickhouse-tag>
docker push ${REGISTRY}/clickhouse/clickhouse-server:<clickhouse-tag>

Optional: Push the Helm chart tarballs to your private registry as OCI artifacts so your disconnected cluster can run helm install directly from it.
```
helm push management-*.tgz oci://${REGISTRY}/solo-enterprise-helm/charts
helm push relay-*.tgz oci://${REGISTRY}/solo-enterprise-helm/charts
```
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 the Solo UI from your private registry

On your disconnected device, create an image pull secret in the solo-enterprise namespace and run the Helm installation with registry overrides.

Create the solo-enterprise namespace.

kubectl create namespace solo-enterprise

Create an image pull secret with credentials for your private registry.

kubectl create secret docker-registry solo-enterprise-pull-secret \
  -n solo-enterprise \
  --docker-server=${REGISTRY} \
  --docker-username=<username> \
  --docker-password=<password>

Install the management chart. Set global.image.registry to the registry path where you pushed the Solo-owned images, telemetry.image.registry for the OTel collector image, and clickhouse.image.repository for the ClickHouse image.

helm upgrade -i solo-management oci://${REGISTRY}/solo-enterprise-helm/charts/management \
  -n solo-enterprise \
  --version ${SOLO_UI_VERSION} \
  --set cluster=${cluster1} \
  --set licensing.licenseKey=${SOLO_ISTIO_LICENSE_KEY} \
  --set oidc.issuer="" \
  --set products.mesh.enabled=true \
  --set global.image.registry=${REGISTRY} \
  --set global.imagePullSecrets[0].name=solo-enterprise-pull-secret \
  --set idp.registry=${REGISTRY} \
  --set telemetry.image.registry=${REGISTRY} \
  --set "clickhouse.image.repository=${REGISTRY}/clickhouse/clickhouse-server"

For multicluster installations, install the relay chart in each workload cluster. The registry overrides for the relay chart are the same as for the management chart, except there is no ClickHouse image.

helm upgrade -i solo-relay oci://${REGISTRY}/solo-enterprise-helm/charts/relay \
  -n solo-enterprise \
  --create-namespace \
  --kube-context ${context2} \
  --version ${SOLO_UI_VERSION} \
  --set cluster=${cluster2} \
  --set tunnel.fqdn=<tunnel-server-fqdn> \
  --set telemetry.fqdn=<telemetry-gateway-fqdn> \
  --set global.image.registry=${REGISTRY} \
  --set global.imagePullSecrets[0].name=solo-enterprise-pull-secret \
  --set telemetry.image.registry=${REGISTRY}

Next steps

Explore the Solo UI to review your Istio workloads, traffic flows, and resources.

High availability Upgrade