Skip to content

Helm values ​

Every key of the chart at deployment/helm/poiesis, with its default. The Deploy page writes a values.yaml with only the keys you change. values.schema.json validates values at helm install and helm lint: an unknown key (a typo such as taskpod:) fails the install.

Defaults are layered: top-level keys apply to every component, and api: and tctl: override only what differs. taskpods: shapes what runs for a task, not the control plane.

The chart never creates Secrets for credentials. Create the database Secret (and the S3 Secret, unless you use IRSA) before installing; the chart references them by name.

Chart-wide ​

KeyDefaultWhat it does
nameOverride, fullnameOverride""Name overrides; empty uses the release name.
commonLabels, commonAnnotations{}Added to every resource the chart renders.
image.registrydocker.ioImage registry, kept apart from the repository for policy engines.
image.repositoryjaeaeich/poiesisImage repository.
image.tag""Empty uses the chart's appVersion.
image.pullPolicyIfNotPresentPull policy.
imagePullSecrets[]Applied to the API, TCtl, the migration hook and every TaskPod.
podSecurityContext, containerSecurityContext{}Security contexts for the API, TCtl and the hook, merged over a profile derived from podSecurityEnforce.
podSecurityEnforcerestrictedPodSecurity profile for Poiesis-owned containers (API, TCtl, hook, and trec/tif/tof/ack): restricted, baseline or off. Executors run user images and are exempt.
nodeSelector, tolerations, affinity{}, [], {}Default scheduling; per-component values win.
extraEnv, extraEnvFrom[]Extra environment for the API and TCtl; component extras append.
extraVolumes, extraVolumeMounts[]Extra volumes for the API and TCtl; component extras append. Names must not collide.
extraManifests[]Manifests rendered verbatim (strings or templates).
logLevelINFOApplication log level. The audit log ignores it.
logging.formatjsonLog line format of the API, TCtl, trec, tif and tof: json, text (coloured), or "" (text on a terminal, else JSON). The audit log ignores it. See Logs.

Service accounts ​

KeyDefaultWhat it does
serviceAccount.api.createtrueCreate the API's ServiceAccount; false with name binds an existing one (IRSA, Workload Identity).
serviceAccount.api.name""Name of the ServiceAccount.
serviceAccount.api.annotations{}e.g. eks.amazonaws.com/role-arn.
serviceAccount.tctl.*sameThe same for TCtl.
serviceAccount.taskpod.*sameThe same for TaskPods (used by trec; executors don't get its token).

Database ​

KeyDefaultWhat it does
database.existingSecret""Secret holding the full DATABASE_URL. Required.
database.existingSecretKeyDATABASE_URLKey in that Secret.
database.caConfigmap""ConfigMap with ca.crt, mounted read-only at /etc/ssl/poiesis in the API, TCtl and every TaskPod's Poiesis containers.

The URL has the form postgresql://USER:PASS@HOST:PORT/DB?sslmode=verify-full&sslrootcert=/etc/ssl/poiesis/ca.crt.

S3 ​

KeyDefaultWhat it does
s3.endpoint""AWS_ENDPOINT_URL; empty for AWS.
s3.region""AWS_REGION.
s3.existingSecret""Secret with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN; empty with IRSA or IMDS credentials.

Needed only when inputs or outputs use s3://. See Storage and staging.

auth ​

Rendered as POIESIS_AUTH_* variables. See Authentication.

KeyDefaultWhat it does
auth.enabledtrueWith true, at least one issuer is required. false accepts every request as one anonymous owner (local dev, air-gapped single tenant).
auth.issuers[]Trusted issuers (POIESIS_AUTH_ISSUERS, JSON). Keys below.
auth.resource""Public URL; enables RFC 9728 metadata and resource_metadata in every 401. See Discovery.
auth.apiKeys.enabledfalseTurn API keys on.
auth.apiKeys.defaultTtl7dLifetime when the minting request names none (<n>d or <n>h).
auth.apiKeys.maxTtl90dLongest lifetime a request may ask for.
auth.apiKeys.maxPerOwner20Active keys one owner may hold.
auth.swaggerUi.issuer""One of auth.issuers (with discovery); empty turns the Swagger UI login off.
auth.swaggerUi.clientId""Public client allowing <API URL>/docs/oauth2-redirect.
auth.swaggerUi.scopesopenidSpace-separated scopes requested.

auth.issuers[] ​

KeyDefaultWhat it does
issuerrequiredExact iss of the tokens and the discovery base URL.
audiencerequiredAccepted aud: a string or a list.
tokenTypes[at+jwt]Accepted header typ values, case-insensitive, application/ optional. Keycloak: [JWT]. [] turns the check off.
clientsanyAccepted OAuth clients (azp, else client_id).
namespacethe issuerPrefix of owner ids, <namespace>|<subject>. No |.
principalClaimsubClaim naming the subject; dotted paths walk nested objects.
requiredScopesnoneScopes a token must carry, else 403.
requiredClaimnoneAdmission rule {name, values, prefixes}; see Claim rule.
adminnoneBuilt-in admin rule {name, values, prefixes}; ignored with a decision service.
actorsnoneActors (act.sub) whose delegated tokens the built-in policy accepts.
userinfo.enabledfalseFetch userinfo per token (cached until expiry, at most 5 minutes). Not with jwksUri.
jwksUridiscoveryStatic JWKS URL, for gateways that sign their own JWTs.
jwksCacheTtl3600Seconds to cache keys; unknown kids refetch at most every 30 s.
clockSkew30Seconds of leeway on exp, nbf, iat.
timeout10Seconds per call to the issuer.
keyMinting.clientsnoneClients whose tokens may mint API keys; without keyMinting, none may.
keyMinting.maxAuthAgenoneAlso require a login at most this many seconds ago (auth_time).

authz ​

Rendered as POIESIS_AUTHZ_*. See Authorization.

KeyDefaultWhat it does
authz.decisionService.url""OpenID AuthZEN 1.0 evaluation URL; empty keeps the built-in owner rule. Failures and timeouts are 503.
authz.decisionService.timeout2Seconds per evaluation.
authz.decisionService.claims[]Claims sent in subject.properties.claims.
authz.decisionService.credentialFile""Path (in the API pod) of a file with a bearer credential for the service.
authz.sharingfalseLet the decision service show tasks to others than their owner. Needs decisionService.url.
authz.maxOwners1000Most owners one list scope may name; more is 403.
authz.adminReadfalseBuilt-in admins may list, get and cancel every task.

The former global authz.requiredClaim is refused; set it per issuer.

audit ​

KeyDefaultWhat it does
audit.enabledtrueOne JSON line per decision and API key event on stdout. See Audit log.

serviceInfo ​

Empty keeps the built-in value. Invalid values stop the API from starting. See Service info.

KeyDefaultWhat it does
serviceInfo.id""Unique id, reverse domain recommended; also context.tes.service_id. Built-in: org.ga4gh.poiesis.
serviceInfo.name, serviceInfo.description""Human-readable name and description.
serviceInfo.organization.name, .url""Who runs the deployment; url is http(s).
serviceInfo.contactUrl""http(s) URL or mailto:.
serviceInfo.documentationUrl""Docs for this deployment's users.
serviceInfo.environment""e.g. prod, test, dev, staging; left out when empty.
serviceInfo.createdAt""ISO 8601 with a UTC offset; empty is the time of the request.

api ​

KeyDefaultWhat it does
api.replicas1API replicas.
api.image{}Image override (registry, repository, tag, pullPolicy), e.g. for canaries; TaskPods use the same image.
api.resourcesrequests 100m/256Mi, limits 1000m/512MiContainer resources.
api.probes.startupenabled, every 2 s, 30 failuresStartup probe.
api.probes.readinessenabled, every 5 s, timeout 2 s, 3 failuresReadiness probe.
api.probes.livenessenabled, every 10 s, timeout 2 s, 3 failuresLiveness probe.
api.preStopSleepSeconds5Seconds the Pod sleeps in a preStop hook before SIGTERM, so Services and ingresses stop sending it requests first. 0 is no hook.
api.terminationGracePeriodSeconds40Grace period. Gunicorn lets running requests finish for up to 30 s after SIGTERM; keep it at least preStopSleepSeconds + 30.
api.topologySpreadConstraints[]Pod topology spread, e.g. across zones. An entry without labelSelector gets the API Pods' labels.
api.service.type, .port, .annotationsClusterIP, 8000, {}The API Service.
api.ingress.enabledfalseCreate an Ingress.
api.ingress.className""Ingress class; empty for the cluster default.
api.ingress.annotations{}e.g. cert-manager.io/cluster-issuer.
api.ingress.hostspoiesis.local, path /Hosts and paths.
api.ingress.tls[]TLS entries {secretName, hosts}.
api.pdb.enabled, .minAvailablefalse, 1PodDisruptionBudget.
api.autoscaling.*off, 1–4 replicas, 70% CPUHorizontalPodAutoscaler.
api.extraEnv, .extraEnvFrom, .extraVolumes, .extraVolumeMounts, .extraContainers[]Appended to the chart-wide extras.
api.podAnnotations, .podLabels, .nodeSelector, .tolerations, .affinityemptyPod metadata and scheduling.

tctl ​

KeyDefaultWhat it does
tctl.replicas1Leader election keeps one active; more give faster failover, not throughput. The chart renders no PodDisruptionBudget for TCtl: with one replica it would block node drains, and an evicted TCtl only delays task state updates.
tctl.unschedulableTimeoutSecondsnullSeconds a task may wait for its Pod to be created and scheduled before it ends SYSTEM_ERROR, at least 1. null waits until the time limit.
tctl.probes.liveness.enabledtrueLiveness probe: TCtl touches /tmp/poiesis-tctl-heartbeat after each loop iteration, and the probe fails when the file is missing or older than maxHeartbeatAgeSeconds.
tctl.probes.liveness.maxHeartbeatAgeSeconds600Heartbeat age at which the probe fails. Keep it above your longest pass.
tctl.probes.liveness.periodSeconds, .timeoutSeconds, .failureThreshold30, 5, 3Probe timing.
tctl.image{}Image override.
tctl.resourcesrequests 50m/128Mi, limits 500m/256MiContainer resources.
tctl.extraEnv, .extraEnvFrom, .extraVolumes, .extraVolumeMounts, .extraContainers[]Appended to the chart-wide extras.
tctl.podAnnotations, .podLabels, .nodeSelector, .tolerations, .affinityemptyPod metadata and scheduling.

taskpods ​

Baked into TaskPod manifests by the API when a task is created. See Task volumes.

KeyDefaultWhat it does
taskpods.namespace""Namespace for TaskPods; empty is the release namespace. When split, the chart renders the API and TaskPod Roles there.
taskpods.databaseSecret""Secret in the TaskPod namespace that trec, tif and tof read DATABASE_URL from, by reference. Empty is database.existingSecret. The key is database.existingSecretKey.
taskpods.s3Secret""The same for the S3 keys. Empty is s3.existingSecret.
taskpods.persistence.defaultSizeGi10Volume size when a task omits resources.disk_gb.
taskpods.persistence.maxSizeGi100Largest disk_gb; more is 400. Required by the schema.
taskpods.persistence.storageClass"""" cluster default; "-" sets storageClassName: ""; else a named class.
taskpods.persistence.accessModes[ReadWriteOnce]Access modes; [ReadWriteMany] for RWX-only storage.
taskpods.persistence.labels{}Labels on every task volume.
taskpods.persistence.annotations{}Annotations on every task volume.
taskpods.persistence.retainAfterSeconds3600ttlSecondsAfterFinished of the Job; null keeps Job and volume.
taskpods.activeDeadlineSeconds3600Time limit of a task in seconds (activeDeadlineSeconds of the Job), at least 1; null is no limit. Also ends the wait of a task that can't be scheduled.
taskpods.outputGlobFallbackfalseUpload everything under path_prefix when an output glob matches nothing.
taskpods.fileUrlRoots[]Directories file:// URLs may point into; empty turns the scheme off. See Local paths.
taskpods.systemResources.recorderrequests 10m/128Mi, limits 200m/256MiResources of trec, the sidecar that records the task.
taskpods.systemResources.filerrequests 100m/256Mi, limits 1000m/1GiResources of tif and tof. Transfers are streamed, so memory doesn't grow with file size.
taskpods.systemResources.ackrequests 10m/128Mi, limits 100m/256MiResources of ack, the last container.
taskpods.extraEnv[]Env for trec, tif, tof. Reserved: DATABASE_URL, AWS_ENDPOINT_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, POIESIS_*.
taskpods.extraVolumes[]Volumes added to every TaskPod. Reserved names: task-data, postgres-ca, tmp.
taskpods.extraVolumeMounts[]Mounts for Poiesis containers and executors (reference data).

taskpods.systemResources entries are Kubernetes resources blocks (requests, limits). Your values merge with the defaults key by key; null (e.g. ack: null) leaves that container without requests or limits. A malformed block, or a request above its limit, stops the API at startup. Executors get their resources from the task.

The serialised TaskPod extras are capped at about 32 KiB (the Kubernetes env-var limit); use a mounted ConfigMap for very large sets.

networkPolicy ​

KeyDefaultWhat it does
networkPolicy.enabledfalseRender NetworkPolicies for the API and TCtl. They may reach DNS, any address on TCP 443 and 6443, and Postgres; the API accepts traffic on 8000 from the release's own Pods and the peers below.
networkPolicy.databaseEgress.port5432Postgres port.
networkPolicy.databaseEgress.to[]NetworkPolicy peers where Postgres is (ipBlock, namespaceSelector, podSelector); empty is any address. databaseEgress: null drops the rule.
networkPolicy.ingressFrom[]Peers allowed to reach the API, e.g. the ingress controller's namespace.
networkPolicy.ingressFromPodSelector{}Labels of further Pods in the release namespace allowed to reach the API.
networkPolicy.extraEgress[]Extra egress rules for the API and TCtl, e.g. an issuer or S3 endpoint on another port.

migrations ​

KeyDefaultWhat it does
migrations.image.registrydocker.ioMigration image registry.
migrations.image.repositoryjaeaeich/poiesis-migrationsgolang-migrate image with the schema.
migrations.image.tag, .pullPolicy"", IfNotPresentTag (empty: appVersion) and pull policy.
migrations.resourcesrequests 50m/64Mi, limits 200m/128MiHook resources.