> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes CRD Reference

> Field reference, status schema, and CoPilot object naming conventions for the Aviatrix FirewallPolicy and WebgroupPolicy custom resources.

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

<a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/dcf-kubernetes"}>Distributed Cloud Firewall for Kubernetes</a>
, 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`.         |

<Note>**Note:** Controller 10.1.0 changes the per-rule **Enforcement** control in CoPilot from a two-value slider to a three-value dropdown — **Enforce**, **Monitor**, and **Disable** (see [Distributed Cloud Firewall > Policies](/docs/enterprise/10.1/reference/ui/security/distributed-cloud-firewall#parameter-details)). The **Disable** option removes a rule from policy evaluation entirely. This option is not available for rules created through a Kubernetes CRD in Controller 10.1.0 — CRD-managed rules recognize only **Enforce** and **Monitor** (the latter via the `watch` field above). Support for the **Disable** option on CRD-managed rules is planned for Controller 10.2.0.</Note>

### SmartGroup and WebGroup Reference Resolution

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

1. An inline definition under `spec.smartGroups[]` or `spec.webGroups[]` in the
   same `FirewallPolicy`.
2. 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

```yaml theme={null}
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

```yaml theme={null}
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>`               |

<Warning>
  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.
</Warning>

## Related Topics

* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/dcf-kubernetes"}>Distributed Cloud Firewall for Kubernetes</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard"}>Onboarding Kubernetes Clusters</a>
* <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-prerequisites"}>Kubernetes Prerequisites and Permissions</a>
* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/kubernetes-overview"}>Aviatrix Kubernetes Firewall</a>