custom-assembly: add iac content (#40)

Add an example of how you could manage Chainguard Containers
declaratively.

Author: ribbybibby

custom-assembly/iac/README.md

@@ -0,0 +1,68 @@
+# Custom Assembly: Infrastructure as Code Example
+
+This is an example of how you could manage Custom Assembly images
+declaratively with an IaC/GitOps approach.
+
+## How it Works
+
+Each YAML file under [`images/`](images/) represents a Chainguard image
+repository with the naming convention `images/{name}.yaml`.
+
+This example does not recommend a specific CI/CD solution. Instead it provides
+generic scripts that could be ran in response to GitHub repository events in
+any given workflow engine.
+
+### Pre Submit
+
+The `presubmit.sh` script is designed to run as part of the checks on a Pull
+Request. It validates that the yaml files are valid.
+
+It performs the following checks.
+
+1. Ensures that the image described by the file exists and is enabled for
+   Custom Assembly.
+2. Validates that each package described by the configuration exists in the
+   private APK repository that Custom Assembly uses.
+
+### Post Submit
+
+The `postsubmit.sh` script is designed to run when changes are merged to the
+`main` branch. It applies each of the yaml files with `chainctl image repo build
+apply`.
+
+## Usage
+
+### IAM
+
+Before running the scripts, you must login to Chainguard with `chainctl auth
+login`.
+
+You must be an `owner` in the organization. Or, you can construct a [custom
+role](https://edu.chainguard.dev/chainguard/administration/iam-organizations/roles-role-bindings/roles-role-bindings/)
+with the `repo.update` permission.
+
+For your automation, create an [Assumable
+Identity](https://edu.chainguard.dev/chainguard/administration/assumable-ids/assumable-ids/)
+to run the scripts with. The kind of identity will depend on the platform your
+pipelines are hosted in.
+
+### Checking Available Packages
+
+Not all packages are available via Custom Assembly. Before adding a package to
+an image, you can check if it's available by querying the index of the private
+APK repository used by Custom Assembly.
+
+You must have the `apk (list)` capability in your organization to do this. This
+is provided by the `apk.pull` role or other more privileged roles like `viewer`
+or `owner`.
+
+```shell
+export ORGANIZATION=your.org
+
+curl \
+    -sSf \
+    -u "_token:$(chainctl auth token --audience apk.cgr.dev)" \
+    "https://apk.cgr.dev/${ORGANIZATION}/x86_64/APKINDEX.tar.gz" \
+    | tar -xOz APKINDEX \
+    | grep '^P:curl$'
+```

custom-assembly/iac/demo.sh

@@ -0,0 +1,59 @@
+#! env bash
+. ../../base.sh
+
+ORGANIZATION="cs-ttt-demo.dev"
+
+# Check we have the required tools installed to run the script
+cmds="
+  yq
+"
+missing_cmds=""
+for cmd in ${cmds}; do
+  if ! command -v "${cmd}" &> /dev/null; then
+    missing_cmds+="${cmd} "
+  fi
+done
+if [[ -n "${missing_cmds}" ]]; then
+  echo "Missing required commands: ${missing_cmds}" >&2
+  exit 1
+fi
+
+# Set the demo back to its initial state 
+git checkout HEAD images
+./postsubmit.sh "${ORGANIZATION}"
+
+clear
+
+banner "We have two images in the 'images/' directory. One for python, another for node."
+pe "ls -l images/"
+pe "cat images/custom-iac-demo-node.yaml"
+pe "cat images/custom-iac-demo-python.yaml"
+
+banner "Let's try adding 'curl' to our custom node image. First, let's check it exists in the private APK repo."
+pe "curl -sSf -u \"_token:\$(chainctl auth token --audience apk.cgr.dev)\" \"https://apk.cgr.dev/${ORGANIZATION}/x86_64/APKINDEX.tar.gz\" | tar -xOz APKINDEX | grep '^P:curl$'"
+
+banner "Next, let's add it to the file and run the presubmit checks."
+pe "yq -i '.contents.packages += [\"curl\"]' images/custom-iac-demo-node.yaml"
+pe "git diff images/custom-iac-demo-node.yaml"
+pe "./presubmit.sh ${ORGANIZATION}"
+
+banner "If we add an invalid package to one of the files, the presubmit check should fail."
+pe "yq -i '.contents.packages += [\"foobar\"]' images/custom-iac-demo-python.yaml"
+pe "cat images/custom-iac-demo-python.yaml"
+pe "./presubmit.sh ${ORGANIZATION}"
+pe "git checkout HEAD images/custom-iac-demo-python.yaml"
+
+banner "We'll also get an error if the repo doesn't exist."
+pe "cp images/custom-iac-demo-python.yaml images/custom-iac-demo-foobar.yaml"
+pe "ls -l images/"
+pe "./presubmit.sh ${ORGANIZATION}"
+pe "rm images/custom-iac-demo-foobar.yaml"
+
+banner "Check that the presubmit checks are still passing."
+pe "./presubmit.sh ${ORGANIZATION}"
+
+banner "Now we can apply the changes."
+pe "./postsubmit.sh ${ORGANIZATION}"
+
+banner "Running the postsubmit again should be a no-op."
+pe "./postsubmit.sh ${ORGANIZATION}"

custom-assembly/iac/images/custom-iac-demo-node.yaml

@@ -0,0 +1,2 @@
+contents:
+  packages: []

custom-assembly/iac/images/custom-iac-demo-python.yaml

@@ -0,0 +1,4 @@
+contents:
+  packages:
+    - mariadb-connector-c
+    - mariadb-connector-c-dev

custom-assembly/iac/postsubmit.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -euo pipefail
+
+org_name="${1:?Must provide organization name as the first argument.}"
+
+tmp_dir=$(mktemp -d)
+trap "rm -rf ${tmp_dir}" EXIT
+
+# Apply each yaml file
+while read -r f; do
+  repo="${f#images/}"
+  repo="${repo%.yaml}"
+  repo="${repo%.yml}"
+
+  echo "${f}: applying..." 2>/dev/null  
+  chainctl image repo build apply --yes \
+    --parent="${org_name}" \
+    --repo="${repo}" \
+    -f "${f}"
+done < <(find images -type f -name '*.yaml' -o -name '*.yml')

custom-assembly/iac/presubmit.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+set -euo pipefail
+
+org_name="${1:?Must provide organization name as the first argument.}"
+
+tmp_dir=$(mktemp -d)
+trap "rm -rf ${tmp_dir}" EXIT
+
+# Download the APKINDEX for the private repository. We use this to check if
+# packages in the yaml files exist in the private APK repository.
+apk_repo="https://apk.cgr.dev/${org_name}"
+apk_token=$(chainctl auth token --audience apk.cgr.dev)
+apk_index="${tmp_dir}/APKINDEX"
+for arch in x86_64 amd64; do
+  echo "${apk_repo}: downloading the APKINDEX for ${arch}" >&2
+  curl \
+    -sSf \
+    -u "_token:${apk_token}" \
+    "${apk_repo}/${arch}/APKINDEX.tar.gz" \
+    2>/dev/null \
+    | tar -xOz \
+    >> "${apk_index}"
+done
+
+# Validate each yaml file
+while read -r f; do
+  repo="${f#images/}"
+  repo="${repo%.yaml}"
+  repo="${repo%.yml}"
+
+  # Ensure the repository is configured for custom assembly
+  echo "${repo}: checking the repository is enabled for custom assembly." >&2
+  chainctl image repo list --parent=${org_name} -o json \
+    | jq --arg repo "${repo}" -e \
+      '.items[] | select(.name == $repo) | .sync_config.apkoOverlay != null' \
+      >/dev/null \
+      || (echo "${repo}: ERROR: not a custom assembly enabled repository" >&2; exit 1)
+
+  # Check that every package defined in the yaml file exists in the private APK
+  # repository
+  echo "${repo}: validating package list" >&2
+  while read -r package; do
+    echo "${repo}: checking package '${package}' is in ${apk_repo}" >&2
+    grep -q "^P:${package}$" "${apk_index}" || (echo "${repo}: ERROR: package '${package}' not found in ${apk_repo}" >&2; exit 1)
+  done < <(yq '.contents.packages[]' "${f}")
+done < <(find images -type f -name '*.yaml' -o -name '*.yml')