Use Custom Images and Git Repos

This guide demonstrates how to create, upload and use custom images and Git repos within Structsure. The following example shows how to manually update Confluence's image and Git repo.

caution

Structsure will respect any overriden values until removed from config. Please see documentation on removing overriden values to revert to Structsure-provided container images and Git repos.

Prerequisites

• Access to custom images and Git repos
• Kubeconfig for target cluster

Required Tools

• Zarf
• Docker (only required on system building the custom package)

Overview

In order to use new container images or Git repos, they need to be uploaded to Zarf's internal registry. The following are the steps to customize Structsure for a new Git repo or new image

1. Creating a Custom Package
2. Deploying a Custom Package
3. Customizing an App to Use a New Git Repo
4. Customizing an App to Use a New Image

Creating a Custom Package

note

You must docker login to any private registries before building the package.

The following is an example Zarf Package Config for packaging a new Git repo and container image for Confluence. More information about creating packages and example packages can be found in Zarf's official documentation.

kind: ZarfPackageConfig
metadata:
  name: custom-package
  description: Package for arbitrary container images and git repos
  version: "1.0.0"
  architecture: amd64
components:
  - name: custom
    description: "Git Repositories and images used by the Confluence add-on"
    required: true
    repos:
      - https://repo1.dso.mil/big-bang/product/community/confluence.git@1.18.1-bb.4
      # any additional repos can be added here
    images:
      - registry1.dso.mil/ironbank/atlassian/confluence-data-center/confluence-node:8.9.0
      # any additional images can be added here

Zarf expects package files to be named zarf.yaml, so please ensure to name the package file as such.

To build the package, assuming zarf.yaml is in the current directory:

1. Run the command: zarf package create.
2. When prompted: enter y to build the package.

Once Zarf has completed building the package, it will create a package file named zarf-package-custom-package-amd64-1.0.0.tar.zst. This package can be transferred to any air-gapped environment that has access to the target Kubernetes cluster for deployment.

Deploying a Custom Package

With the kubeconfig file for the target cluster, ensure you have access to the cluster and the zarf-state secret: zarf tools kubectl get secret zarf-state -n zarf.

Afterwards, you can install the package into the cluster by:

1. Run the command: zarf package deploy zarf-package-custom-package-amd64-1.0.0.tar.zst
2. When prompted: enter y to install the package

You should receive confirmation that the images have been pushed to the Zarf registry and any Git repos that have been processed.

Customizing an App to Use a New Git Repo

Structsure applications are deployed through Big Bang. There are three categories of applications within Big Bang that determine how to correctly supply the new Git repo:

• Big Bang core apps (found at the root in the bigbang values. i.e. .Values.kyverno)
• Big Bang add-on apps (found under addons in the bigbang values, i.e., .Values.addons.argocd)
• Big Bang third-party apps (found under packages in the bigbang values, i.e., .Values.packages.confluence)

To manually override the Git repo for Confluence, update the confluence-overrides config map in the structsure-system namespace and add the following content:

apiVersion: v1
data:
  values.yaml: |
    packages:
      confluence:
        git:
          repo: https://repo1.dso.mil/big-bang/product/community/confluence.git
          path: "./chart" # path to helm chart in repo; dependant on repo structsure
          tag: 1.18.1-bb.4
kind: ConfigMap
metadata:
  name: confluence-overrides
  namespace: structsure-system

Structsure will need a few minutes to process the new config and supply the config to the bigbang helm release. Afterwards, the bigbang helm release will need a few minutes to propogate the changes to the confluence Git repo. Once the bigbang helm release has finished reconciling, the changes can be verified by viewing Confluences' Git repo with the following command, zarf tools kubectl get gitrepo confluence -n confluence:

NAME          READY   STATUS
confluence    True    stored artifact for revision '1.18.1-bb.4@sha1:7245b496aeb32b9066aeea3e86d879cf0367b900'

Customizing an App to Use a New Image

Please refer to the previous section for an overview of the Big Bang values structure.

Setting a new container image is highly dependent upon the helm chart being deployed and requires review in order to set the appropriate values for the image. For the Confluence chart, the appropriate values to set are:

image:
  repository: registry1.dso.mil/ironbank/atlassian/confluence-data-center/confluence-node
  tag: "8.9.0"

To set these values in Structsure, update the confluence-overrides config map in the structsure-system namespace with the following content:

apiVersion: v1
data:
  values.yaml: |
    packages:
      confluence:
        values: # values for the chart go here
          image:
            repository: registry1.dso.mil/ironbank/atlassian/confluence-data-center/confluence-node
            tag: "8.9.0"
kind: ConfigMap
metadata:
  name: confluence-overrides
  namespace: structsure-system

Structsure will need a few minutes to process the new config and supply the config to the bigbang helm release. Afterwards, the bigbang helm release will need a few minutes to propogate the changes to the confluence helm release. Once the bigbang and confluence helm releases have finished reconciling, the changes can be verified by viewing the Confluence pods with the following command, zarf tools kubectl get pods -n confluence -o yaml:

# portions removed for brevity
apiVersion: v1
items:
- apiVersion: v1
  kind: Pod
  metadata:
    name: confluence-0
    namespace: confluence
  spec:
    containers:
    - image: 127.0.0.1:31999/ironbank/atlassian/confluence-data-center/confluence-node:8.9.0-zarf-2131014678
      name: confluence
kind: List