Configuration reference
Every JaaS flag is listed here with its default and a one-line description. Run
jaas --help to see the same list at runtime. The tables on this page are
generated from the binary’s own flag definitions, so they never drift from the
runtime contract.
The Helm chart exposes most flags under arguments.*; operator-specific flags
are under operator.*. The full set of chart values is in the
Helm chart values
reference.
Jsonnet server
The Jsonnet server evaluates snippets and returns JSON. It binds on
--listen-address:--port by default.
| Flag | Type | Default | Description |
|---|---|---|---|
--jsonnet-endpoint-path | string | jsonnet | The path to the jsonnet endpoint |
--listen-address | string | 127.0.0.1 | The listen address to bind to for the Jsonnet server |
--port | string | 8080 | The port to bind to for the Jsonnet server |
--read-timeout | duration | 10s | maximum duration for reading the entire request, including the body in the Jsonnet server |
--write-timeout | duration | 10s | The maximum duration before timing out writes of the response in the Jsonnet server |
Management server
The management server exposes the three Kubernetes probe endpoints. It binds on
--management-listen-address:--management-port.
| Flag | Type | Default | Description |
|---|---|---|---|
--management-listen-address | string | 127.0.0.1 | The listen address to bind to for the management server |
--management-port | string | 8081 | The port to bind to for the management server |
--management-read-timeout | duration | 10s | maximum duration for reading the entire request, including the body in the management server |
--management-write-timeout | duration | 10s | The maximum duration before timing out writes of the response in the management server |
Endpoints: GET /start (startup probe), GET /ready (readiness probe),
GET /live (liveness probe). Startup and readiness return 503 with a
{"status":"…"} JSON body when the server is not yet ready. Liveness is an
unconditional 200.
Snippets and libraries
Flags for declaring the Jsonnet files the server serves.
| Flag | Type | Default | Description |
|---|---|---|---|
--library-path | stringArray | [] | The path of a directory containing jsonnet libraries (can be specified multiple times). Rightmost matching library will be used. |
--snippet | stringArray | [] | The path of a jsonnet file or directory containing snippets (can be specified multiple times). Snippets will be loaded from the given path, where the file name is the snippet name. |
--snippet-directory | stringArray | [] | The path of a directory containing snippets as subdirectories (can be specified multiple times). Snippets will be loaded from subdirectories of the given path, where the directory name is the snippet name. |
Snippet name resolution uses Go’s os.OpenRoot, which rejects .. traversal
and symlinks that escape the configured directory. This is security-critical;
see Evaluation and security
.
External variables
| Flag | Type | Default | Description |
|---|---|---|---|
--ext-var | stringArray | [] | External variable as KEY=VALUE for std.extVar lookups (can be specified multiple times). Takes precedence over JAAS_EXT_VAR_* env vars on conflict. |
Environment variable alternative: set JAAS_EXT_VAR_<NAME>=<VALUE> to
expose <NAME> as an external variable. The --ext-var flag overrides the env
mechanism on key conflict. See
External variables and TLAs
for usage
examples.
Evaluation limits
| Flag | Type | Default | Description |
|---|---|---|---|
--evaluation-timeout | duration | 5s | Maximum duration a single Jsonnet evaluation is allowed to take. Set to 0 to disable. |
--max-concurrent-evals | int | max(GOMAXPROCS×4, 16) | Maximum number of in-flight Jsonnet evaluations. Excess requests return 503 (HTTP) or RequeueAfter (operator). Set to 0 to disable. Defaults to max(GOMAXPROCS*4, 16). |
--max-stack | int | 500 | Maximum Jsonnet call-stack depth. Set to 0 to use go-jsonnet's default. |
--evaluation-timeout fires the HTTP response but does not terminate the
underlying go-jsonnet call — the evaluation continues consuming CPU until it
finishes naturally. Size container resources accordingly and use
--max-concurrent-evals to bound worst-case goroutine pile-up. See
Evaluation and security
for the full
discussion.
Lifecycle
| Flag | Type | Default | Description |
|---|---|---|---|
--shutdown-delay | duration | 5s | Time to wait after readiness flips to false before initiating graceful shutdown; gives Kubernetes time to propagate the not-ready status to endpoint controllers. Set to 0 to disable. |
Operator (Flux integration)
The following flags are only active when --enable-flux-integration is set.
| Flag | Type | Default | Description |
|---|---|---|---|
--artifact-gc-grace | duration | 5m0s | Minimum time a superseded artifact revision is retained after being evicted from the keep-set. Closes the pin→fetch race in which a Flux consumer reads status.artifact a moment before the operator garbage-collects the superseded revision. Zero disables and restores eager pruning. The deletion path (snippet teardown) is unaffected. |
--default-service-account | string | (empty) | ServiceAccount the operator impersonates when a JsonnetSnippet has no spec.serviceAccountName. Empty rejects such snippets at reconcile time. |
--enable-flux-integration | bool | false | Boot the Kubernetes operator that watches JsonnetSnippet / JsonnetLibrary CRs and publishes evaluated results as Flux ExternalArtifacts. |
--kubeconfig | string | (empty) | Path to a kubeconfig file for the operator. Empty falls back to KUBECONFIG env, then to in-cluster service-account credentials. |
--label-selector | string | (empty) | Narrow the operator's watch to CRs matching this label selector. Empty selects every CR in the watched scope. |
--max-artifact-bytes | int64 | 0 | Cap the rendered artifact size in bytes. Snippets whose rendered output exceeds this fail with ReasonArtifactTooLarge. Zero disables. |
--max-withdraw-wait | duration | 1h0m0s | Bound the time a deleted JsonnetSnippet's finalizer can hold while Publisher.Withdraw keeps failing. Past this, the operator emits a Warning WithdrawForced event, drops the finalizer, and lets the snippet be garbage-collected — possibly leaving an orphan tarball in storage. Required so a permanently-broken backend doesn't block namespace teardown. |
--no-cross-namespace-refs | bool | true | When true (default), reject JsonnetSnippet / library CRs that reference a SourceRef in a different namespace. |
--rerender-burst | int | 120 | Per-snippet token-bucket depth for re-render rate limiting. |
--rerender-rate | string | 60/min | Per-snippet steady-state re-render budget, as N/period (sec|min|hour). Token-bucket combined with --rerender-burst. |
--watch-namespaces | string | (empty) | Comma-separated list of namespaces this operator watches. Empty (the default) means cluster-wide. When set, the manager's cache only observes CRs in these namespaces — multi-tenant operator-instances pattern. Falls back to JAAS_WATCH_NAMESPACES env var when the flag is empty. |
Environment variable: JAAS_WATCH_NAMESPACES — comma-separated namespace
list. Superseded by --watch-namespaces when both are set.
Storage server (local and S3)
The storage server is the HTTP file server that downstream Flux consumers fetch
artifacts from. It is started only when --enable-flux-integration is set.
| Flag | Type | Default | Description |
|---|---|---|---|
--storage-backend | string | local | Artifact backend the operator publishes ExternalArtifact tarballs through. local (default; emptyDir/PVC) or s3 (any S3-compatible object store; pairs with leader election for HA across replicas). |
--storage-base-url | string | (empty) | Public URL prefix the operator's storage HTTP server serves tarballs at. Required when --enable-flux-integration is set. |
--storage-listen-address | string | 0.0.0.0 | The listen address to bind to for the storage HTTP server |
--storage-path | string | (empty) | Directory the operator writes ExternalArtifact tarballs to. Required when --enable-flux-integration is set. |
--storage-port | string | 8082 | The port to bind to for the storage HTTP server |
--storage-read-timeout | duration | 30s | Maximum duration for reading the entire request on the storage server. |
--storage-sweep-interval | duration | 10m0s | How often the operator sweeps orphaned <rev>.tar.gz.tmp residue left by Puts whose process died mid-rename. Zero disables. |
--storage-sweep-max-tmp-age | duration | 30m0s | Minimum age before an orphaned .tmp file is eligible for sweep. Wider than the longest plausible in-flight Put to avoid racing live writers. |
--storage-write-timeout | duration | 5m0s | Maximum duration before timing out writes of the response on the storage server. Tarballs can be MBs, so this is generous by default. |
S3 flags
Active only when --storage-backend=s3.
| Flag | Type | Default | Description |
|---|---|---|---|
--s3-access-key | string | (empty) | Static AWS_ACCESS_KEY_ID. Empty triggers the IAM/IRSA discovery chain (AWS_*, web-identity, EC2 metadata). |
--s3-anonymous | bool | false | Skip request signing entirely. Only useful against a public bucket — test/dev only. |
--s3-bucket | string | (empty) | S3 bucket the artifacts live in. Must already exist. Required when --storage-backend=s3. |
--s3-endpoint | string | (empty) | S3 service host:port (e.g. s3.amazonaws.com or minio.minio.svc:9000). Required when --storage-backend=s3. |
--s3-prefix | string | (empty) | Optional object-key prefix prepended under the bucket, so jaas can coexist with other tenants in one bucket. |
--s3-region | string | (empty) | S3 region the bucket lives in. Required for AWS multi-region setups; ignored by most S3-compatible servers. |
--s3-secret-key | string | (empty) | Static AWS_SECRET_ACCESS_KEY. Pairs with --s3-access-key. |
--s3-session-token | string | (empty) | Optional AWS_SESSION_TOKEN, paired with --s3-access-key/--s3-secret-key for temporary credentials. |
--s3-use-ssl | bool | true | Talk HTTPS to the S3 endpoint. Set to false only for local MinIO over HTTP. |
Webhook (TLS provisioning)
Active only when --enable-webhook is set (which also requires
--enable-flux-integration).
| Flag | Type | Default | Description |
|---|---|---|---|
--enable-webhook | bool | false | Boot the validating admission webhook for JsonnetSnippet. Requires --enable-flux-integration and a TLS cert/key in --webhook-cert-dir. |
--webhook-cert-dir | string | /tmp/k8s-webhook-server/serving-certs | Directory holding the TLS cert (tls.crt) and key (tls.key) the webhook server presents. |
--webhook-cert-mode | string | cert-manager | How the webhook's TLS material is provisioned: cert-manager (chart renders a Certificate; cert injected via Secret mount), or self-signed (operator generates a CA + serving cert in-pod and patches the ValidatingWebhookConfiguration's caBundle). |
--webhook-cert-validity | duration | 8760h0m0s | Validity of the self-signed serving cert. Operators that want short-lived rotation should use cert-manager instead. |
--webhook-port | int | 9443 | Port the validating webhook server binds to. |
--webhook-service-name | string | jaas-webhook | Service name the webhook is reachable through. Used to build cert SANs when --webhook-cert-mode=self-signed. |
--webhook-service-namespace | string | (empty) | Namespace the webhook Service lives in. Empty falls back to --leader-election-namespace, then to in-cluster downward API. |
--webhook-validating-config-name | string | (empty) | Name of the ValidatingWebhookConfiguration whose caBundle this operator patches. Required when --webhook-cert-mode=self-signed. |
See Admission webhook
for the full failurePolicy
trade-off and cert rotation details.
Leader election
| Flag | Type | Default | Description |
|---|---|---|---|
--leader-election | bool | true | Enable controller-runtime leader election so only one operator replica reconciles at a time. Honored only when --enable-flux-integration is set. |
--leader-election-id | string | jaas-operator | Lease object name used for leader election. Must be unique across JaaS installations sharing a namespace. |
--leader-election-namespace | string | (empty) | Namespace holding the leader-election Lease. Empty defaults to the operator pod's namespace. |
Observability
Metrics
| Flag | Type | Default | Description |
|---|---|---|---|
--metrics-bind-address | string | :8083 | Bind address for the controller-runtime Prometheus metrics endpoint. Use "0" to disable. The default avoids the conflict between controller-runtime's built-in :8080 and the jsonnet HTTP server. |
Tracing
| Flag | Type | Default | Description |
|---|---|---|---|
--tracing-endpoint | string | (empty) | OTLP gRPC collector host:port (e.g. otel-collector.observability.svc:4317). Empty disables tracing entirely. |
--tracing-insecure | bool | false | Skip TLS when dialing the OTLP collector. Use only for in-cluster collectors that don't terminate TLS themselves. |
--tracing-sample-ratio | float64 | 1 | TraceID-ratio sampling (0.0..1.0). 1.0 samples every trace. |
Logging and lifecycle
| Flag | Type | Default | Description |
|---|---|---|---|
--log-format | string | json | The log output format to use (json, text) |
--log-level | string | info | The log level to use (debug, info, warn, error) |
--version | bool | false | Print version and exit |