Add getting-started guide for Spark FIPS container

[matthewhelmke]

Summary

• Adds content/chainguard/chainguard-images/getting-started/spark-fips.md, a new getting-started guide for the Chainguard Spark FIPS container
• Covers BCFKS keystore generation, local Docker validation with SparkPi, and Kubernetes cluster-mode deployment using the Spark Operator FIPS container
• All commands verified end-to-end on Linux with Docker 29.5, kind v0.31, Helm v3.16, kubectl v1.31, and cgr.dev/chainguard-private/spark-fips:latest (Spark 4.1.2, Java 21, Bouncy Castle FIPS)

Closes chainguard-dev/internal#5596.

Test plan

Prerequisites: Docker with chainctl auth configure-docker, plus kubectl, helm, and kind for Example 2.

Example 1 — Local Docker

1. Export KEY_PASSWORD and TRUSTSTORE_PASSWORD in your shell
2. Run the keystore generation block; confirm three .bcfks files appear in spark-ssl/
3. Run the verification block; confirm output lists spark-server as PrivateKeyEntry
4. Run the spark-submit block; confirm Pi is roughly 3.14... appears in stdout

Example 2 — Kubernetes with Spark Operator

1. kind create cluster --name spark-fips-test — cluster comes up
2. kind load docker-image for both images — no errors
3. Namespace/RBAC commands — all resources created
4. kubectl create secret generic spark-ssl-stores — secret created (requires spark-ssl/ from Example 1)
5. helm install spark-operator ... — STATUS: deployed
6. kubectl wait deployment/spark-operator-controller ... — condition met
7. kubectl apply -f spark-pi-fips.yaml (substitute $KEY_PASSWORD and $TRUSTSTORE_PASSWORD with the values used in Example 1) — SparkApplication created
8. kubectl get pods --namespace spark-jobs --watch — driver pod reaches Completed
9. kubectl logs ... | grep "Pi is" — Pi estimate appears in output
10. kubectl logs ... | grep "JDK_JAVA_OPTIONS" — confirms -Dorg.bouncycastle.fips.approved_only=true is present
11. Clean up: kubectl delete -f spark-pi-fips.yaml and kind delete cluster

Bugs found in reference repositories

These bugs are in SE reference repos, not in official image documentation. They need attention from the SE or images teams before those repos are shared with customers.

chainguard-dev/ynad — spark-fips-bcfks/README.md

1. Typo in --properties-file path: the README ends with --properties-file /var/run/spark-sslspark-defaults.conf (missing slash). Should be /var/run/spark-ssl/spark-defaults.conf.

2. Inconsistent keystore paths: the "Spark SSL configuration" section shows paths under /usr/lib/spark/conf/, which the same README's "K8s Cluster Mode Consideration" section correctly explains are overwritten at pod startup. The first section should use the mount-safe path or be scoped to local/non-Kubernetes use.

ericbannon/cg-spark-operator-fips — README.md

3. Missing -f flag: kubectl apply spark_props_configmap.yaml errors without -f. Should be kubectl apply -f spark_props_configmap.yaml.

4. Dev-only values.yaml without a warning: pullPolicy: Never and tag 2.2.1-dev only work with images pre-loaded into a local Docker Desktop node. Any other cluster produces ImagePullBackOff. Needs a prominent callout.

5. Operator installed in job namespace: helm install ... -n dist-test puts the operator in the same namespace as the jobs. The Kubeflow Spark Operator design assumes the operator runs in its own namespace and watches separate job namespaces via spark.jobNamespaces.

ericbannon/cg-spark-operator-fips — spark_props_configmap.yaml

6. Duplicate property keys: spark.driver.extraJavaOptions and spark.executor.extraJavaOptions are each defined twice. The second definition silently overrides the first. The first definitions (setting only -Dorg.bouncycastle.fips.approved_only=true) are dead code.

---

Created in collaboration with Claude Code running claude-sonnet-4-6[1m] on 2026-06-04.

[netlify]

✅ Deploy Preview for ornate-narwhal-088216 ready!

Name	Link
🔨 Latest commit	fb8d466
🔍 Latest deploy log	https://app.netlify.com/projects/ornate-narwhal-088216/deploys/6a21784bdc5245000886b1e9
😎 Deploy Preview	https://deploy-preview-3384--ornate-narwhal-088216.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[matthewhelmke]

I'm tagging these people to request they take a look at this:

• @ericbannon since you filed the original issue / request (THANK YOU!!) and because there were problems in what I found in your source materials, noted above, so you will want to know if you are sharing with customers, and to verify the Kubernetes deployment approach
• @xnox or your designated representative, because you know FIPS better than anyone here and can catch any errors more quickly and accurately than anyone, and to verify the BCFKS configuration and FIPS mode enforcement

[xnox]

nice!