A custom resource used to represent plugin-specific entities inside Kubernetes. It allows arbitrary gateway entities to be defined as declarative objects and delivered through the same configuration flow as services, routes, and plugins. This helps avoid separate database-backed management paths for plugin data.
What KongCustomEntity Is Built to Do
KongCustomEntity is a Kubernetes custom resource pattern for defining plugin-specific gateway objects declaratively. It extends the normal configuration model so custom plugin data can move through the same control plane as routes, services, and plugins.
The practical value is consistency. Instead of splitting plugin state across a separate database-backed workflow, operators can represent gateway-specific entities as Kubernetes-native objects and manage them with the same tooling, review process, and delivery path used for the rest of the gateway configuration.
How It Fits into Kubernetes-Native Gateway Configuration
The key idea is not simply “custom data in Kubernetes,” but custom gateway data that behaves like first-class configuration. That makes the resource part of the desired-state model, where declarative manifests become the source of truth and reconciliation handles distribution.
This is especially useful when plugin logic needs structured metadata, references, or policy inputs that belong with the gateway rather than in an external admin store. The custom resource becomes a bridge between platform configuration and plugin behavior, while still preserving Kubernetes conventions for versioning, rollout, and ownership.
Why Plugin-Specific Entities Need a Dedicated Resource
Gateway plugins often need their own schema, lifecycle, and validation rules. A dedicated custom resource lets those entities be modeled explicitly instead of being flattened into generic annotations or hidden in an auxiliary database.
That distinction matters because custom entities can evolve independently of the core gateway objects. If the plugin configuration is more expressive than a simple key-value setting, a purpose-built resource gives operators a clearer contract for how the data should be created, updated, and consumed.
Operational Consequences for Platform Teams
KongCustomEntity changes the operational model by aligning plugin configuration with GitOps-style delivery and Kubernetes RBAC boundaries. It also makes the gateway configuration easier to audit, replicate, and treat as part of standard cluster operations.
At the same time, the abstraction can increase configuration sprawl if teams define too many entity types without clear ownership or schema discipline. The benefit comes from consistency and declarative control, not from using custom resources for every plugin preference.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
NIST SP 800-53 Rev 5 and CIS Controls v8 set the technical controls, while ISO/IEC 27001:2022 defines the regulatory obligations.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | CM-2 — Baseline Configuration | Custom entities are configuration items that need controlled definition and lifecycle governance. |
| CM-6 — Configuration Settings | The term describes declarative settings that shape gateway behaviour and plugin state. | |
| AU-2 — Audit Events | Declarative custom resources benefit from event logging and traceability for change history. | |
| Recommendation — Define KongCustomEntity objects as controlled configuration items and review changes before promotion. Standardize and validate KongCustomEntity settings before they are applied to the gateway. Log create, update, and delete events for KongCustomEntity objects to preserve traceability. | ||
| ISO/IEC 27001:2022 | A.8.9 — Configuration management | Kubernetes custom resources are governed configuration objects that need controlled change handling. |
| Recommendation — Treat KongCustomEntity manifests as managed configuration and control their lifecycle changes. | ||
| CIS Controls v8 | CIS-4 — Secure Configuration of Enterprise Assets and Software | Declarative gateway entities depend on secure, standardized configuration management. |
| Recommendation — Harden and standardize KongCustomEntity deployment and change processes. | ||
