# Kubernetes

Modern backup for Kubernetes clusters with automatic discovery of databases, persistent volumes, ConfigMaps, Secrets, namespace workload definitions, and Helm releases.

SimpleBackups connects to your Kubernetes cluster and scans it for everything worth protecting — then backs it up on a schedule to any storage destination. No agents, no in-cluster components, no cluster-admin permissions required.

## Prerequisites

Before setting up a Kubernetes Stack:

- A **server added to SimpleBackups** that has SSH access and `kubectl` installed and configured — alternatively, you can use our Serverless workers in a click
- The server must have network access to your Kubernetes cluster API
- `kubectl` must work on that server (run `kubectl cluster-info` to verify)
- For Helm release backups, `helm` must also be installed on the server

## Supported resource types

| Resource type | What gets backed up |
| --- | --- |
| Databases | MySQL, MariaDB, PostgreSQL, MongoDB, Redis pods — full database dump |
| Persistent Volume Claims (PVCs) | File contents of the volume |
| ConfigMaps | Exported as YAML |
| Secrets | Exported as YAML (encrypted at rest) |
| Namespace Workload Config | Deployments, StatefulSets, DaemonSets, Services, Ingresses, HPAs, NetworkPolicies — exported as YAML |
| Helm Releases | Release values (`helm get values`) and manifests (`helm get manifest`) |

## Setup guide

### Step 1 — Create a Kubernetes Stack

Go to [Stacks](https://my.simplebackups.com/stack) → **Create Stack** and:

1. Select **Kubernetes** as the provider
2. Select your server or Serverless

### Step 2 — Authenticate

You have two options.

**Option A — Use the server's existing kubeconfig (recommended).** If your server already has `~/.kube/config` set up and `kubectl` works without any extra flags, leave the kubeconfig field empty. SimpleBackups will use the server's existing configuration.

**Option B — Paste a kubeconfig.** If you want to use a specific kubeconfig (for example, for a remote cluster), paste the contents of your kubeconfig file into the **Kubeconfig** field.

To get your kubeconfig:

```bash
cat ~/.kube/config
```

If your kubeconfig contains multiple clusters, specify which context to use in the **Context** field. Leave it empty to use the current or default context.

### Step 3 — Configure discovery

Choose what to scan:

| Setting | Default | Notes |
| --- | --- | --- |
| Namespaces | All | Comma-separated list, or leave empty to scan all |
| Discover Database Pods | On | Detects MySQL, PostgreSQL, MongoDB, Redis by image name |
| Discover PVCs | On | Finds Persistent Volume Claims and their mount paths |
| Discover ConfigMaps & Secrets | Off | Enable if you want to back up cluster configuration |
| Discover Namespace Workload Configs | On | Exports Deployments, Services, Ingresses, and so on per namespace |
| Discover Helm Releases | Off | Requires `helm` installed on your server |

### Step 4 — Run discovery

Click **Discover Resources**. Discovery typically takes 10–30 seconds depending on cluster size.

### Step 5 — Review and enable

You'll see a list of everything discovered, grouped by type. For each resource:

- Review the auto-detected configuration (namespace, pod name, credentials for databases)
- Adjust anything that looks incorrect
- Click **Create Backup** to activate the backup

## How each resource type is backed up

### Databases (MySQL, PostgreSQL, MongoDB, Redis)

SimpleBackups detects pods running known database images and auto-discovers the database host (resolved from the Kubernetes Service targeting the pod), the port, and credentials (from environment variables or Kubernetes Secrets referenced by the pod). Backups use standard dump tools — the same as any other database backup in SimpleBackups.

### Persistent Volume Claims (PVCs)

SimpleBackups resolves the correct pod automatically using the app label or pod name discovered at scan time, with fallbacks if the pod name changes. It then dumps the mount path and streams it to your selected storage compressed.

### ConfigMaps and Secrets

The output is a standard Kubernetes YAML file that can be re-applied with `kubectl apply -f`.

**Secret values are sensitive:**
Secret values are base64-encoded in the exported YAML, as is standard Kubernetes behavior. Treat these backup files as sensitive.

### Namespace workload config

Exports the following resource types for the entire namespace as a single YAML file:

- Deployments
- StatefulSets
- DaemonSets
- Services
- Ingresses
- HorizontalPodAutoscalers
- ServiceAccounts
- NetworkPolicies

This gives you a full snapshot of your workload definitions, useful for disaster recovery or cluster migration.

### Helm releases

Two files are exported per release:

- `helm-<namespace>-<release>-values.yaml` — the release's current values
- `helm-<namespace>-<release>-manifest.yaml` — the full rendered manifest

This requires `helm` to be installed on your server.

## Credential discovery

For database pods, SimpleBackups attempts to resolve credentials automatically:

1. **Kubernetes Secrets** — if env vars reference a Secret via `secretKeyRef`, SimpleBackups reads the secret value and stores it encrypted
2. **Hardcoded env vars** — if the password or username is set directly on the pod spec, it's picked up from the env var value
3. **Default usernames** — if no username is found, defaults are applied (`root` for MySQL/MariaDB, `postgres` for PostgreSQL)

If credentials can't be resolved automatically, you'll be prompted to enter them manually when enabling the backup.

## Multi-cluster setup

If you manage multiple Kubernetes clusters, create a **separate Stack per cluster**. Use different contexts within the same kubeconfig, or provide separate kubeconfig files per Stack. Each Stack can have its own schedule and storage destination.

## Namespace filtering

By default, SimpleBackups discovers all namespaces. To limit the scan, go to **Stack → Configuration → Discovery Settings** and enter a comma-separated list of namespaces (for example, `default,production,staging`). This is useful for large clusters where you only want to back up specific namespaces.

## Troubleshooting

### "kubectl not available or cannot connect to cluster"

- Verify `kubectl cluster-info` works on your server
- Check that the server has network access to the Kubernetes API endpoint
- If using a kubeconfig, make sure it's valid (`apiVersion` and `clusters` sections must be present)

### Database pod discovered but credentials missing

- Check that the pod's environment variables reference Kubernetes Secrets correctly
- You can enter credentials manually when enabling the backup
- The credentials are stored encrypted and never exposed in the UI

### PVC backup fails with "No running pod found"

- The pod that had the PVC mounted may have been rescheduled with a new name
- Re-run discovery to refresh pod information
- Make sure the pod is in **Running** state

### Helm discovery returns no results

- Verify `helm` is installed on your server: `helm version`
- Make sure the namespaces you're scanning actually have Helm releases: `helm list -A`

## Frequently asked questions

**Does SimpleBackups install anything in my cluster?**

No. There are no agents, CRDs, or cluster-side components of any kind.

**What kubectl permissions are needed?**

Read access to the namespaces you want to discover: `get`, `list` on pods, pvcs, configmaps, secrets, services, deployments, and so on. For PVC backups, `exec` access on pods is also required.

**Are Secret values stored by SimpleBackups?**

Database credentials resolved from Secrets (username and password) are stored encrypted in SimpleBackups. Full Secret YAML exports (if you enable ConfigMaps & Secrets discovery) are stored in your own storage destination — SimpleBackups does not read or store the file contents.

**Can I back up across multiple namespaces with one Stack?**

Yes. By default all namespaces are scanned. You can also specify a list of namespaces in the discovery settings.

**What if a pod is rescheduled after discovery?**

For databases, the connection goes through the Kubernetes Service (stable DNS), so pod rescheduling doesn't affect backups. For PVCs, SimpleBackups uses a multi-step pod resolution strategy (app label → stored pod name → PVC scan) to find a running pod even if the name changed.

- [Stack Discovery Overview](https://simplebackups.com/docs/stack-discovery/overview): How Stacks scan your infrastructure and turn discovered resources into automated backups.