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.
Install
Section titled “Install”-
Get the chart
Tagged releases publish the chart as an OCI artifact to
oci://ghcr.io/entrepotproj/charts/entrepot(and the imagesghcr.io/entrepotproj/entrepotandghcr.io/entrepotproj/entrepot-scanner). To trackmainor modify the chart, use a checkout instead:Terminal window git clone https://github.com/entrepotproj/entrepot.gitcd entrepot # the chart is deploy/helm/entrepot -
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 tokenkubectl -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>andtrivy-token. -
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.yamlTerminal window helm install entrepot deploy/helm/entrepot -n entrepot \-f deploy/helm/entrepot/examples/eks-s3.yaml \-f my-values.yaml -
Bootstrap access with the bootstrap token, then remove it:
Terminal window curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" https://entrepot.example.com/api/v1/meCreate role bindings (or rely on
auth.adminGroups), then delete thebootstrap-tokenkey 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.
Storage layouts
Section titled “Storage layouts”Each repository picks one blob store, so you can mix them. See Storage & backups for the trade-offs.
replicaCount: 1baseURL: https://entrepot.example.comdatabase: 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: 200Giingress: 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.
replicaCount: 3baseURL: https://entrepot.example.comdatabase: existingSecret: entrepot-dbauth: existingSecret: entrepot-auth # session-secret (shared by replicas), oidc-client-secret, ...blobStores: - name: default type: file volume: storageClass: efs-sc # EFS CSI driver StorageClass accessMode: ReadWriteMany size: 1Ti # EFS ignores the size but Kubernetes requires onepodDisruptionBudget: enabled: true minAvailable: 2topologySpreadConstraints: - maxSkew: 1 topologyKey: topology.kubernetes.io/zone whenUnsatisfiable: ScheduleAnyway labelSelector: matchLabels: {app.kubernetes.io/name: entrepot}replicaCount: 1 # the EBS store below is ReadWriteOnce; drop it to scale outbaseURL: https://entrepot.example.comserviceAccount: annotations: eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/entrepot-s3database: existingSecret: entrepot-dbblobStores: - name: s3 type: s3 s3: bucket: my-entrepot-artifacts region: eu-west-2 prefix: prod redirectDownloads: true # large downloads go straight to S3 via presigned URLs - name: ebs type: file volume: storageClass: gp3 accessMode: ReadWriteOnce size: 100GiIAM policy for S3 (IRSA)
Section titled “IAM policy for S3 (IRSA)”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).
Database
Section titled “Database”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
Section titled “Ingress”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.
Single sign-on and GitLab
Section titled “Single sign-on and GitLab”baseURL: https://entrepot.example.comauth: 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.ymlSee Keycloak setup and GitLab CI.
Scan workers and a Trivy server
Section titled “Scan workers and a Trivy server”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-gitlabblobStores: - name: artifacts type: s3 s3: {bucket: my-entrepot-artifacts, region: eu-west-2, redirectDownloads: true}replicaCount: 2scanning: worker: enabled: true # Deployment running `entrepot scan-worker` with trivy + grype replicaCount: 2 trivyServer: enabled: true # shared vulnerability DB, port 4954cleanup: 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 ofscanning.worker.cache.size(an emptyDir when the size is empty). - The Trivy server is
<release>-entrepot-trivy:4954; register it as a scanner withtrivy.serverUrl(the NOTES show the command). Setscanning.trivyServer.tokenor thetrivy-tokensecret key to require a token. - Scan workers need the same blob stores as the server: use S3 or ReadWriteMany volumes.
Other values
Section titled “Other values”| 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.