# Adding Agents Inside your Connectware Installation ## Setting up Agents inside Connectware Connectware protocol-mapper agents are additional components of Connectware that can be deployed and started individually. You can use agents for the following: * Inside your Connectware installation for specialization and load distribution * Outside your Connectware installation as edge deployments close to your shop floor **Related Links** * [Agents](https://docs.cybus.io/2-0-6/documentation/agents) ## Adding Agents inside Your Connectware Installation You can add additional agents to your Connectware installation via the Connectware Helm chart. The section to add agents is commented out by default. 1. In the `values.yaml` file, search for #protocolMapperAgents within the global context and remove the #. 2. Add the agents. The minimum configuration requires you to add the agent name. Note: You cannot change the name of an agent after creating it. 3. Add configurations to each agent. For example, define the storage size or the CPU and memory resources of each agent. **Example** In this example, two agents are added to the protocolMapperAgents section of the `values.yaml` file. {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: welder-robots - name: bender-robots ``` {% endcode %} ### Specifying the Storage Size for Agents (Optional) Agents require a persistent volume to store their data. The default storage size value is 40 Mi (40 Mebibytes). * To specify the storage size for an agent, add the parameter storageSize and define the storage size. Specify the storage size as Kubernetes quantities. {% hint style="info" %} You cannot change the storage size of an agent after creating it. {% endhint %} **Example** {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots storageSize: 1Gi ``` {% endcode %} **Related Links** * [Persistent volumes (Kubernetes documentation)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) * [Quantities (Kubernetes documentation)](https://kubernetes.io/docs/reference/glossary/?all=true#term-quantity) ### Specifying a StorageClass for Agents (Optional) Agents require a persistent volume to store their data. By default, the agents use the default storage class of the Kubernetes cluster. You can specify any Kubernetes StorageClass that offers the ReadWriteOnce access mode and is available in your Kubernetes cluster. * To specify a StorageClass for a persistent volume, add the parameter storageClassName and define a name. Note: You cannot change the name of the StorageClass after creating it. **Example** {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots storageClassName: longhorn ``` {% endcode %} **Related Links** * [Persistent volumes (Kubernetes documentation)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) * [StorageClass (Kubernetes documentation)](https://kubernetes.io/docs/concepts/storage/storage-classes/) * [Access modes for persistent volumes (Kubernetes documentation)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) ### Specifying CPU and Memory Resources for Agents You can use the Kubernetes resource requests and limits to specify CPU and memory resources for agents. Depending on their role and workload, agents can consume varying amounts of CPU and memory resources. We recommend that you use the Kubernetes metrics-server to identify the resource requirements of each agent and adjust the configuration if necessary. {% hint style="info" %} Important: Adjusting CPU and memory resources can impact the performance and availability of Connectware. When you customize the settings for CPU and memory resources, make sure that you monitor the performance and make adjustments if necessary. {% endhint %} * In the `values.yaml` file, specify the CPU and memory limits and requests in the Helm value global.podResources.distributedProtocolMapper. Specify the limits and requests as Kubernetes quantities. **Example** {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots resources: requests: cpu: 1000m memory: 1000Mi limits: cpu: 2000m memory: 2000Mi ``` {% endcode %} **Related Links** * [Kubernetes resource management (Kubernetes documentation)](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) * [Metrics server (Kubernetes documentation)](https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-server) * [Quantities (Kubernetes documentation)](https://kubernetes.io/docs/reference/glossary/?all=true#term-quantity) ### Specifying Additional Environment Variables for Agents You can specify a YAML array of objects to add additional environment variables for agents. In the `values.yaml` file, define a name and a value for the environment variable. Note: Kubernetes only accepts strings as environment variables. {% hint style="warning" %} Do not specify the following environment variables as they are already used by the Helm chart of Connectware: * CYBUS\_AGENT\_NAME * CYBUS\_AGENT\_MODE * CYBUS\_HOSTNAME\_INGRESS * CYBUS\_STREAMSERVER\_HOST * CYBUS\_STREAMSERVER\_PORT * CYBUS\_STREAMSERVER\_SCHEME * CYBUS\_DATAPLANE\_USE\_TLS * CYBUS\_DATAPLANE\_HOST * CYBUS\_DATAPLANE\_PORT * CYBUS\_DATAPLANE\_SCHEME * CYBUS\_USE\_MUTUAL\_TLS {% endhint %} **Example** {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots env: - name: CYBUS_TRUST_ALL_CERTS value: 'true' - name: SOME_OTHER_VARIABLE value: bar ``` {% endcode %} ### Directly Targeting the MQTT Broker Agents target the MQTT broker of Connectware through an Ingress proxy via the Kubernetes LoadBalancer Service. In your new Connectware installation, the LoadBalancer is named connectware. However, you can bypass the Ingress proxy. This allows you to reduce the number of services that move data, increase throughput or reduce load. Note: Only target the MQTT broker directly if the necessity was identified. To directly target the MQTT broker, do one of the following in the `values.yaml` file: * Ensure that your `cybus_server.crt` contains the hostname `broker`. * If you are using the default certificates, add the name to the Helm value `global.ingressDNSNames`. * Set the value of `dataPlane.host` to `broker`. **Example** Directly target the MQTT broker: {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots dataPlane: host: broker ``` {% endcode %} ## Defining Kubernetes Labels and Annotations for Agents You can define sets of labels and annotations that are added to the pod and controller resources of your agents. The following Helm values are available: | Helm value | Applied to | | ------------------- | ------------------------------------------------------------- | | labels | Controller (StatefulSet), Pod, Service, PersistentVolumeClaim | | service.labels | Service | | podLabels | Pod | | annotations | Controller (StatefulSet) | | podAnnotations | Pod | | service.annotations | Service | **Example** {% code lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots labels: tld.mycompany/robots: benders # label is common to all resources podLabels: pod: only # label is only on pods annotations: controller: only # annotation is only on StatefulSet controller podAnnotations: pod: only # annotation is only on pods service: labels: service: only # label is only on the service annotations: service: only # annotations is only on the service ``` {% endcode %} **Related Links** * [Labels (Kubernetes documentation)](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) * [Annotations (Kubernetes documentation)](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)