> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/connectors/kubernetes.md).

# Kubernetes

## Overview

Connect Kubernetes to Nullify to audit your clusters for misconfiguration. Nullify evaluates a dedicated Kubernetes ruleset — workload, RBAC, network, and cluster-configuration checks — as part of its [Cloud Audits](https://docs.nullify.ai/capabilities/cloud-audits.md) (CSPM) capability, then correlates findings with the accounts and code that own those clusters.

## Key Benefits

* **Cluster misconfiguration detection** — Catch insecure workloads, over-broad RBAC, missing network policy, and weak cluster controls before they are exploited.
* **Collection choices** — Managed EKS scanning and in-cluster EKS/GKE collectors have different identity and network prerequisites. Confirm the collection method for AKS or self-hosted clusters with Nullify before deploying.
* **Refreshes as data lands** — Findings reconcile each time a cluster's inventory arrives. The in-cluster collector uploads on a schedule (daily by default, configurable), and Nullify re-audits each time new inventory lands.
* **Read-only** — The collector reads cluster metadata through the Kubernetes API and uploads it for analysis. Nullify does not modify your cluster.

## What It Scans

Nullify ships a dedicated Kubernetes ruleset (alongside the AWS, GCP, and Azure rulesets) that runs against the collected cluster inventory. Checks span:

* **Workloads** — privileged containers, host namespace sharing (host PID / IPC / network), privilege escalation, dangerous capabilities, hostPath volumes, image pinning, and pull-policy hygiene.
* **RBAC** — cluster-admin bindings, wildcard and escalation verbs, anonymous and default-service-account bindings, and stale or over-broad role grants.
* **Network & admission** — missing default-deny network policies, overly permissive ingress, and admission/webhook configuration weaknesses.
* **Cluster configuration** — etcd encryption, control-plane settings, and config-map hygiene (sensitive data, embedded credentials).

Each detection becomes a CSPM finding that is AI-triaged for false-positive likelihood and priority, the same as any AWS, GCP, or Azure cloud finding. See [Cloud Audits](https://docs.nullify.ai/capabilities/cloud-audits.md) for the cross-provider view.

## How It Works

Nullify supports two scanning paths depending on cluster type:

1. **Managed EKS scan** — Nullify reaches a public EKS API endpoint using the connected AWS role, an EKS access entry, and dedicated read-only Kubernetes RBAC. This path does not install an in-cluster collector. Cloud account access alone is insufficient. Set it up with the connector's `setup-eks-managed-scan.sh` script, the `nullify-eks-managed-scan-access.json` CloudFormation template, or the Terraform `enable_managed_scan` option. The cluster's public endpoint must admit Nullify's egress IPs; private-only clusters need the in-cluster collector. GKE workload collection uses the [GKE collector setup](https://docs.nullify.ai/connectors/gcp/configuration.md#kubernetes-collector-gke). Azure subscription Reader does not grant AKS workload access.
2. **On-prem / self-hosted clusters** — Scanned by the in-cluster Nullify Kubernetes collector, which walks the cluster API and uploads a cluster-inventory envelope to Nullify's secured upload area. An ingestor then validates the upload and stores it for scanning.

In both cases, a completed scan emits an event that drives the CSPM reconcile: new misconfigurations are stored and triaged, fixed ones are resolved, and reintroduced ones re-open — so cluster posture stays current without a fixed schedule.

## Collector Setup (On-Prem / Self-Hosted)

The published collector chart offers `aws` (EKS) and `gcp` (GKE) identity modes. It has no AKS or generic on-prem identity mode. Arrange a supported upload identity with Nullify before applying it to another cluster type. At a high level:

1. **Deploy the collector** into the target cluster via Helm. It runs on a schedule, authenticates to the Kubernetes API in-cluster (read-only), and collects cluster resources — nodes, namespaces, pods, services, deployments, RBAC, and related objects.
2. **Grant upload access.** The collector uploads its inventory envelope to Nullify's secured S3 upload area. Encryption in transit is enforced; the collector supports a KMS key for upload encryption.
3. **Whitelist the account(s).** Nullify must allow the uploading AWS account(s) to write to the bucket (and use the KMS key). See [Whitelisting Collector Accounts](#whitelisting-collector-accounts) below.

{% hint style="info" %}
The collector is read-only. It reads cluster metadata through the Kubernetes API and never writes to your cluster.
{% endhint %}

Cluster registration is managed through the admin API (`POST /admin/integrations/cloud/k8s/settings`). A site administrator declares each cluster (name, type — `EKS`, `AKS`, `GKE` or `ON_PREM` — and, for managed clusters, the cloud account ID and region; an AKS cluster can also give its Azure resource ID) and optionally the Nullify role ARN used to reach the cluster. Each request replaces the whole set of registered clusters, so include every cluster you want to keep. Each cluster can turn off Secret metadata collection (`collectSecrets`) or ConfigMap collection (`collectConfigMaps`); both are on for a new cluster.

## Whitelisting Collector Accounts

Collector uploads land in a Nullify-managed bucket whose access policy is allowlisted per AWS account. In the dashboard, the Kubernetes connector (**Settings → Connectors**, or the Cloud step of [Onboarding](https://docs.nullify.ai/getting-started/getting-started.md)) lists the accounts allowed to upload under **Account access** (add other accounts with **Add AWS account**), shows the collector S3 bucket, KMS key ARN and S3 access point ARN to configure the collector with, and lists the clusters discovered so far. The platform normally reconciles this allowlist automatically when cloud settings are saved, but a dedicated endpoint exists to (re)apply it on demand — useful during onboarding or if the bucket/KMS policy drifts:

```http
POST /admin/integrations/cloud/k8s/whitelist
```

```json
{
  "accountIds": ["123456789012"]
}
```

Behaviour:

* **`accountIds` (optional)** — The AWS account IDs allowed to upload collector data. The list replaces the accounts previously saved through this endpoint or the panel. Accounts in the AWS cloud settings keep their own grants, and access granted outside Nullify is kept. Without `expectedRevision`, omitting the list or sending an empty list falls back to every account stored on the tenant's AWS cloud settings; if no AWS settings exist, the request returns not found.
* **`expectedStateId` and `expectedRevision` (optional, send both)** — The `stateId` and `revision` returned by `GET /admin/integrations/cloud/k8s/whitelist`. A stale revision is rejected with a conflict, and an empty list removes only the accounts saved here. The dashboard uses this mode.
* The handler reconciles the **upload bucket policy** and, when configured, the **S3 access point policy** and the **KMS key policy**, and reports which were updated. If no KMS key ARN is configured, the response reports `"kmsSkipped": true` with `kmsPolicyUpdated: false` and no `kmsError`.

This endpoint requires config-write permission; the `GET` requires config-read permission.

{% hint style="warning" %}
Whitelisting only grants upload access — it does not register a cluster or start a scan. Declare the cluster through cloud settings, then deploy the collector.
{% endhint %}

## Support

* Implementation assistance and feature requests: <support@nullify.ai>

Findings flow asynchronously into Jira, Slack, and the Nullify dashboards so remediation stays aligned with cluster and cloud owners.

## Collector versions

Pin the chart version that you install. Collector chart **0.6.0** uses image **4.0.0** and needs a source-qualified upload prefix from Nullify, set as `collector.s3.keyPrefix`. The Kubernetes panel does not show this prefix: get it from Nullify, and do not infer it from an AWS account ID. The managed EKS scan uses the separate **readonly-access** chart.

A successful Helm install proves resource creation. Confirm a collector job runs, its upload is accepted, and a fresh cluster inventory and audit appear in Nullify.

## Collector deployment choices

On EKS, AWS integration templates can establish OIDC trust for multiple clusters. Install collector resources using either the Terraform `k8s-resources` module or the [Helm chart](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/helm-charts/nullify-k8s-collector), following that version's values and permissions. Trust configuration alone does not deploy a collector.

For AKS, start with [Azure cloud federation](https://docs.nullify.ai/connectors/azure-cloud.md) and configure the cluster collection path for your tenant. Cloud subscription Reader access and Kubernetes API access are separate grants.
