Kubernetes CRD Reference

This page is the field-level reference for the two Aviatrix custom resources that DCF reconciles inside a Kubernetes cluster: FirewallPolicy and WebgroupPolicy. Use it alongside Distributed Cloud Firewall for Kubernetes, which covers the day-to-day authoring workflow.

Policy as Code

The CRDs make Aviatrix DCF policy a first-class Kubernetes object, which turns network security into policy as code: declarative, versioned, and governed by the same controls your platform team already trusts. Application teams shift left and own the egress posture for their workload alongside the workload itself. Policies are declared in Git, applied with kubectl, and reviewed in a pull request, instead of filing a ticket with the network team for every change. Because each policy is a Kubernetes resource, you can govern it end-to-end:

Kubernetes RBAC scopes who can create, edit, or delete a FirewallPolicy in each namespace, so a team can author its own egress rules without touching another team’s.
Git-based review (CODEOWNERS, branch protection, PR approvals) makes every policy change an auditable, reviewable artifact before it ever reaches the cluster.
Admission policy engines such as Open Policy Agent (OPA/Gatekeeper) or Kyverno enforce guardrails on the resources themselves. For example, the engine can reject any rule that combines action: permit with destinationSmartGroups: [{ cidr: 0.0.0.0/0 }], require a tlsProfile on TLS-inspected rules, or forbid wildcard allowedDomains in production namespaces.

The Aviatrix Controller stays the single source of truth for the data plane. The CRDs give application teams a safe, governed seat at the policy table.

API Group

Both resources are installed by the Aviatrix k8s-firewall Helm chart and served under the API group networking.aviatrix.com/v1alpha1.

FirewallPolicy

A FirewallPolicy defines an ordered list of DCF rules along with any SmartGroups and WebGroups they reference. The Aviatrix Controller reconciles the resource into a single ruleset on the controller side.

Top-level Fields

Field	Type	Notes
`spec.rules[]`	list	Required. Evaluated top-down in the order they appear.
`spec.smartGroups[]`	list	Optional. Inline SmartGroup definitions referenced by `rules[]`.
`spec.webGroups[]`	list	Optional. Inline WebGroup definitions referenced by `rules[]`.

Rule Fields

Field	Allowed values	Notes
`name`	string	Required. Must be unique within the policy.
`action`	`permit`, `deny`, `intrusion_detection_permit`	`intrusion_detection_permit` permits the flow but inspects it.
`protocol`	`tcp`, `udp`, `icmp`, `any`	Required.
`port`	integer	Optional. Single port when used alone.
`endPort`	integer	Optional. When set with `port`, defines an inclusive port range.
`selector.matchLabels`	label map	Source workloads by Kubernetes label. Mutually exclusive with `selector.service`.
`selector.service`	service name	Source workloads = the endpoints of the named Service.
`destinationSmartGroups[]`	list of `{name}` or `{uuid}`	Required. At least one entry.
`webGroups[]`	list of `{name}` or `{uuid}`	Optional. Adds FQDN-based filtering to the rule.
`decryptPolicy`	`decryptAllowed`, `decryptNotAllowed`	Required when `webGroups[]` is set and TLS inspection is desired.
`tlsProfile`	profile name	Must already exist on the controller.
`flowAppRequirement`	`tlsRequired`, `tlsNotRequired`	Optional flow-application constraint.
`logging`	boolean	When `true`, log entries are produced for matches.
`logProfile`	`start`, `end`, `start/end`	Must reference a log profile that already exists on the controller.
`watch`	boolean	When `true`, the rule is in watch (log-only) mode regardless of `action`.

SmartGroup and WebGroup Reference Resolution

A name reference under destinationSmartGroups[] or webGroups[] is resolved in this order:

An inline definition under spec.smartGroups[] or spec.webGroups[] in the same FirewallPolicy.
A SmartGroup or WebGroup that already exists on the Aviatrix Controller (created by Terraform, the UI, or another team).

A uuid reference skips name resolution and is used directly. This resolution order lets you reuse shared controller-side groups (for example, corporate-cidrs or production-vpcs) without redefining them in every cluster.

Example

apiVersion: networking.aviatrix.com/v1alpha1
kind: FirewallPolicy
metadata:
  name: payments-egress
  namespace: payments
spec:
  rules:
    - name: allow-stripe
      selector:
        matchLabels:
          app: payments-api
      action: permit
      protocol: tcp
      port: 443
      decryptPolicy: decryptAllowed
      tlsProfile: "Default SNI Verify"
      destinationSmartGroups:
        - name: anywhere
      webGroups:
        - name: stripe
      logging: true
      logProfile: start/end

  smartGroups:
    - name: anywhere
      selectors:
        - cidr: 0.0.0.0/0

  webGroups:
    - name: stripe
      domains:
        - "api.stripe.com"
        - "*.stripe.com"

WebgroupPolicy

A WebgroupPolicy is a shorthand for the common case of “let workload X reach domain list Y over TLS.” Each WebgroupPolicy reconciles to a single permit rule with a target SmartGroup, a WebGroup, and TLS inspection.

Spec Fields

Field	Allowed values	Notes
`selector.matchLabels`	label map	Required. Source workloads by Kubernetes label.
`allowedDomains[]`	list of FQDNs	Required. Wildcard prefixes such as `*.example.com` are supported.
`decryptPolicy`	`decryptAllowed`, `decryptNotAllowed`	Required for TLS inspection.
`tlsProfile`	profile name	Must already exist on the controller.
`logging`	boolean	When `true`, log entries are produced for matches.
`logProfile`	`start`, `end`, `start/end`	Must reference a log profile that already exists on the controller.

Example

apiVersion: networking.aviatrix.com/v1alpha1
kind: WebgroupPolicy
metadata:
  name: frontend-allowlist
  namespace: web
spec:
  selector:
    matchLabels:
      app: frontend
  allowedDomains:
    - "google.com"
    - "*.googleapis.com"
  decryptPolicy: decryptAllowed
  tlsProfile: "Default SNI Verify"
  logging: true
  logProfile: start/end

Status Schema

After each reconciliation, the Aviatrix Controller writes the resulting state into .status on the resource. Inspect it with kubectl describe or kubectl get -o yaml.

Field	Description
`status.ruleset`	UUID of the policy list created on the controller. An empty value means reconciliation has not happened or has failed.
`status.attachmentPoint`	UUID of the attachment in the DCF policy tree.
`status.smartGroups[]`	Names and UUIDs of the SmartGroups created or referenced by this resource.
`status.webGroups[]`	Names and UUIDs of the WebGroups created or referenced by this resource.
`status.lastReconciledGeneration`	The `metadata.generation` of the most recent spec the controller has reconciled. If it lags `metadata.generation`, the latest spec change has not been applied yet.

Object Naming in CoPilot

Objects created from CRs follow predictable name patterns so you can locate them by their source resource. The placeholders are: <namespace> (the resource’s Kubernetes namespace), <crName> (the resource’s metadata.name), <clusterId> (the Aviatrix cluster identifier), <sgName> (an inline SmartGroup name), and <wgName> (an inline WebGroup name).

Object in CoPilot	Pattern
Policy list (ruleset)	`firewallpolicylist-<namespace>--<crName>--<clusterId>`
Source SmartGroup (per rule)	`firewallpolicysource-<namespace>--<crName>--<clusterId>--...`
Inline destination SmartGroup	`firewallpolicy-smartgroup-<namespace>--<crName>--<sgName>--<clusterId>`
Inline WebGroup	`firewallpolicy-<namespace>--<crName>--<wgName>--<clusterId>`
WebgroupPolicy WebGroup	`webgrouppolicy-<namespace>--<crName>--<clusterId>`
WebgroupPolicy target SmartGroup	`webgrouppolicy-target-<namespace>--<crName>--<clusterId>`

These objects are owned by the source CR. Do not rename or hand-edit them in CoPilot. The next reconciliation overwrites manual changes. To modify them, edit the source CR and reapply.

Concepts & Architecture

Guides

Reference

Policy as Code

API Group

FirewallPolicy

Top-level Fields

Rule Fields

SmartGroup and WebGroup Reference Resolution

Example

WebgroupPolicy

Spec Fields

Example

Status Schema

Object Naming in CoPilot

​Policy as Code

​API Group

​FirewallPolicy

​Top-level Fields

​Rule Fields

​SmartGroup and WebGroup Reference Resolution

​Example

​WebgroupPolicy

​Spec Fields

​Example

​Status Schema

​Object Naming in CoPilot

​Related Topics

Policy as Code

API Group

FirewallPolicy

Top-level Fields

Rule Fields

SmartGroup and WebGroup Reference Resolution

Example

WebgroupPolicy

Spec Fields

Example

Status Schema

Object Naming in CoPilot

Related Topics