Using Big Bang with Zarf

This tutorial describes how to use Big Bang with Zarf for Air Gap deployments through the use of the Big Bang Zarf extension. If you are not familiar with Big Bang you can learn more about it here: https://p1.dso.mil/products/big-bang, but in short it is a DevSecOps platform that contains many useful tools for building, managing, and running software projects while adhering to the United States Department of Defense DevSecOps Reference Design.

Zarf integrates with Big Bang through the use of an extension that simplifies the selection of Big Bang packages and the pulling of the required artifacts to deploy those packages in an Air Gap.

The current version of this extension requires Big Bang version 1.54.0 or later, and is not fully integrated into the zarf package remove lifecycle (see the Big Bang example for how to introduce those lifecycle hooks manually). Zarf also relies on helm.sh/images annotations to discover images within charts (e.g. GitLab) - this is a relatively new feature for Big Bang so if you see an ImagePullBackOff error, check that these annotations are set correctly for the sub charts you are using. To work around this issue if you come across it, simply add the missing image to the images list on the same component that contains the Big Bang extension like the following:

components:
  - name: bigbang
    required: true
    images:
      - registry1.dso.mil/ironbank/gitlab/gitlab/gitlab-exporter:15.9.2
    extensions:
      bigbang:
        version: 1.54.0

Big Bang requires a reasonably powerful amd64 system that scales up with the number of components deployed. We recommend at least 32 GB of RAM and a high-speed internet connection to complete this tutorial.

To learn more about Big Bang’s requirements in general, see their documentation: https://docs-bigbang.dso.mil/latest/docs/prerequisites/minimum-hardware-requirements/

Before beginning this tutorial you will need the following:

A local copy of the Zarf repository
- git clone https://github.com/defenseunicorns/zarf.git
A kubernetes cluster onto which you can deploy Zarf and Big Bang
The latest version of the Zarf cli
- Follow instructions on https://docs.zarf.dev/getting-started/install/
An account on https://registry1.dso.mil to retrieve Big Bang images
- You can register for an account here

If you followed the Setting Up a Local Kubernetes Cluster instructions for other Zarf tutorials, you will need to pass additional command flags to k3d for it to work with Big Bang. See the below to create a working cluster:

k3d cluster create
  # Required by the PLG stack
  --volume /etc/machine-id:/etc/machine-id

  # Required for Istio ingress
  --k3s-arg "--disable=traefik@server:0"
  --port 80:80@loadbalancer
  --port 443:443@loadbalancer

  # Required for TLS to work correctly with kubectl
  --k3s-arg "--tls-san=$SERVER_IP@server:0"
  --api-port 6443

If you tweak the packages that are deployed there may be other configuration options you need to specify, please refer to the Big Bang documentation for more details.

The below section covers creating and tuning the Big Bang package:

By default, Big Bang uses images from Iron Bank which will require you to set your login credentials for Registry One (see pre-requisites for information on account setup).

# Authenticate to https://registry1.dso.mil/, then retrieve your CLI secret from your User Profile and run the following:
set +o history
export REGISTRY1_USERNAME=<REPLACE_ME>
export REGISTRY1_CLI_SECRET=<REPLACE_ME>
echo $REGISTRY1_CLI_SECRET | zarf tools registry login registry1.dso.mil --username $REGISTRY1_USERNAME --password-stdin
set -o history

Now navigate to the examples/big-bang folder within the Zarf repository you cloned in the pre-requisites section.

Within the examples/big-bang folder you will see a zarf.yaml that has the following component defined:

components:
  - name: bigbang
    required: true
    extensions:
      bigbang:
        version: 1.54.0
        skipFlux: false
        valuesFiles:
          - config/minimal.yaml #turns on just istio
          - config/ingress.yaml # adds istio certs for *.bigbang.dev
          - config/kyverno.yaml # turns on kyverno
          - config/loki.yaml # turns on loki and monitoring

This component uses the bigbang extension to define the version of Big Bang to use and the values files to apply. Feel free to inspect and configure the values.yaml files as you wish and to learn more about Big Bang’s configuration see their values guide: https://docs-bigbang.dso.mil/latest/docs/guides/using-bigbang/values-guide/

When you’re ready to continue you can create a Big Bang package by running the following command in examples/big-bang:

zarf package create

Now wait for the package creation to complete and you should see a zarf-package-big-bang-example-amd64-x.x.x.tar.zst file in the directory.

The below section covers deploying the Big Bang package from the previous section:

Before you can deploy the Big Bang package you must first initialize Zarf on the cluster you created in the pre-requisites section. To do so you can run the following:

# Initialize Zarf (interactively)
zarf init
# Make these choices at the prompts
# ? Do you want to download this init package? Yes
# ? Deploy this Zarf package? Yes
# ? Deploy the k3s component? No
# ? Deploy the logging component? No
# ? Deploy the git-server component? Yes

# (Optional) Inspect the results
zarf tools k9s

Now you are ready to deploy Big Bang, and can do so with the following in the examples/big-bang directory:

# Deploy Big Bang (interactively)
zarf package deploy
# Make these choices at the prompts
# ? Choose or type the package file [tab for suggestions] zarf-package-big-bang-example-amd64-x.x.x.tar.zst
# ? Deploy this Zarf package? Yes

Once the install completes you can inspect the results and watch the Big Bang components deploy using the following:

zarf tools k9s

# To view different k8s objects you can use the following:

# Helm Releases:
# :hr [Enter]
# Pods:
# :pods [Enter]
# Services:
# :svc [Enter]
# Secrets:
# :secret [Enter]
# ConfigMaps:
# :configmap [Enter]

# When you are done use the following to quit
# :q [Enter]

The Big Bang extension is not fully integrated into the Zarf package remove lifecycle. To get around this limitation, an onRemove.before action has been added to the bigbang component in the zarf.yaml file that ensures all the Big Bang resources are torn down in the correct order when Zarf is used to remove the package:

zarf package remove big-bang-example --confirm

See the Troubleshooting section of the Big Bang Quick Start for help troubleshooting the Big Bang deployment: https://repo1.dso.mil/big-bang/bigbang/-/blob/master/docs/guides/deployment-scenarios/quickstart.md#troubleshooting

Also, ensure that you have followed all of the steps required in the pre-requisites section.

If you feel that the error you are encountering is one with Zarf feel free to open an issue or reach out via slack.