This resource is part of the v1alpha1 API (an Envoy Gateway extension) and is subject to change. Fields and behavior may change in future releases.
Identity
| |
|---|
| Group | gateway.envoyproxy.io |
| Version | v1alpha1 |
| Kind | SecurityPolicy |
| Scope | Project |
Overview
A SecurityPolicy applies security controls to a Gateway or to a route served by it. It is an Envoy Gateway extension to the Gateway API standard, defined by the Envoy Gateway API, attached to a target resource through a policy reference rather than being embedded in the Gateway itself.
Use it when you want to enforce authentication, authorization, or browser access rules on traffic entering your Project — for example requiring JWT or OIDC login, checking API keys or HTTP Basic credentials, delegating to an external authorization service, or configuring Cross-Origin Resource Sharing (CORS). A single policy attaches to one or more Gateways (or specific listeners/routes) and must live in the same Project as the resources it targets.
Spec fields
Each of the security features below is optional; set the ones you want to enforce. targetRefs selects what the policy applies to.
| Field | Type | Required | Description |
|---|
spec.targetRefs | []Object | No | The Gateway resources this policy attaches to. Attach by direct reference. |
spec.targetRefs[].group | string | Yes | Group of the target resource. |
spec.targetRefs[].kind | string | Yes | Kind of the target resource. |
spec.targetRefs[].name | string | Yes | Name of the target resource. |
spec.targetRefs[].sectionName | string | No | A section within the target: a Gateway listener name, an HTTPRoute rule name, or a Service port name. When unset, targets the whole resource. |
spec.targetSelectors | []Object | No | Attach to resources by label instead of by name (kind required; group, matchLabels, matchExpressions optional). |
spec.targetRef | Object | No | Deprecated single-target reference. Use targetRefs/targetSelectors instead. |
spec.jwt | Object | No | JSON Web Token authentication. Requires providers; set optional to allow missing (but not invalid) tokens. |
spec.oidc | Object | No | OpenID Connect authentication. Requires a client secret; supply clientID (or clientIDRef) and optional cookie settings. |
spec.apiKeyAuth | Object | No | API key authentication. |
spec.basicAuth | Object | No | HTTP Basic authentication. |
spec.extAuth | Object | No | Delegate authorization to an external service. |
spec.authorization | Object | No | Ordered allow/deny rules; defaultAction (Allow or Deny) applies when no rule matches (defaults to Deny). |
spec.cors | Object | No | Cross-Origin Resource Sharing settings (allowOrigins, allowMethods, allowHeaders, exposeHeaders, allowCredentials, maxAge). |
Status fields (read-only)
| Field | Type | Description |
|---|
status.ancestors | []Object | The ancestor resources (usually Gateways) this policy is associated with, and the policy’s status against each. Up to 16 entries; an empty list means the policy applies to nothing. |
Usage
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
name: require-cors
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: my-gateway
cors:
allowOrigins:
- "https://app.example.com"
allowMethods:
- GET
- POST
allowHeaders:
- "*"
allowCredentials: true
maxAge: 1h
datumctl apply -f securitypolicy.yaml --project my-project
datumctl get securitypolicies --project my-project
datumctl describe securitypolicy require-cors --project my-project
Run datumctl explain securitypolicies --recursive to see the full, live field tree for this resource.
