GatewaySettings¶

Overview¶

The GatewaySettings custom resource configures tenant-specific traffic settings for Gateway and EgressGateway resources. It defines Source NAT (SNAT) pools and specifies how ingress and egress traffic should be handled. This custom resource references infrastructure elements — such as IPAM pools and networks — defined in a separate Infra CR, which enables modular and reusable network design.

Scope and persona¶

Scope: Namespaced. Must be deployed in the same namespace as the Gateway or EgressGateway that references it.
Persona: Cluster operator or tenant network administrator.

API details¶

Property	Value
API group	`gateway.k8s.f5.com`
API version	`v1alpha1`
Kind	`GatewaySettings`
Short name	`gws`
Scope	Namespaced

Spec fields¶

The spec must include at least one of ingressConfig or egressConfigs (or both).

sourceNATPools¶

Defines SNAT pools available for use by ingress and egress configurations. SNAT pool addresses are auto-generated by IPAM from the pools referenced in the Infra CRD.

Field	Type	Required	Default	Description
`name`	string	Yes	—	Name of the SNAT pool. Max 255 characters.
`vrfRef.name`	string	No	—	Reference to a VRF for this SNAT pool. If not provided, the default VRF is used.
`ipamRefs[].name`	string	Yes	—	Name of an IPAM configuration entry in the referenced Infra CRD (`infra.spec.ipams[].name`).
`shared`	boolean	No	`false`	When `true`, enables SNAT address sharing across multiple TMMs.

ingressConfig¶

Configuration for handling incoming traffic. Contains a single defaultListenerNetwork object.

defaultListenerNetwork¶

Field	Type	Required	Default	Description
`ipamRefs[].name`	string	Yes	—	Name of an IPAM configuration entry in the Infra CRD (`infra.spec.ipams[].name`). Listener addresses are auto-generated from these pools.
`networkRefs[].name`	array	No	—	Name of a network entry in the Infra CRD (`infra.spec.networks[].name`). The selected network provides the VLAN/VXLAN context used when programming Ingress behavior.
`vrfRef.name`	string	No	—	Reference to a VRF for this listener network. If not provided, the default VRF is used.
`sourceNATConfig`	object	No	—	SNAT configuration for the listener network.

sourceNATConfig (ingress)¶

Field	Type	Required	Default	Description
`type`	string	Yes	`"Automap"`	SNAT mode. Accepted values: `Automap`, `None`, `Pool`.
`sourceNATPoolRef.name`	string	Conditional	—	Name of a `sourceNATPools[]` entry in this GatewaySettings. Required when `type` is `Pool`. Must not be set otherwise.

egressConfigs¶

An array of one or more named egress configurations for handling outgoing traffic.

Field	Type	Required	Default	Description
`name`	string	Yes	—	Name of this egress configuration. Max 255 characters. This name is referenced by the `sectionName` field in EgressGateway CRs.
`vrfRef.name`	string	No	—	Reference to a VRF for this egress configuration.
`networkRef.name`	string	No	—	Name of a network entry in the Infra CRD (`infra.spec.networks[].name`). The selected network provides the VLAN/VXLAN context used when programming egress behavior.
`sourceNATConfig`	object	Yes	—	SNAT configuration for the egress path.
`hardwareAcceleration`	string	No	`"none"`	Preferred acceleration mode for the Packet Velocity ASIC (PVA). Accepted values: `none`, `full`, `assisted`, `dedicated`.

sourceNATConfig (egress)¶

Field	Type	Required	Default	Description
`type`	string	Yes	`"Automap"`	SNAT mode. Accepted values: `Automap`, `None`, `Pool`, `UseIngressAddress`.
`sourceNATPoolRef.name`	string	Conditional	—	Name of a `sourceNATPools[]` entry in this GatewaySettings. Required when `type` is `Pool`. Must not be set otherwise.

SNAT mode descriptions:

Mode	Behavior
`Automap`	Default. Automatically maps egress traffic to available SNAT addresses.
`None`	Disables SNAT for egress traffic.
`Pool`	Uses a specific SNAT pool referenced by `sourceNATPoolRef`.
`UseIngressAddress`	Uses the ingress path source address as the SNAT address for egress traffic. Available for egress only.

Configuration patterns¶

Pattern	What to configure
Minimal ingress	Set only `ingressConfig.defaultListenerNetwork.ipamRefs` for listener address allocation.
Routed ingress	Add `networkRefs` and `vrfRef` to the `defaultListenerNetwork`.
Deterministic SNAT (ingress)	Set `sourceNATConfig.type` to `Pool` and provide `sourceNATPoolRef`.
Simple egress	Set `egressConfigs` with a `name` and `sourceNATConfig` type `Automap`. The product creates VXLAN tunnels internally.
Egress with specific path	Add `networkRef` for a specific egress network and `vrfRef` for route domain control.
Combined ingress and egress	Configure both `ingressConfig` and `egressConfigs`, with shared or distinct `sourceNATPools`.
Egress-only deployment	Configure only `egressConfigs`.
Ingress-only deployment	Configure only `ingressConfig`.

Status fields¶

The controller populates the status section after reconciliation.

Top-level status¶

Field	Type	Description
`observedGeneration`	integer	Most recent `metadata.generation` observed by the controller.
`conditions[]`	array	Top-level conditions. Max 8 conditions.

Condition types¶

Type	Description
`Accepted`	The resource is syntactically valid and accepted by the controller.
`ResolvedRefs`	All referenced resources (Infra, SNAT pools) have been resolved.

Known reason values¶

Programmed, UserError, DependencyMissing.

Per-resource status¶

Status section	Description	Max items
`ingressConfig`	Sub-status for the ingress configuration. Includes `observedGeneration`, `allocatedListenerAddresses` (max 256 entries), and `conditions`.	—
`egressConfigs[]`	Sub-status for each egress configuration, keyed by `name`. Includes `observedGeneration` and `conditions`.	64
`sourceNATPools[]`	Sub-status for each SNAT pool, keyed by `name`. Includes `observedGeneration`, `allocatedIPCount`, and `conditions`.	64

Printer columns¶

When you run kubectl get gatewaysettings, the following columns display:

Column	Source
Accepted	`.status.conditions[?(@.type=="Accepted")].status`
ResolvedRefs	`.status.conditions[?(@.type=="ResolvedRefs")].status`
Age	`.metadata.creationTimestamp`

Example¶

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: my-gateway-settings
  namespace: f5-gateways
spec:
  # Source NAT pools
  sourceNATPools:
    - name: egress-snat
      ipamRefs:
        - name: server-pool
      shared: false

  # Ingress configuration
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: listener-pool
      sourceNATConfig:
        type: Automap

  # Egress configuration
  egressConfigs:
    - name: default-egress
      networkRef:
        name: tmm-server
      sourceNATConfig:
        type: Pool
        sourceNATPoolRef:
          name: egress-snat