> 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/upgrading-the-connectware-agent-helm-chart.md).

# Upgrading the connectware-agent Helm Chart

{% hint style="info" %}
Upgrading from `connectware-agent` chart version 2.1.0 to 3.0.0? That release contains breaking changes to the `values.yaml` file. Follow [Upgrading Connectware and Connectware-Agent Helm Charts to 3.0.0 — Part B](/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-kubernetes/upgrading-connectware-helm-charts-to-3-0-0.md#part-b-connectware-agent-chart-migration) instead of this page.
{% endhint %}

## Prerequisites

* [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/)).

## Overview

Upgrading the connectware-agent Helm chart consists of the following steps:

1. Picking a compatible version
2. Determining the name of your connectware-agent installation
3. Obtaining your `values.yaml` file
4. Reviewing changes and adjusting Helm values
5. Starting the upgrade
6. Verifying the upgrade

### Picking a Compatible Version

Each version of the `connectware-agent` Helm chart bundles a specific agent version that must match your Connectware installation. Agents must run the same version as Connectware itself.

Before upgrading, consult the [Compatibility Matrix](/cybus-helm-charts/compatibility-matrix.md#connectware-agent-helm-chart) to determine which Helm chart version corresponds to your Connectware version.

To prevent accidental upgrades to incompatible agent versions, lock the protocol-mapper image version in your `values.yaml` file using the `protocolMapperAgentDefaults.image.tag` value.

**Example**

{% code lineNumbers="true" %}

```yaml
protocolMapperAgentDefaults:
  image:
    tag: 2.3.0
```

{% endcode %}

You can also lock the version of the `connectware-agent` Helm chart valid for your `values.yaml` file by setting the chart version in the Helm value `validVersion`. For more information, see [Locking the Helm Chart Version](/cybus-helm-charts/working-with-cybus-helm-charts/locking-chart-version.md).

### Determining the Name of Your connectware-agent Installation

Identify the release name from your initial installation. If you followed this documentation, it's likely `connectware-agent`. Use `helm list` to verify the name in your target namespace. For more information, see [Obtaining the Name, Namespace, and Version of Your Installation](/cybus-helm-charts/cybus-helm-charts.md#obtaining-the-name-namespace-and-version-of-your-installation).

### Obtaining Your values.yaml File

The `values.yaml` file configures your `connectware-agent` installation. Keep it in version control for operational use. If you do not have it available, extract it from your installation using `helm get values`. For more information, see [Extracting the values.yaml File](/cybus-helm-charts/cybus-helm-charts.md#extracting-the-valuesyaml-file).

### Reviewing Changes and Adjusting Helm Values

Review the Helm chart's README file for changes that might require adjustments to your configuration. Use `helm show readme` to view the README.

**Example**

{% code lineNumbers="true" %}

```bash
helm show readme oci://repo.cybus.io/charts/connectware-agent --version ${VERSION}
```

{% endcode %}

If nothing is mentioned for the version you are upgrading to, no configuration adjustments are required.

If you locked the version for the agent's protocol-mapper image using `protocolMapperAgentDefaults.image.tag` or any agent-specific configuration under `protocolMapperAgents`, update these values to the target version.

### Starting the Upgrade

To start the upgrade, run `helm upgrade` specifying the target version with the `--version` parameter and providing your `values.yaml` file.

{% code lineNumbers="true" %}

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

{% endcode %}

Replace `${VERSION}` with the target Helm chart version, `${INSTALLATION_NAME}` with the name determined earlier, and `${NAMESPACE}` with the namespace of your `connectware-agent` installation. You can find additional details in the [Helm documentation](https://helm.sh/docs/helm/helm_upgrade/).

### Verifying the Upgrade

Verify that all pods are restarting with the new image version. Using `kubectl get pods`, check their AGE, verify they are in state `Running`, and are `READY`.

**Example**

{% code lineNumbers="true" %}

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

{% endcode %}

Next, head to the Connectware Admin UI and verify your agents are connected in the correct version as described in [Monitoring Agents](/documentation/agents/monitoring-agents.md).

Should any pods not become READY, continue with [Troubleshooting on Kubernetes](/cybus-helm-charts/troubleshooting-on-kubernetes.md).


---

# 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/upgrading-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.