Configuring Registries and Pull Secrets

Configure image registries and pull secrets for the connectware and connectware-agent Helm charts.

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.

The default pull secret is created only when a literal license key is set in global.licenseKey.

values.yaml

global:
  licenseKey: ${LICENSE_KEY}

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.

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.

To authenticate with registry.cybus.io, use license as the username and your license key as the password:

kubectl create secret docker-registry my-registry-pull-secret \
  --docker-server=registry.cybus.io \
  --docker-username=license \
  --docker-password=${LICENSE_KEY} \
  --namespace=${NAMESPACE}

${LICENSE_KEY} — your Connectware license key.
${NAMESPACE} — the namespace of your Helm release.

Reference the Secret in your values.yaml:

values.yaml

global:
  existingLicenseKeySecret: my-license-secret # must contain key "licenseKey"
  image:
    pullSecrets:
      - name: my-registry-pull-secret

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.

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.

values.yaml

licenseKey: ${LICENSE_KEY}

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.

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.

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

Set global.image.registry to your registry URL. The following example applies it to all Connectware images:

values.yaml

global:
  image:
    registry: 'my-registry.company.tld/cybus' # replaces registry.cybus.io/cybus for all images

The following example combines a custom registry with an explicit pull secret:

values.yaml

global:
  licenseKey: ${LICENSE_KEY}
  image:
    registry: 'my-registry.company.tld/cybus'
    pullSecrets:
      - name: my-custom-registry-secret

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:

The registry override applies only to the authServer component. All other components use the default registry.

values.yaml

authServer:
  image:
    registry: 'my-registry.company.tld/cybus'

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.

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:

values.yaml

protocolMapperAgentDefaults:
  image:
    registry: 'my-registry.company.tld/cybus' # replaces registry.cybus.io/cybus for all agents
protocolMapperAgents:
  - name: bender-robots
  - name: welder-robots

The following example overrides the registry for a specific agent only:

values.yaml

protocolMapperAgentDefaults:
  # ... shared defaults
protocolMapperAgents:
  - name: bender-robots
    image:
      registry: 'my-registry.company.tld/cybus'

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:

kubectl create secret docker-registry ${SECRET_NAME} \
  --docker-server=${REGISTRY_HOST} \
  --docker-username=${USERNAME} \
  --docker-password=${PASSWORD} \
  --docker-email=${EMAIL} \
  --namespace=${NAMESPACE}

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

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:

values.yaml

global:
  image:
    pullSecrets:
      - name: my-custom-registry-secret

The following example references multiple pull secrets. All unique Secrets are attached to every Connectware Pod:

values.yaml

global:
  image:
    pullSecrets:
      - name: my-primary-registry-secret
      - name: my-secondary-registry-secret

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:

values.yaml

protocolMapperAgentDefaults:
  image:
    registry: 'my-registry.company.tld/cybus'
    pullSecrets:
      - name: my-registry-pull-secret
protocolMapperAgents:
  - name: bender-robots
  - name: welder-robots

The following example applies a pull secret to a specific agent only:

values.yaml

protocolMapperAgents:
  - name: bender-robots
    image:
      registry: 'my-registry.company.tld/cybus'
      pullSecrets:
        - name: my-registry-pull-secret

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.

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:

values.yaml

global:
  image:
    pullPolicy: Always

The following example overrides the pull policy for a specific component only:

values.yaml

global:
  image:
    pullPolicy: IfNotPresent
authServer:
  image:
    pullPolicy: Always

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:

values.yaml

protocolMapperAgentDefaults:
  image:
    pullPolicy: Always

The following example overrides the pull policy for a specific agent only:

values.yaml

protocolMapperAgentDefaults:
  image:
    pullPolicy: IfNotPresent
protocolMapperAgents:
  - name: bender-robots
  - name: welder-robots
    image:
      pullPolicy: Always

PreviousWorking with Cybus Helm Charts NextOverriding Security Contexts

Last updated 4 days ago

Was this helpful?