SecPolicy

SecPolicy was developed according to the Gateway Enhancement Proposal (GEP: 2648). SecPolicy CRD, a Gateway extension (gateway.k8s.f5.com), attaches security policies, such as ACL policies (F5BigFwPolicy), DOS Policies (F5BigDdosGlobal) and F5BigLogProfile to Gateway API objects. The YAML file defines a CustomResourceDefinition (CRD) for Kubernetes to create and manage custom resources with the specified schema and behavior.

The specification section in the YAML file includes these two arrays:

  • extensionRefs: Represents external resource configurations (For example, F5BigFwPolicies) that apply to specific Gateway resources in the cluster.

  • targetRefs: Specifies Gateway/Gateway Listener/GatewayClass resources that will receive the configurations from the extensionRefs.

According to GEP: 2648, the status.ancestors section is implemented to show the status of targetRefs attachments.

Note

Perform Custom Resource (CR) operations only when the controller is in a running state.

BNKSecPolicy configuration guidelines

Target references

  • You can attach a SecPolicy with an extensionRef of type F5BigDdosGlobal to a GatewayClass target only.

  • You can attach a SecPolicy to multiple objects using the targetRefs array field. However, you can attach it to only one GatewayClass.

  • You can define a maximum of 16 targetRefs in a single SecPolicy. A GatewayClass in targetRefs is valid only when you apply the SecPolicy in the controller’s namespace.

  • Attach only one SecPolicy to each target (GatewayClass, Gateway, or Gateway Listener). If multiple SecPolicies target the same resource, a conflict occurs. Resolve conflicts using the “oldest by creation date wins” policy as outlined in GEP-2648.

Extension references

  • Every SecPolicy must include at least one of the following in its extensionRefs array: F5BigFwPolicy, F5BigDdosGlobal, or F5BigLogProfile.

  • You can reference the same F5BigFwPolicy or F5BigLogProfile in multiple SecPolicy custom resources.

Namespace requirements

  • Deploy all extensionRef custom resources and the custom resources they reference in the same namespace as the SecPolicy. This includes:

    • F5BigLogProfile and its referenced F5BigLogHslpub

    • F5BigFwPolicy and its referenced F5BigFwRuleList

  • If cross-namespace targeting is not needed, place all related custom resources (Gateway, EgressGateway, SecPolicy, and security policy extension CRs) in the same namespace and omit the SectionName in the GatewayClass.

Cross-namespace targeting

To target a Gateway or EgressGateway in a different namespace, apply the following label to the target resource or its namespace, with the value set to the SecPolicy’s namespace:

labels:
  secpolicy.gateway.k8s.f5.com/allowed-cross-namespace: "sec-policies"

All matching resources within that namespace can then be targeted. Labels on the Gateway or EgressGateway take precedence over namespace-level labels.

The BNKSecPolicy CR supports general extensions. The CR can reference resources such as F5BigFWPolicy, F5BigDdosGlobal and F5BigLogProfile. This image illustrates the scope of the BNKSecPolicy CR.

SecPolicy

CR Parameters

This section provides a description and default value of the parameters in the SecPolicy CR.

metadata

Parameter

Description

name

The unique name identifying the resource. Example: secpolicy-gateway, secpolicy-gatewayclass.

namespace

The Kubernetes namespace in which the policy object is applied. It can be the CNE Controller’s namespace (e.g. f5-bnk) or the application namespace.

spec

Parameter

Type

Description

Default

extensionRefs

array

Array of references to extension resources that should be applied to the targetRefs resources. Only specific kinds are allowed and each kind can appear only once. Max items: 3. List is treated as a map keyed by kind.

[]

extensionRefs[].group

string

API group of the referenced extension resource. Max length 255. Pattern: ^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$

k8s.f5net.com

extensionRefs[].kind

string

Kind of the referenced extension resource. Allowed values: F5BigFwPolicy, F5BigLogProfile, F5BigDdosGlobal. Min length 1, max length 63. Required.

(none)

extensionRefs[].name

string

Name of the referenced extension resource. Max length 255. Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$. Required.

(none)

targetRefs

array

Array of references to resources the extensionRefs should be applied to. Can reference only Gateway or GatewayClass. Min items: 1. Max items: 16. Immutable after creation (cannot be modified).

(none)

targetRefs[].group

string

API group of the target resource. Max length 255. Pattern: ^$^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

gateway.networking.k8s.io

targetRefs[].kind

string

Kind of the target resource. Allowed values: Gateway, GatewayClass. Min length 1, max length 63. Required.

Gateway

targetRefs[].name

string

Name of the target resource. Min length 1, max length 255. Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$. Required.

(none)

targetRefs[].namespace

string

Specifies the namespace of the target resource. Max length: 63; Pattern: ^$^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Note: If omitted (empty string), it defaults to the namespace of this SecurityPolicy.

""

targetRefs[].sectionName

string

Section within the target. For Gateway, this indicates a listener name. Must be empty/omitted when kind is GatewayClass. Max length 253.

""

status

The status section is controller-populated and shows current state of SecPolicy.

Parameter

Type

Description

Default

ancestors

array

List of ancestor resources (usually Gateways) that are targets of the policy, plus conditions indicating attachment/status per ancestor.

(none)

descendants

array

List of descendant/extension resources associated with the policy, plus conditions indicating status per descendant.

(none)

Spec validation rules (from CRD)

Rule

Effect

If extensionRefs includes kind: F5BigDdosGlobal, targetRefs[].kind must be GatewayClass (no Gateway allowed).

Prevents attaching F5BigDdosGlobal to a Gateway target.

targetRefs cannot be modified after creation (self == oldSelf).

targetRefs is immutable.

sectionName must be unique when targetRefs includes 2+ references to the same target.

Avoids duplicate target entries with same section.

Per-item: if targetRefs[].kind == GatewayClass, then sectionName must be "" (or omitted).

Enforces GatewayClass restriction.

Samples of status section

The status section shows the current state of SecPolicy.

SecPolicy with F5BigLogProfile attached to Gateway

Sample SecPolicy CR with F5BigLogProfile attached to Gateway:

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: SecPolicy
metadata:
  name: secpolicy-gateway
  namespace: gatewayns
spec:
  extensionRefs:
  - group: k8s.f5net.com
    kind: F5BigLogProfile
    name: logprofile
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: f5-gateway
    sectionName: ""

The status section in this YAML code provides ancestors block to indicate the success state of the custom resource.

status:
  ancestors:
  - ancestorRef:
      group: gateway.networking.k8s.io
      kind: Gateway
      name: f5-gateway
      namespace: gatewayns
    conditions:
    - lastTransitionTime: "2026-03-18T09:00:16Z"
      message: Gateway CR "gatewayns"/"f5-gateway" exists
      observedGeneration: 1
      reason: ResolvedRef
      status: "True"
      type: ResolvedRefs
    controllerName: f5.com/f5-bnk-f5-cne-controller
  descendants:
  - conditions:
    - lastTransitionTime: "2026-03-18T08:58:41Z"
      message: F5BigLogProfile CR "gatewayns"/"logprofile" exists
      observedGeneration: 1
      reason: ResolvedRef
      status: "True"
      type: ResolvedRefs
    descendantRef:
      group: k8s.f5net.com
      kind: F5BigLogProfile
      name: logprofile

SecPolicy with F5BigFWPolicy attached to Gateway Listener

Sample F5SecPolicy CR with F5BigLogProfile attached to Gateway:

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: SecPolicy
metadata:
  name: secpolicy-gateway
  namespace: gatewayns
spec:
  extensionRefs:
  - group: k8s.f5net.com
    kind: F5BigFwPolicy
    name: firewallpolicy-gateway
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: f5-gateway
    sectionName: tcp-listener

The status section in this YAML code provides ancestors and descendants blocks to indicate the success state of the custom resource.

status:
  ancestors:
  - ancestorRef:
      group: gateway.networking.k8s.io
      kind: Gateway
      name: f5-gateway
      namespace: gatewayns
      sectionName: tcp-listener
    conditions:
    - lastTransitionTime: "2026-03-18T09:00:16Z"
      message: Gateway CR "gatewayns"/"f5-gateway" exists
      observedGeneration: 1
      reason: ResolvedRef
      status: "True"
      type: ResolvedRefs
    controllerName: f5.com/f5-bnk-f5-cne-controller
  descendants:
  - conditions:
    - lastTransitionTime: "2026-03-18T08:58:41Z"
      message: F5BigFwPolicy CR "gatewayns"/"firewallpolicy-gateway" exists
      observedGeneration: 1
      reason: ResolvedRef
      status: "True"
      type: ResolvedRefs
    descendantRef:
      group: k8s.f5net.com
      kind: F5BigFwPolicy
      name: firewallpolicy-gateway

SecPolicy with F5BigDdosGlobal attached to GatewayClass

Sample SecPolicy CR with F5BigDdosGlobal attached to GatewayClass:

apiVersion: "gateway.k8s.f5.com/v1alpha1"
kind: SecPolicy
metadata:
  name: secpolicy-gatewayclass
  namespace: f5-bnk 
spec:
  extensionRefs:
    - name: gateway-global-ddos
      group: k8s.f5net.com
      kind: F5BigDdosGlobal
  targetRefs:
    - name: f5-gateway-class
      kind: GatewayClass
      group: gateway.networking.k8s.io

The status section in this YAML code provides ancestors and descendants blocks to indicate the success state of the custom resource.

status:
  ancestors:
  - ancestorRef:
      group: gateway.networking.k8s.io
      kind: GatewayClass
      name: f5-gateway-class-1
      namespace: f5-bnk
    conditions:
    - lastTransitionTime: "2026-03-18T09:57:26Z"
      message: GatewayClass CR "f5-gateway-class-1" exists
      observedGeneration: 1
      reason: ResolvedRef
      status: "True"
      type: ResolvedRefs
    controllerName: f5.com/f5-bnk-f5-cne-controller
  descendants:
  - conditions:
    - lastTransitionTime: "2026-03-18T09:57:26Z"
      message: F5BigDdosGlobal CR "f5-bnk"/"gateway-global-ddos" exists
      observedGeneration: 1
      reason: ResolvedRef
      status: "True"
      type: ResolvedRefs
    descendantRef:
      group: k8s.f5net.com
      kind: F5BigDdosGlobal
      name: gateway-global-ddos