> ## 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 Intra-Cluster Inspection

> Enable Distributed Cloud Firewall (DCF) intra-cluster inspection to enforce pod-to-pod security policies inside Kubernetes clusters using native NetworkPolicy objects translated from DCF rules.

Distributed Cloud Firewall (DCF) intra-cluster inspection extends DCF
enforcement to **pod-to-pod traffic within a Kubernetes cluster**. The
Controller translates DCF rules that use K8s SmartGroup selectors into native
Kubernetes NetworkPolicy objects. The cluster's CNI plugin enforces these
objects at the pod network level.

This is fundamentally different from DCF enforcement at the spoke gateway (which
inspects traffic entering or leaving the cluster). Intra-cluster inspection
operates inside the cluster using Kubernetes-native enforcement. No Aviatrix
gateway is in the data path for intra-cluster flows.

A single DCF rule with K8s SmartGroups on both source and destination generates
NetworkPolicy for every enabled cluster **and** still enforces at the Aviatrix
gateway. Because NetworkPolicy selects pods by label, policy follows pods
through restarts, rescheduling, and autoscaling without IP-based gaps.

<Warning>
  Kubernetes NetworkPolicy is **allow-list-based and union-based**. There is no
  native DENY action. If any NetworkPolicy from any source (including
  non-Aviatrix policies) permits a flow, a DCF DENY rule translated into an
  isolation policy has no effect on that flow. Review your existing
  NetworkPolicies carefully before enabling intra-cluster inspection.
</Warning>

## Supported Environments

Intra-cluster inspection is a{" "}

<a href={"/docs/enterprise/" + "10.1" + "/reference/feature-modes/index"}>Preview Feature</a>
in Controller 10.1 and is supported on the following Kubernetes distributions:

| Distribution                                 | Support level  |
| -------------------------------------------- | -------------- |
| AWS EKS                                      | Public Preview |
| Azure AKS                                    | Public Preview |
| Self-managed clusters (with a supported CNI) | Public Preview |

<Note>
  GKE is not supported for intra-cluster inspection in Controller 10.1.
</Note>

### CNI Requirements

The cluster's CNI plugin must enforce NetworkPolicy. The following CNIs are
supported:

* Calico
* Cilium
* AWS VPC CNI 1.14 or later
* Weave Net
* Antrea
* Canal

<Warning>
  If the cluster's CNI does not enforce NetworkPolicy (such as Flannel, Kubenet,
  or Kindnet), all translated NetworkPolicies are **silently ignored**. The
  Controller and CoPilot do not raise an error or warning. Pods remain
  unrestricted. Verify that your CNI enforces NetworkPolicy before enabling this
  feature.
</Warning>

## Prerequisites

Before you enable intra-cluster inspection, confirm the following:

* **Distributed Cloud Firewall** is enabled (CoPilot > **Security** >
  **Distributed Cloud Firewall**).

* **Kubernetes Resource Discovery** is enabled (CoPilot > **Groups** >
  **Settings** > **Discovery of Kubernetes Resources**).

* The target cluster is
  <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard"}>onboarded to Aviatrix</a>
  .

* The Aviatrix K8s Helm chart is installed in the cluster with the
  `manageNetworkPolicies` flag set to `true`. This flag ships `false` by
  default, so you must explicitly enable it when running or upgrading the Helm
  chart.

* The cluster's CNI plugin enforces Kubernetes NetworkPolicy (see
  [CNI Requirements](#cni-requirements)).

* You have K8s SmartGroups defined that use Kubernetes selectors
  (`k8s_cluster_id`, `k8s_namespace`, `k8s_pod`, `k8s_service`, or
  `tags.<label>`). See
  <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/smartgroups-about"}>Creating SmartGroups</a>
  .

<Warning>
  **Brownfield clusters:** Enabling intra-cluster inspection makes DCF the sole
  source of truth for managed NetworkPolicy objects. Existing NetworkPolicies
  from other sources are **not** preserved, and disabling the feature does
  **not** restore prior policies. Audit your existing NetworkPolicies and
  traffic flows before enabling this feature on clusters that already have
  NetworkPolicies deployed.
</Warning>

## Enabling Intra-Cluster Inspection

Intra-cluster inspection uses a two-level enable: a global Controller setting
and a per-cluster toggle. Both must be enabled for a cluster to receive
translated NetworkPolicies.

<Steps>
  <Step title="Go to Distributed Cloud Firewall settings">
    In CoPilot, go to **Security** > **Distributed Cloud Firewall** > **Settings**.
  </Step>

  <Step title="Open the Manage Intra-Cluster Orchestration dialog">
    On the **Kubernetes Intra-Cluster Orchestration** card, click **Manage**.
  </Step>

  <Step title="Turn on the global setting">
    Turn on **Intra-Cluster Orchestration**.
  </Step>

  <Step title="Turn on the setting for a specific cluster">
    In the **Manage Intra-Cluster Orchestration** dialog, locate the cluster in the
    table and turn on the switch for the target cluster.
  </Step>

  <Step title="Wait for orchestration to complete">
    The **Orchestration Status** column shows **In Progress** while the Controller
    translates and applies policies. Wait until the status changes to **Completed**.
  </Step>
</Steps>

<Note>
  You can also enable the per-cluster setting with Terraform using the
  `intra_cluster_inspection_enabled` attribute on the
  `aviatrix_kubernetes_cluster` resource.
</Note>

## How DCF Rules Map to NetworkPolicy

When intra-cluster inspection is enabled, the Controller evaluates every DCF
rule to determine whether it is eligible for Kubernetes NetworkPolicy
translation:

* The rule must have an action of **Permit** or **Deny**.
* The rule must use K8s SmartGroup selectors on the source, destination, or
  both.
* The rule must specify TCP or UDP protocols.
* The rule must not be a web-filter (Layer 7) rule.

No other rule action, such as **Intrusion Detection - Permit**, is supported for
translation to NetworkPolicy. This applies whether the rule is created in
CoPilot or with Terraform.

### Translation Behavior

| DCF rule type                   | NetworkPolicy translation                                                       |
| ------------------------------- | ------------------------------------------------------------------------------- |
| Permit (specific port/protocol) | Ingress or Egress rule allowing the specified peer and port                     |
| Deny (specific peer)            | Isolation policy that permits all traffic except the denied peer                |
| Default Deny (catch-all)        | A deny-all NetworkPolicy per namespace (empty ingress/egress arrays)            |
| ICMP rules                      | Not translated (Kubernetes NetworkPolicy translation supports TCP and UDP only) |
| Web-filter (L7) rules           | Not translated                                                                  |

The Controller labels each generated NetworkPolicy with
`app.kubernetes.io/managed-by: avx-controller` and annotates it with the
originating DCF rule names.

### Limitations of the Translation

<Warning>
  **No default-allow rule in Controller 10.1.** Once any DCF rule selects a pod,
  Kubernetes default-deny isolation applies to that pod for all unmatched
  traffic. You must explicitly permit all desired flows. A default-allow rule is
  planned for a future release.
</Warning>

<Note>
  ICMP-only DCF rules are silently excluded from Kubernetes translation. If you
  need to allow ICMP between pods, configure it outside of DCF or use a
  CNI-native policy.
</Note>

<Note>
  System namespaces (`kube-system`, `kube-public`, `kube-node-lease`) are not
  automatically excluded from default-deny policies. If your DCF rules produce
  default-deny isolation, cluster infrastructure services (DNS, CoreDNS,
  kube-proxy) may be impacted. Create explicit Permit rules for system namespace
  traffic before applying broad deny policies.
</Note>

## Creating DCF Rules for Intra-Cluster Enforcement

The following example demonstrates namespace isolation: pods in `ns-team-a` can
reach the `web` service in `ns-team-b` on port 443, while all other
cross-namespace traffic is denied.

<Steps>
  <Step title="Create K8s SmartGroups">
    Create SmartGroups that target Kubernetes resources:

    * **sg-team-a-pods**: Match expression with `k8s_cluster_id` = your cluster and
      `k8s_namespace` = `ns-team-a`.
    * **sg-team-b-web**: Match expression with `k8s_cluster_id` = your cluster,
      `k8s_namespace` = `ns-team-b`, and `k8s_service` = `web`.

    See <a href={"/docs/enterprise/" + "10.1" +
      "/concepts-architectures/components/dcf/smartgroups-about"}>Creating
    SmartGroups</a> for details on K8s selectors.
  </Step>

  <Step title="Create DCF rules">
    In CoPilot, go to **Security** > **Distributed Cloud Firewall** > **Policies**
    and create the following rules:

    * **Permit rule** (priority 100): Source = `sg-team-a-pods`, Destination =
      `sg-team-b-web`, Port = 443/TCP, Action = Permit.
    * **Deny rule** (priority 200): Source = Any, Destination = Any, Action = Deny.

    The Controller translates these into NetworkPolicy objects:

    * An ingress NetworkPolicy in `ns-team-b` allowing traffic from `ns-team-a` pods
      on port 443/TCP.
    * A deny-all NetworkPolicy in each namespace, blocking all other unmatched
      traffic.
  </Step>

  <Step title="Confirm orchestration completed">
    Check the **Orchestration Status** in the Manage dialog. It should show
    **Completed**.
  </Step>

  <Step title="List the managed NetworkPolicies">
    Use `kubectl` to list the managed NetworkPolicies in the target namespace:

    ```bash theme={null}
    kubectl get networkpolicies -n ns-team-b \
      -l app.kubernetes.io/managed-by=avx-controller
    ```
  </Step>

  <Step title="Verify the policy details">
    Verify that the expected policies appear with the correct pod selectors and
    ingress/egress rules:

    ```bash theme={null}
    kubectl describe networkpolicy <policy-name> -n ns-team-b
    ```
  </Step>

  <Step title="Test connectivity">
    Test connectivity from a pod in `ns-team-a` to the `web` service in `ns-team-b`:

    ```bash theme={null}
    kubectl exec -n ns-team-a <pod-name> -- curl -s https://web.ns-team-b:443
    ```

    Verify that traffic from other namespaces to `ns-team-b` is denied.
  </Step>
</Steps>

## Pausing and Resuming Policy Sync

You can pause the translation pipeline without disabling intra-cluster
inspection. When the translation pipeline is paused, the Controller stops
pushing new or updated NetworkPolicies to the cluster. Existing policies remain
in place.

* **Pause:** In the Manage Intra-Cluster Orchestration dialog, the orchestration
  status shows **Paused**.
* **Resume:** Toggling the pause off restarts the sync. The Controller
  reconciles the full policy set.

## Disabling Intra-Cluster Inspection

To disable intra-cluster inspection for a cluster, in the **Manage Intra-Cluster
Orchestration** dialog, turn off the switch for that cluster. The Controller
removes all managed NetworkPolicy objects (those labeled
`app.kubernetes.io/managed-by: avx-controller`) from the cluster.

To disable the feature globally, turn off **Intra-Cluster Orchestration** in the
DCF Settings.

<Warning>
  Disabling intra-cluster inspection removes all Aviatrix-managed
  NetworkPolicies from the cluster. It does **not** restore any NetworkPolicies
  that existed before the feature was enabled. If you need to restore prior
  policies, you must re-apply them manually.
</Warning>

## Troubleshooting

### Orchestration Status Does Not Reach "Completed"

* Verify the Helm chart is installed with `manageNetworkPolicies=true`:

  ```bash theme={null}
  helm get values k8s-firewall -n default --all | grep manageNetworkPolicies
  ```

* Confirm that the cluster is reachable from the Controller and that the
  Aviatrix service account has permissions to manage NetworkPolicy objects.

### Policies Exist but Traffic Is Not Enforced

* Verify that the cluster's CNI enforces NetworkPolicy. CNIs such as Flannel,
  Kubenet, and Kindnet do not enforce NetworkPolicy and silently ignore all
  policies.
* Check that the NetworkPolicy pod selectors match the target pods:

  ```bash theme={null}
  kubectl get networkpolicies -n <namespace> -o yaml
  ```

### Unexpected Traffic Drops After Enabling

* Remember that once any NetworkPolicy selects a pod, all traffic not explicitly
  permitted by a NetworkPolicy is denied (Kubernetes default-deny isolation).
  Verify that you have Permit rules for all required flows, including DNS (port
  53/UDP to `kube-system`).
* Check whether system namespaces are covered by deny-all policies. Create
  explicit Permit rules for cluster infrastructure traffic.

### ICMP Traffic Not Blocked Inside the Cluster

* ICMP rules are not translated to Kubernetes NetworkPolicy. Only TCP and UDP
  protocols are supported for translation.

## Known Limitations (Controller 10.1)

* Intra-cluster flow logs are not viewable in CoPilot.
* ICMP rules are not translatable to Kubernetes NetworkPolicy.
* Layer 7 (web-filter) rules are not translatable to Kubernetes NetworkPolicy.
* Kubernetes Services cannot be used as direct policy targets.
* GCP (GKE and self-managed clusters on GCP) is not supported for intra-cluster
  inspection in Controller 10.1.
* IP Blocks (CIDR-based NetworkPolicy peers) are not supported for translation
  in Controller 10.1.
* Services (Service-type SmartGroups) are not supported for translation in
  Controller 10.1.
* There is no automated CNI compatibility check in CoPilot.
* There is no default-allow rule. All traffic not explicitly permitted by a
  NetworkPolicy selecting a pod is denied.
* A DCF Deny rule has no effect if another NetworkPolicy (from any source)
  already permits the same flow.
* Terraform can manage the per-cluster enable but cannot manage the global
  Intra-Cluster Orchestration setting, cluster registration, orchestration
  status, or pause/resume.

## 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" + "/guides/security/dcf/kubernetes-resource-discovery"}>Discovery of Kubernetes Resources</a>
* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/smartgroups-about"}>Creating SmartGroups</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/dcf-enable-feature"}>Distributed Cloud Firewall Setup</a>