Adding Sidecars and Volumes

Attach sidecar containers and shared volumes to Connectware and Connectware agent components for advanced Kubernetes scheduling.

Sidecars extend Connectware component functionality by running auxiliary containers alongside the main application container within the same pod.

Advanced configuration, use with caution

These configurations require deep Kubernetes and Connectware expertise. Misconfiguration can compromise system stability, security, and functionality. Always thoroughly test before applying to production environments.

Cybus does not officially support modified installations. We recommend informing Customer Success of your planned changes to identify compatibility concerns.

When to Use Sidecars

Sidecars run continuously alongside the main container, sharing the pod's lifecycle. Use sidecars when you need auxiliary processes that support the main application.

Common use cases:

• Separation of concerns: Log shipping, metrics collection, or security scanning that runs continuously alongside the main application.

• Dynamic configuration and secrets syncing: Fetch, rotate, or sync data (such as TLS certificates) from external systems into a shared volume.

• Network proxying: Intermediary process (Envoy, Nginx) to handle TLS termination or routing for a specific Connectware component.

Configuration Values

The following Helm values attach sidecar containers and storage to Connectware components:

Value	Description
extraContainers	List of containers to run within the pod alongside the main Connectware container. Accepts standard Kubernetes container specifications.
extraVolumes	List of volumes attached at the pod level. Can be mounted by both the main Connectware container and sidecars.
extraVolumeMounts	Volume mounts for the main Connectware container. Requires corresponding volume definition in extraVolumes.
extraVolumeClaimTemplates	List of Kubernetes StatefulSet volumeClaimTemplate definitions, appended to the workload's existing volume claim templates. Available only for broker and nats in the connectware chart, and agents in the connectware-agent chart.

Volume mounts require a matching volume

If you define extraVolumeMounts, you must also define the corresponding volume in extraVolumes. Defining a volume mount without its underlying volume definition causes the deployment to fail.

Adding Sidecar Containers

Attach sidecar containers to a component using the extraContainers Helm value. This value accepts a standard Kubernetes container definition list.

Overriding defaults with the connectware-agent Helm chart

When configuring connectware-agent, values set on a specific agent in protocolMapperAgents[] completely replace values from protocolMapperAgentDefaults. This applies to extraContainers, extraVolumes, extraVolumeMounts, and extraVolumeClaimTemplates. Set an empty list ([]) on a specific agent to exclude it from defaults.

Example: Adding a Basic Sidecar Container

The following tabs show how to configure sidecar containers for the connectware Helm chart and the connectware-agent Helm chart.

connectware Helm Chart

values.yaml

# Note: 'authServer' is used as an example, but this configuration
# is applicable to any Connectware component.
authServer:
  extraContainers:
    - name: tls-proxy
      image: registry.my-company.tld/tls-proxy/tls-proxy:latest
      env:
        - name: 'PROXY_HANDLE_TCP_CONNECTIONS'
          value: 'true'

connectware-agent Helm Chart

The connectware-agent chart can be deployed standalone or as a subchart within the connectware Helm chart. Both deployment modes use the same values structure, but when used as a subchart you need to configure it in the connectwareAgent Helm value section.

Configure sidecars globally with protocolMapperAgentDefaults or per-agent with protocolMapperAgents[]. Per-agent values completely replace the defaults.

Example: Applying sidecars to all agents (default)

values.yaml

protocolMapperAgentDefaults:
  extraContainers:
    - name: tls-proxy
      image: registry.my-company.tld/tls-proxy/tls-proxy:latest
      env:
        - name: 'PROXY_HANDLE_TCP_CONNECTIONS'
          value: 'true'

protocolMapperAgents:
  - name: my-agent

Example: Applying sidecars to a specific agent

values.yaml

protocolMapperAgentDefaults:
  # ... shared defaults

protocolMapperAgents:
  - name: my-agent
    extraContainers:
      - name: tls-proxy
        image: registry.my-company.tld/tls-proxy/tls-proxy:latest
        env:
          - name: 'PROXY_HANDLE_TCP_CONNECTIONS'
            value: 'true'

Example: Deploying agents as part of the connectware Helm chart with default sidecars

values.yaml

global:
  licenseKey: ${LICENSE_KEY}
connectwareAgent:
  protocolMapperAgentDefaults:
    extraContainers:
      - name: tls-proxy
        image: registry.my-company.tld/tls-proxy/tls-proxy:latest
        env:
          - name: 'PROXY_HANDLE_TCP_CONNECTIONS'
            value: 'true'

  protocolMapperAgents:
    - name: my-agent

Replace ${LICENSE_KEY} with your Connectware license key.

Adding Shared Volumes

If your sidecar needs to share data with the main Connectware component or main agent container or requires its own storage, you can define pod-level volumes using extraVolumes. This Helm value accepts standard Kubernetes volume definitions (such as emptyDir, secret, configMap, or persistentVolumeClaim).

Once a volume is defined, you can mount it into the main Connectware component or main agent container using extraVolumeMounts as described in Kubernetes documentation, and mount it into your sidecar using a standard volumeMounts block within the extraContainers definition.

Example: Sharing an emptyDir Volume

The following tabs show how to share volumes between the main container and sidecars for the connectware Helm chart and the connectware-agent Helm chart.

connectware Helm Chart

values.yaml

# Note: 'authServer' is used as an example, but this configuration
# is applicable to any Connectware component.
authServer:
  extraVolumes:
    - name: shared-data
      emptyDir: {}
  extraVolumeMounts:
    - name: shared-data
      mountPath: /opt/connectware/shared
  extraContainers:
    - name: data-processor
      image: busybox:latest
      command: ['sh', '-c', 'while true; do date > /sidecar-data/time.txt; sleep 10; done']
      volumeMounts:
        - name: shared-data
          mountPath: /sidecar-data

connectware-agent Helm Chart

Example: Adding an extra volume & sidecar to all agents as a default value

values.yaml

protocolMapperAgentDefaults:
  extraVolumes:
    - name: shared-data
      emptyDir: {}
  extraVolumeMounts:
    - name: shared-data
      mountPath: /opt/connectware/shared
  extraContainers:
    - name: data-processor
      image: busybox:latest
      command: ['sh', '-c', 'while true; do date > /sidecar-data/time.txt; sleep 10; done']
      volumeMounts:
        - name: shared-data
          mountPath: /sidecar-data
protocolMapperAgents:
  - name: my-agent

Using Existing Kubernetes Volumes

You can use the extraVolumes Helm value to mount existing Kubernetes resources into your sidecars without modifying the main Connectware component or the main agent container's mounts.

Example: Mounting a ConfigMap

The following tabs show how to mount existing Kubernetes resources for both Helm charts.

connectware Helm Chart

Example: Mounting a ConfigMap into a sidecar

values.yaml

# Note: 'authServer' is used as an example, but this configuration
# is applicable to any Connectware component.
authServer:
  extraVolumes:
    - name: custom-config-volume
      configMap:
        name: my-custom-config
  extraContainers:
    - name: custom-app
      image: my-company/custom-app:1.0.0
      volumeMounts:
        - name: custom-config-volume
          mountPath: /app/config

connectware-agent Helm Chart

Example: Mounting a ConfigMap to a specific agent (subchart deployment)

values.yaml

global:
  licenseKey: ${LICENSE_KEY}
connectwareAgent:
  protocolMapperAgentDefaults:
  # ... shared defaults
  protocolMapperAgents:
    - name: my-agent
      extraVolumes:
        - name: custom-config-volume
          configMap:
            name: my-custom-config
      extraContainers:
        - name: custom-app
          image: my-company/custom-app:1.0.0
          volumeMounts:
            - name: custom-config-volume
              mountPath: /app/config

Adding Extra Volume Claim Templates

For some workloads, you can request dedicated persistent storage for each replica using extraVolumeClaimTemplates. This value accepts a list of Kubernetes StatefulSet volume claim template definitions, which Kubernetes uses to provision a separate PersistentVolumeClaim for each pod in the StatefulSet. Your templates are appended to the workload's existing volume claim templates. This is currently supported by the broker and nats workloads of the connectware Helm chart.

Additionally, the same mechanism is supported by the connectware-agent chart to deploy additional volumes with agents, supporting the protocolMapperAgentDefaults configuration style of the chart, however agents are not horizontally scalable.

Unlike extraVolumes and extraVolumeMounts, which apply to all components, extraVolumeClaimTemplates is available only for broker and nats in the connectware chart, and agents in the connectware-agent chart.

The data claim name is reserved

Each of these workloads already defines a hardcoded volume claim template named data. Do not use data as the name of a template in extraVolumeClaimTemplates. Reusing the reserved name causes the StatefulSet to fail.

The following tabs show how to add extra volume claim templates for the connectware Helm chart and the connectware-agent Helm chart.

connectware Helm Chart

Set extraVolumeClaimTemplates on the broker or nats workload. Other Connectware components do not support this value.

values.yaml

broker:
  extraVolumeClaimTemplates:
    - metadata:
        name: broker-extra-storage
      spec:
        accessModes: ['ReadWriteOnce']
        resources:
          requests:
            storage: 10Gi

nats:
  extraVolumeClaimTemplates:
    - metadata:
        name: nats-extra-storage
      spec:
        accessModes: ['ReadWriteOnce']
        resources:
          requests:
            storage: 5Gi

connectware-agent Helm Chart

The connectware-agent chart can be deployed standalone or as a subchart within the connectware Helm chart. Both deployment modes use the same values structure, but when used as a subchart you need to configure it in the connectwareAgent Helm value section.

Configure volume claim templates globally with protocolMapperAgentDefaults or per-agent with protocolMapperAgents[]. Per-agent values completely replace the defaults.

Example: Applying a volume claim template to all agents (default)

values.yaml

protocolMapperAgentDefaults:
  extraVolumeClaimTemplates:
    - metadata:
        name: agent-extra-storage
      spec:
        accessModes: ['ReadWriteOnce']
        resources:
          requests:
            storage: 10Gi

protocolMapperAgents:
  - name: my-agent

Example: Applying a volume claim template to a specific agent

values.yaml

protocolMapperAgentDefaults:
  # ... shared defaults

protocolMapperAgents:
  - name: my-agent
    extraVolumeClaimTemplates:
      - metadata:
          name: agent-extra-storage
        spec:
          accessModes: ['ReadWriteOnce']
          resources:
            requests:
              storage: 10Gi

Example: Deploying agents as part of the connectware Helm chart with a default volume claim template

values.yaml

global:
  licenseKey: ${LICENSE_KEY}
connectwareAgent:
  protocolMapperAgentDefaults:
    extraVolumeClaimTemplates:
      - metadata:
          name: agent-extra-storage
        spec:
          accessModes: ['ReadWriteOnce']
          resources:
            requests:
              storage: 10Gi

  protocolMapperAgents:
    - name: my-agent

Replace ${LICENSE_KEY} with your Connectware license key.

Verification

After applying your changes, verify that sidecars are running successfully:

# Check pod status and container list
kubectl get pods -n ${NAMESPACE}

# View sidecar logs
kubectl logs -n ${NAMESPACE} ${POD_NAME} -c ${SIDECAR_NAME}

# Describe the pod to see all containers and their status
kubectl describe pod -n ${NAMESPACE} ${POD_NAME}

Replace ${NAMESPACE} with your Connectware namespace, ${POD_NAME} with the pod name, and ${SIDECAR_NAME} with the name you defined in extraContainers.

Result

All containers (main Connectware component and sidecars) show a Running status in the pod description. Both the main Connectware container and sidecars start together and run continuously. If a sidecar fails, it restarts according to the pod's restart policy.