Distributed Cloud Firewall for Kubernetes

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.

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

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.

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

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:

Meet the prerequisites for your cloud provider.
Enable Kubernetes Resource Discovery.
Onboard your Kubernetes clusters. For private clusters, see Onboarding Private Kubernetes Clusters.
Enable DCF policies for Kubernetes
Optionally, install CRDs for in-cluster policy management.
Create SmartGroups and DCF rules.

Enabling DCF Policies for Kubernetes

The Aviatrix k8s-firewall helm chart 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.

CoPilot UI
Terraform

To enable DCF policies for Kubernetes using the CoPilot UI, follow these steps:

Enable Discovery of Kubernetes Resources

On Groups > Settings, click Enable on the Discovery of Kubernetes Resources card.See Discovery of Kubernetes Resources for more information.

Enable Enforcement on Kubernetes

On Security > Distributed Cloud Firewall > Settings, click Enable on the Enforcement on Kubernetes card.

A notification appears to confirm the changes.

To enable DCF policies for Kubernetes using Terraform, add the following to your Terraform configuration:

resource "aviatrix_k8s_config" "this" {
  enable_k8s          = true
  enable_dcf_policies = true
}

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

helm install --repo https://aviatrixsystems.github.io/k8s-firewall-charts k8s-firewall k8s-firewall

Verify the CRD registration:

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:

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:

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:

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:

kubectl apply -f webgroup-policy.yaml

Verifying Policy Status

Check policy events to confirm the policy was applied successfully:

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 Kubernetes CRD Reference.

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.

When ordering between rules matters, place them in the same FirewallPolicy resource.

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.

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.

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

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:

Aviatrix refuses the offboard if any SmartGroup elsewhere still references this cluster. Clean those references up first.
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.

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

Concepts & Architecture

Guides

Reference

Distributed Cloud Firewall for Kubernetes

Overview

Key Capabilities

Supported Kubernetes Distributions

Getting Started

Enabling DCF Policies for Kubernetes

Managing Policies with Kubernetes CRDs

Installing the CRDs

Writing a Firewall Policy

Writing a WebGroup Policy

Verifying Policy Status

Rule Ordering

Within a Single FirewallPolicy

Between Different FirewallPolicy Resources

FirewallPolicy vs. WebgroupPolicy

CR-Managed Rules vs. Admin-Authored DCF Rules

Troubleshooting

Common Pitfalls

Reading Reconciliation Events

Updating and Deleting Policies

Updating a Policy

Deleting a Policy

Cluster Offboarding Caveat

​Overview

​Key Capabilities

​Supported Kubernetes Distributions

​Getting Started

​Enabling DCF Policies for Kubernetes

​Managing Policies with Kubernetes CRDs

​Installing the CRDs

​Writing a Firewall Policy

​Writing a WebGroup Policy

​Verifying Policy Status

​Rule Ordering

​Within a Single FirewallPolicy

​Between Different FirewallPolicy Resources

​FirewallPolicy vs. WebgroupPolicy

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

​Troubleshooting

​Common Pitfalls

​Reading Reconciliation Events

​Updating and Deleting Policies

​Updating a Policy

​Deleting a Policy

​Cluster Offboarding Caveat

​Related Topics

Overview

Key Capabilities

Supported Kubernetes Distributions

Getting Started

Enabling DCF Policies for Kubernetes

Managing Policies with Kubernetes CRDs

Installing the CRDs

Writing a Firewall Policy

Writing a WebGroup Policy

Verifying Policy Status

Rule Ordering

Within a Single FirewallPolicy

Between Different FirewallPolicy Resources

FirewallPolicy vs. WebgroupPolicy

CR-Managed Rules vs. Admin-Authored DCF Rules

Troubleshooting

Common Pitfalls

Reading Reconciliation Events

Updating and Deleting Policies

Updating a Policy

Deleting a Policy

Cluster Offboarding Caveat

Related Topics