example42/piace repository overview

⁠PIACE

Puppet Impact Assessment & Change Explorer. Compare the catalog PuppetDB holds for a node against a catalog compiled for a candidate environment, and report exactly what a change does before it reaches an agent.

One statically linked, CGO-free binary. No Ruby, no Puppet agent, no Facter, no package manager, and no dependency resolution at run time.

⁠Supported tags

latest moves with every full release and never with a prerelease.

⁠What is in the image

gcr.io/distroless/static-debian12:nonroot plus one binary. No shell, no package manager, no git. The CA bundle is there because piace explain verifies an inference service against the system roots; the compiler and PuppetDB transports trust only the CA bundle named in your own services file.

• Entrypoint: /usr/local/bin/piace
• Working directory: /work
• User: nonroot, uid 65532

The binary is not compiled during the image build. It is the release artifact published on GitHub, byte for certifies, copied in.

⁠Usage

It runs as a non-root user our workspace there and pass your own uid. Without both, writing a report into the mount fails with a permission error.

docker run --rm \
  --user "$(id -u):$(id -g)"
  --volume "$PWD:/work" \
  example42/piace:0.2.1 \
  compare --targets targets.yaml --services services.yaml \
          --json-out report.j

The optional, advisory change assessment is a second, independent step over a stored result document. It iscontacts anything other than your compiler and PuppetDB:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --volume "$PWD:/work" \
  --env PIACE_INFERENCE_TOKEN \
  example42/piace:0.2.1 \
  explain --json-in report.json --services services-explain.yaml \
          --ai-out assessmentml

Every path inside targets.yaml and services.yaml (CA bundle, client certificate, private key, snaesolved inside the container, so keep them under the mount. TLS paths in a services file resolve against the process wnst the file itself.

⁠Exit codes

⁠This is not a CI job image

It has no shell, and its entrypoint is the binary. GitLab's docker executor runs a job script by passing e, and GitHub Actions container: jobs expect a shell too, so neither can use this image as a job image. In a pipeline, installry into whatever image your job already uses. See docs/ci.md⁠ for copy-ready GitHub Actions and GitLab CI jobs.

⁠Verifying what you pulled

docker run --rm example42/pia

The reported version comes from the -X main.toolVersion stamp the release workflow applied and assertedand again on the image before pushing it. For the binaries and their checksum manifest, see docs/release.md⁠.

⁠Links

• Source and full documentatiample42/piace>
• Running it in CI: https://github.com/example42/piace/blob/main/docs/ci.md⁠
• Release artifacts and verifhttps://github.com/example42/piace/blob/main/docs/release.md⁠
• Changelog: https://github.ain/CHANGELOG.md⁠