Kubernetes Archive

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

Removing Default Values

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)

Full Example: Individual Resources for a Single Agent

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)

Configuring the Target Connectware Hostname

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:

TCP/443
TCP/1883

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)

Configuring Agents for 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 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.

Enabling TLS for MQTT

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.

(Advanced) Overriding MQTT Target Parameters

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.

Override MQTT data host

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)

Override MQTT Control Host

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)

Override MQTT Data Port

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)

Override MQTT control-plane Port

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”

Configuring Security Context

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.

Unsetting Security Context

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)

Assigning Agents to Kubernetes Nodes

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)

Unsetting protocolMapperAgentDefaults Node Selector Labels

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)

Configuring Environment Variables

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)

Unsetting protocolMapperAgentDefaults Environment Variables

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)

Changing Connectware Agent Version

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)

Changing Connectware Agent Image

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)

Prerequisites

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

Uninstalling All Agents from One Installation

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)

Uninstalling Single Agents from a Larger Installation

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)

Prerequisites

Helm V3 installed (Helm | Installing Helm).
kubectl installed (K8s Install Tools).
kubectl configured with the current context pointing to your target cluster (Configure Access to Multiple Clusters).

Upgrading the connectware-agent Helm Chart

Upgrading the connectware-agent Helm chart consists of the following steps:

Picking a compatible version
Determining the name of your connectware-agent installation
Obtaining your values.yaml file
Reviewing changes and adjusting Helm values
Starting the upgrade
Verifying the upgrade

Picking a Compatible Version

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)

Determining the name of your connectware-agent installation

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.

Obtaining Your values.yaml File

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)

Reviewing Changes and Adjusting Helm Values

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

Starting the Upgrade

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.

Verifying the Upgrade

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

Removing Default Values

Full Example: Individual Resources for a Single Agent

Configuring the Target Connectware Hostname

Configuring Agents for Connectware with Separate control-plane-broker

Enabling TLS for MQTT

(Advanced) Overriding MQTT Target Parameters

Override MQTT data host

Override MQTT Control Host

Override MQTT Data Port

Override MQTT control-plane Port

Configuring Security Context

Unsetting Security Context

Assigning Agents to Kubernetes Nodes

Unsetting protocolMapperAgentDefaults Node Selector Labels

Configuring Environment Variables

Unsetting protocolMapperAgentDefaults Environment Variables

Changing Connectware Agent Version

Changing Connectware Agent Image

Prerequisites

Uninstalling All Agents from One Installation

Uninstalling Single Agents from a Larger Installation

Prerequisites

Upgrading the connectware-agent Helm Chart

Picking a Compatible Version

Determining the name of your connectware-agent installation

Obtaining Your values.yaml File

Reviewing Changes and Adjusting Helm Values

Starting the Upgrade

Verifying the Upgrade

Newsletter

Ihr Browser unterstützt diese Webseite nicht.