For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
RBAC hardening
Verified : Automated tests passed for: End-to-end run: Every step ran in a fresh test environment and the results were checked.Harden the Kubernetes RBAC permissions for the agentgateway controller.
The Solo Enterprise for agentgateway controller requires a ClusterRole with permissions to manage Gateway API resources, create data plane Deployments, and read Secrets across namespaces. In production environments, you can tighten these permissions to reduce the controller’s blast radius.
This guide explains what each permission category does, why the controller needs it, and how to harden your installation.
Default ClusterRole permissions
The following table summarizes the permissions that the Solo Enterprise for agentgateway ClusterRole grants by default. Permissions are grouped by purpose to help you assess which ones to tighten for your environment.
Controller management
These permissions let the controller manage Gateway API resources and report status.
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
gateway.networking.k8s.io | Gateways, HTTPRoutes, GRPCRoutes, TCPRoutes, TLSRoutes, BackendTLSPolicies, ReferenceGrants, ListenerSets | get, list, watch | Watch Gateway API resources to build routing configuration. |
gateway.networking.k8s.io | GatewayClasses | create, get, list, patch, update, watch | Register and manage the enterprise-agentgateway GatewayClass. |
gateway.networking.k8s.io | Status subresources (all above) | patch, update | Report status on Gateway API resources. |
agentgateway.dev | AgentgatewayBackends, AgentgatewayParameters, AgentgatewayPolicies | get, list, watch | Watch agentgateway custom resources. |
agentgateway.dev | Status subresources (all above) | get, patch, update | Report status on agentgateway custom resources. |
apiextensions.k8s.io | CustomResourceDefinitions | get, list, watch | Discover installed CRDs at startup. |
Data plane lifecycle
These permissions let the controller create and manage proxy Deployments for each Gateway.
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
apps | Deployments | create, delete, get, list, patch, update, watch | Create and manage proxy Deployments for each Gateway resource. |
"" (core) | Services | create, delete, get, list, patch, update, watch | Create and manage proxy Services (LoadBalancer, ClusterIP) for each Gateway. |
"" (core) | ConfigMaps | create, delete, get, list, patch, update, watch | Store proxy configuration and bootstrap data. |
autoscaling | HorizontalPodAutoscalers | create, delete, get, list, patch, update, watch | Manage HPA resources for proxy Deployments. |
policy | PodDisruptionBudgets | create, delete, get, list, patch, update, watch | Manage PDB resources for proxy Deployments. |
Secrets and authentication
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
"" (core) | Secrets | create, delete, get, list, patch, watch | Read TLS certificates, API keys, and auth credentials referenced by backends and policies. Create Secrets for license keys and proxy xDS certificates. |
"" (core) | ServiceAccounts | create, delete, get, list, patch, watch | Create ServiceAccounts for proxy Deployments. |
authentication.k8s.io | TokenReviews | create | Validate tokens for the security token service (STS) when token exchange is enabled. |
RBAC resource management (enterprise only)
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
rbac.authorization.k8s.io | Roles, RoleBindings, ClusterRoles, ClusterRoleBindings | create, patch, delete, get, list, watch | Create RBAC bindings so that proxy ServiceAccounts can read Secrets and ConfigMaps in their namespace. |
Note
The controller does not have the escalate or bind verbs, so it cannot grant permissions beyond its own. However, it can create named RBAC objects with any content within its existing permission set.
Observability and coordination
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
"" (core) | Events | create, patch | Emit Kubernetes events for status changes and errors. |
coordination.k8s.io | Leases | create, get, update | Leader election for high-availability controller replicas. |
"" (core) | Endpoints, Namespaces, Nodes, Pods | get, list, watch | Discover endpoints for routing and read cluster topology. |
discovery.k8s.io | EndpointSlices | get, list, watch | Discover endpoints for routing. |
Service mesh integration
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
networking.istio.io | ServiceEntries, WorkloadEntries | get, list, watch | Discover Istio services and workloads when Istio integration is enabled. |
The controller reads these resources only. The ClusterRole grants no permission on the security.istio.io group, so the controller never reads or writes Istio AuthorizationPolicies.
Enterprise-specific resources
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
extauth.solo.io | AuthConfigs | get, list, watch (+ status update) | Read external auth configuration for ext auth policies. |
ratelimit.solo.io | RateLimitConfigs | get, list, watch (+ status update) | Read rate limit configuration for rate limiting policies. |
admin.solo.io | Segments | get, list, watch | Read segment configuration for multi-tenancy. |
enterprise.solo.io | EnterpriseListenerSets | get, list, update, watch (+ status) | Manage enterprise listener sets. |
Inference extension (optional)
These permissions are only added when the inference extension is enabled in the Helm values (inferenceExtension.enabled: true).
| API group | Resources | Verbs | Purpose |
|---|---|---|---|
inference.networking.k8s.io | InferencePools | get, watch, list | Watch InferencePool resources for AI workload routing. |
inference.networking.k8s.io | InferencePools/status | patch, update | Report status on InferencePool resources. |
Hardening options
Review the following options to harden your default Solo Enterprise for agentgateway environment.
Scope namespace discovery
By default, the controller watches all namespaces. Use the discoveryNamespaceSelectors Helm value to limit which namespaces the controller includes in configuration discovery.
discoveryNamespaceSelectors:
- matchLabels:
agentgateway.dev/discovery: "true"Then, label the namespaces that contain your Gateway, HTTPRoute, and backend resources.
kubectl label namespace agentgateway-system agentgateway.dev/discovery=true
kubectl label namespace my-app agentgateway.dev/discovery=trueThis precaution does not constrain the ClusterRole itself, but it reduces the set of resources the controller actively processes.
Set container and pod security contexts
The Solo Enterprise for agentgateway Helm chart ships with empty securityContext: {} and podSecurityContext: {} by default. The enterprise chart does not apply hardened defaults when these values are empty. Set explicit security contexts in your Helm values to enforce non-root execution and drop capabilities.
podSecurityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
runAsNonRoot: true
capabilities:
drop:
- ALLPre-provision the license Secret
By default, the Helm chart creates a Secret for the license key (licensing.createSecret: true). To manage the license Secret through your own tooling and remove the controller’s need to write this Secret, set licensing.createSecret: false and create the Secret separately.
Create the Secret before installing the chart.
kubectl create secret generic enterprise-agentgateway-license \ -n agentgateway-system \ --from-literal=enterprise-agentgateway-license-key="$AGENTGATEWAY_LICENSE_KEY"In the Helm chart values file, refer to the Secret.
licensing: createSecret: false secretName: "enterprise-agentgateway-license"
The secretKeyRef in the deployment spec uses optional: true, so the controller starts gracefully without the key and logs a license validation failed error rather than crashing.
Control runtime images with Helm values
The top-level image.registry Helm value sets the default image registry for the controller and for the proxy and extension Deployments that the controller creates at runtime. Set a component-specific registry only when a workload must pull from a different registry.
image:
registry: my-registry.example.com/enterprise-agentgateway| Value | Use |
|---|---|
image.registry | Set the default registry for the controller, proxy, ext-auth, rate-limiter, ext-cache, and WAF images. |
controller.image.registry | Override the default registry for the controller. |
proxy.image.registry, extAuth.image.registry, rateLimiter.image.registry, extCache.image.registry, waf.image.registry | Override the default registry for one runtime-created workload. |
image.variant | Append a suffix to the controller, proxy, ext-auth, rate-limiter, and WAF image tags. Set image.variant: fips to deploy the FIPS builds. For more information, see FIPS TLS profile. |
For more information, see the Airgap installation guide.
Disable unused features
Disable Helm features that you do not use to avoid adding unnecessary RBAC rules.
# Disable inference extension if not routing to local AI inference workloads
inferenceExtension:
enabled: false
# Disable token exchange if not using OBO or elicitation flows
tokenExchange:
enabled: false
# Drop the Istio discovery rule when the Istio CRDs are not installed
istio:
enabled: falseThe istio.enabled value controls RBAC generation only. When you set it to false, the ClusterRole omits the networking.istio.io rule that discovers ServiceEntry and WorkloadEntry resources, which is the only rule that grants access to resource kinds that a cluster without Istio does not have. It does not turn off Istio integration in the controller. To change whether gateways join the mesh, use istio.autoEnabled or the spec.istio section of an AgentgatewayParameters resource instead.
Important
Helm accepts a value that the installed chart does not define, so istio.enabled: false succeeds without narrowing anything on a chart version that predates the flag. Confirm the rule is gone after you upgrade. The chart names the ClusterRole after the release namespace, so adjust the name if you installed into a different namespace.
kubectl get clusterrole enterprise-agentgateway-agentgateway-system -o yaml | grep networking.istio.ioA command that returns no output means the rule is no longer granted.