helm-charts/keycloak/values.schema.json

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "title": "keycloak values",
  "description": "Strict values schema (issue #68). additionalProperties is false on every chart-owned object level, so a key this chart does not read is rejected at render time instead of being silently ignored; the objects that go verbatim into the Kubernetes pod spec (probes, security contexts, global, free-form annotation maps) stay open, because the chart does not interpret their contents. The blocks the chart dereferences additionally accept null, because an erased block means 'chart defaults apply' (issue #99) rather than a vanished setting. Note what this schema CANNOT enforce: secrets.databaseSecretRef, keycloak.db.host, ingress.domain and ingress.admin.domain all ship as null and JSON Schema's 'required' tests presence, not null-ness, so a 'required' array would never fire - the enforcement is required() in the templates (issue #18).",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "global": {
      "description": "Helm's conventional cross-chart values. Unused by this chart, kept open so an umbrella install cannot break on it.",
      "type": "object"
    },
    "scaleDown": {
      "description": "true renders the Deployment with replicas: 0 and takes precedence over keycloak.replicas. Also the first half of the minor-upgrade procedure, because Keycloak supports a rolling update only inside a minor line.",
      "type": "boolean"
    },
    "secrets": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "databaseSecretRef": {
          "description": "op:// item path. The item must carry the fields 'username' and 'password' of the PostgreSQL role, which has to be able to create its own schema. Always required - the chart has no default database.",
          "type": ["string", "null"]
        },
        "bootstrapAdminSecretRef": {
          "description": "op:// item path. The item must carry the fields 'username' and 'password' of the TEMPORARY bootstrap administrator. Required while keycloak.bootstrapAdmin.enabled is true.",
          "type": ["string", "null"]
        }
      }
    },
    "keycloak": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "replicas": {
          "description": "Default 2, because an SSO outage takes every dependent login with it. An explicit 0 is allowed and is the per-workload way to stop the release. Above 1 the rolling-update restriction applies: a minor version jump needs the whole cluster down.",
          "type": "integer",
          "minimum": 0
        },
        "db": {
          "description": "May be null / empty: the chart then falls back to its defaults. The host has no default and is enforced by required() in the Deployment.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "vendor": {
              "description": "A Keycloak BUILD option - it is passed to `kc.sh build` in the init container, never to the serving container. dev-file and dev-mem are rejected on purpose: they are Keycloak's development defaults, and an identity provider on an embedded database works until the pod moves. Only 'postgres' is exercised by this chart's CI.",
              "type": "string",
              "enum": ["postgres", "mariadb", "mysql", "mssql", "oracle"]
            },
            "host": {
              "description": "Host of the external PostgreSQL. Required - enforced by required() in the Deployment, because a null here would render an empty KC_DB_URL_HOST and a pod that waits on a connection it can never make.",
              "type": ["string", "null"]
            },
            "port": { "$ref": "#/definitions/port" },
            "database": {
              "type": ["string", "null"],
              "minLength": 1
            },
            "pool": {
              "description": "Connection pool sizes, PER REPLICA. Upstream's db-pool-max-size default is 100; this chart ships 20, because two replicas at 100 ask a default PostgreSQL (max_connections = 100) for twice what it has.",
              "type": ["object", "null"],
              "additionalProperties": false,
              "properties": {
                "initialSize": { "type": ["integer", "null"], "minimum": 0 },
                "minSize": { "type": ["integer", "null"], "minimum": 0 },
                "maxSize": { "type": ["integer", "null"], "minimum": 1 }
              }
            }
          }
        },
        "bootstrapAdmin": {
          "description": "The temporary bootstrap administrator. Switch this off once a permanent administrator exists - it also stops the per-start log line about the initial administrator not being created.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "enabled": { "type": "boolean" }
          }
        },
        "metrics": {
          "description": "A Keycloak BUILD option (metrics-enabled). ON, and not for the metrics: upstream's table of health checks has a 'Requires Metrics' column, and the DATABASE check is the row that says yes. With this false, /health/ready still answers 200 while the database is gone - the urlaubsverwaltung shape (#218), with the dependency hidden behind an option whose name says observability. The price is that /metrics then answers on the management port, unauthenticated, carrying realm and client names - that port is ClusterIP-only and in no Ingress. Switching this off is a decision about whether readiness can fail.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "enabled": { "type": "boolean" }
          }
        },
        "features": {
          "description": "Additional Keycloak feature flags (--features), a BUILD option. A list rather than a comma-separated string, so two entries cannot arrive as one unknown feature name - which Keycloak rejects at build time, inside the init container. The pattern keeps a value out that could not be a feature name.",
          "type": ["array", "null"],
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]*$"
          }
        },
        "cache": {
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "clusterName": {
              "description": "--cache-embedded-cluster-name. null means Keycloak's default, 'ISPN'. Read the comment in values.yaml before setting it: two releases sharing one database MERGE into one cluster unless the names differ, but upstream also warns that cache invalidation does not work between differently-named clusters.",
              "type": ["string", "null"],
              "minLength": 1
            }
          }
        },
        "ports": {
          "description": "May be null / empty: the chart then falls back to its defaults. The Deployment renders these as containerPorts and the Services address them by name, so both follow one source.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "http": { "$ref": "#/definitions/port" },
            "management": {
              "description": "The management port. It carries the unauthenticated /health/* endpoints and optionally /metrics, and all three probes address it by name. It is deliberately in no Ingress.",
              "$ref": "#/definitions/port"
            },
            "jgroups": {
              "description": "JGroups transport port. Declared as a containerPort for the record; jdbc-ping opens direct pod-to-pod connections on it.",
              "$ref": "#/definitions/port"
            }
          }
        },
        "resources": {
          "description": "Resources of the SERVING container. The memory request is not only about scheduling here: the image sizes the JVM heap relative to the container limit (-XX:MaxRAMPercentage=70), so request x limitFactor decides how much memory the application believes it has.",
          "$ref": "#/definitions/resources"
        },
        "build": {
          "description": "The build init container, which runs the one-shot Quarkus augmentation. Its resources are transient - it is gone before the serving container starts - but they count for scheduling, because a pod's effective request is the maximum of its init containers' and the sum of its containers'.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "resources": { "$ref": "#/definitions/resources" }
          }
        },
        "livenessProbe": { "$ref": "#/definitions/probe" },
        "readinessProbe": { "$ref": "#/definitions/probe" },
        "startupProbe": { "$ref": "#/definitions/probe" },
        "securityContext": { "$ref": "#/definitions/securityContext" },
        "podDisruptionBudget": {
          "description": "The first PodDisruptionBudget in this repository. It is rendered only while the effective replica count is >= 2: minAvailable 1 with a single replica forbids every voluntary eviction, so a node drain would block forever on a pod nothing may move.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "enabled": { "type": "boolean" },
            "minAvailable": { "type": "integer", "minimum": 1 }
          }
        },
        "env": { "$ref": "#/definitions/env" },
        "extraVolumes": {
          "description": "Additional pod volumes, rendered verbatim into the pod spec. The ITEMS stay loosely typed on purpose - a volume source can be any of the Kubernetes forms (configMap, secret, persistentVolumeClaim, emptyDir, projected, csi, ...), and a stricter schema here would reject valid configurations rather than catch mistakes; the API server validates the shape anyway. Declaring the key itself is not optional, because the levels above carry additionalProperties: false. Places files, configures nothing: an extra root CA additionally needs KC_TRUSTSTORE_PATHS (a runtime option, so keycloak.env) and a theme additionally needs to be selected per realm in Keycloak's database.",
          "type": ["array", "null"]
        },
        "extraVolumeMounts": {
          "description": "Additional volume mounts, rendered verbatim and TWICE - on the build init container as well as on the serving container (Gitea #88). That is deliberate: a login theme is read at runtime, but an SPI provider JAR must be present while `kc.sh build` writes the provider registry, or it is never registered and nothing reports it. Items loosely typed for the same reason as extraVolumes. Never mount on /opt/keycloak/themes itself - it would hide the image's base, keycloak and keycloak.v2 themes; use a subpath /opt/keycloak/themes/<name>.",
          "type": ["array", "null"]
        }
      }
    },
    "ingress": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "description": "Gates the public Ingress object only (issue #93). Checked in both directions for this chart: ingress.domain is ALSO read as KC_HOSTNAME on the Deployment, so switching the Ingress off frees clusterIssuer but NOT domain - Keycloak refuses to start in production mode without a hostname.",
          "type": "boolean"
        },
        "clusterIssuer": { "type": ["string", "null"] },
        "domain": {
          "description": "The public hostname, a plain host - the chart renders it as the full URL https://<domain> for KC_HOSTNAME, which upstream requires as soon as hostname-admin is in play. Required even with enabled: false.",
          "type": ["string", "null"]
        },
        "className": { "type": ["string", "null"] },
        "annotations": {
          "description": "Extra annotations for the public Ingress, merged with the cert-manager annotation the chart always sets. Free-form keys by nature, so this object stays open.",
          "type": "object"
        },
        "admin": {
          "description": "The administration console on a hostname of its own. NOT AN ACCESS CONTROL: hostname-admin decides which URLs the server generates; upstream states that it does not prevent reaching the Administration REST API through the public hostname, and that restricting that API is reverse-proxy work. The chart renders no deny rule for /admin.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "enabled": { "type": "boolean" },
            "domain": {
              "description": "The admin hostname, a plain host - rendered as https://<domain> for KC_HOSTNAME_ADMIN. Required while enabled.",
              "type": ["string", "null"]
            },
            "className": {
              "description": "null falls back to ingress.className. An internal ingress class here keeps the console off the public controller, which is the useful half of the admin hostname.",
              "type": ["string", "null"]
            },
            "annotations": {
              "description": "Extra annotations for the admin Ingress, merged with the cert-manager annotation. Free-form keys by nature, so this object stays open. Inert in Gateway mode.",
              "type": "object"
            }
          }
        }
      }
    },
    "httpRoute": {
      "description": "Gateway-API alternative to the TWO Ingresses (Gitea #114). Mutually exclusive with ingress.enabled - the render aborts when both are true, naming both value paths. The chart renders only HTTPRoutes with parentRefs; class and certificate sit on the Gateway and belong to the platform. TWO routes, the public hostname and the admin one; the second is gated on ingress.admin.enabled, because that value also sets KC_HOSTNAME_ADMIN on the Deployment and is therefore not an Ingress switch. The Gateway-API CRDs must be present in the cluster, because the chart cannot detect them. NOT COVERED IN THIS MODE: the proxy-buffer-size and proxy-buffers-number annotations this installation relies on - the Gateway API has no counterpart for proxy buffer sizing, and Keycloak's large headers make a too-small buffer answer 502 at the proxy while the application logs success. See values.yaml, httpRoute block.",
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "enabled": { "type": "boolean" },
        "parentRefs": {
          "description": "The Gateway(s) the public route attaches to. Required while httpRoute.enabled is true, enforced by required()-equivalent in the template (an empty list aborts the render) - a JSON Schema \"required\" cannot do it, because the key ships as an empty list and is therefore present. Entries are the Gateway API's ParentReference and are passed through unchanged.",
          "type": "array",
          "items": { "$ref": "#/definitions/parentRef" }
        },
        "hostnames": {
          "description": "Empty means [ingress.domain], so the public hostname has a single source of truth.",
          "type": "array",
          "items": { "type": "string" }
        },
        "admin": {
          "description": "The admin route. Rendered while ingress.admin.enabled is true - the same switch the admin Ingress uses, so the admin hostname is available in both modes.",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "parentRefs": {
              "description": "Empty falls back to httpRoute.parentRefs - the counterpart of ingress.admin.className falling back to ingress.className, because \"which data path\" is a property of the Gateway in this API and not of the route. An internal Gateway here is what an internal ingress class is in the other mode, and still not an access control.",
              "type": "array",
              "items": { "$ref": "#/definitions/parentRef" }
            },
            "hostnames": {
              "description": "Empty means [ingress.admin.domain].",
              "type": "array",
              "items": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "parentRef": {
      "description": "A Gateway API ParentReference, passed verbatim into HTTPRoute.spec.parentRefs. Deliberately left OPEN (no additionalProperties: false), for the same reason probes and security contexts are: Kubernetes owns this schema, the Gateway API adds fields to it across releases, and a closed list here would reject a field only upstream knows about. What the chart can assert is that \"name\" is there - it is required by the API and a reference without it attaches to nothing, which is the silent failure this chart aborts the render over.",
      "type": "object",
      "required": ["name"]
    },
    "port": {
      "type": ["integer", "null"],
      "minimum": 1,
      "maximum": 65535
    },
    "resources": {
      "description": "May be null / empty: the chart then falls back to its default requests and computed limits (issue #99) instead of rendering a container without resource accounting.",
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "limitFactor": {
          "type": "number",
          "exclusiveMinimum": 0
        },
        "requests": { "$ref": "#/definitions/resourceList" },
        "limits": { "$ref": "#/definitions/resourceList" }
      }
    },
    "resourceList": {
      "description": "Both spellings of the ephemeral-storage key are accepted because the resources helper normalizes camelCase to the Kubernetes key.",
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "cpu": { "type": ["string", "number", "null"] },
        "memory": { "type": ["string", "number", "null"] },
        "ephemeral-storage": { "type": ["string", "number", "null"] },
        "ephemeralStorage": { "type": ["string", "number", "null"] }
      }
    },
    "env": {
      "description": "Additive container env entries. An entry repeating a name the chart already sets does not replace it - on an existing release the pair collapses to the chart's own value while helm upgrade reports success. A BUILD option's variable name (KC_DB, KC_HEALTH_ENABLED, KC_METRICS_ENABLED, KC_FEATURES, ...) is refused by the template with a fail: on the serving container it would disagree with what the init container built, and Keycloak answers that by re-augmenting onto a read-only path.",
      "type": ["array", "null"],
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "value": { "type": "string" },
          "valueFrom": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "secretKeyRef": { "$ref": "#/definitions/keyRef" },
              "configMapKeyRef": { "$ref": "#/definitions/keyRef" }
            }
          }
        }
      }
    },
    "keyRef": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "key"],
      "properties": {
        "name": { "type": "string" },
        "key": { "type": "string" }
      }
    },
    "securityContext": {
      "description": "May be null / empty at any level: the chart then falls back to its hardening defaults (issue #99). This chart's fallback reproduces ITS defaults, which deviate from the repo's usual 20000/1000 pair: the published image declares keycloak:x:1000:0 in /etc/passwd and copies the whole install tree with --chown=1000:0, so uid 1000 is the OWNER of everything the process reads. The GROUP is 1000 and not the image's own 0 - counted across the image layer, 521 of 522 entries are owned by 1000:0 with every mode granting the owner full access, so group 0 (upstream's OpenShift arbitrary-uid pattern) buys nothing once the owning uid is pinned, and leaving it out keeps a root GID out of the pod. Every container in the pod, both init containers included, uses the same container context: readOnlyRootFilesystem: true holds throughout, which is the reason the chart has two init containers rather than one writable one.",
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "pod": {
          "description": "Merged onto the chart's pod hardening defaults and rendered as the pod's securityContext; kept open because the chart does not interpret the individual fields.",
          "type": ["object", "null"]
        },
        "container": {
          "description": "Merged onto the chart's container hardening defaults and rendered as the securityContext of every container in the pod; kept open because the chart does not interpret the individual fields.",
          "type": ["object", "null"]
        }
      }
    },
    "probe": {
      "description": "Merged onto the chart's probe defaults and rendered as a container probe; kept open because the chart does not interpret the individual fields. May be null / empty, which means the defaults apply (issue #99) rather than the probe disappearing. The defaults carry the probe's CONTEXT: the port NAME 'management' for all three, and three DIFFERENT paths - /health/live for liveness (no database check), /health/ready for readiness (with one), /health/started for startup. Pointing liveness at /health or /health/ready would restart every pod of the cluster for as long as the database is away.",
      "type": ["object", "null"]
    }
  }
}