pyrra-fips

packaged by Chainguard

Chainguard Container for pyrra-fips

FIPS-enabled minimalist image for Pyrra, which turns ServiceLevelObjective definitions into Prometheus recording rules and multi-window multi-burn-rate alerts and serves an SLO dashboard

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/pyrra-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Chainguard's pyrra-fips image is comparable to the upstream Pyrra image and is designed to be a drop-in replacement for it. The binary is installed at /usr/bin/pyrra, which is the same path the upstream image uses as its entrypoint, so existing arguments and Kubernetes manifests work unchanged.

The image contains only the pyrra binary and its runtime dependencies. It has no shell and no package manager, so commands must be passed to the entrypoint rather than wrapped in sh -c.

Apart from its crypto backend, described below, this variant is identical to cgr.dev/ORGANIZATION/pyrra: flags, paths, and the Helm chart wiring are unchanged.

FIPS Support

The pyrra-fips image routes cryptography through the FIPS-validated OpenSSL FIPS provider rather than Go's own implementations. The binary is compiled with a Go toolchain that delegates to that provider, and the image ships openssl-config-fipshardened, which configures OpenSSL to permit only approved algorithms. Refer to Chainguard's FIPS documentation for how these images are built and validated.

Because the restriction is enforced by OpenSSL rather than by pyrra, any non-approved algorithm fails at the point of use rather than being silently downgraded.

Prerequisites

Pyrra reads metrics from Prometheus, so a reachable Prometheus instance is required for the api and filesystem modes. The kubernetes mode additionally needs access to a Kubernetes API server and the ServiceLevelObjective custom resource definition, which the Helm chart installs.

Getting Started

Pyrra has four subcommands: api serves the web UI and API, filesystem and kubernetes are the two backends that turn objectives into Prometheus rules, and generate performs a one-shot conversion.

The generate subcommand needs no cluster and is the quickest way to see the image do real work. Create an objective:

mkdir -p slo rules
cat > slo/prometheus-api.yaml <<EOF
apiVersion: pyrra.dev/v1alpha1
kind: ServiceLevelObjective
metadata:
  name: prometheus-api-errors
  namespace: monitoring
spec:
  target: "99"
  window: 4w
  indicator:
    ratio:
      errors:
        metric: prometheus_http_requests_total{handler=~"/api.*",code=~"5.."}
      total:
        metric: prometheus_http_requests_total{handler=~"/api.*"}
EOF

Convert it into Prometheus recording rules and alerts:

docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" cgr.dev/ORGANIZATION/pyrra-fips:latest \
  generate --config-files='/work/slo/*.yaml' --prometheus-folder=/work/rules

The generated file contains the recording rules for every burn-rate window, an SLOMetricAbsent alert, and one ErrorBudgetBurn alert per window pair:

grep -E "record:|alert:" rules/prometheus-api.yaml

    record: prometheus_http_requests:increase4w
  - alert: SLOMetricAbsent
    record: prometheus_http_requests:burnrate5m
    record: prometheus_http_requests:burnrate30m
    record: prometheus_http_requests:burnrate1h
    record: prometheus_http_requests:burnrate2h
    record: prometheus_http_requests:burnrate6h
    record: prometheus_http_requests:burnrate1d
    record: prometheus_http_requests:burnrate4d
  - alert: ErrorBudgetBurn
  - alert: ErrorBudgetBurn
  - alert: ErrorBudgetBurn
  - alert: ErrorBudgetBurn

The web UI is served by the api subcommand, which does not read objectives itself: it fetches them from a backend on --api-url (default http://localhost:9444), served by either filesystem or kubernetes. Run the pair on one network so the UI has a backend to talk to:

docker network create pyrra-demo

docker run -d --name pyrra-backend --network pyrra-demo \
  -v "$PWD/slo:/etc/pyrra" -v "$PWD/rules:/rules" \
  cgr.dev/ORGANIZATION/pyrra-fips:latest \
  filesystem --prometheus-folder=/rules \
  --prometheus-url=http://prometheus.example.com:9090

filesystem writes a rule file per objective as well as serving them, and --prometheus-folder defaults to /etc/prometheus/pyrra/, which the image does not create. Point it at a writable directory, or the backend logs a write error for every objective it loads.

docker run -d --name pyrra-ui --network pyrra-demo -p 9099:9099 \
  cgr.dev/ORGANIZATION/pyrra-fips:latest \
  api --api-url=http://pyrra-backend:9444 \
  --prometheus-url=http://prometheus.example.com:9090

The UI is then available on port 9099, listing the objectives from slo/. Availability and error-budget figures are read from Prometheus, so point both --prometheus-url flags at an instance that scrapes the metrics your objectives name.

To exercise the FIPS provider, serve the UI over TLS. The api subcommand takes a certificate and key, and the handshake it then performs runs through the validated module:

openssl req -x509 -newkey rsa:4096 -sha256 -days 1 -nodes \
  -keyout tls.key -out tls.crt -subj "/CN=localhost"

docker run -d --name pyrra-ui-tls --network pyrra-demo -p 9443:9099 \
  -v "$PWD:/tls" cgr.dev/ORGANIZATION/pyrra-fips:latest \
  api --api-url=http://pyrra-backend:9444 \
  --tls-cert-file=/tls/tls.crt --tls-private-key-file=/tls/tls.key

Confirm the negotiated connection, which fails if the provider rejects the cipher suite:

curl -sSf --insecure https://localhost:9443/ -o /dev/null -w '%{http_code}\n'

200

Configuration

Pyrra is configured through command-line flags. Objectives themselves are read from YAML, via --config-files on the filesystem and generate subcommands or from ServiceLevelObjective resources in the kubernetes subcommand; a few flags also accept an environment variable, such as DISABLE_WEBHOOKS for kubernetes --disable-webhooks. Each subcommand has its own flags, which --help lists:

docker run --rm cgr.dev/ORGANIZATION/pyrra-fips:latest kubernetes --help

For a Kubernetes deployment, the upstream Helm chart runs the kubernetes and api subcommands as two containers in one pod. Point the chart at this image with a values file:

cat > values.yaml <<EOF
image:
  repository: cgr.dev/ORGANIZATION/pyrra-fips
  tag: latest
prometheusUrl: http://prometheus.observability.svc.cluster.local:9090
extraKubernetesArgs:
  - --config-map-mode=true
EOF

The chart already defaults prometheusUrl to a prometheus-operated service in the monitoring namespace, so it only needs setting when Prometheus lives elsewhere; the address above is an example, and pyrra reports no availability figures until it points at a Prometheus that is actually reachable and scraping the metrics your objectives name. extraKubernetesArgs is shown here switching the operator to ConfigMap output, which is what to use when the Prometheus Operator custom resource definitions are not installed.

Install the chart with that file:

helm repo add pyrra https://pyrra-dev.github.io/helm-charts
helm install pyrra pyrra/pyrra --values values.yaml

The kubernetes backend writes PrometheusRule objects by default, which requires the Prometheus Operator custom resource definitions to be present in the cluster. Pass --config-map-mode=true through the chart's extraKubernetesArgs to have it write ConfigMaps instead.

The image runs as UID 65533 by default, matching upstream. The chart sets runAsNonRoot and a read-only root filesystem, both of which this image supports without further configuration.

Documentation and Resources

• Pyrra documentation covers the objective format and each backend in detail.
• Pyrra Helm charts documents every chart value.
• Chainguard Academy has guides on working with Chainguard Containers.

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.