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
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.
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:
- read upstream commits and database migrations;
- back up metadata and objects together;
- validate both config and migration modes;
- exercise a real cache push and pull;
- 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 SyncedVerified 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
endAttic Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Parent-provided Helm global values accepted for dependency composition. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Common Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonAnnotations | object | - | Chart configuration parameter |
Mode(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mode | string | standalone | Chart configuration parameter Allowed: standalonedistributed |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Replica Count(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| replicaCount | integer | - | Chart configuration parameter |
Container Ports(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| containerPorts.http | integer | - | Chart configuration parameter |
Configuration(20)
| Parameter | Type | Default | Description |
|---|---|---|---|
| config.listenAddress | string | - | Chart configuration parameter |
| config.listen | string | - | Chart configuration parameter |
| config.apiEndpoint | string | - | Chart configuration parameter |
| config.substituterEndpoint | string | - | Chart configuration parameter |
| config.allowedHosts | array | - | Chart configuration parameter |
| config.requireProofOfPossession | boolean | - | Chart configuration parameter |
| config.softDeleteCaches | boolean | - | Chart configuration parameter |
| config.maxNarInfoSize | integer | - | Chart configuration parameter |
| config.logLevel | string | - | Chart configuration parameter |
| config.chunking.narSizeThreshold | integer | - | Chart configuration parameter |
| config.chunking.minSize | integer | - | Chart configuration parameter |
| config.chunking.avgSize | integer | - | Chart configuration parameter |
| config.chunking.maxSize | integer | - | Chart configuration parameter |
| config.compression.type | string | - | Chart configuration parameter Allowed: nonebrotlizstdxz |
| config.compression.level | integernull | - | Chart configuration parameter |
| config.garbageCollection.enabled | boolean | - | Chart configuration parameter |
| config.garbageCollection.interval | string | - | Chart configuration parameter |
| config.garbageCollection.defaultRetentionPeriod | string | - | Chart configuration parameter |
| config.jwt.tokenBoundIssuer | string | - | Chart configuration parameter |
| config.jwt.tokenBoundAudiences | array | - | Chart configuration parameter |
Database(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.type | string | - | Chart configuration parameter Allowed: sqlitepostgresql |
| database.sqlite.path | string | - | Chart configuration parameter |
| database.postgresql.secretKey | string | - | Chart configuration parameter |
| database.postgresql.heartbeat | boolean | - | Chart configuration parameter |
Storage(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| storage.type | string | - | Chart configuration parameter Allowed: locals3 |
| storage.local.path | string | - | Chart configuration parameter |
| storage.s3.region | string | - | Chart configuration parameter |
| storage.s3.bucket | string | - | Chart configuration parameter |
| storage.s3.endpoint | string | - | Chart configuration parameter |
| storage.s3.accessKeyIdKey | string | - | Chart configuration parameter |
| storage.s3.secretAccessKeyKey | string | - | Chart configuration parameter |
Authentication(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| auth.generate | boolean | - | Chart configuration parameter |
| auth.existingSecret | string | - | Chart configuration parameter |
| auth.hs256SecretKey | string | - | Chart configuration parameter |
| auth.rs256SecretKey | string | - | Chart configuration parameter |
| auth.rs256PublicKey | string | - | Chart configuration parameter |
| auth.hs256Secret | string | - | Chart configuration parameter |
Persistence(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | - | Chart configuration parameter |
| persistence.existingClaim | string | - | Chart configuration parameter |
| persistence.storageClass | string | - | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.size | string | - | Chart configuration parameter |
| persistence.annotations | object | - | Chart configuration parameter |
| persistence.retain | boolean | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | string | - | Chart configuration parameter Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Gateway API(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | - | Chart configuration parameter |
| gatewayAPI.httpRoutes | array | - | Chart configuration parameter |
External Secrets(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | - | Chart configuration parameter |
| externalSecrets.refreshInterval | string | - | Chart configuration parameter |
| externalSecrets.items | array | - | Chart configuration parameter |
Network Policy(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.ingressFrom | array | - | Chart configuration parameter |
| networkPolicy.egress.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.egress.allowDNS | boolean | - | Chart configuration parameter |
| networkPolicy.egress.extraTo | array | - | Chart configuration parameter |
| networkPolicy.egress.extraEgress | array | - | Chart configuration parameter |
Pdb(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| pdb.enabled | boolean | - | Chart configuration parameter |
| pdb.minAvailable | integerstring | - | Chart configuration parameter |
| pdb.maxUnavailable | integerstring | - | Chart configuration parameter |
Health Probes(12)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| resources.requests.memory | stringnumber | - | Chart configuration parameter |
| resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| resources.limits.memory | stringnumber | - | Chart configuration parameter |
Garbage Collector Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| garbageCollectorResources.requests.cpu | stringnumber | - | Chart configuration parameter |
| garbageCollectorResources.requests.memory | stringnumber | - | Chart configuration parameter |
| garbageCollectorResources.limits.cpu | stringnumber | - | Chart configuration parameter |
| garbageCollectorResources.limits.memory | stringnumber | - | Chart configuration parameter |
Pod Security(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| podSecurityContext.runAsUser | integer | - | Chart configuration parameter |
| podSecurityContext.runAsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter Allowed: RuntimeDefaultLocalhostUnconfined |
| podSecurityContext.seccompProfile.localhostProfile | string | - | Chart configuration parameter |
Container Security(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| securityContext.capabilities.add | array | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Extra Env(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraEnv | array | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.