Compute resource requests are used by Kubernetes to schedule workloads on a node that has the required resources available. Compute resource limits are used to limit a workloads consumption.
In order to be scheduled in Kubernetes highest Quality of Service class, agents installed through the connectware-agent
Helm chart come with a default of using the same value for requests and limits. These values are:
Resource | Value (request and limit) |
---|---|
CPU | 2000m |
Memory | 2000Mi |
To adjust the compute resources for the agent, specify a Kubernetes Quantity for cpu
and memory
for resources.requests
and resources.limits
inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
resources:
requests:
cpu: 1000m
memory: 1500Mi
limits:
cpu: 3000m
memory: 2500Mi
Code-Sprache: YAML (yaml)
Hint: cpu
is usually specified in m
, representing “Milli-CPU”, with 1000m
roughly meaning one CPU core. memory
is usually specified in Mi
, representing “Mebibytes”.
In order to be scheduled in Kubernetes highest Quality of Service class, agents installed through the connectware-agent
Helm chart come with a default of using the same value for requests and limits. These values are:
Resource | Value (request and limit) |
---|---|
CPU | 2000m |
Memory | 2000Mi |
To remove either you can set the value resources.request
and resources.limits
inside the agents entry in protocolMapperAgents
context of your values.yaml file to an empty YAML object {}
.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
resources:
limits: {} # Limits are removed from this agent
Code-Sprache: YAML (yaml)
You can also completely remove resource definitions by setting resources
inside the agents entry in protocolMapperAgents
context of your values.yaml file to an empty YAML object {}
.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
resources: {} # No resources are specified for this agent
Code-Sprache: YAML (yaml)
In this example, we will set lower default resources, but for our agent welder-robots
we will request more resources and remove limits, as we do want it to not be limited for its important work.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
resources:
requests:
cpu: 500m
memory: 500Mi
limits:
cpu: 1500m
memory: 2000Mi
protocolMapperAgents:
- name: bender-robots # this agent will have the default resources
- name: welder-robots # this agent will have more resource requests and no limits
resources:
requests:
cpu: 2000m
memory: 2000Mi
limits: {}
- name: painter-robots # this agent will have the default resources
Code-Sprache: YAML (yaml)
By default agents will target a Connectware installation in the same Kubernetes namespace. If your Connectware installation is in a different namespace or outside of this 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:
Specify the hostname of Connectware that the agent connects to by setting the Helm value connectwareHost
inside the agents entry in protocolMapperAgents
context of your values.yaml file. For Connectware deployments in a different Kubernetes namespace this is “connectware.<namespace>”.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
Code-Sprache: YAML (yaml)
To connect to a Connectware that uses the separate control-plane-broker, you need to set the Helm value controlPlaneBrokerEnabled
to true
inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
controlPlaneBrokerEnabled: true
Code-Sprache: YAML (yaml)
Note: This adds TCP/1884 to required network ports.
To enable Transport Layer Security encryption for MQTT you set the parameter mqtt.tls
inside the agents entry in protocolMapperAgents
context of your values.yaml file to true
.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
mqtt:
tls: true
Code-Sprache: YAML (yaml)
Note: This adds TCP/8883 and TCP/8884 to required network ports.
By default, the connectware-agent
Helm chart will control the parameters in this section, and adjust them according to your chosen configuration, however, optionally you can override these values in advanced setups.
To override the hostname which the agent will connect to using MQTT to move data, you set the parameter mqtt.dataHost
inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
mqtt:
dataHost: broker.cybus
Code-Sprache: YAML (yaml)
To override the hostname which the agent will connect to using MQTT to exchange control-plane information, you set the parameter mqtt.controlHost
inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
mqtt:
controlHost: control-plane-broker.cybus
Code-Sprache: YAML (yaml)
To override the TCP port which the agent will connect to using MQTT to move data, you set the parameter mqtt.dataPort
inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
mqtt:
dataPort: 10883
Code-Sprache: YAML (yaml)
To override the TCP port which the agent will connect to using MQTT to exchange control-plane information, you set the parameter mqtt.controlPort
inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
licenseKey: <your-connectware-license-key>
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
mqtt:
controlPort: 10884
Code-Sprache: YAML (yaml)
By default, agents created through the connectware-agent
Helm chart will be controlled through Kubernetes objects that are prefixed with the name of your installation (called a “release” in Helm terms) and the name of the Helm chart. This is done to ensure non-conflicting Kubernetes object names.
If these prefixes are identical, they are only used once. This means, that by default, when following our recommendations, an agent named “bender-robots” would create a StatefulSet name “connectware-agent-connectware-agent-bender-robots”, which is shortened to “connectware-agent-bender-robots”.
There are two Helm values, that allow you to control these prefixes:
Value | Effect |
---|---|
nameOverride | Overrides the Helm chart name, which is the second half of the prefix |
fullnameOverride | Overrides the full prefix (first and second part) |
Setting either value to an empty string (““) removes the prefix part it controls.
Example:
Setting nameOverride
to “cw-agent” for an installation named “agents”.
nameOverride: cw-agent protocolMapperAgents: - name: bender-robots
Code-Sprache: YAML (yaml)
This will result in an agent StatefulSet named “agents-cw-agent-bender-robots”
Example:
Setting fullnameOverride
to “my-agents” for an installation named “connectware-agents”.
fullnameOverride: my-agents protocolMapperAgents: - name: bender-robots
Code-Sprache: YAML (yaml)
This will result in an agent StatefulSet named “my-agents-bender-robots”
Example:
Setting fullnameOverride
to “” for an installation named “connectware-agents”.
fullnameOverride: "" protocolMapperAgents: - name: bender-robots
Code-Sprache: YAML (yaml)
This will result in an agent StatefulSet named “bender-robots”
Connectware agents installed using the connectware-agent
Helm chart allow changing the security context of executed containers by defining the securityContext
and podSecurityContext
sections inside the agents entry in the protocolMapperAgents
context of your values.yaml file.
It is important to note, that the security context required by the agent is dependent on installed services, so any modifications made should be verified to work with your use case.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
podSecurityContext:
runAsUser: 1000
runAsGroup: 1000
Code-Sprache: YAML (yaml)
The difference between securityContext
and podSecurityContext
is, that securityContext
puts restrictions on the container, while podSecurityContext
puts restrictions on the pod. While this may seem pointless with the agents single container inside its pod, it does play a role when, for example, attaching an ephemeral container to the pod.
If you set a securityContext
or podSecurityContext
in the protocolMapperAgentDefaults
section of your values.yaml file, you can unset them for individual agents by setting the value of securityContext
or podSecurityContext
to {}
inside the agents entry in the protocolMapperAgents
context of your values.yaml.
Example:
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
podSecurityContext:
runAsUser: 1000
runAsGroup: 1000
protocolMapperAgents:
- name: bender-robots # this agent will run as user & group 1000
- name: welder-robots # this agent will not run as user & group 1000
podSecurityContext: {}
Code-Sprache: YAML (yaml)
You can target specific Kubernetes nodes with your agent using the Kubernetes node selector. This can for example be used to select a remote node close to your shop floor.
Kubernetes node selector is a set of one or more labels, that the target Kubernetes node must have, to be eligible to run the agent.
To set these node selector labels, use the nodeSelector
value inside the agent’s entry in the protocolMapperAgents
context of your values.yaml file.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
nodeSelector:
mycompany.tld/node-location: shopfloor
mycompany.tld/building: 1a
Code-Sprache: YAML (yaml)
If you used the nodeSelector
value in the protocolMapperAgentDefaults
context of your values.yaml file, you can unset them for individual agents by setting the value of nodeSelector
to {}
inside the agents entry in the protocolMapperAgents
context of your values.yaml.
Example:
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
nodeSelector:
mycompany.tld/node-location: shopfloor
mycompany.tld/building: 1a
protocolMapperAgents:
- name: bender-robots # this agent will use the node selector labels
- name: welder-robots # this agent will NOT use the node selector labels
nodeSelector: {}
Code-Sprache: YAML (yaml)
You can add Kubernetes labels and annotations to your agents. There are three pairs of values, that control where labels and annotations are added:
Value | Added to |
---|---|
annotations labels | StatefulSet |
podAnnotations podLabels | Pod |
service.annotations service.labels | Service |
All six values exist for protocolMapperAgentDefaults
and in per-agent protocolMapperAgents
entries. When you specify them in both contexts, both will be added to the Kubernetes objects.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
annotations:
tld.mycompans.costcenter: '12345'
labels:
mycompany.tld/environment: production
podAnnotations:
tld.mycompans.costcenter: '12345'
podLabels:
mycompany.tld/environment: production
service:
annotations:
tld.mycompans.costcenter: '12345'
labels:
mycompany.tld/environment: production
Code-Sprache: YAML (yaml)
To define a set of environment variables to be applied to the protocol-mapper agent, use the env
list of name
and value
pairs inside the agents entry in the protocolMapperAgents
section of your values.yaml file.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
env:
- name: CYBUS_PROTOCOL_MAPPER_PASSWORD
value: ooth9oon7Taim]oo
- name: CUSTOM_ENV_VARIABLE_FOO
value: bar
Code-Sprache: YAML (yaml)
If you used the list value env
in the protocolMapperAgentDefaults
section of your values.yaml file, you can unset them for individual agents by setting the value of env
to []
inside the agents entry in the protocolMapperAgents
context of your values.yaml.
Example
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
env:
- name: CUSTOM_ENV_VARIABLE_FOO
value: bar
protocolMapperAgents:
- name: bender-robots # this agent will have the ENV CUSTOM_ENV_VARIABLE_FOO
- name: welder-robots # this agent will NOT have the ENV CUSTOM_ENV_VARIABLE_FOO
env: []
Code-Sprache: YAML (yaml)
By default, agents deployed using the connectware-agent
Helm chart will be using the official default protocol-mapper
image in a specific version coupled with the Helm chart version you are using.
You can view this version by executing a Helm search for the connectware-agent
Helm chart, and viewing the “APP VERSION” column.
Example
helm search repo connectware-agent -l
Code-Sprache: YAML (yaml)
NAME CHART VERSION APP VERSION DESCRIPTION
cybus/connectware-agent 1.0.0 1.1.5 Cybus Connectware standalone agents
Code-Sprache: YAML (yaml)
To change the image version used by the agent, specify the version of the protocol-mapper image you want in the image.version
value inside the agents entry in the protocolMapperAgents
context of your values.yaml file.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
image:
version: "1.1.5" # set to desired version
Code-Sprache: YAML (yaml)
If you are using a custom protocol-mapper image instead of the official default image, you can specify the image name in the image.name
value inside the agents entry in the protocolMapperAgents
context of your values.yaml file.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
image:
name: my-custom-protocol-mapper # set name of your image
Code-Sprache: YAML (yaml)
You can use a custom image registry, if it provides the necessary image for your agents.
To change the registry for the agent, specify the address under which the image is pull-able in the image.registry
value inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
image:
registry: registry.my-company.tld/cybus
Code-Sprache: YAML (yaml)
If your custom registry requires authentication, you must also provide a manually created kubernetes.io/dockerconfigjson
secret in the image.pullSecrets
list inside the agents entry in protocolMapperAgents
context of your values.yaml file.
Example
protocolMapperAgents:
- name: bender-robots
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
image:
registry: registry.my-company.tld/cybus
pullSecrets:
- name: my-company-pull-secret
Code-Sprache: YAML (yaml)
Hint: kubernetes.io/dockerconfigjson
secrets can be created with this command:
kubectl create secret <secret-name> --docker-server=<registry-address> --docker-username=<username> --docker-password=<password> --docker-email=<user-email>
Code-Sprache: YAML (yaml)
The connectware-agent
Helm chart follows a configuration principle, in which settings can be defined for all configured agents comfortably using the protocolMapperAgentDefaults
section of your values.yaml file.
Example
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus
controlPlaneBrokerEnabled: true
mqtt:
tls: true
Code-Sprache: YAML (yaml)
All configuration specified inside this context is applied to all agents, unless you specifically override them on a per-agent basis.
In addition to protocolMapperAgentDefaults
there is a section named protocolMapperAgents
, which is a list of entries, each describing a single protocol-mapper agent. You can create an agent by simply setting its name
value. Every other configuration parameter will be taken from protocolMapperAgentDefaults
or default values.
To override protocolMapperAgentDefaults
Helm values for an agent, simply set the same parameter to a different value inside the agents entry of the protocolMapperAgents
context.
Example
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus
controlPlaneBrokerEnabled: true
mqtt:
tls: true
protocolMapperAgents:
- name: bender-robots
- name: welder-robots
mqtt:
tls: false # unlike the other agents, this agent will not use TLS for MQTT
- name: painting-robots
Code-Sprache: YAML (yaml)
kubectl
installed (Install Tools).kubectl
configured with the current context pointing to your target cluster (Configure Access to Multiple Clusters).If you want to remove all agents that were installed using the connectware-agent
Helm chart, you can use helm uninstall
command with the name of your installation (called a „release“). You chose this name yourself when installing with the connectware-agent
Helm chart. If you follow our docs it is named “connectware-agent”, but you can look it up by using the helm list
command targeting the namespace in which you installed your agents.
Example
helm list -n <namespace>
Code-Sprache: YAML (yaml)
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
connectware-agent <namespace> 1 2023-03-29 14:49:49.29654165 +0200 CEST deployed connectware-agent-1.0.0 1.1.5
Code-Sprache: YAML (yaml)
Once you determined the name of your installation, you can uninstall it.
Example
helm uninstall -n <namespace> connectware-agent
Code-Sprache: YAML (yaml)
This terminates running pods and removes their Kubernetes objects, however PersistentVolumeClaims, and with them the Persistent Volumes are retained. If you wish to clean them up, you can do so by using the label app.kubernetes.io/instance
in combination with kubectl delete
. The value for this label is again the release name you already used to uninstall.
Example
kubectl delete -n <namespace> pvc -l app.kubernetes.io/instance=connectware-agent
Code-Sprache: YAML (yaml)
If you want to remove one or more agents from a larger group of agents installed using the connectware-agent
Helm chart, you can simply remove their whole configuration from your values.yaml file and running a Helm upgrade as described in Configuring agents with the connectware-agent Helm chart.
Example
protocolMapperAgentDefaults:
connectwareHost: connectware.cybus # adjust to actual hostname of Connectware
protocolMapperAgents:
- name: bender-robots
resources:
limits:
cpu: 2000m
memory: 4000Mi
- name: welder-robots # remove all configuration for this agent
resources: #
limits: #
cpu: 500m #
memory: 1000Mi #
- name: painter-robots
resources:
limits:
cpu: 1000m
memory: 2000Mi
Code-Sprache: YAML (yaml)
Upgrading the connectware-agent Helm chart consists of the following steps:
Agents installed using the connectware-agent Helm chart are installed in a Connectware version coupled with the Helm chart. When upgrading the Helm chart, there may be a change in the agents version.
Connectware agents need to run the same version as Connectware itself, meaning you have to update the agents version in tandem with your Connectware.
The orchestration information provided by the Helm chart is tuned towards specific versions of Connectware’s protocol-mapper agent image. You can view the correct version of the Helm chart to pick for the version of the Connectware agent by executing a Helm search for the connectware-agent Helm chart, and viewing the “APP VERSION” column.
helm search repo connectware-agent -l
Code-Sprache: YAML (yaml)
If you want to make sure you don’t accidentally update to a Connectware agent version, which is incompatible with your Connectware version, we recommend you lock the version of the agents protocol-mapper image in your connectware-agent values.yaml file using the Helm value protocolMapperAgentDefaults.image.version.
Example
protocolMapperAgentDefaults:
image:
version: 1.1.5
Code-Sprache: YAML (yaml)
To upgrade your connectware-agent installation, you need to know the name you chose upon installation. If you followed our docs, this is most likely connectware-agent, but to make sure, you can use the helm list command on your target namespace.
helm list -n <namespace>
Code-Sprache: YAML (yaml)
If you are unsure, in what namespace you deployed your connectware-agent installation, you can use the helm list -A command to display all Helm installations cluster wide.
helm list -A
Code-Sprache: YAML (yaml)
Once you determined the name and namespace of your installation, you can upgrade it.
Your values.yaml file acts as a configuration file for your connectware-agent Helm installation. Ideally you should have it in a safe, versioned spot and available for operations, however, should you not have it at hand, you can also extract it from your connectware-agent Helm installation using the helm get values command.
Example
helm get values -o yaml -n connectware-agent connectware-agent > values.yaml
Code-Sprache: YAML (yaml)
In this step you will review the Helm charts README file to review all changes noted there, that might need adjustments in your settings. You can use the helm show readme command to view them.
Example
helm show readme cybus/connectware-agent
Code-Sprache: Roboconf (roboconf)
If nothing is mentioned for the version you are upgrading to, then there are no configuration adjustments for you to do.
Review anything you find and adjustment your configuration accordingly.
If you locked the version for the agent’s protocol-mapper image using the value protocolMapperAgentDefaults.image.version or any agent specific configuration under protocolMapperAgents, make sure to update this to the target version of your upgrade.
Example
To start the upgrade of your connectware-agent Helm installation, you use the command helm upgrade on it, while specifying the target version with the –version parameter and providing your values.yaml file.
Example
helm upgrade --namespace <namespace> <installation-name> <cybus-repository>/connectware-ag
Code-Sprache: YAML (yaml)
You can find additional details to this command in the Helm documentation.
Next, verify that all pods are restarting with the new image version. Using the command kubectl get pod, look at their AGE, verify they are in STATE Running, and report as READY.
Example
kubectl get pod -n <namespace>
Code-Sprache: YAML (yaml)
Next, head to the Connectware Admin UI and verify your agents are connected in the correct version as described in the Connectware Documentation.
Should any pods not become READY, continue with Troubleshooting agents installed with the connectware-agent Helm chart