Installing Connectware Agents Using the connectware-agent Helm Chart

Flexible, scalable, and secure data infrastructure with agents.

Agents must run the same application version as Connectware. The connectware-agent Helm chart has its own version number — separate from the agent version it deploys, and separate from the connectware Helm chart version. To find the correct chart version for your target agent version, look it up in the Compatibility Matrix and use that chart version when installing with the --version flag.

Prerequisites

• Connectware is installed and configured.

• Connectware license key is available.

• Helm version 4 is installed on your system.

• kubectl is installed on your system.

• kubectl configured with the current context pointing to your target cluster (Configure Access to Multiple Clusters).

• A Kubernetes namespace for the agent installation.

For complete agent system requirements including Kubernetes platform requirements, storage, and network access, see System Requirements.

Creating Your values.yaml File

As with all Helm charts, the connectware-agent chart is configured using a YAML file. This file can have any name, but is referred to throughout this guide as the values.yaml file.

Create this file to start configuring your agent installation by using your preferred editor:

vi values.yaml

Installing a Single Agent

Configuring Image Pull Access

The licenseKey Helm value creates an image pull secret for registry.cybus.io. Agents do not use it for license validation. Instead, they validate the license by connecting to Connectware at runtime.

You can either provide licenseKey for automatic authentication, or manually configure registry access using one of the methods below.

For a full reference on registries and pull secrets, see Configuring Registries and Pull Secrets.

Choosing a method:

• Use Method 1 for quick setup when you have a license key available.

• Use Method 2 for production environments where secrets should be managed separately from configuration files.

• Use Method 3 when pulling from a custom or mirrored registry.

• Use Method 4 when agents are installed in the same cluster as Connectware.

Method 1: Plaintext License Key

Add your Connectware license key directly to your values.yaml file. The chart creates a pull secret for registry.cybus.io automatically:

values.yaml

licenseKey: ${LICENSE_KEY}

Replace ${LICENSE_KEY} with your Connectware license key.

Method 2: Kubernetes Secret

If you prefer not to store the license key in plain text, create a Kubernetes Secret first, then reference it in your values.yaml file via protocolMapperAgentDefaults.image.pullSecrets.

1. Create the image pull secret in your target namespace:

kubectl create secret docker-registry cybus-registry-secret \
  --docker-server=registry.cybus.io \
  --docker-username=license \
  --docker-password=${LICENSE_KEY} \
  -n ${NAMESPACE}

Replace ${LICENSE_KEY} with your Connectware license key and ${NAMESPACE} with your target namespace.

1. Reference the Secret in your values.yaml file. If you use a different secret name, adjust the name entry under pullSecrets accordingly.

values.yaml

protocolMapperAgentDefaults:
  image:
    pullSecrets:
      - name: cybus-registry-secret

Method 3: Custom Registry

If you pull images from a custom or mirrored registry, no pull secret for registry.cybus.io is needed. See Using a Custom Registry for configuration details.

Method 4: Reuse the Connectware Pull Secret

When Connectware is installed with a literal global.licenseKey, the Connectware Helm chart creates a pull secret named ${CONNECTWARE_RELEASE_NAME}-image-registry. If you install agents in the same namespace as Connectware, you can reuse this secret without providing licenseKey in the agent chart at all.

1. To find the name of this secret, you can use kubectl to show it based on a label:

kubectl get secret -n ${CONNECTWARE_NAMESPACE} -l app.kubernetes.io/name=connectware-image-registry

Replace ${CONNECTWARE_NAMESPACE} with the namespace of your Connectware installation.

1. Reference the name of the Secret in protocolMapperAgentDefaults.image.pullSecrets:

values.yaml

# licenseKey is not needed when reusing Connectware's pull secret
protocolMapperAgentDefaults:
  image:
    pullSecrets:
      - name: connectware-image-registry # adjust to match your Connectware release name

If your Connectware installation is in a different namespace, copy the secret to the target namespace first:

kubectl get secret -l app.kubernetes.io/name=connectware-image-registry \
  --namespace=${CONNECTWARE_NAMESPACE} -o yaml \
  | sed "s/namespace: .*/namespace: ${AGENT_NAMESPACE}/" \
  | kubectl apply -f -

Replace ${CONNECTWARE_NAMESPACE} with the namespace of your Connectware installation, and ${AGENT_NAMESPACE} with the namespace where you install the agent.

Example:

kubectl get secret -l app.kubernetes.io/name=connectware-image-registry \
  --namespace=connectware -o yaml \
  | sed 's/namespace: .*/namespace: connectware-agent/' \
  | kubectl apply -f -

If you need to copy between Kubernetes clusters, use the --context parameter of kubectl to target your local contexts.

Changing the Target Connectware

By default, the agent connects to a Connectware installation in the same Kubernetes namespace. If your Connectware installation is in a different namespace or cluster, configure the connectwareHost parameter.

Add the following to your values.yaml file. Replace ${CONNECTWARE_HOSTNAME} with the actual hostname.

values.yaml

protocolMapperAgentDefaults:
  connectwareHost: ${CONNECTWARE_HOSTNAME}

Hostname Formats

• Different namespace in the same cluster: Use connectware.${CONNECTWARE_NAMESPACE} (for example, connectware.production).

• Outside Kubernetes cluster: Use the full hostname or IP address where Connectware is reachable.

Network Access

Ensure the agent has network access to the Connectware installation. For detailed network requirements, see Agent Requirements. For TLS verification, the exact name used here must be a SAN entry in the cybus_server.crt. See Server Certificates for details.

TLS Configuration

Connectware agents verify TLS certificates by default. Configure TLS verification before connecting agents to Connectware using one of the following methods:

Choosing a method:

• Use Method 1 for quick setup and testing (not recommended for production)

• Use Method 2 for production environments

Method 1: Disabling TLS Verification

Disable TLS verification to allow agents to accept any TLS certificate.

Disabling TLS verification removes transport encryption security. Only use this for testing, not in production environments.

• To configure agents to skip TLS verification, set the environment variable CYBUS_TRUST_ALL_CERTS to "true" using the env Helm value section:

values.yaml

protocolMapperAgentDefaults:
  env:
    - name: CYBUS_TRUST_ALL_CERTS
      value: 'true'

Method 2: Provide Connectware CA Certificate to Agents

Recommended for production. Configure agents to trust your Connectware CA certificate.

Follow the steps in Configuring CA Certificate Chain for Agents with the connectware-agent Helm Chart to configure your values.yaml file, then return here to continue with deployment.

Deploying the Agent

After configuring your values.yaml file with any of the methods above, deploy your Connectware agent. Replace ${NAMESPACE} with your target Kubernetes namespace.

helm upgrade -i connectware-agent oci://repo.cybus.io/charts/connectware-agent --version ${VERSION} -f values.yaml -n ${NAMESPACE}

Replace ${VERSION} with the target Helm chart version. See the Compatibility Matrix for the correct version.

Example Output

Release "connectware-agent" does not exist. Installing it now.
Pulled: repo.cybus.io/charts/connectware-agent:3.0.0
Digest: sha256:f328b12e2a0b1aa6g5bad396465139ef287f5921393bse48b4a263dba78f159a
NAME: connectware-agent
LAST DEPLOYED: Wed Apr  8 11:55:30 2026
NAMESPACE: connectware-agent-staging
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
Thank you for using the Cybus Connectware agent Helm chart!
For additional information visit https://cybus.io/

Number of agents: 1
--------------------
- agent


If any of these agents are new, please remember to visit Connectware's client registry to set up the connection to Connectware.

Hint: If you have agents stuck in a status other than "Running", you need to delete the stuck pods before a pod with your new configuration will be created.

This starts a single Connectware agent named agent, which connects to a Connectware installation deployed in the same namespace. When you edit your values.yaml file, repeat the helm upgrade command to apply the changes.

Verifying the Installation

Check that the agent pod is running. Replace ${NAMESPACE} with your target Kubernetes namespace:

kubectl get pods -n ${NAMESPACE} -l app.kubernetes.io/component=protocol-mapper-agent

The pod should show a Running status. If the pod is stuck in another status, you may need to delete it to allow a new pod to be created with your configuration. If the agent fails to start, or to reach Connectware, see Troubleshooting on Kubernetes for how to adjust your configuration.

Connecting the Agent to Connectware

Use the Client Registry to connect this agent to Connectware. For more information, see Client Registry.

Installing Multiple Agents with a Single Helm Installation

You can deploy multiple agents with a single Helm release. Follow the same steps as Installing a Single Agent, but add the configuration shown below to your values.yaml file.

Define each agent with a unique name in the protocolMapperAgents list, replacing the default name "agent". For details on sharing common settings across agents while customizing individual configurations, see Configuration Principles for the connectware-agent Helm Chart.

Example

1. Add the following to your values.yaml file:

values.yaml

protocolMapperAgents:
  - name: bender-robots
  - name: welder-robots

1. Apply the changes to your agent deployment. Replace ${NAMESPACE} with your target Kubernetes namespace:

helm upgrade -i connectware-agent oci://repo.cybus.io/charts/connectware-agent -f values.yaml -n ${NAMESPACE}

This deploys two agents: bender-robots and welder-robots. Both agents connect to the Connectware host specified in protocolMapperAgentDefaults.connectwareHost via the Client Registry. See Client Registry for details.