> 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/registries-and-pull-secrets.md). # Configuring Registries and Pull Secrets By default, Cybus Helm charts pull container images from the official Cybus container registry at `registry.cybus.io`. This guide explains how to configure image registries and Kubernetes pull secrets, including using a custom or mirrored registry and managing authentication. ## Default Pull Secret Behavior When you provide your Connectware license key as a literal value in your `values.yaml` file, the chart automatically creates a Kubernetes Secret named `${RELEASE_NAME}-image-registry`. This Secret authenticates with `registry.cybus.io` using your license key as the password and is automatically attached to all Pods. {% tabs %} {% tab title="connectware Helm Chart" %} The default pull secret is created only when a literal license key is set in `global.licenseKey`. {% code title="values.yaml" lineNumbers="true" %} ```yaml global: licenseKey: ${LICENSE_KEY} ``` {% endcode %} {% hint style="info" %} If you reference an existing Kubernetes Secret via `global.existingLicenseKeySecret` instead, no pull secret is created automatically. In this case, you must provide your own pull secret and reference it via `global.image.pullSecrets`. {% endhint %} The following example uses an existing Secret for the license key. No pull secret is created automatically, so you must create and reference one manually. 1. To authenticate with `registry.cybus.io`, use `license` as the username and your license key as the password: {% code lineNumbers="true" %} ```bash kubectl create secret docker-registry my-registry-pull-secret \ --docker-server=registry.cybus.io \ --docker-username=license \ --docker-password=${LICENSE_KEY} \ --namespace=${NAMESPACE} ``` {% endcode %} * `${LICENSE_KEY}` — your Connectware license key. * `${NAMESPACE}` — the namespace of your Helm release. 2. Reference the Secret in your `values.yaml`: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: existingLicenseKeySecret: my-license-secret # must contain key "licenseKey" image: pullSecrets: - name: my-registry-pull-secret ``` {% endcode %} {% endtab %} {% tab title="connectware-agent Helm Chart" %} The default pull secret is created only when a literal license key is provided in `licenseKey` and the chart is installed as a standalone release. {% hint style="info" %} The `licenseKey` value is used **only** to create the pull secret. Agents validate the license by connecting to Connectware at runtime, not via the key itself. If you provide the required pull secret manually via `image.pullSecrets`, you can leave `licenseKey` empty. {% endhint %} {% code title="values.yaml" lineNumbers="true" %} ```yaml licenseKey: ${LICENSE_KEY} ``` {% endcode %} {% hint style="info" %} When the `connectware-agent` Helm chart is installed as a subchart of the `connectware` Helm chart, the pull secret is provided by the parent chart instead. If you install `connectware-agent` separately but in the same namespace as a standalone Connectware installation, you can reuse the pull secret Connectware created without setting `licenseKey`. For details, see [Installing Connectware Agents Using the connectware-agent Helm Chart](/2-4-1/documentation/agents/agents-in-kubernetes/installing-connectware-agents-using-the-connectware-agent-helm-chart.md#method-4-reuse-the-connectware-pull-secret). {% endhint %} {% endtab %} {% endtabs %} ## Using a Custom Registry Cybus Helm charts support pulling images from a custom or mirrored registry instead of the official Cybus container registry at `registry.cybus.io`. Use this when your cluster cannot reach `registry.cybus.io` directly, or when your organization requires images to be sourced from an internal registry. {% hint style="warning" %} When using a custom registry, you must mirror the required images to that registry and provide authentication credentials. For more information, see [Configuring Pull Secrets](#configuring-pull-secrets) below. {% endhint %} {% tabs %} {% tab title="connectware Helm Chart" %} Set `global.image.registry` to your registry URL. The following example applies it to all Connectware images: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: image: registry: 'my-registry.company.tld/cybus' # replaces registry.cybus.io/cybus for all images ``` {% endcode %} The following example combines a custom registry with an explicit pull secret: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: licenseKey: ${LICENSE_KEY} image: registry: 'my-registry.company.tld/cybus' pullSecrets: - name: my-custom-registry-secret ``` {% endcode %} To override the registry for a single component, set `image.registry` under that component's configuration section. A component-level value takes precedence over `global.image.registry`. The following example sets a registry only for the `authServer` component: {% hint style="info" %} The registry override applies only to the `authServer` component. All other components use the default registry. {% endhint %} {% code title="values.yaml" lineNumbers="true" %} ```yaml authServer: image: registry: 'my-registry.company.tld/cybus' ``` {% endcode %} {% hint style="info" %} Pull secrets are merged: the default pull secret (if created from `licenseKey`), `global.image.pullSecrets`, are all combined. All unique Secrets are attached to all Pods. {% endhint %} {% endtab %} {% tab title="connectware-agent Helm Chart" %} Set `image.registry` in `protocolMapperAgentDefaults` to apply the registry to all agents, or override it per agent inside `protocolMapperAgents`. The following example sets a custom registry for all agents: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: image: registry: 'my-registry.company.tld/cybus' # replaces registry.cybus.io/cybus for all agents protocolMapperAgents: - name: bender-robots - name: welder-robots ``` {% endcode %} The following example overrides the registry for a specific agent only: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: # ... shared defaults protocolMapperAgents: - name: bender-robots image: registry: 'my-registry.company.tld/cybus' ``` {% endcode %} {% endtab %} {% endtabs %} ## Configuring Pull Secrets If your environment requires authentication to pull images from a custom registry or a private mirror, create a Kubernetes Secret of type `kubernetes.io/dockerconfigjson` and reference it in your `values.yaml`. ### Creating a Pull Secret Create the Secret manually using `kubectl`: {% code lineNumbers="true" %} ```bash kubectl create secret docker-registry ${SECRET_NAME} \ --docker-server=${REGISTRY_HOST} \ --docker-username=${USERNAME} \ --docker-password=${PASSWORD} \ --docker-email=${EMAIL} \ --namespace=${NAMESPACE} ``` {% endcode %} Replace the placeholders with values for your environment: * `${SECRET_NAME}` — the name you reference in your `values.yaml` file. * `${REGISTRY_HOST}` — the hostname of your registry. * `${USERNAME}` — the username used to authenticate with the registry. * `${PASSWORD}` — the password or token used to authenticate with the registry. * `${EMAIL}` — a contact email address associated with the registry account. * `${NAMESPACE}` — the namespace of your Helm release. ### Referencing Pull Secrets {% tabs %} {% tab title="connectware Helm Chart" %} Reference pull secrets using `global.image.pullSecrets`. All Secrets in the list are attached to every Connectware Pod. The following example references a single pull secret: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: image: pullSecrets: - name: my-custom-registry-secret ``` {% endcode %} The following example references multiple pull secrets. All unique Secrets are attached to every Connectware Pod: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: image: pullSecrets: - name: my-primary-registry-secret - name: my-secondary-registry-secret ``` {% endcode %} {% endtab %} {% tab title="connectware-agent Helm Chart" %} Reference pull secrets using `image.pullSecrets` in `protocolMapperAgentDefaults` to apply to all agents, or per agent in `protocolMapperAgents`. The following example applies a pull secret to all agents: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: image: registry: 'my-registry.company.tld/cybus' pullSecrets: - name: my-registry-pull-secret protocolMapperAgents: - name: bender-robots - name: welder-robots ``` {% endcode %} The following example applies a pull secret to a specific agent only: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgents: - name: bender-robots image: registry: 'my-registry.company.tld/cybus' pullSecrets: - name: my-registry-pull-secret ``` {% endcode %} {% endtab %} {% endtabs %} ## Changing the Image Pull Policy Cybus Helm charts expose an `image.pullPolicy` setting that controls when Kubernetes pulls container images. Valid values are: * `Always` — Pull the image on every Pod start. * `IfNotPresent` — Pull only if the image is not already present on the node. * `Never` — Never pull the image. The image must already be present on the node. {% tabs %} {% tab title="connectware Helm Chart" %} Set `global.image.pullPolicy` to apply a pull policy to all Connectware components. To override it for a specific component, set the same value under that component's configuration section. The following example sets the pull policy globally for all components: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: image: pullPolicy: Always ``` {% endcode %} The following example overrides the pull policy for a specific component only: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: image: pullPolicy: IfNotPresent authServer: image: pullPolicy: Always ``` {% endcode %} {% endtab %} {% tab title="connectware-agent Helm Chart" %} Set `image.pullPolicy` in `protocolMapperAgentDefaults` to apply a pull policy to all agents. To override it for a specific agent, set the same value inside the relevant entry in `protocolMapperAgents`. The following example sets the pull policy for all agents: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: image: pullPolicy: Always ``` {% endcode %} The following example overrides the pull policy for a specific agent only: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: image: pullPolicy: IfNotPresent protocolMapperAgents: - name: bender-robots - name: welder-robots image: pullPolicy: Always ``` {% endcode %} {% endtab %} {% endtabs %} --- # 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/registries-and-pull-secrets.md?ask=&goal= ``` `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.