> 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-init-containers.md).

# Adding Init Containers

Init containers run to completion before the main application container starts, enabling pre-flight tasks and dependency validation.

{% 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 Init Containers

Init containers execute sequentially before the main container launches. Use init containers when you need to perform one-time setup tasks that must complete before the application starts.

**Common use cases:**

* **Pre-populate volumes**: Download files, generate certificates, or prepare data that the main container requires at startup.
* **Wait for dependencies**: Block startup until external services (databases, APIs, network resources) become available.
* **Process configuration**: Transform, validate, or template configuration files before the main application consumes them.
* **Adjust permissions**: Modify file ownership or access rights on mounted volumes before the application process attempts to use them.
* **Initialize networking**: Configure routing rules, iptables entries, or service mesh sidecars (such as Istio) before application traffic begins.

## Configuration Values

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

| Value                 | Description                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `extraInitContainers` | List of init containers to run within the pod before the main Connectware container starts.                           |
| `extraVolumes`        | List of volumes attached at the pod level. Can be mounted by both the main Connectware container and init containers. |
| `extraVolumeMounts`   | Volume mounts for the main Connectware container of the pod.                                                          |

{% 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 Init Containers

To add an initialization container to a component, use the `extraInitContainers` Helm value. This Helm value accepts a [standard Kubernetes list of container definitions](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container) that will be executed before the component's main container.

{% hint style="info" %}

## Execution order of init containers

Some Connectware components (such as `authServer`) include built-in init containers. Containers defined in `extraInitContainers` always execute before built-in init containers, but before the main Connectware container starts.
{% endhint %}

### Example: Adding a Basic Init Container

The following tabs show how to configure init 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:
  extraInitContainers:
    - name: wait-for-dependency
      image: busybox:latest
      command: ['sh', '-c', "echo 'Waiting 10 seconds for dependency...'; sleep 10; echo 'Done!'"]
```

{% endcode %}
{% endtab %}

{% tab title="connectware-agent Helm Chart" %}
The `connectware-agent` Helm 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 init containers globally with `protocolMapperAgentDefaults` or per-agent with `protocolMapperAgents[]`. Per-agent values completely replace the defaults.

**Applying to all agents (default)**

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

```yaml
protocolMapperAgentDefaults:
  extraInitContainers:
    - name: wait-for-dependency
      image: busybox:latest
      command: ['sh', '-c', "echo 'Waiting 10 seconds for dependency...'; sleep 10; echo 'Done!'"]

protocolMapperAgents:
  - name: my-agent
```

{% endcode %}

**Applying to a specific agent**

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

```yaml
protocolMapperAgentDefaults:
  # ... shared defaults

protocolMapperAgents:
  - name: my-agent
    extraInitContainers:
      - name: wait-for-dependency
        image: busybox:latest
        command: ['sh', '-c', "echo 'Waiting 10 seconds for dependency...'; sleep 10; echo 'Done!'"]
```

{% endcode %}

**Deploying agents as part of the connectware Helm chart with default init containers**

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

```yaml
global:
  licenseKey: ${LICENSE_KEY}
connectwareAgent:
  protocolMapperAgentDefaults:
    extraInitContainers:
      - name: wait-for-dependency
        image: busybox:latest
        command: ['sh', '-c', "echo 'Waiting 10 seconds for dependency...'; sleep 10; echo 'Done!'"]

  protocolMapperAgents:
    - name: my-agent
```

{% endcode %}

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

{% hint style="info" %}

## Per-agent containers replace global defaults

When you set `extraInitContainers` on a specific agent in `protocolMapperAgents[]`, it completely replaces the value from `protocolMapperAgentDefaults`. This allows you to apply init containers to all agents by default, then override individual agents. Set `extraInitContainers: []` on a specific agent to exclude it from default init containers.
{% endhint %}
{% endtab %}
{% endtabs %}

## Using Shared Volumes and Existing Storage

Init containers can share data with the main container through volumes, or mount existing Kubernetes resources (ConfigMaps, Secrets, PersistentVolumeClaims).

Define pod-level volumes using `extraVolumes` and mount them with `extraVolumeMounts`. Volume configuration works identically to sidecars. See [Adding Sidecars and Volumes](/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/adding-sidecars-and-volumes.md) for detailed examples.

## Verification

After applying your changes, verify that init containers execute successfully:

{% code lineNumbers="true" %}

```bash
# Check pod status and init container completion
kubectl get pods -n ${NAMESPACE}

# View init container logs
kubectl logs -n ${NAMESPACE} ${POD_NAME} -c ${INIT_CONTAINER_NAME}

# Describe the pod to see init container status and events
kubectl describe pod -n ${NAMESPACE} ${POD_NAME}
```

{% endcode %}

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

**Result**

Init containers show a `Completed` status in the pod description. The main container starts only after all init containers complete successfully. If an init container fails, the pod enters a `CrashLoopBackOff` or `Init:Error` state.


---

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