> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foggyhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes RBAC

> What Kubernetes permissions Foggy requests, why, and how to review or customize them.

<Info>
  **Scope of this page: Kubernetes RBAC only.** Permissions for external connectors (Grafana, Slack, GitHub, Linear, Sentry) are controlled by the API tokens you generate on those services. You choose the scope on each token; Foggy only has what you grant.
</Info>

## Overview

Foggy runs as a pod with a Kubernetes `ServiceAccount` and uses Kubernetes-native RBAC to query your cluster read-only. All permissions are declared as `ClusterRole` resources in the Helm chart, auditable before `helm install`. Every API call is recorded in your cluster's audit log if enabled.

## What Foggy reads from Kubernetes

| Resource category                                      | Purpose                                                                                 |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| **Pods** and **pod logs**                              | Identify crashing, OOMKilled, or unhealthy workloads; read logs for errors and warnings |
| **Events**                                             | Surface cluster events (scheduling failures, image pull errors, restarts)               |
| **Deployments, ReplicaSets, StatefulSets, DaemonSets** | Understand workload topology, rollout status, replica counts                            |
| **Services, Endpoints**                                | Map network routing between workloads                                                   |
| **ConfigMaps**                                         | Read non-sensitive configuration (Secrets explicitly excluded, see below)               |
| **Nodes**                                              | Inspect node capacity, conditions, taints                                               |
| **Namespaces**                                         | Enumerate namespaces for scoping queries                                                |

All verbs are limited to `get`, `list`, and `watch`. No creation, modification, or deletion.

## What Foggy does NOT access

Foggy's default `ClusterRole` explicitly excludes:

* **Secrets.** API keys, database passwords, TLS certs. Foggy cannot read them.
* **`pods/exec`.** No shell into any running pod.
* **`pods/portforward`.** No direct network access to pods.
* **`create`, `update`, `patch`, `delete`** on any resource. Foggy cannot modify, create, or delete anything in your cluster.
* **Custom Resources** from operators (Argo, Istio, cert-manager, etc.). Not in the default scope.

Adding any of these for a new feature requires an explicit `values.yaml` opt-in alongside a version bump. We never silently expand the scope.

## Default ClusterRole

The exact `ClusterRole` the Helm chart creates:

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: foggy-readonly
rules:
  - apiGroups: [""]
    resources: [pods, events, services, endpoints, configmaps, nodes, namespaces]
    verbs: [get, list, watch]
  - apiGroups: [""]
    resources: [pods/log]
    verbs: [get, list]
  - apiGroups: [apps]
    resources: [deployments, replicasets, statefulsets, daemonsets]
    verbs: [get, list, watch]
```

<Tip>
  Preview every resource the chart will create, including the full `ClusterRole`:

  ```bash theme={null}
  helm template foggy foggy/foggy | less
  ```

  For a focused RBAC-only review, use `--show-only`:

  ```bash theme={null}
  helm template foggy foggy/foggy \
    --show-only templates/clusterrole.yaml \
    --show-only templates/clusterrolebinding.yaml \
    --show-only templates/serviceaccount.yaml
  ```
</Tip>

## Customization

Narrow Foggy's Kubernetes access via `values.yaml`.

### Namespace-scoped installation

Restrict Foggy to specific namespaces:

```yaml theme={null}
rbac:
  scope: namespace
  namespaces:
    - python-services
    - core-platform
```

Foggy generates a `Role` and `RoleBinding` per namespace instead of a cluster-wide `ClusterRole`.

### Disable the Kubernetes connector entirely

To connect only to external tools (Grafana, Slack) without Kubernetes access:

```yaml theme={null}
rbac:
  disabled: true
```

No `ServiceAccount`, `ClusterRole`, or `RoleBinding` is created. Foggy installs and runs; it cannot query Kubernetes.

### Bring your own ClusterRole

If your security policy requires a custom role:

```yaml theme={null}
rbac:
  customClusterRoleName: my-company-foggy-role
```

Foggy only creates the `RoleBinding` and expects the `ClusterRole` to exist.

## Kubernetes remediation actions (future)

Today, Foggy is **strictly read-only in Kubernetes**. Write actions (pod restart, deployment rollback, similar remediations) are deferred to a future opt-in feature with a separate RBAC bundle. Kubernetes writes will always require an explicit `values.yaml` opt-in, never silent expansion. This is distinct from external connector writes (Slack messages, GitHub PRs, Linear tickets), which are already supported today and governed by the API token scopes you grant on those services.