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

Configure the CA certificate chain for agents deployed with the connectware-agent Helm chart to verify TLS connections to Connectware.

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.

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 is installed on your system.

• kubectl is installed and configured to access your Kubernetes cluster.

Procedure

1

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.

For production setups, replace the Public Key Infrastructure (PKI) generated during Connectware installation with a PKI managed and approved by your organization.

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

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.

2

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.

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.

values.yaml

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

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.

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

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

values.yaml

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

3

Apply Your Configuration

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

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

Replace ${VERSION} with the target chart version (see the Compatibility Matrix) and ${NAMESPACE} with the namespace of your connectware-agent installation. If you followed the naming recommendations in this documentation, ${RELEASE_NAME} is connectware-agent.

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:

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

To restart all agents from your installation:

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

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