Offline Installation (Kubernetes)

Install Connectware on a Kubernetes cluster without Internet access using Cybus Helm charts.

This guide walks you through installing Connectware on Kubernetes in environments without Internet access. When your Kubernetes cluster cannot reach external registries, you must adapt the standard installation procedure:

1. Images: Container images cannot be pulled directly from registry.cybus.io.

2. Helm Chart: The chart cannot be downloaded dynamically from the Cybus Helm repository.

3. Licensing: The Connectware license key cannot be validated online. You must use an offline license file provided by Cybus.

The examples use a local single-node Kubernetes cluster with an internal image and Helm chart registry. While this is not a likely production environment, the concept translates to large Kubernetes clusters, and mimics some infrastructure you may already have, like an OCI registry.

In production environments, isolation setups vary widely. You might be working with a completely air-gapped system requiring physical transfer mediums such as a USB drive, or a corporate network where you can use a bastion host or sync images directly into an internal registry.

This guide demonstrates the entire procedure on a local cluster with a registry running on the same host. Adapt the registry address and transfer method to match your environment.

Prerequisites

• A local system with Internet access

• Docker installed on your host system

• kind, helm, skopeo, and kubectl installed on your host system

• Connectware license key (for authenticating with the Cybus registry)

• Access to the Cybus Portal to download license files

1

Download License Files

Download the license key and offline license file from the Cybus Portal. You need the license key to authenticate with the Cybus registry when downloading container images, and the offline license file to validate Connectware in environments without Internet access.

1. Go to the Cybus Portal.

2. Sign in with your credentials.

3. Navigate to Licenses to view your available Connectware licenses.

4. Select your license and download both the license key file (.key) and license file (.lic).

5. Save both files in a secure location on your system.

For detailed instructions on obtaining license files, see Acquiring License Keys.

2

Setting Up the Local Registry

Set up a local Docker registry as a standalone container and configure the kind cluster to trust and communicate with it. Skip this section if you already have a Kubernetes cluster and OCI registry.

1. Create the registry container:

docker run -d --restart=always -p 5001:5000 --name kind-registry registry:2

1. Create a file named kind-config.yaml to configure containerd to use the standalone registry:

kind-config.yaml

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
containerdConfigPatches:
  - |-
    [plugins."io.containerd.grpc.v1.cri".registry]
      config_path = "/etc/containerd/certs.d"
nodes:
  - role: control-plane
    kubeadmConfigPatches:
      - |
        kind: InitConfiguration
        nodeRegistration:
          kubeletExtraArgs:
            node-labels: "ingress-ready=true"

1. Apply the cluster configuration:

kind create cluster --config kind-config.yaml

1. Connect the kind-registry to the kind network and configure each node to route localhost:5001 to it:

# Connect the registry to the cluster network
docker network connect kind kind-registry

# Configure each node to route localhost:5001 to the registry
REGISTRY_DIR="/etc/containerd/certs.d/localhost:5001"
for node in $(kind get nodes); do
  docker exec "${node}" mkdir -p "${REGISTRY_DIR}"
  cat <<EOF | docker exec -i "${node}" cp /dev/stdin "${REGISTRY_DIR}/hosts.toml"
[host."http://kind-registry:5000"]
EOF
done

The registry is now accessible from your host machine at localhost:5001. The Kubernetes cluster routes pod-level image pulls for localhost:5001 directly to the kind-registry container.

These steps follow the official Kind Local Registry documentation. If you already have a Kubernetes environment and registry configured, skip this section and substitute localhost:5001 with your registry's URL in the steps below.

3

Preparing the Artifacts

Downloading the Helm Chart

Download the connectware Helm chart from the Cybus OCI repository as a .tgz package and push it to your local registry:

# Download the chart
helm pull oci://repo.cybus.io/charts/connectware --version ${CHART_VERSION}

# Push to your local registry
# --plain-http is required because the local registry has no TLS certificate configured
helm push connectware-${CHART_VERSION}.tgz oci://localhost:5001/helm --plain-http

Replace ${CHART_VERSION} with the connectware Helm chart version you want to install. See the Compatibility Matrix for the chart version that matches your target Connectware version.

Repeat this step for the connectware-agent Helm chart, if required.

Downloading Container Images

Generate a list of images required by the connectware Helm chart, then copy them directly to your local registry using skopeo:

# Generate the image list from the chart
helm template connectware ./connectware-${CHART_VERSION}.tgz | awk '/image:/ {print $2}' | sed 's/"//g' | sort | uniq > images.txt

# Copy images to the local registry
while read image; do
  image_name=$(basename $image)
  skopeo copy --src-creds "license:${LICENSE_KEY}" \
    docker://$image docker://localhost:5001/$image_name \
    --dest-tls-verify=false
done < images.txt

Replace ${LICENSE_KEY} with the Connectware license key downloaded in step 1.

--dest-tls-verify=false is used because the local registry in this example has no TLS certificate configured. In production environments with secure registries, omit this flag.

4

Configuring the Image Registry

The connectware Helm chart needs to know which registry to pull its component images from. Set global.image.registry to your internal registry address.

If your internal registry requires authentication, first create a pull secret in the namespace where Connectware will be deployed. If it does not require authentication, skip this step.

kubectl create secret docker-registry my-local-registry-secret \
  --docker-server=my.internal.registry.com \
  --docker-username=${REGISTRY_USERNAME} \
  --docker-password=${REGISTRY_PASSWORD} \
  --namespace=${NAMESPACE}

Replace ${REGISTRY_USERNAME} and ${REGISTRY_PASSWORD} with the credentials for your internal registry, and ${NAMESPACE} with the Kubernetes namespace where you plan to install Connectware.

Then reference the registry in your values.yaml:

values.yaml

global:
  image:
    registry: 'localhost:5001'
    # Only required if your registry uses authentication
    # pullSecrets:
    #   - name: my-local-registry-secret

5

Providing the Offline License Details

Connectware requires a license key in all installations. In an online environment, this key is validated against the Cybus Portal. For offline installations, you must also provide a pre-validated offline license file downloaded in step 1.

You can provide license details in the following ways.

Using Direct Helm Values

Provide both your Connectware license key and the license file payload directly in your values.yaml:

values.yaml

global:
  licenseKey: ${LICENSE_KEY}
  licenseFile: ${LICENSE_FILE}

Replace ${LICENSE_KEY} with your Connectware license key and ${LICENSE_FILE} with the contents of the offline license file (.lic) downloaded in step 1.

Using Existing Kubernetes Secrets

Store the license key and license file in Kubernetes Secrets and reference them in the Helm values. This approach is more secure than embedding credentials directly in values files and prevents secrets from being stored in version control.

Recommended for production. Using Kubernetes Secrets separates sensitive credentials from configuration and follows Kubernetes security best practices.

1. Create the Secrets:

# Store the license key
kubectl create secret generic connectware-offline-license-key \
  --from-literal=licenseKey=${LICENSE_KEY} \
  --namespace=${NAMESPACE}

# Store the offline license file saved as connectware-license.txt
# The explicit licenseFile= ensures the secret key is correctly named
kubectl create secret generic connectware-offline-license-file \
  --from-file=licenseFile=connectware-license.txt \
  --namespace=${NAMESPACE}

Replace ${LICENSE_KEY} with your Connectware license key.

1. Reference the Secrets in your values.yaml:

values.yaml

global:
  existingLicenseKeySecret: connectware-offline-license-key
  existingLicenseFileSecret: connectware-offline-license-file

Define either licenseFile or existingLicenseFileSecret — not both. The same applies to licenseKey and existingLicenseKeySecret. If both are set, the Secret reference takes priority.

6

Installing Connectware

With your registry populated and license configured, install Connectware using the Helm chart and images from your local registry. Your final values.yaml combines the registry configuration and license details:

values.yaml

global:
  # Using the offline license via Secret references
  existingLicenseKeySecret: connectware-offline-license-key
  existingLicenseFileSecret: connectware-offline-license-file

  image:
    # Internal registry configured on the cluster nodes
    registry: 'localhost:5001'
    # pullSecrets are not needed if the registry does not require authentication
    # pullSecrets:
    #   - name: my-local-registry-secret

Install the Helm chart from your local OCI registry:

helm upgrade --install connectware oci://localhost:5001/helm/connectware \
  --version ${CHART_VERSION} \
  --namespace ${NAMESPACE} \
  --create-namespace \
  -f values.yaml

Connectware initializes and pulls all images from your local registry.

Verifying the Installation

Verify that all Connectware pods are running and pulling images from your local registry:

kubectl get pods -n ${NAMESPACE}

All pods should show a Running status. To verify that images are being pulled from your local registry, check the image URLs for all Connectware pods:

kubectl get pod -n ${NAMESPACE} -l app.kubernetes.io/part-of=connectware -o jsonpath='{range .items[*]}{@.metadata.name}{": "}{@.spec.containers[0].image}{"\n"}{end}'

The image URLs should reference your local registry (localhost:5001 in this example).

Accessing Connectware

After installation, access Connectware through your web browser:

1. Determine the ingress hostname configured during installation.

2. Navigate to https://${HOSTNAME} in your web browser, replacing ${HOSTNAME} with the ingress hostname.

3. Log in using the default credentials:

   • Username: admin

   • Password: admin

For security reasons, change the default admin password immediately after your first login. See Default Admin User.

License Validation in Offline Environments

When running Connectware in an offline environment, you may see a warning message in the system status indicating that the system cannot connect to the license validation server at https://graphql-server.cybus.io/graphql.

This warning can be safely ignored in offline installations. The license validation has already been performed locally using the offline license file you provided. Your license will show as valid.

The license information is stored in the Kubernetes Secret and does not require Internet connectivity to function. However, you will not be able to refresh the license automatically from the Admin UI, as this feature requires Internet access.