Support root-level spire-lib chart reuse (#785)

* Add root-level spire-lib chart

Signed-off-by: Faisal Memon <[email protected]>

* Make spire consume root-level spire-lib

Signed-off-by: Faisal Memon <[email protected]>

* Prepare chart dependencies in CI

Signed-off-by: Faisal Memon <[email protected]>

* Document DCO requirement in CODEX

Signed-off-by: Faisal Memon <[email protected]>

* Centralize local chart dependency prep

Signed-off-by: Faisal Memon <[email protected]>

* Exclude spire-lib from chart-testing install

Signed-off-by: Faisal Memon <[email protected]>

* Rename CODEX guide to AGENTS

Signed-off-by: Faisal Memon <[email protected]>

* Add make target for chart dependencies

Signed-off-by: Faisal Memon <[email protected]>

---------

Signed-off-by: Faisal Memon <[email protected]>

.github/scripts/prepare-local-chart-deps.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT="$(readlink -f "$0")"
+SCRIPTPATH="$(dirname "${SCRIPT}")"
+REPO_ROOT="$(dirname "${SCRIPTPATH}")/.."
+
+charts=(
+  "charts/spire"
+  "charts/spire-ha-agent"
+  "charts/spire-nested"
+)
+
+for chart in "${charts[@]}"; do
+  chart_path="${REPO_ROOT}/${chart}"
+  if grep -q 'file://../spire-lib' "${chart_path}/Chart.yaml"; then
+    helm dependency update --skip-refresh "${chart_path}"
+  fi
+done

.github/workflows/helm-chart-ci.yaml

@@ -84,12 +84,20 @@ jobs:
           cache-dependency-path: tests/go.sum
           check-latest: true
 
+      - name: Set up Helm
+        uses: azure/[email protected]
+        with:
+          version: ${{ env.HELM_VERSION }}
+
       - name: Install do dependencies
         run: |
           go mod download
           go install github.com/onsi/ginkgo/v2/ginkgo@latest
         working-directory: ./tests/unit
 
+      - name: Prepare local chart dependencies
+        run: ./.github/scripts/prepare-local-chart-deps.sh
+
       - name: Run Unit Tests
         run: ginkgo
         working-directory: ./tests/unit
@@ -173,10 +181,13 @@ jobs:
         run: ./pre-install.sh
         working-directory: .github/tests
 
+      - name: Prepare local chart dependencies
+        run: ./.github/scripts/prepare-local-chart-deps.sh
+
       - name: Run chart-testing (install)
         run: |
           helm install -n spire-server spire-crds charts/spire-crds
-          ct install --config ct.yaml --excluded-charts spire-crds,spiffe-step-ssh,spire-ha-agent \
+          ct install --config ct.yaml --excluded-charts spire-crds,spiffe-step-ssh,spire-ha-agent,spire-lib \
             --target-branch ${{ github.base_ref || inputs.target_branch }}
 
       - name: Test summary
@@ -252,6 +263,9 @@ jobs:
           config: .github/kind/conf/kind-config.yaml
           verbosity: 1
 
+      - name: Prepare local chart dependencies
+        run: ./.github/scripts/prepare-local-chart-deps.sh
+
       - name: Install and test example
         run: |
           if [ "${{ matrix.example }}" = "examples/federation" -o "${{ matrix.example }}" = "examples/nested-full" -o "${{ matrix.example }}" = "examples/nested-security" ]; then
@@ -304,6 +318,9 @@ jobs:
           config: .github/kind/conf/kind-config.yaml
           verbosity: 1
 
+      - name: Prepare local chart dependencies
+        run: ./.github/scripts/prepare-local-chart-deps.sh
+
       - name: Install and test integration
         run: |
           helm install --create-namespace -n spire-mgmt spire-crds charts/spire-crds
@@ -347,5 +364,8 @@ jobs:
           config: .github/kind/conf/kind-config.yaml
           verbosity: 1
 
+      - name: Prepare local chart dependencies
+        run: ./.github/scripts/prepare-local-chart-deps.sh
+
       - name: Install and test example
         run: tests/integration/production/run-tests.sh -u

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS
+
+This file is a lightweight working guide for Codex and human contributors in this repository.
+
+## Repo Overview
+
+- Main charts live in `charts/`
+- The integrated SPIRE chart is `charts/spire`
+- Supporting charts include `charts/spire-crds`, `charts/spire-ha-agent`, `charts/spiffe-step-ssh`, and subcharts under `charts/spire/charts/`
+- Example installs and scenario configs live in `examples/`
+- Go-based unit tests live in `tests/unit`
+- Cluster-backed integration tests live in `tests/integration`
+
+## Common Commands
+
+- `make lint`
+  - Runs chart-testing lint using `ct.yaml`
+- `cd tests/unit && ginkgo`
+  - Runs Go unit/render tests for Helm templates
+- `make test`
+  - Runs chart tests and example tests against a dedicated Kubernetes cluster
+- `./helm-docs.sh`
+  - Regenerates chart README files after `Chart.yaml` or `values.yaml` changes
+
+## Working Agreements
+
+- Do not bump chart versions as part of normal contributions; maintainers handle release versioning
+- If you change `Chart.yaml` or `values.yaml`, regenerate docs with `./helm-docs.sh`
+- Prefer focused changes to a single chart or feature area per branch
+- Preserve existing Helm templating patterns and values structure unless the task requires a broader refactor
+- When possible, validate template changes with `cd tests/unit && ginkgo` before broader cluster tests
+- PR commits should include a `Signed-off-by:` trailer to satisfy the repository's DCO check
+- If DCO fails after commits are already pushed, fix it by rewriting the affected commits with signoff and force-pushing the branch
+
+## Testing Notes
+
+- `make test` assumes access to a dedicated Kubernetes cluster
+- CI also runs Kind-based install tests and example matrices from `.github/workflows/helm-chart-ci.yaml`
+- Unit tests render the `charts/spire` chart directly and assert against generated template output
+
+## Useful Paths
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `.github/workflows/helm-chart-ci.yaml`
+- `ct.yaml`
+- `charts/spire/`
+- `tests/unit/spire_test.go`
+
+## Editing Guidance
+
+- Keep generated README sections in sync by rerunning `./helm-docs.sh`
+- Avoid hardcoded image references in templates; CI checks for overridable image templating
+- Be careful with changes that affect nested charts, examples, or appVersion alignment across subcharts

Makefile

@@ -37,10 +37,15 @@ install-test-deps: ## Install test dependency resources
 	@echo Installing test dependencies…
 	@.github/tests/pre-install.sh
 
+.PHONY: chart-deps
+chart-deps: ## Prepare local Helm chart dependencies
+	@echo Preparing local chart dependencies…
+	@.github/scripts/prepare-local-chart-deps.sh
+
 .PHONY: test-charts
 test-charts: ## Run tests on charts using Helm chart-testing
 	@echo Running tests…
-	@ct install --config ct.yaml
+	@ct install --config ct.yaml --excluded-charts spire-crds,spiffe-step-ssh,spire-ha-agent,spire-lib
 
 .PHONY: cleanup-test-deps
 cleanup-test-deps: ## Cleans up all test dependencies resources

charts/spiffe-step-ssh/Chart.yaml

@@ -34,7 +34,7 @@ maintainers:
 
 dependencies:
   - name: spire-lib
-    repository: file://../spire/charts/spire-lib
+    repository: file://../spire-lib
     version: 0.1.0
   - name: step-certificates
     alias: step

charts/spire-ha-agent/Chart.lock

@@ -1,6 +1,6 @@
 dependencies:
 - name: spire-lib
-  repository: file://../spire/charts/spire-lib
+  repository: file://../spire-lib
   version: 0.1.0
-digest: sha256:e397a79d7d3b94b353f8458cb435f2cae9fd9495b367b9216958bff2771b801c
+digest: sha256:0c6454c06ba554747a20ec39b7fee1fe4632eb49ceedb8aafacbc9f0bbc84b78
-generated: "2024-11-08T00:50:47.925287061Z"
+generated: "2026-04-05T16:27:01.136911-07:00"

charts/spire-ha-agent/Chart.yaml

@@ -19,5 +19,5 @@ maintainers:
     email: [email protected]
 dependencies:
   - name: spire-lib
-    repository: file://../spire/charts/spire-lib
+    repository: file://../spire-lib
     version: 0.1.0

charts/spire-lib/Chart.yaml

@@ -0,0 +1,25 @@
+apiVersion: v2
+name: spire-lib
+description: A library of helper templates for SPIRE charts.
+type: library
+version: 0.1.0
+appVersion: "0.1.0"
+keywords: ["spiffe", "spire", "library"]
+home: https://github.com/spiffe/helm-charts-hardened/tree/main/charts/spire-lib
+sources:
+  - https://github.com/spiffe/helm-charts-hardened/tree/main/charts/spire-lib
+icon: https://spiffe.io/img/logos/spire/icon/color/spire-icon-color.png
+maintainers:
+  - name: marcofranssen
+    email: [email protected]
+    url: https://marcofranssen.nl
+  - name: kfox1111
+    email: [email protected]
+  - name: faisal-memon
+    email: [email protected]
+  - name: edwbuck
+    email: [email protected]
+annotations:
+  org.opencontainers.image.source: https://github.com/spiffe/helm-charts-hardened
+  artifacthub.io/category: security
+  artifacthub.io/license: Apache-2.0

charts/spire-nested/Chart.yaml

@@ -21,7 +21,7 @@ maintainers:
 kubeVersion: ">=1.21.0-0"
 dependencies:
   - name: spire-lib
-    repository: file://../spire/charts/spire-lib
+    repository: file://../spire-lib
     version: 0.1.0
   - name: spire-server
     alias: root-spire-server

charts/spire/Chart.lock

@@ -0,0 +1,36 @@
+dependencies:
+- name: spire-lib
+  repository: file://../spire-lib
+  version: 0.1.0
+- name: spire-server
+  repository: file://./charts/spire-server
+  version: 0.1.0
+- name: spire-agent
+  repository: file://./charts/spire-agent
+  version: 0.1.0
+- name: spire-agent
+  repository: file://./charts/spire-agent
+  version: 0.1.0
+- name: spiffe-csi-driver
+  repository: file://./charts/spiffe-csi-driver
+  version: 0.1.0
+- name: spiffe-csi-driver
+  repository: file://./charts/spiffe-csi-driver
+  version: 0.1.0
+- name: spiffe-oidc-discovery-provider
+  repository: file://./charts/spiffe-oidc-discovery-provider
+  version: 0.1.0
+- name: tornjak-frontend
+  repository: file://./charts/tornjak-frontend
+  version: 0.1.0
+- name: spike-keeper
+  repository: file://./charts/spike-keeper
+  version: 0.1.0
+- name: spike-nexus
+  repository: file://./charts/spike-nexus
+  version: 0.1.0
+- name: spike-pilot
+  repository: file://./charts/spike-pilot
+  version: 0.1.0
+digest: sha256:59ed273c48633e8a1ae07be0e1628c9f21849b865dae10195ce46d68c093b4b2
+generated: "2026-04-05T16:48:18.584331-07:00"

charts/spire/Chart.yaml

@@ -23,7 +23,7 @@ maintainers:
 kubeVersion: ">=1.21.0-0"
 dependencies:
   - name: spire-lib
-    repository: file://./charts/spire-lib
+    repository: file://../spire-lib
     version: 0.1.0
   - name: spire-server
     condition: spire-server.enabled

charts/spire/charts/spire-lib/Chart.yaml

@@ -1,24 +0,0 @@
-apiVersion: v2
-name: spire-lib
-description: A Helm chart for Kubernetes
-
-# A chart can be either an 'application' or a 'library' chart.
-#
-# Application charts are a collection of templates that can be packaged into versioned archives
-# to be deployed.
-#
-# Library charts provide useful utilities or functions for the chart developer. They're included as
-# a dependency of application charts to inject those utilities and functions into the rendering
-# pipeline. Library charts do not define any templates and therefore cannot be deployed.
-type: library
-
-# This is the chart version. This version number should be incremented each time you make changes
-# to the chart and its templates, including the app version.
-# Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.1.0
-
-# This is the version number of the application being deployed. This version number should be
-# incremented each time you make changes to the application. Versions are not expected to
-# follow Semantic Versioning. They should reflect the version the application is using.
-# It is recommended to use it with quotes.
-appVersion: ""

examples/external-mysql/run-tests.sh

@@ -12,6 +12,8 @@ source "${SCRIPTPATH}/../../.github/scripts/parse-versions.sh"
 # shellcheck source=/dev/null
 source "${TESTDIR}/common.sh"
 
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
+
 CLEANUP=1
 
 for i in "$@"; do

examples/external-postgresql/run-tests.sh

@@ -12,6 +12,8 @@ source "${SCRIPTPATH}/../../.github/scripts/parse-versions.sh"
 # shellcheck source=/dev/null
 source "${TESTDIR}/common.sh"
 
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
+
 CLEANUP=1
 
 for i in "$@"; do

examples/federation/run-tests.sh

@@ -11,6 +11,8 @@ source "${SCRIPTPATH}/../../.github/scripts/parse-versions.sh"
 # shellcheck source=/dev/null
 source "${TESTDIR}/common.sh"
 
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
+
 CLEANUP=1
 
 for i in "$@"; do

examples/nested-full/run-tests.sh

@@ -45,8 +45,7 @@ teardown() {
 
 trap 'EC=$? && trap - SIGTERM && teardown $EC' SIGINT SIGTERM EXIT
 
-# Update deps
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
-helm dep up charts/spire-nested
 
 # List nodes
 kubectl get nodes
@@ -136,4 +135,3 @@ helm test --namespace spire-mgmt spire
 
 helm test --kubeconfig "${SCRIPTPATH}/kubeconfig-child" --namespace spire-mgmt spire
 helm test --kubeconfig "${SCRIPTPATH}/kubeconfig-other" --namespace spire-mgmt spire
-

examples/nested-security/run-tests.sh

@@ -45,8 +45,7 @@ teardown() {
 
 trap 'EC=$? && trap - SIGTERM && teardown $EC' SIGINT SIGTERM EXIT
 
-# Update deps
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
-helm dep up charts/spire-nested
 
 # List nodes
 kubectl get nodes
@@ -124,4 +123,3 @@ fi
 helm test --namespace spire-mgmt spire
 
 helm test --kubeconfig "${SCRIPTPATH}/kubeconfig-child" --namespace spire-mgmt spire
-

examples/stateless-server/run-tests.sh

@@ -12,6 +12,8 @@ source "${SCRIPTPATH}/../../.github/scripts/parse-versions.sh"
 # shellcheck source=/dev/null
 source "${TESTDIR}/common.sh"
 
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
+
 CLEANUP=1
 
 for i in "$@"; do

examples/tornjak/run-tests.sh

@@ -9,6 +9,8 @@ TESTDIR="${SCRIPTPATH}/../../.github/tests"
 # shellcheck source=/dev/null
 source "${TESTDIR}/common.sh"
 
+"${SCRIPTPATH}/../../.github/scripts/prepare-local-chart-deps.sh"
+
 helm_install=(helm upgrade --install --create-namespace)
 ns=spire-system
 

tests/integration/production/run-tests.sh

@@ -15,6 +15,8 @@ source "${SCRIPTPATH}/../../../.github/scripts/parse-versions.sh"
 # shellcheck source=/dev/null
 source "${TESTDIR}/common.sh"
 
+"${SCRIPTPATH}/../../../.github/scripts/prepare-local-chart-deps.sh"
+
 helm_install=(helm upgrade --install --create-namespace)
 ns=spire-server
 

tests/integration/spiffe-step-ssh/run-tests.sh

@@ -80,8 +80,7 @@ sudo -u spiffe-test chmod 600 /home/spiffe-test/.ssh/id_ed25519
 sudo -u spiffe-test cp /home/spiffe-test/.ssh/id_ed25519.pub /home/spiffe-test/.ssh/authorized_keys
 sudo -u spiffe-test ssh -T -n -i /home/spiffe-test/.ssh/id_ed25519 [email protected] hostname || echo Expected fail here
 
-# Update deps
+"${SCRIPTPATH}/../../../.github/scripts/prepare-local-chart-deps.sh"
-helm dep up charts/spire-nested
 
 # List nodes
 kubectl get nodes