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 has a lot of flexibility, but in a nutshell, 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.

Learn More About

• 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.

• You have kubectl installed and configured to access your Kubernetes cluster.

• You have Helm v3 installed.

Procedure

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

1. Extract the Certificate Authority certificate

2. Configure your agent to use the Certificate Authority

3. Apply your configuration

Extracting Certificate Authority Certificate

In order to use TLS connections, you must extract the Certificate Authority (CA) 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.

Note: 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.

namespace=[namespace]
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

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:

Make sure to pay attention to the indentation of your CA certificate. It needs to be indented once relative to certChain and keep this indentation (see Example).

Example

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

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. Please 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, so keep it at hand. We recommend choosing a name following the scheme <chart-name>-<release-name>-tls-ca-cert.

Example

cp cybus_ca.crt ca-chain.pem
kubectl create configmap <configmap-name> --from-file ca-chain.pem

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, it is recommended to provide the CA certificate through protocolMapperAgentDefaults instead of protocolMapperAgents, because it should be the same for all agents.

Example

protocolMapperAgentDefaults:
    tls:
        ca:
            existingConfigMap: <configmap-name>

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

helm upgrade [release-name] cybus/connectware-agent -f values.yaml -n [namespace]

Replacing CA Certificate for the connectware-agent Helm Chart

If you want to replace the CA certificate, you follow the same steps as when adding them. 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 these docs, 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”.

kubectl -n [namespace] rollout restart sts [statefulset-name]

This will restart the agent and apply the new certificates/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:

kubectl -n [namespace] rollout restart sts -l app.kubernetes.io/instance=[release-name]

If you followed the recommendations in these docs, [release-name] is connectware-agent.