Install in air-gapped environments

Install Solo Enterprise for Istio in an air-gapped environment by downloading required images from a public registry and pushing them to a private registry accessible to your disconnected cluster.

Before you begin

Before you begin, set up the following prerequisites.

Set up your environment for an air-gapped installation

Make sure that your environment accounts for the following components of an air-gapped installation.

Connected and disconnected devices:

Connected device: To get the required images to run Solo Enterprise for Istio, you must have a device that can connect to the public internet and access a Kubernetes cluster.
Disconnected device: You install the downloaded images to set up Solo Enterprise for Istio on your disconnected device, such as a server in an on-premises datacenter, a cluster in a private-only network, or other type of host in an air-gapped environment. The disconnected device must have access to a Kubernetes cluster to install Istio and Solo Enterprise for Istio in.

Private registry: To transfer the downloaded images from your connected device to your disconnected device, you commonly set up some sort of private registry. The registry might be local to a private network that both devices are connected to, or you might use a service such as Sonatype Nexus Repository or JFrog Artifactory. Your connected device can push the downloaded images to the private registry so that the disconnected device can pull these images during the Solo Enterprise for Istio installation.

To set up your private registry, review the following considerations.

Registry credentials in your cluster: When you use a private registry, you might have to add its credentials to your cluster, such as in a global image pull secret for OpenShift clusters.
Allowed access to common registry domains: You might have a firewall set up for your private registry or private network, and want to allow access to the public registry domains that Solo Enterprise for Istio uses.
- docker.io
- gcr.io and k8s.gcr.io subdomain
- quay.io

Install the required command-line interfaces

Install the following command-line (CLI) tools.

helm, the Kubernetes package manager.
kubectl, the Kubernetes command line tool. Download the kubectl version that is within one minor version of the Kubernetes clusters you plan to use.

meshctl, the Solo command line tool.

curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=v2.12.7 sh -
export PATH=$HOME/.gloo-mesh/bin:$PATH

Optional: yq, a YAML processor that is used in a script that helps to push and pull images to the private registry.

Your disconnected device also must have these CLI tools, which might be harder to install without a public internet connection. Follow each CLI’s documentation for an air-gapped installation method. For example, you might follow a similar process to this procedure to download the CLI images to your connected device, transfer to a private registry, and install on the disconnected device.

Install in an air-gapped environment by using a private registry

The following steps provide an example when using a private registry. You can also download each image individually, as described in the Versions reference page, such as if you want to manually transfer the images to your air-gapped environment.

Set an environment variable for the registry address that you want to use. The example is for a local registry to your connected device, but you might want to use a remote, private registry. If you need to set up credentials to the registry, consult your registry provider.
```
export REGISTRY=localhost:5000
```
Set the Solo Enterprise for Istio version. This example uses the latest version.
For more information, such as to download hardened Solo or FIPS versions of the Istio image, see the Versions reference page.
```
export MGMT_VERSION=2.12.7
```

Download and run the script in the public solo-cop repository to list the images that you need for the Solo Enterprise for Istio version that you want to install. Include the --pull option to pull the images locally to your connected device. Note that Solo Enterprise for Istio components are multi-arch images by default, but some community images, such as Redis, might not be.

Note

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

./get-image-list ${MGMT_VERSION} --pull

Example output:

Finding images for Solo Enterprise for Istio version 2.12.7

############################################
# Getting Solo Enterprise for Istio images #
############################################
cassandra:3.11.6
criteord/cassandra_exporter:2.0.2
docker.io/bitnami/bitnami-shell:11-debian-11-r51
docker.io/bitnami/bitnami-shell:11-debian-11-r57
docker.io/bitnami/clickhouse:23.11.1-debian-11-r1
docker.io/bitnami/jmx-exporter:0.17.2-debian-11-r23
docker.io/bitnami/kafka-exporter:1.6.0-debian-11-r34
docker.io/bitnami/kafka:3.3.1-debian-11-r19
docker.io/bitnami/kubectl:1.25.4-debian-11-r6
docker.io/bitnami/os-shell:11-debian-11-r91
docker.io/bitnami/os-shell:11-debian-11-r92
docker.io/bitnami/postgres-exporter:0.15.0-debian-11-r2
docker.io/bitnami/postgresql:16.1.0-debian-11-r15
docker.io/bitnami/zookeeper:3.8.0-debian-11-r56
docker.io/bitnami/zookeeper:3.8.3-debian-11-r3
docker.io/bitnami/zookeeper:3.9.1-debian-11-r2
gcr.io/gloo-mesh/ext-auth-service:0.55.3
gcr.io/gloo-mesh/gloo-mesh-agent:2.12.7
gcr.io/gloo-mesh/gloo-mesh-analyzer:2.12.7
gcr.io/gloo-mesh/gloo-mesh-apiserver:2.12.7
gcr.io/gloo-mesh/gloo-mesh-envoy:2.12.7
gcr.io/gloo-mesh/gloo-mesh-insights:2.12.7
gcr.io/gloo-mesh/gloo-mesh-mgmt-server:2.12.7
gcr.io/gloo-mesh/gloo-mesh-portal-server:2.12.7
gcr.io/gloo-mesh/gloo-mesh-spire-controller:2.12.7
gcr.io/gloo-mesh/gloo-mesh-ui:2.12.7
gcr.io/gloo-mesh/otel-collector:0.2.0
gcr.io/gloo-mesh/rate-limiter:0.11.7
gcr.io/gloo-mesh/kubectl:1.16.4
gcr.io/gloo-mesh/hubble-ui:v0.0.11
gcr.io/gloo-mesh/opa:0.59.0
gcr.io/gloo-mesh/prometheus:v2.49.1
gcr.io/gloo-mesh/redis:7.2.4-alpine 
gcr.io/gloo-mesh/spire-server:1.8.6
gloo-mesh/gloo-network-agent-8d33bc4d8c7a/gloo-network-agent:0.2.3
gloo-mesh/sidecar-accel/sidecar-accel:0.1.1
jaegertracing/example-hotrod:latest
jimmidyson/configmap-reload:v0.8.0
maorfr/cain:0.6.0
otel/opentelemetry-collector-contrib: latest
prom/pushgateway:latest
quay.io/brancz/kube-rbac-proxy:v0.14.0
quay.io/prometheus/alertmanager:latest
quay.io/prometheus/node-exporter:latest
registry.k8s.io/kube-state-metrics/kube-state-metrics:latest

#######################################
# Getting Solo distributions of Istio #
#######################################
us-docker.pkg.dev/gloo-mesh/istio-workshops/pilot:1.29.6-solo
us-docker.pkg.dev/gloo-mesh/istio-workshops/proxyv2:1.29.6-solo

Pulling images locally
6: Pulling from library/redis
7d63c13d9b9b: Pull complete
...

Pull the Solo distribution of Istio image for the version of Istio that you want to use.
Warning
Do not rename the pilot image when mirroring it to your private registry. Gloo Mesh mesh discovery identifies the Istio control plane by checking for a container image with a pilot suffix. Renaming it causes failed to find pilot container discovery errors. You can change the image prefix (hub), but the image name must end in pilot (for example, <your-registry>/pilot:VERSION or <your-registry>/custom-pilot:VERSION).

Tag and push each image to your private registry. For pinned-version images such as redis, the OTel collector, and prometheus, use the exact tags returned by the script in the previous step.

# Versioned Gloo Platform images
for img in gloo-mesh-mgmt-server gloo-mesh-apiserver gloo-mesh-ui gloo-mesh-envoy gloo-mesh-agent; do
  docker tag gcr.io/gloo-mesh/${img}:${MGMT_VERSION} ${registry}/${img}:${MGMT_VERSION}
  docker push ${registry}/${img}:${MGMT_VERSION}
done

# Redis (use the exact tag from the script output)
docker tag gcr.io/gloo-mesh/redis:<redis-tag> ${registry}/redis:<redis-tag>
docker push ${registry}/redis:<redis-tag>

# Telemetry collector (pushed under gloo-otel-collector path to match Helm values)
docker tag gcr.io/gloo-mesh/otel-collector:<otel-tag> ${registry}/gloo-otel-collector:<otel-tag>
docker push ${registry}/gloo-otel-collector:<otel-tag>

# Prometheus server (renamed path to match Helm values)
docker tag gcr.io/gloo-mesh/prometheus:<prometheus-tag> ${registry}/prometheus/prometheus:<prometheus-tag>
docker push ${registry}/prometheus/prometheus:<prometheus-tag>

# Prometheus configmap reloader (renamed path to match Helm values)
docker tag jimmidyson/configmap-reload:<reloader-tag> ${registry}/prometheus-config-reloader:<reloader-tag>
docker push ${registry}/prometheus-config-reloader:<reloader-tag>

# Prometheus server migration image
docker tag gcr.io/gloo-mesh/kubectl:<kubectl-tag> ${registry}/kubectl:<kubectl-tag>
docker push ${registry}/kubectl:<kubectl-tag>

# Istio images — the IstioLifecycleManager hub must point to the parent path of the pilot image
for img in pilot proxyv2; do
  docker tag us-docker.pkg.dev/gloo-mesh/istio-workshops/${img}:${ISTIO_IMAGE}-solo \
    ${registry}/istio/${img}:${ISTIO_IMAGE}-solo
  docker push ${registry}/istio/${img}:${ISTIO_IMAGE}-solo
done

Optional: You might want to set up your private registry so that you can also pull the Helm charts. For instructions, consult your registry provider, such as Nexus Repository Manager or JFrog Artifactory.

Create an image pull secret with the credentials to your private registry in the same namespace where you plan to install the Solo Enterprise for Istio, such as gloo-mesh. For more information about the credentials, consult your private registry provider. You can refer to the image pull secret in your Helm values file for the components in the following table.

Component	Helm field
Agent	`glooAgent.imagePullSecrets[0].name`
Analyzer	`glooAnalyzer.imagePullSecrets[0].name`
Insights engine	`glooInsightsEngine.imagePullSecrets[0].name`
Management server	`glooMgmtServer.imagePullSecrets[0].name`
Portal server	`glooPortalServer.imagePullSecrets[0].name`
Spire server	`glooSpireServer.imagePullSecrets[0].name`
UI server	`glooUi.imagePullSecrets[0].name`
Redis instance for the external auth service and portal server	`redisStore.extAuthService.deployment.imagePullSecrets[0].name`
Redis instance for the insights engine	`redisStore.insights.deployment.imagePullSecrets[0].name`
Redis instance for the rate limiter	`redisStore.rateLimiter.deployment.imagePullSecrets[0].name`
Redis instance for snapshots	`redisStore.snapshot.deployment.imagePullSecrets[0].name`

Prepare the other image options for each component. You must include the image.registry location. If you renamed the image, you can configure the image.repository and image.tag options. Optionally, you can update other image values, such as the image.pullPolicy. For more information, see the Helm reference docs.
For Istio components, configure the image hub and pull secret in your IstioLifecycleManager resource. Set spec.template.values.global.hub to the parent path of the pilot image you pushed in the previous step (for example, ${registry}/istio), and spec.template.values.global.imagePullSecrets to the name of your pull secret.

When you install Solo Enterprise for Istio and an ambient mesh, make sure to use the specific images that you downloaded and stored in your private registry in the previous steps. For installation steps, refer to the following guides:

Note: Update your Helm value file or use --set flags to overwrite the default images to the images in the private registry. The images that you replace depend on the components that you use. For example, you might replace several Redis instances or have a multicluster OTel setup. Also, update the following commands to include any other image options that you prepared, such as image.pullSecret if your private registry requires an image pull secret.

Example Helm installation command for the management cluster:

helm upgrade --install gloo-platform gloo-platform/gloo-platform \
--kube-context ${context1} \
-n gloo-mesh \
--version ${MGMT_VERSION} \
--values mgmt-plane.yaml \
--set common.cluster=${cluster1} \
--set licensing.glooMeshLicenseKey=${SOLO_ISTIO_LICENSE_KEY} \
--set glooMgmtServer.image.registry=${registry} \
--set prometheus.configmapReload.prometheus.image.repository=${registry}/prometheus-config-reloader \
--set prometheus.server.image.repository=${registry}/prometheus/prometheus \
--set prometheus.prometheus-server-migration.image.registry=${registry} \
--set prometheus.prometheus-server-migration.image.repository=kubectl \
--set glooUi.image.registry=${registry} \
--set glooUi.sidecars.console.image.registry=${registry} \
--set glooUi.sidecars.envoy.image.registry=${registry} \
--set redis.deployment.image.registry=${registry} \
--set telemetryCollector.image.repository=${registry}/gloo-otel-collector \
--set telemetryGateway.image.repository=${registry}/gloo-otel-collector

Example Helm installation command for workload clusters:

helm upgrade --install gloo-platform gloo-platform/gloo-platform \
--kube-context ${context2} \
-n gloo-mesh \
--version ${MGMT_VERSION} \
--values data-plane.yaml \
--set glooAgent.image.registry=${registry} \
--set telemetryCollector.image.repository=${registry}/gloo-otel-collector

Multicluster management