How to | 22 Mai 2023

Installing Connectware agents using the connectware-agent Helm chart

By: Philipp Geschke

by Philipp Geschke

Prerequisites

• Connectware is already installed and configured.
• Connectware license key.
• Helm V3 installed (Helm | Installing Helm).
• kubectl installed (Install Tools).
• kubectl configured with the current context pointing to your target cluster (Configure Access to Multiple Clusters).
• A Kubernetes namespace that will be used.

Adding the Helm chart repository

Add the Cybus connectware-helm repository to your local Helm installation to use the connectware-agent Helm chart to install Connectware agents in Kubernetes:

helm repo add cybus https://repository.cybus.io/repository/connectware-helm

To verify that the Helm chart is available you can execute a Helm search:

helm search repo connectware-agent

NAME	CHART VERSION	APP VERSION DESCRIPTION
cybus/connectware-agent	1.0.0	1.1.5 Cybus Connectware
standalone agents

Creating your values.yaml file

As with all Helm charts, the connectware-agent chart is configured using a YAML file. This file can have any name, however we will refer to it as the values.yaml file.

Create this file to start configuring your agent installation by using your preferred editor:

vi values.yaml

Installing a single agent

To quickly install a single agent you only need to add your Connectware license key to your values.yaml file as the Helm value licenseKey:

licenseKey: <your-connectware-license-key>

You can now use this file to deploy your Connectware agent in a Kubernetes namespace of your choice:

helm upgrade -i connectware-agent cybus/connectware-agent -f values.yaml -n <namespace>

NAME: connectware-agent
LAST DEPLOYED: Mon Mar 13 14:31:39 2023
NAMESPACE: connectware
STATUS: deployed
REVISION: 1
TEST SUITE: None

NOTES:

Thank you for using the Cybus Connectware agent Helm chart!
For additional information visit https://cybus.io/
Number of agents: 1

--------------------
- agent

If any of these agents are new, please remember to visit Connectware's client registry to set up the connection to Connectware.

❗️Hint: If you have agents stuck in a status other than "Running", you need to delete the stuck pods before a pod with your new configuration will be created.

This will start a single Connectware agent named “agent”, which will connect to a Connectware installation deployed in the same namespace. Unlock the Client Registry in your Connectware admin UI to connect this agent. Refer to Client Registry — Cybus Documentation 1.1.5 documentation to learn how to use the Client Registry to connect agents.

You can repeat the same command to apply any changes to your values.yaml file configuration in the future.

Changing the target Connectware

If you are not deploying the agent in the same Kubernetes namespace, or even inside the same Kubernetes cluster, you need to specify the hostname under which Connectware is reachable for this agent.

In the default configuration, the following network ports on Connectware must be reachable for the agent:

• TCP/443
• TCP/1883

Specify the hostname of Connectware to which the agent connects to by setting the Helm value connectwareHost inside the protocolMapperAgentDefaults context of your values.yaml file. For Connectware deployments in a different Kubernetes namespace this is “connectware.<namespace>”.

Example:

licenseKey: <your-connectware-license-key>
protocolMapperAgentDefaults:
  connectwareHost: connectware.cybus # adjust to actual hostname of Connectware

Connectware with separate control-plane-broker

To connect to a Connectware that uses the separate control-plane-broker, you need to set the Helm value controlPlaneBrokerEnabled to true inside the protocolMapperAgentDefaults section of your values.yaml file.

Example:

licenseKey: <your-connectware-license-key>
protocolMapperAgentDefaults:
  connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
  controlPlaneBrokerEnabled: true

❗️Note: This adds TCP/1884 to required network ports.

Installing multiple agents with a single Helm installation

You can use the agent chart to install multiple Connectware agents. Every agent you configure needs to be named using the Helm value name in a collection entry inside the context protocolMapperAgents. This way, the default name “agent” will be replaced by the name you give the agent.

Example:

licenseKey: <your-connectware-license-key>
protocolMapperAgentDefaults:
  connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
protocolMapperAgents:
- name: bender-robots
- name: welder-robots

This will deploy two Connectware agents, named “bender-robots” and “welder-robots”, both of which will contact the Client Registry of Connectware inside the Kubernetes namespace “cybus”, as described in Client Registry — Cybus Documentation 1.1.5 documentation