> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/documentation/agents/agents-in-kubernetes/installing-connectware-agents-using-the-connectware-agent-helm-chart.md).

# Installing Connectware Agents Using the connectware-agent Helm Chart

{% hint style="info" %}
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](/cybus-helm-charts/compatibility-matrix.md#connectware-agent-helm-chart) and use that chart version when installing with the `--version` flag.
{% endhint %}

## Prerequisites

* Connectware is [installed and configured](/documentation/installation-and-upgrades/installing-connectware/installing-connectware-kubernetes.md).
* Connectware [license key](/documentation/installation-and-upgrades/licensing.md) is available.
* [Helm version 4](https://helm.sh/docs/intro/quickstart/#install-helm) is installed on your system.
* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) is installed on your system.
* kubectl configured with the current context pointing to your target cluster ([Configure Access to Multiple Clusters](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)).
* A Kubernetes namespace for the agent installation.

For complete agent system requirements including Kubernetes platform requirements, storage, and network access, see [System Requirements](/getting-started/system-requirements.md#connectware-agents-on-kubernetes).

## 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:

{% code lineNumbers="true" %}

```bash
vi values.yaml
```

{% endcode %}

## 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](/cybus-helm-charts/working-with-cybus-helm-charts/registries-and-pull-secrets.md).

**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:

{% code title="values.yaml" lineNumbers="true" %}

```yaml
licenseKey: ${LICENSE_KEY}
```

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

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

{% code title="values.yaml" lineNumbers="true" %}

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

{% endcode %}

#### 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](/cybus-helm-charts/working-with-cybus-helm-charts/registries-and-pull-secrets.md#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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

2. Reference the name of the Secret in `protocolMapperAgentDefaults.image.pullSecrets`:

{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}

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

{% code lineNumbers="true" %}

```bash
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 -
```

{% endcode %}

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

**Example:**

{% code lineNumbers="true" %}

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

{% endcode %}

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.

{% code title="values.yaml" lineNumbers="true" %}

```yaml
protocolMapperAgentDefaults:
  connectwareHost: ${CONNECTWARE_HOSTNAME}
```

{% endcode %}

#### 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](/getting-started/system-requirements.md#network-access). For TLS verification, the exact name used here must be a SAN entry in the `cybus_server.crt`. See [Server Certificates](/documentation/security/tls-certificates/server-certificates.md) 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.

{% hint style="warning" %}
Disabling TLS verification removes transport encryption security. Only use this for testing, not in production environments.
{% endhint %}

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

{% code title="values.yaml" lineNumbers="true" %}

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

{% endcode %}

#### 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](/cybus-helm-charts/connectware-agent-helm-chart/ca-certificate-chain.md) 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.

{% code lineNumbers="true" %}

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

{% endcode %}

Replace `${VERSION}` with the target Helm chart version. See the [Compatibility Matrix](/cybus-helm-charts/compatibility-matrix.md#connectware-agent-helm-chart) for the correct version.

**Example Output**

{% code lineNumbers="true" %}

```bash
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.
```

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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](/cybus-helm-charts/troubleshooting-on-kubernetes.md) 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](/documentation/client-registry.md).

## 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](#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](/cybus-helm-charts/connectware-agent-helm-chart.md#configuration-principles-for-the-connectware-agent-helm-chart).

**Example**

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

{% code title="values.yaml" lineNumbers="true" %}

```yaml
protocolMapperAgents:
  - name: bender-robots
  - name: welder-robots
```

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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](/documentation/client-registry.md) for details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/documentation/agents/agents-in-kubernetes/installing-connectware-agents-using-the-connectware-agent-helm-chart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.