Software References

Software references formalize which Helm charts and container images are used by CIVITAS/CORE components. Their main purposes:

• they provide a single place to track image dependencies for tooling such as image export and vulnerability scanning
• they make image definitions reusable in Helm values templates and Ansible tasks
• they allow to build up a private registry with all images necessary to deploy CIVITAS/CORE.

General structure

Software references are stored in YAML files under a top-level software: key.

For platform core components, the central file is:

• core_platform/vars/software_references.yml

For addons, each addon keeps its own file:

• core_platform/addons/<addon_name>/vars/software_references.yml

Image definitions must follow this structure:

software:
  some_scope:
    some_component:
      registry: docker.io
      repository: example/image
      tag: "1.0.0"

The paths

• software.*.*.registry
• software.*.*.repository
• software.*.*.tag

are intentionally standardized. CIVITAS/CORE tooling relies on this pattern when collecting image references across the repository.

Helm chart metadata

When a component is deployed from a Helm chart, the same file can also hold the chart metadata:

software:
  some_scope:
    some_component:
      helm_chart_name: some-chart
      helm_release_name: some-release
      helm_repo_name: some-repo
      helm_repo_url: https://example.com/charts
      helm_chart_version: "1.0.0"
      registry: docker.io
      repository: example/image
      tag: "1.0.0"

This makes it easy to reuse the same source of truth from deployment tasks.

Using software references in values files

Software references are typically consumed from templated Helm values files.

For charts that split image fields into registry, repository, and tag, use:

image:
  registry: "{{ inv_op_stack.private_registry.registry_full_url | default(software.some_scope.some_component.registry) }}"
  repository: "{{ software.some_scope.some_component.repository }}"
  tag: "{{ software.some_scope.some_component.tag }}"

For charts that expect a single repository string including the registry, use:

image:
  repository: "{{ inv_op_stack.private_registry.registry_full_url | default(software.some_scope.some_component.registry) }}/{{ software.some_scope.some_component.repository }}"
  tag: "{{ software.some_scope.some_component.tag }}"

The exact shape depends on the upstream chart. The important part is that the image values are sourced from software.* and that the URL of the private registry is included.

Using software references in Ansible tasks

If a component is installed through the shared Helm wrapper task, chart metadata from the software references file can be passed through directly:

- name: "[Helm] Install component"
  include_tasks: tasks/templates/k8s-helm.yml
  vars:
    helm_repo_name: "{{ software.some_scope.some_component.helm_repo_name }}"
    helm_repo_url: "{{ software.some_scope.some_component.helm_repo_url }}"
    helm_chart_name: "{{ software.some_scope.some_component.helm_chart_name }}"
    helm_release_name: "{{ software.some_scope.some_component.helm_release_name }}"
    helm_chart_reference: "{{ helm_repo_name }}/{{ helm_chart_name }}"
    helm_chart_version: "{{ software.some_scope.some_component.helm_chart_version }}"
    helm_values_file: "path/to/values.yml"

Core Platform vs Addons

The same pattern is used for both platform core components and addons. The main differences are:

• the platform core keeps its software references in the shared file core_platform/vars/software_references.yml
• each addon keeps its own file in core_platform/addons/<addon_name>/vars/software_references.yml
• addon software references are merged into the overall image inventory by the platform tooling when running the Ansible playbook for deployment
• addons use a namespaced key such as software.<addon_name>.* to avoid collisions

For addon-specific guidance, including repository layout and naming conventions, see Addon Development.

Workflow for Identifying Software References

Analyze Default Values File for Helm Chart

Well-designed Helm charts allow all images to be set in the values file. A keyword search for image: typically allows to identify most images used by a Helm chart. Of course, when a component of a Helm chart is statically disabled, the images used by this component do not have to be listed in software references.

Identifying All Images Used by a Helm Chart

In order to identify if there are additional images used by the Helm chart, which are not listed in a values file, we propose the following workflow:

• Set up a private registry (e.g. Harbor)
• Add the private registry to the inventory
• Disable usage of external registries for the cluster
• Deploy the platform and observe image pulls

With this setup, any missing image results in an ImagePullBackOff error. These cases should then resolved by adding the missing image to software_references.yml. If those images cannot be referenced within the values file, a Helm chart post renderer or a deployment patch are feasible alternatives to set the image being used.

The benefit of this workflow over generating a list of used images by the current deployment is that in addition to the main application images, it also captures short-lived containers (e.g. init containers or transient jobs), which may no longer be visible after deployment, as their images still need to be pulled during the deployment process.