> 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/2-4-1/cybus-helm-charts/connectware-agent-helm-chart/ca-certificate-chain.md).

# Configuring CA Certificate Chain for Agents with the connectware-agent Helm Chart

Connectware verifies TLS connections between agents and Connectware using a CA certificate chain provided to agents.

The following options are available for configuring the CA certificate chain for agents:

* Use the built-in default CA certificate chain
* Add your CA certificate to the built-in default CA certificate chain
* Use a completely custom CA certificate chain

Your choice depends on security requirements for your Connectware instance. You may want different security levels for test and production environments, or you may have corporate requirements for TLS certificates. Once you configure your Public Key Infrastructure (PKI) for Connectware, match this configuration for agents by extracting the certificates used in Connectware.

For background on Connectware's CA certificate setup, see [CA Certificates](/2-4-1/documentation/security/tls-certificates/ca-certificates.md).

## Prerequisites

* You are familiar with Public Key Infrastructure (PKI).
* You have set up TLS certificates for Connectware.
* You have access to Connectware's Kubernetes namespace.
* [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 and configured to access your Kubernetes cluster.

## Procedure

{% stepper %}
{% step %}

### Extract the CA Certificate

If you already have the CA certificate that signed Connectware's server certificate (for example, a corporate CA certificate), skip this step and proceed to Step 2.

To extract the CA certificate from Connectware, retrieve the Certificate Authority (CA) certificate that Connectware uses to sign the Connectware server certificate (`cybus_server.crt`), which is typically `cybus_ca.crt`.

A second certificate called `cybus_combined_ca.crt` is also available. This combines the external CA certificate chain (`cybus_ca.crt`) with the internally used CA certificate chain (`shared_yearly_ca.crt`). Some direct connections to internal components require this CA certificate chain. When unsure which CA certificate chain to use, `cybus_combined_ca.crt` offers the most flexibility.

Run these commands in your Connectware installation namespace, not your `connectware-agent` installation namespace.

{% hint style="info" %}
For production setups, replace the Public Key Infrastructure (PKI) generated during Connectware installation with a PKI managed and approved by your organization.
{% endhint %}

{% code lineNumbers="true" %}

```bash
pod=$(kubectl -n ${NAMESPACE} get pod -o name -l app.kubernetes.io/name=auth-server | head -1 | sed 's/pod\///g');
kubectl -n ${NAMESPACE} cp -c auth-server $pod:/connectware_certs/cybus_ca.crt cybus_ca.crt
kubectl -n ${NAMESPACE} cp -c auth-server $pod:/connectware_certs/cybus_combined_ca.crt cybus_combined_ca.crt
```

{% endcode %}

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

This creates the files `cybus_ca.crt` and `cybus_combined_ca.crt` in your current directory.
{% endstep %}

{% step %}

### Configure the Agent to Use the CA Certificate

Provide the CA certificate chain either directly in your Helm values or through a Kubernetes ConfigMap. Since all agents typically use the same CA certificate chain, configure it in `protocolMapperAgentDefaults`.

To override this setting for specific agents, set the parameter within specific agent entries in `protocolMapperAgents`, as described in [Configuration Principles for the connectware-agent Helm Chart](/2-4-1/cybus-helm-charts/connectware-agent-helm-chart.md#configuration-principles-for-the-connectware-agent-helm-chart).

#### Method 1: CA Certificate via Helm Values

Add the CA certificate file (`cybus_ca.crt` or `cybus_combined_ca.crt`) as a literal block scalar to the `tls.ca.certChain` parameter in your `values.yaml` file.

Ensure correct indentation: the certificate content must be indented once relative to `certChain`.

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

```yaml
protocolMapperAgentDefaults:
  tls:
    ca:
      certChain: |
        -----BEGIN CERTIFICATE-----
        IIEgTCCAmkCFCN+Wi9RpeajIunZnxdIhvdZep6ZMA0GCSqGSIb3DQEBCwUAMIGN
        [skipped for brevity - include whole certificate]
        sD9hY3o=
        -----END CERTIFICATE-----
```

{% endcode %}

#### Method 2: CA Certificate via Kubernetes ConfigMap

To manage the CA certificate as a Kubernetes ConfigMap, create it before configuring your agent. The ConfigMap must:

* Contain a file called `ca-chain.pem` with the CA certificate
* Be in the same namespace as your `connectware-agent` installation

1. Rename the certificate file extracted in Step 1 to `ca-chain.pem`. Use `cybus_combined_ca.crt` if you are unsure which one to use. Then create the ConfigMap. Replace `${CONFIGMAP_NAME}` with a name of your choice (recommended: `<release-name>-<chart-name>-tls-ca-cert`), and `${NAMESPACE}` with the namespace of your `connectware-agent` installation.

{% code lineNumbers="true" %}

```bash
cp cybus_combined_ca.crt ca-chain.pem
kubectl create configmap ${CONFIGMAP_NAME} --from-file ca-chain.pem -n ${NAMESPACE}
```

{% endcode %}

2. Set the `tls.ca.existingConfigMap` parameter in your `values.yaml` file to the name of your ConfigMap:

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

```yaml
protocolMapperAgentDefaults:
  tls:
    ca:
      existingConfigMap: ${CONFIGMAP_NAME}
```

{% endcode %}
{% endstep %}

{% step %}

### Apply Your Configuration

Apply the configuration by running a Helm upgrade on your `connectware-agent` installation:

{% code lineNumbers="true" %}

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

{% endcode %}

Replace `${VERSION}` with the target chart version (see the [Compatibility Matrix](/2-4-1/cybus-helm-charts/compatibility-matrix.md#connectware-agent-helm-chart)) and `${NAMESPACE}` with the namespace of your `connectware-agent` installation. If you followed the naming recommendations in this documentation, `${RELEASE_NAME}` is `connectware-agent`.
{% endstep %}
{% endstepper %}

## Replacing a CA Certificate

To replace the CA certificate, follow the same steps as when adding it. However, agents do not automatically use the new certificate. You must restart the Kubernetes StatefulSets for the affected agents.

The StatefulSet is named `<release-name>-<chart-name>-<agent-name>`. Some characters, most prominently the `.` character, are replaced by `-` in the agent name. If you followed the naming recommendations, the first two parts are abbreviated to `connectware-agent`. An agent named `bender-robots`, for example, deploys as a StatefulSet named `connectware-agent-bender-robots`.

To restart a single agent:

{% code lineNumbers="true" %}

```bash
kubectl -n ${NAMESPACE} rollout restart sts ${STATEFULSET_NAME}
```

{% endcode %}

To restart all agents from your installation:

{% code lineNumbers="true" %}

```bash
kubectl -n ${NAMESPACE} rollout restart sts -l app.kubernetes.io/instance=${RELEASE_NAME}
```

{% endcode %}

If you followed the naming recommendations in this documentation, `${RELEASE_NAME}` is `connectware-agent`.


---

# 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/2-4-1/cybus-helm-charts/connectware-agent-helm-chart/ca-certificate-chain.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.