# 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 TLS certificate setup for Connectware offers flexibility. These are the possible setups:

* Using the built-in default CA certificate chain.
* Using a CA certificate added to the built-in default CA certificate chain.
* Using a completely custom CA certificate chain.

Which of these options you choose likely depends on your security requirements for this specific Connectware instance. You may want different security levels for test and production environments, or you may have corporate requirements for TLS certificates. Once you have set up your Public Key Infrastructure (PKI) for Connectware, you will have to match this configuration for agents. To do this, you can extract the certificates used in Connectware, whether they are built-in or replaced by you.

**See also**

* [CA Certificates](https://docs.cybus.io/2-1-0/documentation/security/tls-certificates/ca-certificates)

## Prerequisites

* You are familiar with Public Key Infrastructure (PKI).
* You have set up your TLS certificate setup for Connectware.
* You have access to Connectware's Kubernetes namespace.
* [Helm version 3](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

To configure the CA certificate for agents, do the following:

1. [Extract the Certificate Authority certificate](#extracting-certificate-authority-certificate)
2. [Configure your agent to use the Certificate Authority](#configuring-your-agent-to-use-the-certificate-authority)
3. [Apply your configuration](#applying-your-configuration)

## Extracting Certificate Authority (CA) Certificate

To use TLS connections, you must extract 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 you to use this CA certificate chain. When you are unsure which CA certificate chain to use, `cybus_combined_ca.crt` offers the most flexibility.

The steps in this section are executed in your Connectware installation, not your connectware-agent installation.

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

{% code lineNumbers="true" %}

```bash
pod=$(kubectl -n ${NAMESPACE} get pod -o name -lapp.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 %}

**Result**

The files `cybus_ca.crt` and `cybus_combined_ca.crt` are created in your current directory.

### Configuring Your Agent to Use the Certificate Authority

You can configure the CA certificate chain in the `tls.ca` section inside the `protocolMapperAgentDefaults` context of your `values.yaml` file, since usually all agents would use the same CA certificate chain. However, there is an override entry in the `protocolMapperAgents` context for each agent, should you need it. Alternatively, you can create a Kubernetes ConfigMap before you deploy your agent.

#### Configuring CA Certificate via Helm Values

To add the CA Certificate to your Helm values, add the CA certificate bundle file (`cybus_ca.crt` or `cybus_combined_ca.crt`) as a literal block scalar to the `tls.ca.certChain` Helm values inside `protocolMapperAgentDefaults` or the agents entry in the `protocolMapperAgents` context of your `values.yaml` file:

Pay attention to the indentation of your CA certificate. It must be indented once relative to `certChain` and keep this indentation (see example below).

**Example**

{% code lineNumbers="true" %}

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

{% endcode %}

#### Configuring CA Certificate via Kubernetes ConfigMap

**Creating the Kubernetes ConfigMap**

If you want to manually manage the CA certificate as a Kubernetes ConfigMap, you will need to create it before configuring your agent. You can use any process you like, as long as the result is a Kubernetes ConfigMap that:

* Contains a file called `ca-chain.pem` containing the CA certificate
* Is in the same namespace as your `connectware-agent` installation

We will demonstrate how to create this ConfigMap through kubectl. Ensure that your CA certificate is stored in a file named `ca-chain.pem` (you can rename it from `cybus_ca.crt` or `cybus_combined_ca.crt` in your local copy).

Define a name for your ConfigMap. You will need this name later to configure the agent. We recommend choosing a name following the scheme `<chart-name>-<release-name>-tls-ca-cert`.

**Example**

{% code lineNumbers="true" %}

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

{% endcode %}

**Configuring the Agent Through Helm Values**

You must specify the name of your ConfigMap in the Helm value `tls.ca.existingConfigMap` inside the agents entry in the `protocolMapperAgents` context of your `values.yaml` file.

If you configure more than one agent, we recommend to provide the CA certificate through `protocolMapperAgentDefaults` instead of `protocolMapperAgents`, as it should be the same for all agents.

**Example**

{% code lineNumbers="true" %}

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

{% endcode %}

## Applying Your Configuration

To apply this configuration to your agent, you must use Helm upgrade on your `connectware-agent` installation with the same parameters you originally used.

**Example**

{% code lineNumbers="true" %}

```bash
helm upgrade ${RELEASE_NAME} cybus/connectware-agent -f values.yaml -n ${NAMESPACE}
```

{% endcode %}

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

## Replacing CA Certificate for the connectware-agent Helm Chart

If you want to replace the CA certificate, follow the same steps as when adding it. However, the agents will not automatically start using the new certificates. You must manually restart the Kubernetes StatefulSets associated with the agents for which you replaced the CA certificate. This StatefulSet is named `<chart-name>-<release-name>-<agent-name>`. Some characters, most prominently the `.` character, will be replaced by `-` characters in the agent name.

If you followed the recommendations in this documentation, the first two parts are abbreviated to `connectware-agent`. An agent named `bender-robots`, for example, would then be deployed as a StatefulSet named `connectware-agent-bender-robots`.

{% code lineNumbers="true" %}

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

{% endcode %}

This will restart the agent and apply the new certificate/key.

If you want to restart all agents from your installation, you can use this command in combination with the name you gave to your agent deployment:

{% code lineNumbers="true" %}

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

{% endcode %}

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