Skip to content
Attic icon
v1.1.0App: v0.1.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Attic

Production-ready Helm chart for the Attic Nix binary cache server.

Why this chart

Attic provides content-addressed global deduplication, multi-tenant caches, managed cache signing and token-scoped access. This chart turns the upstream runtime modes into two explicit Kubernetes topologies and prevents unsafe combinations at render time.

The upstream project is still an early prototype and does not publish semantic releases. HelmForge therefore marks this chart beta and pins an official image by immutable commit SHA.

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install attic helmforge/attic --namespace attic --create-namespace

OCI installation:

helm install attic oci://ghcr.io/helmforgedev/helm/attic \
  --namespace attic --create-namespace --version 1.0.0

Topologies

Standalone

The default runs atticd --mode monolithic with SQLite and local object storage on one PVC. It uses one replica and a Recreate deployment strategy. This topology is appropriate for personal caches, build labs and small teams.

mode: standalone
persistence:
  size: 50Gi
config:
  apiEndpoint: https://cache.example.com/
  allowedHosts: [cache.example.com]

Distributed

Distributed mode runs a replicated stateless API, a singleton garbage collector and a pre-install/pre-upgrade database migration Job. It requires external PostgreSQL, S3-compatible storage and a pre-existing Secret.

mode: distributed
replicaCount: 3
database:
  type: postgresql
storage:
  type: s3
  s3:
    region: us-east-1
    bucket: company-attic-cache
auth:
  generate: false
  existingSecret: attic-production
pdb:
  enabled: true

The Secret must provide database-url and one JWT signing key. S3 credential keys are optional when workload identity is used.

Secret contract

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Standalone mode generates and reuses an HS256 Secret when no existing Secret is selected. Production installations should manage stable signing material outside the chart. Changing JWT keys, issuer or audience invalidates tokens.

Exposure

Ingress and Gateway API are opt-in. Set config.apiEndpoint to the externally visible HTTPS URL, including the trailing slash, and put every accepted host in config.allowedHosts.

Nix uploads can be large and long-running. Configure the proxy or Gateway for unlimited/appropriate body size and generous read/write timeouts. Subpath routing is not a default because canonical Attic endpoints must stay aligned.

See docs/exposure.md.

Storage and backup

Standalone backup must preserve both the SQLite database and local object directory. Quiesce uploads and garbage collection before taking a consistent PVC snapshot.

Distributed backup must coordinate PostgreSQL backup/PITR with S3 object versioning and retention. Restoring only one side can leave metadata pointing to missing objects. Attic has no native backup command.

Custom S3 endpoints may be embedded in presigned client URLs. The endpoint must be reachable by Nix clients, not only from the Attic pod.

See docs/storage-and-backup.md.

Security

Defaults run the root-default upstream image as UID/GID 10001, drop all Linux capabilities, use RuntimeDefault seccomp, disable privilege escalation and mount the root filesystem read-only. The data PVC and /tmp remain writable. The ServiceAccount token is not mounted.

requireProofOfPossession defaults to true. Keep it enabled unless you have a well-understood compatibility reason. Distribute cache public keys through a trusted channel because they participate in Nix supply-chain trust.

See docs/security.md.

Observability and health

Attic writes structured Rust tracing logs to stdout/stderr. Set config.logLevel to change RUST_LOG. The pinned upstream version has no Prometheus endpoint, so this chart intentionally does not render a ServiceMonitor.

Startup, liveness and readiness probes use the named HTTP port configured by containerPorts.http. This value also controls the real Attic listener; service.port remains independently configurable. The probes verify the process listener only and do not prove PostgreSQL or S3 health. Validate production readiness with a real cache create/push/pull workflow and monitor proxy, DB, bucket and Kubernetes metrics externally.

Garbage collection

Standalone monolithic mode owns garbage collection. Distributed mode creates exactly one garbage-collector process because upstream states it cannot be replicated. Time-based deletion is disabled when the default retention is "0"; set retention deliberately after confirming backup policy.

Changing chunking parameters does not corrupt data, but reduces deduplication for newly uploaded NARs because chunk boundaries change.

Configuration reference

The complete default contract is documented in values.yaml and validated by values.schema.json. Major groups are:

Group Purpose
mode, replicaCount Standalone or distributed lifecycle
containerPorts Attic process and container listeners
config Endpoints, hosts, chunking, compression, GC and JWT claims
database SQLite path or PostgreSQL Secret mapping
storage Local path or S3 bucket/endpoint mapping
auth Generated or existing signing/database credential Secret
persistence Standalone PVC lifecycle
ingress, gatewayAPI Optional external HTTP routing
externalSecrets Canonical External Secrets resources
networkPolicy, pdb Availability and traffic policy
podSecurityContext, securityContext Pod hardening

Examples

Upgrade policy

The image tag is an upstream commit, not a semver release. Before changing it:

  1. read upstream commits and database migrations;
  2. back up metadata and objects together;
  3. validate both config and migration modes;
  4. exercise a real cache push and pull;
  5. retain a rollback image and compatible backup.

Do not roll back the container after a database migration unless upstream confirms backward compatibility.

Troubleshooting

Symptom Check
HTTP 400 Add the request hostname to config.allowedHosts
Push timeout Increase proxy body-size and timeouts
Database error Verify database-url and network egress
S3 download fails Ensure the configured endpoint is client-reachable
Permission denied Verify PVC fsGroup behavior and UID 10001 ownership
Tokens stop working Check signing key, issuer and audience changes
Pod Ready but operations fail TCP probes do not validate DB or S3
Migration hook fails Inspect the hook Job and PostgreSQL permissions
GC does not free space Check cache retention and GC logs
Deduplication drops Check whether chunking values changed

Security Scan

Security scan results use the same Kubescape policy set as HelmForge CI.

Security Scan: attic
Framework                  Score
MITRE + NSA + SOC2         95.454544%
Security posture acceptable.

Non-goals

  • Installing PostgreSQL or an S3 service inside this chart.
  • Generating or rotating production RSA keys.
  • Inventing metrics or deep readiness endpoints absent upstream.
  • Hiding the upstream early-prototype and compatibility risks.

References

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  clients[Nix clients and Attic CLI] --> exposure[Ingress or HTTPRoute optional]
  exposure --> service[Attic Service]
  service --> api[Attic API Deployment]
  config[ConfigMap] --> api
  credentials[Secret or ExternalSecret] --> api

  subgraph standalone[Standalone mode]
    api --> local[(SQLite and local objects PVC)]
  end

  subgraph distributed[Distributed mode]
    migration[Migration Job] --> postgres[(External PostgreSQL)]
    api --> postgres
    api --> s3[(External S3-compatible storage)]
    gc[Garbage collector Deployment] --> postgres
    gc --> s3
  end
Official Contractvalues.schema.json

Attic Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

125 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Parent-provided Helm global values accepted for dependency composition.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Chart configuration parameter

Mode(1)

ParameterTypeDefaultDescription
modestringstandaloneChart configuration parameter
Allowed:standalonedistributed

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Chart configuration parameter

Container Ports(1)

ParameterTypeDefaultDescription
containerPorts.httpinteger-Chart configuration parameter

Configuration(20)

ParameterTypeDefaultDescription
config.listenAddressstring-Chart configuration parameter
config.listenstring-Chart configuration parameter
config.apiEndpointstring-Chart configuration parameter
config.substituterEndpointstring-Chart configuration parameter
config.allowedHostsarray-Chart configuration parameter
config.requireProofOfPossessionboolean-Chart configuration parameter
config.softDeleteCachesboolean-Chart configuration parameter
config.maxNarInfoSizeinteger-Chart configuration parameter
config.logLevelstring-Chart configuration parameter
config.chunking.narSizeThresholdinteger-Chart configuration parameter
config.chunking.minSizeinteger-Chart configuration parameter
config.chunking.avgSizeinteger-Chart configuration parameter
config.chunking.maxSizeinteger-Chart configuration parameter
config.compression.typestring-Chart configuration parameter
Allowed:nonebrotlizstdxz
config.compression.levelintegernull-Chart configuration parameter
config.garbageCollection.enabledboolean-Chart configuration parameter
config.garbageCollection.intervalstring-Chart configuration parameter
config.garbageCollection.defaultRetentionPeriodstring-Chart configuration parameter
config.jwt.tokenBoundIssuerstring-Chart configuration parameter
config.jwt.tokenBoundAudiencesarray-Chart configuration parameter

Database(4)

ParameterTypeDefaultDescription
database.typestring-Chart configuration parameter
Allowed:sqlitepostgresql
database.sqlite.pathstring-Chart configuration parameter
database.postgresql.secretKeystring-Chart configuration parameter
database.postgresql.heartbeatboolean-Chart configuration parameter

Storage(7)

ParameterTypeDefaultDescription
storage.typestring-Chart configuration parameter
Allowed:locals3
storage.local.pathstring-Chart configuration parameter
storage.s3.regionstring-Chart configuration parameter
storage.s3.bucketstring-Chart configuration parameter
storage.s3.endpointstring-Chart configuration parameter
storage.s3.accessKeyIdKeystring-Chart configuration parameter
storage.s3.secretAccessKeyKeystring-Chart configuration parameter

Authentication(6)

ParameterTypeDefaultDescription
auth.generateboolean-Chart configuration parameter
auth.existingSecretstring-Chart configuration parameter
auth.hs256SecretKeystring-Chart configuration parameter
auth.rs256SecretKeystring-Chart configuration parameter
auth.rs256PublicKeystring-Chart configuration parameter
auth.hs256Secretstring-Chart configuration parameter

Persistence(7)

ParameterTypeDefaultDescription
persistence.enabledboolean-Chart configuration parameter
persistence.existingClaimstring-Chart configuration parameter
persistence.storageClassstring-Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.sizestring-Chart configuration parameter
persistence.annotationsobject-Chart configuration parameter
persistence.retainboolean-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystring-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Chart configuration parameter
gatewayAPI.httpRoutesarray-Chart configuration parameter

External Secrets(3)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.itemsarray-Chart configuration parameter

Network Policy(6)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingressFromarray-Chart configuration parameter
networkPolicy.egress.enabledboolean-Chart configuration parameter
networkPolicy.egress.allowDNSboolean-Chart configuration parameter
networkPolicy.egress.extraToarray-Chart configuration parameter
networkPolicy.egress.extraEgressarray-Chart configuration parameter

Pdb(3)

ParameterTypeDefaultDescription
pdb.enabledboolean-Chart configuration parameter
pdb.minAvailableintegerstring-Chart configuration parameter
pdb.maxUnavailableintegerstring-Chart configuration parameter

Health Probes(12)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Chart configuration parameter
resources.requests.memorystringnumber-Chart configuration parameter
resources.limits.cpustringnumber-Chart configuration parameter
resources.limits.memorystringnumber-Chart configuration parameter

Garbage Collector Resources(4)

ParameterTypeDefaultDescription
garbageCollectorResources.requests.cpustringnumber-Chart configuration parameter
garbageCollectorResources.requests.memorystringnumber-Chart configuration parameter
garbageCollectorResources.limits.cpustringnumber-Chart configuration parameter
garbageCollectorResources.limits.memorystringnumber-Chart configuration parameter

Pod Security(6)

ParameterTypeDefaultDescription
podSecurityContext.runAsNonRootboolean-Chart configuration parameter
podSecurityContext.runAsUserinteger-Chart configuration parameter
podSecurityContext.runAsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined
podSecurityContext.seccompProfile.localhostProfilestring-Chart configuration parameter

Container Security(4)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.capabilities.addarray-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Extra Env(1)

ParameterTypeDefaultDescription
extraEnvarray-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter