From 94755103c5061c446e0ea83aa6173711766b661c Mon Sep 17 00:00:00 2001 From: Pranay Sanghvi Date: Mon, 23 Feb 2026 19:41:13 +0530 Subject: [PATCH] Add Pack integration how-to for staging Add a new how-to describing how to use the Pack (CNB) CLI as an alternative staging path. Documents Helm values (server.stagingUsePack, server.pack.image, server.stagingWorkloads.dockerSocketPath), container runtime options (host Docker socket or DinD), security considerations, rollback steps, and links to relevant Pack and Epinio customization docs. --- docs/howtos/customization/pack-integration.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/howtos/customization/pack-integration.md diff --git a/docs/howtos/customization/pack-integration.md b/docs/howtos/customization/pack-integration.md new file mode 100644 index 0000000000..62315a9393 --- /dev/null +++ b/docs/howtos/customization/pack-integration.md @@ -0,0 +1,67 @@ +--- +sidebar_label: "Pack integration for staging" +sidebar_position: 20 +title: "Pack integration for staging" +description: "Use Pack CLI as an alternative to the direct buildpack lifecycle for staging." +keywords: [epinio, kubernetes, pack, buildpacks, staging] +doc-type: [how-to] +doc-topic: [how-to, custom, pack, staging] +doc-persona: [epinio-operator] +--- + +Epinio can use [Pack](https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/) (the CNB CLI) as an alternative to the direct buildpack lifecycle for building application source. This aligns the platform with the standard buildpacks tooling and consolidates the developer experience. + +## Enabling Pack-based staging + +Set the following Helm values when installing or upgrading Epinio: + +```yaml +server: + stagingUsePack: true + pack: + image: buildpacksio/pack:0.36.0 # or another tag +``` + +When `stagingUsePack` is `true`: + +- The **Pack** staging script ConfigMap (`epinio-stage-scripts-pack`) is installed and used for builders matching `paketobuildpacks/builder-jammy-*:*`. +- The **lifecycle** jammy script ConfigMap (`epinio-stage-scripts-jammy`) is not installed, so those builders use Pack instead of the direct lifecycle/creator. + +The same `epinio push` flow and Stage API apply; only the build path inside the staging Job changes (Pack runs `pack build` instead of `/cnb/lifecycle/creator`). + +## Helm values + +These keys are defined in the Epinio Helm chart (`values.schema.json`) so they are discoverable and validated on install/upgrade. + +| Value | Description | Default | +|-------|-------------|--------| +| `server.stagingUsePack` | Use Pack CLI for staging when a matching builder is selected. | `false` | +| `server.pack.image` | Image containing the Pack CLI (e.g. `buildpacksio/pack`). | `buildpacksio/pack:0.36.0` | +| `server.stagingWorkloads.dockerSocketPath` | Optional. Host path to the Docker socket (e.g. `/var/run/docker.sock`) so Pack can run the builder container. Omit for daemonless or when using DinD with a different socket. | unset | + +## Container runtime (Docker socket / DinD) + +Pack runs the builder in a container. To do that inside the staging pod you must provide a container runtime: + +- **Docker socket**: mount the host's Docker socket into the build container. Set `server.stagingWorkloads.dockerSocketPath` (e.g. `/var/run/docker.sock`). The staging Job will mount that path only in the build container. +- **DinD (Docker-in-Docker)**: run a DinD sidecar and set `dockerSocketPath` to the socket path inside the pod (e.g. the path where the sidecar exposes the socket). + +If you do not set `dockerSocketPath`, Pack may still be able to push the app image with `--publish` using registry credentials at `DOCKER_CONFIG`, but running the builder container may fail unless the Pack image or environment provides another way to run containers. + +## Security considerations + +- **Docker socket**: mounting the host Docker socket gives the build container effective control of the host's Docker daemon. Use node selectors/taints and dedicated build nodes where possible, and restrict who can run staging jobs. +- **Root/DinD**: if the build runs as root or uses DinD, follow cluster hardening practices and limit exposure. + +## Rollback + +To revert to the lifecycle-based path: + +- Set `server.stagingUsePack: false` and upgrade the Helm release. The Pack ConfigMap will be removed and `epinio-stage-scripts-jammy` will be installed again for jammy builders. + +## See also + +- [Pack – Integrate CI](https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/) +- [Pack build CLI](https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_build/) +- [Customization point: Buildpacks](../references/customization/staging.md) +- [Customization point: Staging scripts](../references/customization/staging-scripts.md)