> ## 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.

# Distributed Cloud Firewall for Kubernetes

> Aviatrix Distributed Cloud Firewall (DCF) for Kubernetes extends Zero Trust security to containerized workloads across AWS EKS, Azure AKS, Google GKE, and self-managed clusters.

## Overview

Aviatrix Distributed Cloud Firewall (DCF) for Kubernetes extends Zero Trust
security to containerized workloads across AWS EKS, Azure AKS, Google GKE, and
self-managed Kubernetes clusters. This integration provides identity-based
security policies, secure egress control, and unified visibility for Kubernetes
environments.

<Note>
  DCF on Kubernetes Clusters is Generally Available (GA) as of Controller 10.1,
  promoted from Feature Previews.
</Note>

### Key Capabilities

* **Identity-Based Security** — Enforce firewall policies based on Kubernetes
  identities (namespace, pod, service) rather than ephemeral IP addresses.
  Policies automatically follow workloads as they scale, move, or restart.
* **Multicloud Kubernetes Security** — Unified security policies across AWS EKS,
  Azure AKS, Google GKE, and self-managed clusters. Define security once,
  enforce everywhere.
* **Native Kubernetes Integration** — Define firewall policies using Kubernetes
  Custom Resource Definitions (CRDs). Security policies are managed with the
  same `kubectl` and YAML workflows your teams already use.
* **Secure Egress Control** — Prevent unauthorized outbound traffic from
  Kubernetes workloads. Control egress at namespace, pod, and cluster levels
  with domain-based filtering.
* **Advanced NAT and IP Management** — Resolve IP overlap and exhaustion issues
  across multiple Kubernetes clusters with advanced NAT capabilities.

<Note>
  DCF currently enforces rules on traffic from Kubernetes clusters to
  destinations outside the VPC/VNet only.
</Note>

### Supported Kubernetes Distributions

* AWS Elastic Kubernetes Service (EKS)
* Azure Kubernetes Service (AKS)
* Google Kubernetes Engine (GKE)
* Self-managed and private Kubernetes clusters in cloud

## Getting Started

To use DCF for Kubernetes:

1. Meet the
   <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-prerequisites"}>prerequisites</a>
   for your cloud provider.
2. Enable
   <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-resource-discovery"}>Kubernetes Resource Discovery</a>.
3. <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard"}>Onboard your Kubernetes clusters</a>.
   For private clusters, see
   <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/private-kubernetes-cluster-onboard"}>Onboarding Private Kubernetes Clusters</a>.
4. [Enable DCF policies for Kubernetes](#enabling-dcf-policies-for-kubernetes)
5. Optionally, install CRDs for in-cluster policy management.
6. Create
   <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/smartgroups-about"}>SmartGroups</a>
   and DCF rules.

## Enabling DCF Policies for Kubernetes

<Warning>
  The Aviatrix
  [k8s-firewall helm chart](https://github.com/AviatrixSystems/k8s-firewall-charts)
  must be installed in the cluster before onboarding so the CRDs and the
  `avx-controller` ClusterRole are present. See the per-provider onboarding pages
  for installation steps.

  CRD-based policy on **AKS and GKE is implemented in the Controller but does not
  have end-to-end test coverage as of 9.0**. Coverage on EKS is complete. Report
  any issues encountered on AKS or GKE to Aviatrix support.
</Warning>

<Tabs>
  <Tab title="CoPilot UI" icon="mouse-pointer">
    To enable DCF policies for Kubernetes using the CoPilot UI, follow these steps:

    <Steps>
      <Step title="Enable Discovery of Kubernetes Resources">
        On **Groups** > **Settings**, click **Enable** on the **Discovery of Kubernetes Resources** card.

        See <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-resource-discovery"}>Discovery of Kubernetes Resources</a> for more information.
      </Step>

      <Step title="Enable Enforcement on Kubernetes">
        On **Security** > **Distributed Cloud Firewall** > **Settings**, click **Enable** on the **Enforcement on Kubernetes** card.
      </Step>
    </Steps>

    A notification appears to confirm the changes.
  </Tab>

  <Tab title="Terraform" icon="file-code">
    To enable DCF policies for Kubernetes using Terraform, add the following to your Terraform configuration:

    ```hcl theme={null}
    resource "aviatrix_k8s_config" "this" {
      enable_k8s          = true
      enable_dcf_policies = true
    }
    ```
  </Tab>
</Tabs>

***

## Managing Policies with Kubernetes CRDs

DCF policies can be defined directly inside Kubernetes clusters using Custom
Resource Definitions (CRDs). This allows platform teams to manage firewall
policies with the same `kubectl` and GitOps workflows used for application
deployments.

### Installing the CRDs

Register the Aviatrix CRDs to your Kubernetes cluster using the Helm chart:

```bash theme={null}
helm install --repo https://aviatrixsystems.github.io/k8s-firewall-charts k8s-firewall k8s-firewall
```

Verify the CRD registration:

```bash theme={null}
kubectl get crds
```

Expected output includes:

```
NAME                                            CREATED AT
firewallpolicies.networking.aviatrix.com        2025-11-14T07:19:03Z
webgrouppolicies.networking.aviatrix.com        2025-11-14T07:19:05Z
```

### Writing a Firewall Policy

A `FirewallPolicy` CRD defines egress rules for pods matching a label selector.
The following example permits pods with the label `app: dev-pods` in the `dev`
namespace to reach `www.google.com` on any protocol:

```yaml theme={null}
kind: FirewallPolicy
apiVersion: networking.aviatrix.com/v1alpha1
metadata:
  name: test-firewall-policy
  namespace: dev
spec:
  rules:
    - name: test
      logging: true
      selector:
        matchLabels:
          app: dev-pods
      action: permit
      protocol: any
      destinationSmartGroups:
        - name: anywhere
      webGroups:
        - name: checkip
  webGroups:
    - name: checkip
      domains:
        - "www.google.com"
  smartGroups:
    - name: anywhere
      selectors:
        - cidr: 0.0.0.0/0
```

Apply the policy:

```bash theme={null}
kubectl apply -f firewall-policy.yaml
```

### Writing a WebGroup Policy

A `WebgroupPolicy` CRD defines domain-based egress filtering as a standalone
resource. The following example permits pods with the label `app: web-client` in
the `default` namespace to reach specific domains:

```yaml theme={null}
kind: WebgroupPolicy
apiVersion: networking.aviatrix.com/v1alpha1
metadata:
  name: pod-to-web
  namespace: default
spec:
  selector:
    matchLabels:
      app: web-client
  domains:
    - "api.example.com"
    - "cdn.example.com"
```

Apply the policy:

```bash theme={null}
kubectl apply -f webgroup-policy.yaml
```

### Verifying Policy Status

Check policy events to confirm the policy was applied successfully:

```bash theme={null}
kubectl get events -n dev
```

Example output for a successful FirewallPolicy:

```
LAST SEEN   TYPE     REASON                    OBJECT                                MESSAGE
57m         Normal   UpdatePolicyListSuccess   firewallpolicy/test-firewall-policy   Updated policy list for firewall policy with UUID e006b5fe-bf73-46f7-93b8-d76e7325e2eb
```

Example output for a successful WebgroupPolicy:

```
LAST SEEN   TYPE     REASON                    OBJECT                      MESSAGE
41s         Normal   CreateWebGroupSuccess     webgrouppolicy/pod-to-web   Created webgroup with name webgrouppolicy-default--pod-to-web--58c5fb5e
41s         Normal   CreateSmartGroupSuccess   webgrouppolicy/pod-to-web   Created smartgroup with name webgrouppolicy-target-default--pod-to-web--58c5fb5e
41s         Normal   CreatePolicySuccess       webgrouppolicy/pod-to-web   Updated policy webgrouppolicy-default-pod-to-web-58c5fb5e
```

If an event shows a `Warning` type or a `Reason` ending in `Failure`, check that
the CRDs are installed correctly and that the Aviatrix Controller can reach the
cluster.

For the full schema of `.status` (including `ruleset`, `attachmentPoint`,
`smartGroups[]`, and `lastReconciledGeneration`), see
<a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-crd-reference#status-schema"}>Kubernetes CRD Reference</a>.

## Rule Ordering

Three things determine the order in which DCF evaluates rules generated from
your custom resources.

### Within a Single FirewallPolicy

Rules under `spec.rules[]` are evaluated top-down in the order they appear. To
reorder rules, edit the resource and reapply.

### Between Different FirewallPolicy Resources

Multiple `FirewallPolicy` resources have **no deterministic order between each
other**. They are peers in DCF. If two rules in two different `FirewallPolicy`
resources could match the same flow, the result is undefined.

<Tip>
  When ordering between rules matters, place them in the same `FirewallPolicy`
  resource.
</Tip>

### FirewallPolicy vs. WebgroupPolicy

`FirewallPolicy` rules are always evaluated before `WebgroupPolicy` rules. Treat
`WebgroupPolicy` as the catch-all egress allow-list.

### CR-Managed Rules vs. Admin-Authored DCF Rules

All CR-managed rules live inside a single dedicated section of the DCF policy
tree. Your Aviatrix administrator can move that section above or below other
hand-authored DCF rules. You cannot interleave individual CR rules with
hand-authored DCF rules. The placement is per-section.

<Tip>
  For bulk allow or deny lists that should "frame" the Kubernetes rules, keep
  them in admin-authored DCF rules and place the Kubernetes section between
  them.
</Tip>

## Troubleshooting

### Common Pitfalls

| Symptom                                                                | Likely cause                                                                                                                        |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| The CR exists but no objects appear in CoPilot.                        | The cluster is not registered with Aviatrix, or the Kubernetes feature is not enabled.                                              |
| `.status` never populates.                                             | The Helm chart is not installed, or the Aviatrix Controller cannot authenticate to the API server. Check cluster status in CoPilot. |
| `tlsProfile not found` events.                                         | The named profile does not exist on the controller. Create it in CoPilot or Terraform first.                                        |
| Rules from different `FirewallPolicy` resources behave inconsistently. | They are peers. See [Rule Ordering](#rule-ordering). Consolidate or use non-overlapping selectors.                                  |
| Two CRs target the same workload.                                      | Both rules apply, and the order between them is undefined. Avoid overlap.                                                           |

### Reading Reconciliation Events

The Aviatrix Controller emits Kubernetes events on every reconciliation:

```bash theme={null}
kubectl get events -n <ns> --field-selector involvedObject.name=<cr-name>
```

Look for `Warning` events with reasons such as:

* **Spec is invalid**: fix the CR spec.
* **app domain with name X not found**: a `name` reference does not match an
  inline definition or any controller-side AppDomain. Either define it inline or
  have your Aviatrix administrator create it.
* **Failed to update k8s root attachment point**: usually a controller-side
  conflict. The controller retries automatically.

## Updating and Deleting Policies

### Updating a Policy

Edit the resource and run `kubectl apply`. The Aviatrix Controller diffs the new
spec against the previous reconciled state, updates the affected DCF objects,
and removes any AppDomains that are no longer referenced. UUIDs of unchanged
rules are preserved so that features such as bandwidth tracking continue to
work.

### Deleting a Policy

Run `kubectl delete`. A finalizer holds the resource until the controller has
cleaned up the attachment point, policy list, and all AppDomains the resource
created.

### Cluster Offboarding Caveat

If you remove a cluster from Aviatrix while CRs still exist in it:

1. Aviatrix refuses the offboard if any SmartGroup elsewhere still references
   this cluster. Clean those references up first.
2. Once offboarded, the controller stops watching the cluster. CRs in the
   cluster are no longer reconciled, and the DCF objects they previously created
   remain in place.

<Warning>
  To offboard cleanly, delete the CRs first so that the finalizer-driven
  teardown runs, then offboard the cluster.
</Warning>

## Related Topics

* <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-crd-reference"}>Kubernetes CRD Reference</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard"}>Onboarding Kubernetes Clusters</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/private-kubernetes-cluster-onboard"}>Onboarding Private 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/smartgroups-about"}>Creating SmartGroups</a>
* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/kubernetes-overview"}>Aviatrix Kubernetes Firewall</a>