floci

Floci

Chainguard's redistribution of the Quenchworks Floci Helm chart, configured with Chainguard's Floci image. Floci emulates AWS APIs for local development and integration testing.

Prerequisites

Authenticate to your organization's registry and create a pull secret in the installation namespace:

chainctl auth login
chainctl auth configure-docker --pull-token --save
helm registry login cgr.dev
kubectl create namespace floci
kubectl create secret docker-registry cgr-pull-secret \
  --docker-server=cgr.dev \
  --docker-username="$(echo cgr.dev | docker-credential-cgr get | jq -r '.Username')" \
  --docker-password="$(echo cgr.dev | docker-credential-cgr get | jq -r '.Secret')" \
  --namespace floci

Installation

helm install floci oci://cgr.dev/ORGANIZATION/charts/floci \
  --namespace floci \
  --set 'imagePullSecrets[0].name=cgr-pull-secret'

The default deployment runs one non-root instance with a read-only root filesystem and writable temporary/data volumes. State is held in memory and lost on restart. Do not increase the replica count in this mode: independent replicas do not share emulated AWS state. Chainguard's Floci image runs on the JVM; retain the chart's JVM-sized resource defaults when evaluating resource requirements.

Use the service endpoint on port 4566 with your AWS client, dummy credentials, and an explicit region. Configure S3 clients for path-style addressing. Health checks use /_floci/health; consumers should also test the specific APIs they need.

Full mode

Both image (hardened mode) and floci.full.image (full mode) use the same regular Chainguard Floci imageLock and digest. The upstream chart's floci-full name is a values slot, not a third Chainguard image or a tag to publish. Both informational chart tags track the regular image version; neither selects -compat. The compat variant adds AWS CLI/Python tools and init hooks, not additional server APIs.

The current Chainguard image defaults to UID 1001. Hardened mode keeps that non-root user and a read-only filesystem. Full mode overrides the Kubernetes security context to root and mounts the host Docker socket; the image entrypoint then drops privileges unless FLOCI_RUN_AS_ROOT=true is explicitly set:

floci:
  mode: full
  full:
    acknowledgeRisk: true
extraEnvVars:
  - name: FLOCI_RUN_AS_ROOT
    value: "true"

The chart tests verify both slots select the same regular image and render the full-mode security context. Runtime coverage exercises hardened HTTP and HTTPS; Docker-backed services remain outside that coverage.

HTTPS in image tests

The reusable fixture accepts tls = true. Floci generates its test CA and serves HTTP and HTTPS on port 4566; the fixture returns the HTTPS endpoint and a URL for importing the public CA. Clients should verify certificates against that CA.

See the upstream chart documentation for configuration and the reusable imagetest module for composing an ephemeral AWS dependency into image tests.