> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/reference/glossary-faq.md). # Glossary and FAQ ## Glossary | Term | Meaning in Kangal | | ---------------------- | ----------------------------------------------------------------------------------------------------- | | API | The control-plane HTTP service used by the console, CLI, data planes, and automation. | | Control plane | Stores desired gateway configuration, identity, policy, audit, and operational state. | | Data plane | Matches and proxies runtime traffic using a versioned configuration bundle. | | Gateway | Tenant-scoped configuration and runtime boundary. | | Service | Logical upstream application attached to routes. | | Route | Request match rules and route-level behavior. | | Upstream | A group of backend targets and load-balancing policy. | | Target | One backend host/port and its health state. | | Consumer | An API client identity. | | Credential | Authentication material associated with a consumer. | | Plugin | Authentication, traffic, transformation, observability, or AI behavior attached at a supported scope. | | Tenant | Primary isolation boundary for organizations, resources, and admin access. | | Workspace | Optional organization boundary inside a tenant. | | Configuration bundle | Tenant-scoped YAML/JSON used for validation, diff, import, and sync. | | Configuration snapshot | Stored tenant configuration created before a sync or by an operator. It is not a database backup. | | Rollout snapshot | Private, lossless gateway checkpoint used for data-plane rollout and exact rollback. | | Last-known-good | Most recent acknowledged data-plane config eligible for offline continuity or rollback. | | ACK/NACK | Data-plane report that a config was applied or rejected. | | Anti-rollback anchor | Trust state stored separately from the data-plane cache to reject older signed bundles. | | Durable job | Redis Streams job with at-least-once delivery, lease takeover, retry, and dead-letter behavior. | | Dead letter | Job that exhausted retries or had an invalid payload and requires operator review. | | Evidence | Immutable external observation reference, digest, and validity window used by DR controls. | | Fencing | Proving the previous writer or traffic owner can no longer accept conflicting work. | | Promotion | Two-phase DR transition to another effective region. | | RPO | Maximum acknowledged data/work interval allowed to be lost. | | RTO | Time from incident declaration/detection to restored verified service. | | Liveness | `/health`; proves the API process can answer HTTP. | | Readiness | `/ready`; proves the API can currently ping MongoDB and Redis. | | Immutable image | Image selected by a release tag or digest that is not overwritten. | | Chart version | SemVer version of the Helm package and values/template contract. | | App version | Product release identifier carried by the chart. | ## Frequently asked questions ### Is Docker Compose supported for production? No. The supplied Compose stack is for local development and isolated demonstrations. It contains local-only defaults and single-node dependencies. Use the signed production Helm release with externally operated MongoDB, Redis, secrets, TLS, monitoring, and backups. ### What is the source of truth? MongoDB is the control-plane source of truth. Redis contains shared runtime state, sessions, caches, and durable-job data when enabled. Data-plane cache supports bounded offline continuity but is not authoritative control-plane storage. ### Why can `/health` pass while `/ready` fails? `/health` only confirms that the API process answers. `/ready` also pings MongoDB and Redis. This separation keeps a dependency outage from causing unnecessary process restarts while removing the pod from ready endpoints. ### Is a configuration snapshot a backup? No. A public configuration snapshot covers the declarative tenant bundle and is useful for preview and rollback. A rollout snapshot is a private gateway-scoped checkpoint. Neither replaces MongoDB/Redis backup, release artifacts, external secrets, or infrastructure recovery. ### Why does exact rollback require a MongoDB replica set or sharded cluster? Gateway rollback replaces multiple related collections. Kangal uses a transaction so all changes commit or none do. Without transaction support, the operation fails before the first write rather than leave partially restored state. ### Can Redis be rebuilt after loss? Some counters and caches can. Sessions and shared rate-limit state are disrupted, and durable stream jobs may be lost or repeated depending on persistence and recovery. Treat Redis according to the strictest enabled feature RPO, not as universally disposable. ### How is a regional promotion coordinated? Kangal validates active-passive policy, fresh evidence, promotion generations, fencing signatures, quorum, and audit. Approved external controllers replicate data, fence the old writer, switch traffic, and submit evidence through the two-phase promotion procedure. ### Where should production secrets live? In a managed secret system delivered through pre-existing Kubernetes Secrets, projected files, or workload identity. Do not put values in Git or Helm values. Kangal encrypts and redacts supported stored fields, but operators must still manage source credentials, rotation, access policy, and legacy records. ### What does `kangalctl sync` do? It validates desired config, compares it with live tenant state, produces a dry-run preview, optionally creates a pre-apply snapshot, and imports changes. It is dry-run by default; `--apply` is required to write. ### Does Helm rollback restore data? No. Helm rollback changes Kubernetes release resources. Database, Redis, and Kangal configuration restoration require separate approval and procedures. ### Which API base path should automation use? Use the versioned admin base path `/api/v1/admin` for automation. Use `/admin` only where an existing documented workflow explicitly requires that path. ### How are background jobs delivered? Production uses Redis Streams consumer groups with at-least-once delivery. A job may complete an external side effect before acknowledgement fails, so handlers and replay procedures must use idempotency keys. ### What must be attached to a support case? Provide UTC timestamps, environment, release tag and commit, chart/Helm revision, component and pod, tenant/gateway identifiers where approved, request/correlation ID, redacted logs, status codes, config versions/checksums, and actions already taken. Never include tokens, cookies, connection strings, private keys, or customer payloads. ### How is a release support window determined? Use the selected release notes and your commercial or support agreement. An image tag identifies an artifact; it does not by itself define support or end-of-life dates. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/reference/glossary-faq.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.