StackState Kubernetes Agent air-gapped

StackState for Kubernetes troubleshooting Self-hosted

When running in an air-gapped environment extra preparation is needed before the agent can be installed:

Configure Helm

Configure helm on your local machine to be able to pull the StackState Helm chart.

helm repo add stackstate
helm repo update

Download the agent Helm chart

Make sure to first run helm repo update again to have the latest version of the Helm chart available.

Download the latest agent helm chart like this:

helm pull stackstate/stackstate-k8s-agent

This results in a file like this stackstate-k8s-agent-1.0.30.tgz. Copy this file (using scp, sftp or any other tool available) to the system from which the agent will be installed.

Copy agent Docker images

Make sure to first run helm repo update again to have the latest version of the Helm chart available.

Download the bash script from the Agent Helm chart Github repository and make it executable:

chmod +x

The script can copy images directly from StackState's registry to your internal registry. If the internal registry isn't accessible from a computer that has direct internet access an intermediate step is needed.

To copy the images directly from the StackState registry to the internal registry run the script like this to copy the images to the registry at


The environment variables are used to setup authentication. If the destination registry doesn't require authentication the DST_REGISTRY_* variables can be omitted.

The script extracts all images from the Helm chart and copies the images to the local registry. Depending on the speed of the internet connection this might take a while.

Customize the Helm command

The StackState UI provides the exact commands to install the agent depending on the distribution but it assumes the internet is accessible. For air-gapped installations the command needs to be extended to use the local copy of the helm chart and to override the docker registry with the local registry. If the local docker registry requires authentication a custom image pull secret can be provided.

This example uses the command for the standard Kubernetes distribution to show how to use a local copy of the Helm chart and add the extra registry argument. Please make sure to use the command that corresponds with your Kubernetes distribution as provided in the StackState UI and apply the same modifications (this example uses as the registry).

This command isn't the right command for your Kubernetes cluster. Instead, copy the command for your Kubernetes distribution from the installed Kubernetes StackPack in the UI. Then replace stackstate-k8s/stackstate with the .tgz file and add the image registry argument.

helm upgrade --install \
--namespace stackstate \
--create-namespace \
--set-string 'stackstate.apiKey'='<api-key>' \
--set-string ''='acme-prod' \
--set-string 'stackstate.url'='https://stackstate.acme.local/receiver/stsAgent' \
--set-string 'logsAgent.enabled'='true' \
--set-string 'all.image.registry'="" \
stackstate-k8s-agent ./stackstate-k8s-agent-1.0.30.tgz

The modifications are:

  • Adding the last --set-string argument

  • Replacing stackstate/stackstate-k8s-agent to reference the Helm chart with the Helm chart filename ./stackstate-k8s-agent-1.0.30.tgz

Last updated