What is the difference between Kong Custom Entities and standard Kubernetes CRD references in an ingress controller?

Kong Custom Entities let teams configure certain plugins declaratively through CRDs, which keeps plugin configuration closer to the Kubernetes control plane. Standard CRD references are the underlying resource links used by the controller and adjacent tooling. The practical difference is that Custom Entities simplify plugin management, while CRD references describe how the controller resolves and publishes its resources.

How Kong Custom Entities differ from standard Kubernetes CRD references

Kong Custom Entities are a declarative convenience layer for specific Kong plugin and configuration workflows. Standard Kubernetes CRD references are the controller’s native object links and relationship pointers. The difference matters because one is about simplifying day-to-day plugin management, while the other is about how the controller discovers, resolves, and publishes the underlying resources.

What each mechanism is doing in the control plane

In practice, Kong Custom Entities are meant to make higher-level Kong configuration feel like part of the Kubernetes API surface. They are useful when teams want to define plugin intent alongside other cluster resources, keep configuration versioned in Git, and let the controller translate that intent into Kong-specific behavior.

CRD references are more structural. They describe the actual Kubernetes objects and relationships that the controller watches and reconciles, so they are part of the plumbing that makes declarative management work. In other words, the reference is the path the controller follows, while the Custom Entity is the user-facing abstraction built on top of that path.

That distinction is important for operators because it separates container security guidance concerns from controller-specific configuration semantics. The controller still depends on Kubernetes resource integrity, but Custom Entities reduce the burden of hand-wiring plugin details into multiple places.

What changes in day-to-day operations

The operational difference is mainly about usability and coupling. Custom Entities reduce friction for platform teams by giving them a more compact, declarative way to manage Kong behavior without exposing every internal reference pattern. Standard CRD references are better understood as the durable schema-level relationships that keep the controller’s reconciliation model consistent.

That means Custom Entities usually improve readability and repeatability, especially when many plugins or environments are involved. CRD references matter more when you need to reason about exact object ownership, reconciliation order, or how a controller resolves one resource into another. If the question is “what should a platform engineer edit?”, the answer often points to the Custom Entity. If the question is “what does the controller actually consume?”, the answer points to the CRD reference.

This is the same practical split you see in broader Kubernetes-oriented identity and workload patterns, where operators care both about the abstraction they manage and the underlying object that enforces it. For that reason, teams often pair controller docs with a workload-identity perspective such as Cloud Workload Identity Guide when their ingress or plugin design depends on external service access.

When the difference becomes material

The difference becomes material when configuration sprawl, ownership boundaries, or rollback behavior starts to matter. Custom Entities can hide complexity from application teams, but that also means operators need a clear source of truth for what the controller ultimately generates or resolves. Standard CRD references expose that plumbing more directly, which is useful for debugging, audits, and controller interoperability.

In larger environments, the risk is not usually the abstraction itself. The risk is assuming the abstraction and the underlying reference model behave identically in every controller path. They do not, and that can affect portability, troubleshooting, and how confidently you can promote configuration between clusters or environments.

For operators who need a concrete security baseline for containerized control planes, NIST SP 800-190 Container Security is the most directly relevant external reference in the supplied pool because it frames orchestrator and runtime risk in a way that aligns with controller-managed resources.

Risk and Threat Considerations

Configuration abstraction can obscure the real access path, especially when a declarative object maps to a more privileged controller action under the hood. If teams treat Custom Entities as harmless metadata, they can miss the fact that a malformed or overbroad resource can still drive meaningful changes in the ingress layer.

Failure mechanism: A controller may reconcile a seemingly simple declarative object into broader configuration changes than operators intended, especially when ownership, naming, or reference integrity is weak. Misunderstanding that translation layer can create blind spots in review, drift detection, and environment separation.

Impact: The practical impact is misconfiguration, unexpected exposure, or harder incident triage when the published Kubernetes object does not obviously reveal the controller action it triggers. In shared platforms, that can also complicate change approval because reviewers may inspect the wrong layer of the stack.

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 governance and control requirements practitioners need to meet.

Framework	Control / Reference	Relevance
NIST SP 800-53 Rev 5	CM-2 — Baseline Configuration	Ingress controller objects need controlled, versioned configuration definitions.
	CM-6 — Configuration Settings	The question hinges on how controller-managed settings are expressed and resolved.
	AC-6 — Least Privilege	Declarative controller objects can widen effective change authority if overexposed.
Recommendation — Define approved Kong resource baselines and review changes before promotion. Standardize Kong configuration settings and validate the reconciled output. Restrict who can modify controller resources and plugin declarations.
CIS Controls v8	CIS-4 — Secure Configuration of Enterprise Assets and Software	The distinction is about safe configuration of controller-managed resources.
	CIS-5 — Account Management	Controller-managed access to configuration depends on tightly governed operator accounts.
Recommendation — Harden and review ingress-controller configuration before deployment. Limit and review who can edit Kong and Kubernetes configuration resources.

Practitioner Guidance

What to verify: Confirm which layer is the source of truth for policy decisions, the Custom Entity, the CRD reference, or the reconciled Kong object. If those layers can diverge operationally, treat that as a governance issue rather than a naming preference.

Common mistake: Teams often standardize on the friendlier abstraction and stop validating the controller output. That works until a plugin, reference, or reconciliation rule behaves differently across environments.

Practitioner takeaway: Use Custom Entities for operator-friendly declarative management, but always validate the lower-level CRD and controller behavior when portability, troubleshooting, or change safety matters.