Skip to content
Latest (currently 2026.10.2) has the newest features, bug fixes, and CVE patches of Solo Enterprise for agentgateway.

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.
Page as Markdown

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 groupResourcesVerbsPurpose
gateway.networking.k8s.ioGateways, HTTPRoutes, GRPCRoutes, TCPRoutes, TLSRoutes, BackendTLSPolicies, ReferenceGrants, ListenerSetsget, list, watchWatch Gateway API resources to build routing configuration.
gateway.networking.k8s.ioGatewayClassescreate, get, list, patch, update, watchRegister and manage the enterprise-agentgateway GatewayClass.
gateway.networking.k8s.ioStatus subresources (all above)patch, updateReport status on Gateway API resources.
agentgateway.devAgentgatewayBackends, AgentgatewayParameters, AgentgatewayPoliciesget, list, watchWatch agentgateway custom resources.
agentgateway.devStatus subresources (all above)get, patch, updateReport status on agentgateway custom resources.
apiextensions.k8s.ioCustomResourceDefinitionsget, list, watchDiscover installed CRDs at startup.

Data plane lifecycle

These permissions let the controller create and manage proxy Deployments for each Gateway.

API groupResourcesVerbsPurpose
appsDeploymentscreate, delete, get, list, patch, update, watchCreate and manage proxy Deployments for each Gateway resource.
"" (core)Servicescreate, delete, get, list, patch, update, watchCreate and manage proxy Services (LoadBalancer, ClusterIP) for each Gateway.
"" (core)ConfigMapscreate, delete, get, list, patch, update, watchStore proxy configuration and bootstrap data.
autoscalingHorizontalPodAutoscalerscreate, delete, get, list, patch, update, watchManage HPA resources for proxy Deployments.
policyPodDisruptionBudgetscreate, delete, get, list, patch, update, watchManage PDB resources for proxy Deployments.

Secrets and authentication

API groupResourcesVerbsPurpose
"" (core)Secretscreate, delete, get, list, patch, watchRead TLS certificates, API keys, and auth credentials referenced by backends and policies. Create Secrets for license keys and proxy xDS certificates.
"" (core)ServiceAccountscreate, delete, get, list, patch, watchCreate ServiceAccounts for proxy Deployments.
authentication.k8s.ioTokenReviewscreateValidate tokens for the security token service (STS) when token exchange is enabled.

RBAC resource management (enterprise only)

API groupResourcesVerbsPurpose
rbac.authorization.k8s.ioRoles, RoleBindings, ClusterRoles, ClusterRoleBindingscreate, patch, delete, get, list, watchCreate 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 groupResourcesVerbsPurpose
"" (core)Eventscreate, patchEmit Kubernetes events for status changes and errors.
coordination.k8s.ioLeasescreate, get, updateLeader election for high-availability controller replicas.
"" (core)Endpoints, Namespaces, Nodes, Podsget, list, watchDiscover endpoints for routing and read cluster topology.
discovery.k8s.ioEndpointSlicesget, list, watchDiscover endpoints for routing.

Service mesh integration

API groupResourcesVerbsPurpose
networking.istio.ioServiceEntries, WorkloadEntriesget, list, watchDiscover 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 groupResourcesVerbsPurpose
extauth.solo.ioAuthConfigsget, list, watch (+ status update)Read external auth configuration for ext auth policies.
ratelimit.solo.ioRateLimitConfigsget, list, watch (+ status update)Read rate limit configuration for rate limiting policies.
admin.solo.ioSegmentsget, list, watchRead segment configuration for multi-tenancy.
enterprise.solo.ioEnterpriseListenerSetsget, 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 groupResourcesVerbsPurpose
inference.networking.k8s.ioInferencePoolsget, watch, listWatch InferencePool resources for AI workload routing.
inference.networking.k8s.ioInferencePools/statuspatch, updateReport 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=true

This 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:
    - ALL

Pre-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.

  1. 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"
  2. 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
ValueUse
image.registrySet the default registry for the controller, proxy, ext-auth, rate-limiter, ext-cache, and WAF images.
controller.image.registryOverride the default registry for the controller.
proxy.image.registry, extAuth.image.registry, rateLimiter.image.registry, extCache.image.registry, waf.image.registryOverride the default registry for one runtime-created workload.
image.variantAppend 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: false

The 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.io

A command that returns no output means the rule is no longer granted.