Skip to content

Deploying on Kubernetes

Entrepot ships a Helm chart (source in the server repository at deploy/helm/entrepot). It deploys stateless pods (ghcr.io/entrepotproj/entrepot), the blob store volumes, a ConfigMap rendered from your values, and optionally a scan-worker Deployment, a Trivy server, an Ingress, an HPA, a PodDisruptionBudget and a ServiceMonitor.

  1. Get the chart

    Tagged releases publish the chart as an OCI artifact to oci://ghcr.io/entrepotproj/charts/entrepot (and the images ghcr.io/entrepotproj/entrepot and ghcr.io/entrepotproj/entrepot-scanner). To track main or modify the chart, use a checkout instead:

    Terminal window
    git clone https://github.com/entrepotproj/entrepot.git
    cd entrepot # the chart is deploy/helm/entrepot
  2. Create the secrets

    Terminal window
    kubectl create namespace entrepot
    # Postgres connection URL (e.g. RDS)
    kubectl -n entrepot create secret generic entrepot-db \
    --from-literal=database-url='postgres://entrepot:…@db.example.com:5432/entrepot?sslmode=require'
    # session secret (shared by replicas), OIDC client secret, optional bootstrap token
    kubectl -n entrepot create secret generic entrepot-auth \
    --from-literal=session-secret="$(openssl rand -base64 48)" \
    --from-literal=secrets-key="$(openssl rand -base64 48)" \
    --from-literal=oidc-client-secret='…' \
    --from-literal=bootstrap-token="$(openssl rand -hex 32)"

    Keys the chart reads from auth.existingSecret: session-secret, bootstrap-token, oidc-client-secret, secrets-key, gitlab-token-<name> and trivy-token.

  3. Write your values — start from one of the examples below, then:

    Terminal window
    helm install entrepot oci://ghcr.io/entrepotproj/charts/entrepot --version <version> \
    -n entrepot -f my-values.yaml
  4. Bootstrap access with the bootstrap token, then remove it:

    Terminal window
    curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" https://entrepot.example.com/api/v1/me

    Create role bindings (or rely on auth.adminGroups), then delete the bootstrap-token key from the secret and roll the Deployment.

The chart’s NOTES print the URL, the blob stores, the OIDC redirect URI to register, the GitLab aud to use and the Trivy server URL.

Each repository picks one blob store, so you can mix them. See Storage & backups for the trade-offs.

examples/eks-ebs.yaml
replicaCount: 1
baseURL: https://entrepot.example.com
database:
existingSecret: entrepot-db # key: database-url (e.g. an RDS Postgres URL)
blobStores:
- name: default
type: file
volume:
storageClass: gp3 # EBS CSI driver StorageClass
accessMode: ReadWriteOnce
size: 200Gi
ingress:
enabled: true
className: nginx
hosts: [{host: entrepot.example.com, paths: ["/"]}]
tls: [{secretName: entrepot-tls, hosts: [entrepot.example.com]}]

A ReadWriteOnce volume can be mounted by one pod only, so the Deployment uses the Recreate strategy and the chart refuses more than one replica — or a separate scan worker.

Annotate the chart’s service account with a role whose trust policy allows the cluster’s OIDC provider, and grant it:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": "arn:aws:s3:::my-entrepot-artifacts"
},
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload"],
"Resource": "arn:aws:s3:::my-entrepot-artifacts/*"
}
]
}

With accessKeyId left empty, the AWS default credential chain is used (IRSA, environment, instance profile). For MinIO, Ceph RGW or R2 set endpoint (and forcePathStyle: true for MinIO).

Use an external Postgres 14+ (RDS, Cloud SQL, a CloudNativePG cluster). Either set database.url, or point database.existingSecret at a Secret with the key database-url. For evaluation only, postgresql.enabled: true runs a single-pod Postgres StatefulSet.

Migrations run automatically on startup and take a Postgres advisory lock, so replicas can start concurrently. See Upgrades.

ingress:
enabled: true
className: nginx
annotations:
# Large uploads (Docker layers, wheels) need generous limits.
nginx.ingress.kubernetes.io/proxy-body-size: "0"
nginx.ingress.kubernetes.io/proxy-read-timeout: "900"
nginx.ingress.kubernetes.io/proxy-send-timeout: "900"
nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
hosts:
- host: entrepot.example.com
paths: ["/"]
tls:
- secretName: entrepot-tls
hosts: [entrepot.example.com]

These annotations are the chart’s defaults. With another ingress controller, make sure request bodies are unlimited (or larger than your largest layer) and not buffered, and that timeouts allow slow uploads. Serve Entrepot at the root of its own host: Docker clients require /v2/ at the root.

The chart sets server.trustForwardedHeaders: true, and baseURL becomes server.baseURL — used for OIDC redirects, the Docker token realm, rewritten metadata and as the default GitLab audience.

examples/keycloak-gitlab.yaml
baseURL: https://entrepot.example.com
auth:
existingSecret: entrepot-auth # keys: session-secret, oidc-client-secret, bootstrap-token (optional)
adminGroups: [entrepot-admins]
anonymousAccess: false
oidc:
enabled: true
issuerURL: https://keycloak.example.com/realms/platform
clientID: entrepot
displayName: Keycloak
groupsClaim: groups
gitlab:
- name: gitlab
issuerURL: https://gitlab.example.com
# audience defaults to baseURL; use the same value as `aud:` in .gitlab-ci.yml

See Keycloak setup and GitLab CI.

examples/scanning.yaml
auth:
existingSecret: entrepot-auth # session-secret, secrets-key, gitlab-token-gitlab, trivy-token
gitlab:
- name: gitlab
issuerURL: https://gitlab.example.com
feedback: true # token from key gitlab-token-gitlab
blobStores:
- name: artifacts
type: s3
s3: {bucket: my-entrepot-artifacts, region: eu-west-2, redirectDownloads: true}
replicaCount: 2
scanning:
worker:
enabled: true # Deployment running `entrepot scan-worker` with trivy + grype
replicaCount: 2
trivyServer:
enabled: true # shared vulnerability DB, port 4954
cleanup:
interval: 12h
  • With scanning.worker.enabled, the in-process workers in the server pods are switched off (scan.workers: 0). Worker resources and image are configurable; the scanner DB cache is an ephemeral volume of scanning.worker.cache.size (an emptyDir when the size is empty).
  • The Trivy server is <release>-entrepot-trivy:4954; register it as a scanner with trivy.serverUrl (the NOTES show the command). Set scanning.trivyServer.token or the trivy-token secret key to require a token.
  • Scan workers need the same blob stores as the server: use S3 or ReadWriteMany volumes.
Value Default Purpose
image.repository / image.tag ghcr.io/entrepotproj/entrepot / appVersion Server image.
replicaCount 1 More than one needs S3 or ReadWriteMany stores.
resources 100m / 256Mi requests, 1Gi limit Pod resources.
tmp.sizeLimit 20Gi /tmp emptyDir used to spool uploads (S3 ingest, multipart forms).
autoscaling.* disabled, 2–6 replicas at 75% CPU HorizontalPodAutoscaler.
podDisruptionBudget.* disabled, minAvailable: 1 PDB.
metrics.serviceMonitor.* disabled, interval: 30s Prometheus Operator ServiceMonitor for /metrics.
cleanup.interval 24h How often cleanup policies run.
log.level / log.format info / json Logging.
config {} Raw configuration merged into config.yaml — anything from the configuration reference.
extraEnv, extraVolumes, extraVolumeMounts [] Escape hatches.

Pods run as non-root (UID 65532) with a read-only root filesystem, no privilege escalation and all capabilities dropped.