# Kubernetes

SureCloud connects to Kubernetes clusters to retrieve RBAC configuration, workload security posture, network policy status, and cluster-level security settings. This allows SureCloud to verify that cluster access is controlled through role-based permissions, that workloads are not running with excessive privileges, and that network policies are in place — providing continuous evidence for container orchestration security controls.

{% hint style="info" %}
SureCloud connects to Kubernetes clusters via the Kubernetes API server. Each cluster requires a separate connection. For clusters running in managed Kubernetes services (EKS, AKS, GKE), the connection configuration may differ slightly — refer to the tabs below.
{% endhint %}

## Authentication and setup

Kubernetes authenticates API requests using a service account token. SureCloud uses a dedicated service account with a ClusterRole scoped to read-only access.

{% tabs %}
{% tab title="Self-managed / on-premises" %}
{% stepper %}
{% step %}
**Create a read-only ClusterRole and ServiceAccount**

Apply the following manifest to your cluster:

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: surecloud-reader
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: surecloud-reader
rules:
  - apiGroups: [""]
    resources: ["pods","nodes","namespaces","services","serviceaccounts","configmaps"]
    verbs: ["get","list"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["roles","rolebindings","clusterroles","clusterrolebindings"]
    verbs: ["get","list"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["networkpolicies"]
    verbs: ["get","list"]
  - apiGroups: ["policy"]
    resources: ["podsecuritypolicies","poddisruptionbudgets"]
    verbs: ["get","list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: surecloud-reader
subjects:
  - kind: ServiceAccount
    name: surecloud-reader
    namespace: kube-system
roleRef:
  kind: ClusterRole
  name: surecloud-reader
  apiGroup: rbac.authorization.k8s.io
```

{% endstep %}

{% step %}
**Extract the service account token**

```bash
kubectl create token surecloud-reader -n kube-system --duration=8760h
```

Copy the generated token.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Kubernetes → Connect**. Enter the API server URL (e.g. `https://your-cluster-api:6443`), the service account token, and the cluster CA certificate (base64 encoded, available from your kubeconfig). Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="EKS / AKS / GKE (managed)" %}
For managed Kubernetes services, SureCloud recommends using the cloud provider's IAM-based authentication rather than a long-lived service account token:

* **EKS**: Create an IAM role with `eks:DescribeCluster` and map it to the `surecloud-reader` ClusterRole via `aws-auth` ConfigMap. SureCloud uses the AWS integration's cross-account role to assume this IAM role.
* **AKS**: Create a service principal with Reader access to the AKS resource and use Azure AD RBAC to bind it to the `surecloud-reader` ClusterRole.
* **GKE**: Use the Google Cloud service account from the GCP integration, granting it the `container.viewer` IAM role on the cluster.

Contact SureCloud Support for guided setup instructions for your specific managed Kubernetes environment.
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                                | Use Case                                                                             |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `GET /api/v1/nodes`                                     | Enumerate cluster nodes and their status                                             |
| `GET /api/v1/namespaces`                                | List namespaces to scope workload collection                                         |
| `GET /api/v1/pods`                                      | Enumerate running pods including security context (privilege settings, host network) |
| `GET /api/v1/serviceaccounts`                           | Enumerate service accounts per namespace                                             |
| `GET /rbac.authorization.k8s.io/v1/clusterroles`        | Retrieve ClusterRole definitions for RBAC analysis                                   |
| `GET /rbac.authorization.k8s.io/v1/clusterrolebindings` | Retrieve ClusterRoleBinding assignments                                              |
| `GET /rbac.authorization.k8s.io/v1/roles`               | Retrieve namespace-scoped Role definitions                                           |
| `GET /rbac.authorization.k8s.io/v1/rolebindings`        | Retrieve namespace-scoped RoleBinding assignments                                    |
| `GET /networking.k8s.io/v1/networkpolicies`             | Retrieve network policies to confirm traffic segmentation is enforced                |

## Pagination

Kubernetes API list endpoints use `continue` token pagination. SureCloud uses the `continue` field from each response's `metadata` to retrieve subsequent pages until no `continue` token is returned.

```json
GET /api/v1/pods?limit=500&continue=<value_from_previous_response>
```

## Required permissions

SureCloud requires the ClusterRole defined in the setup section above. Key permissions:

| Resource                                               | Verbs     |
| ------------------------------------------------------ | --------- |
| pods, nodes, namespaces, services, serviceaccounts     | get, list |
| roles, rolebindings, clusterroles, clusterrolebindings | get, list |
| networkpolicies                                        | get, list |
| podsecuritypolicies (if applicable)                    | get, list |

No create, update, delete, or exec permissions are required.

## Polling frequency

| Data Type                                 | Interval       |
| ----------------------------------------- | -------------- |
| Node and namespace inventory              | Every 24 hours |
| Pod security context and workload posture | Every 24 hours |
| RBAC roles and bindings                   | Every 24 hours |
| Network policies                          | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test fails with TLS certificate error</summary>

The cluster CA certificate entered in SureCloud does not match the API server's certificate, or the API server URL is using a private CA. Retrieve the correct CA certificate from your kubeconfig (`clusters[].cluster.certificate-authority-data`) and re-enter it in **SureCloud → Integrations → Kubernetes → Edit Connection**.

</details>

<details>

<summary>RBAC resources return empty despite roles being configured</summary>

Confirm the service account has `get` and `list` verbs on `rbac.authorization.k8s.io` resources. Some clusters use namespace-scoped RBAC only and may not grant ClusterRole visibility. Review the ClusterRoleBinding applied in the setup step to ensure it covers RBAC resources at the cluster level.

</details>

<details>

<summary>API server is unreachable from SureCloud</summary>

Kubernetes API servers on private networks require network access from the SureCloud collector. For private clusters, a VPN, bastion, or API server allowlist entry may be required. Contact SureCloud Support for connectivity options.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/kubernetes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.