> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/adding-sidecars-and-volumes.md).

# Adding Sidecars and Volumes

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

{% hint style="danger" %}

## 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.
{% endhint %}

## 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`.                            |

{% hint style="warning" %}

## 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.
{% endhint %}

## Adding Sidecar Containers

Attach sidecar containers to a component using the `extraContainers` Helm value. This value accepts a [standard Kubernetes container definition list](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container).

{% hint style="info" %}

## 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`, and `extraVolumeMounts`. Set an empty list (`[]`) on a specific agent to exclude it from defaults.
{% endhint %}

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

{% tabs %}
{% tab title="connectware Helm Chart" %}
{% code title="values.yaml" lineNumbers="true" %}

```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'
```

{% endcode %}
{% endtab %}

{% tab title="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)**

{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}

**Example: Applying sidecars to a specific agent**

{% code title="values.yaml" lineNumbers="true" %}

```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'
```

{% endcode %}

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

{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}

Replace `${LICENSE_KEY}` with your Connectware license key.
{% endtab %}
{% endtabs %}

## 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](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/volume/#volume) (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](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#volumes-1), 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.

{% tabs %}
{% tab title="connectware Helm Chart" %}
{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}
{% endtab %}

{% tab title="connectware-agent Helm Chart" %}
**Example: Adding an extra volume & sidecar to all agents as a default value**

{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="connectware Helm Chart" %}
**Example: Mounting a ConfigMap into a sidecar**

{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}
{% endtab %}

{% tab title="connectware-agent Helm Chart" %}
**Example: Mounting a ConfigMap to a specific agent (subchart deployment)**

{% code title="values.yaml" lineNumbers="true" %}

```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
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Verification

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

{% code lineNumbers="true" %}

```bash
# 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}
```

{% endcode %}

{% hint style="info" %}
Replace `${NAMESPACE}` with your Connectware namespace, `${POD_NAME}` with the pod name, and `${SIDECAR_NAME}` with the name you defined in `extraContainers`.
{% endhint %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/adding-sidecars-and-volumes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.