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

# Kubernetes Troubleshooting

> Common issues and solutions when deploying Flipt v2 to Kubernetes

This guide covers common issues encountered when deploying Flipt v2 to Kubernetes using the official Helm chart, along with their solutions.

## Helm Schema Validation Errors

When installing or upgrading the Flipt Helm chart, you may encounter schema validation errors like:

```text theme={null}
helm install flipt flipt/flipt-v2 -f values.yaml
Error: INSTALLATION FAILED: values don't meet the specifications of the schema(s) in the following chart(s):
flipt-v2:
- autoscaling: Additional property targetMemoryUtilizationPercentage is not allowed
- resources: Additional property limits is not allowed
- resources: Additional property requests is not allowed
```

This happens when the chart's JSON schema doesn't cover all valid configuration options. To work around this, skip schema validation (requires Helm 3.13+):

```bash theme={null}
helm install flipt flipt/flipt-v2 -f values.yaml --skip-schema-validation
```

Or for upgrades:

```bash theme={null}
helm upgrade flipt flipt/flipt-v2 -f values.yaml --skip-schema-validation
```

<Note>
  `--skip-schema-validation` bypasses chart schema checks entirely. Use it as a
  temporary workaround while tracking upstream schema fixes in
  [flipt-io/helm-charts](https://github.com/flipt-io/helm-charts) — typos in
  your `values.yaml` will no longer be caught automatically when this flag is
  set.
</Note>

## Machine ID Not Found (License Validation)

When running Flipt Pro on containerd-based Kubernetes clusters (such as GKE or modern EKS), you may see:

```text theme={null}
license is invalid; additional features are disabled.
{"error": "machineid: machineid: no machine-id found"}
```

### Why This Happens

Flipt uses a machine fingerprint for license validation. The fingerprinting library reads from:

1. `/var/lib/dbus/machine-id`
2. `/etc/machine-id`
3. Docker-specific paths in `/proc/self/cgroup` and `/proc/self/mountinfo`

In containerd-based environments (GKE, EKS with containerd, etc.), none of these files exist inside the container because:

* The Flipt container image is Alpine-based and doesn't include dbus
* `/etc/machine-id` is not present in minimal container images
* The Docker-specific fallback paths don't match containerd's format

### Solution: Mount the Host Machine ID

Mount the Kubernetes node's `/etc/machine-id` into the Flipt container by adding these values to your `values.yaml`:

```yaml theme={null}
extraVolumeMounts:
  - name: machine-id
    mountPath: /etc/machine-id
    readOnly: true

extraVolumes:
  - name: machine-id
    hostPath:
      path: /etc/machine-id
```

This mounts the host node's machine ID into the container, allowing the license system to identify the machine.

<Note>
  This workaround depends on `hostPath` volumes and a node filesystem. It won't
  work in environments that don't allow `hostPath` (for example, many managed
  serverless node offerings such as EKS Fargate).
</Note>

<Warning>
  If your cluster's security policy restricts `hostPath` volumes, you may need
  to request an exception for this read-only mount, or wait for the
  [configurable machine fingerprint
  feature](https://github.com/flipt-io/flipt/issues/5426) to ship.
</Warning>

### Affected Environments

* Google Kubernetes Engine (GKE)
* Amazon EKS with containerd runtime
* Any Kubernetes cluster using containerd instead of Docker
* Rootless container environments

## Persistent Volume Configuration

Flipt needs a writable directory for local state. If you see read-only filesystem errors or Flipt fails to start with write permission errors, you likely need to configure persistence.

### Enable Persistence

Add the following to your `values.yaml`:

```yaml theme={null}
persistence:
  enabled: true
  storageClass: "standard" # Use your cluster's storage class
  size: 10Gi
```

<Tip>
  Run `kubectl get storageclass` to see available storage classes in your
  cluster. The default varies by provider and cluster configuration.
</Tip>

### Match the Storage Backend Path

The `path` in your Flipt storage backend configuration refers to the path **inside the container**, not on the host. It must match where the PersistentVolumeClaim is mounted.

The Helm chart mounts the PVC at `/var/opt/flipt` by default. Your storage backend configuration should use this path:

```yaml theme={null}
flipt:
  config:
    storage:
      my-storage:
        backend:
          type: local
          path: /var/opt/flipt
```

<Warning>
  Do not use a relative path like `"."` for the backend path. This writes to the
  container's working directory, which may be read-only. Always use the absolute
  path where the PVC is mounted.
</Warning>

## Secrets Management with GitOps

When deploying Flipt via ArgoCD, FluxCD, or other GitOps tools, you should not commit sensitive values (license keys, Git access tokens) to your Git repository inside `values.yaml`.

### Using Kubernetes Secrets with Environment Variable Substitution

Flipt supports [environment variable substitution](/v2/configuration/overview#environment-substitution-and-secret-references) in configuration values using the `${env:VAR_NAME}` syntax. Combined with the Helm chart's `envFrom` support, this lets you keep secrets out of your values file.

**Step 1:** Create a Kubernetes Secret containing your sensitive values:

```bash theme={null}
kubectl create secret generic flipt-secrets \
  --from-literal=FLIPT_LICENSE_KEY=your-license-key \
  --from-literal=FLIPT_GIT_ACCESS_TOKEN=your-access-token
```

Or use [External Secrets Operator](https://external-secrets.io/) to sync from your cloud provider's secret manager (GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault).

**Step 2:** Reference the Secret in your `values.yaml`:

```yaml theme={null}
envFrom:
  - secretRef:
      name: flipt-secrets
```

**Step 3:** Use environment variable references in your Flipt configuration:

```yaml theme={null}
flipt:
  config:
    license:
      key: ${env:FLIPT_LICENSE_KEY}
    credentials:
      my-git:
        type: access_token
        access_token: ${env:FLIPT_GIT_ACCESS_TOKEN}
    storage:
      my-storage:
        remote: "https://github.com/your-org/flipt-config.git"
        branch: main
        credentials: "my-git"
```

This approach keeps your `values.yaml` free of secrets and safe to commit to Git.

### Compatible Secret Management Tools

This pattern works with any tool that creates Kubernetes Secrets:

* **[External Secrets Operator](https://external-secrets.io/)** — syncs secrets from GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault
* **[Sealed Secrets](https://sealed-secrets.netlify.app/)** — encrypt secrets client-side, commit encrypted `SealedSecret` resources to Git
* **[ArgoCD Vault Plugin](https://argocd-vault-plugin.readthedocs.io/)** — inject secrets from Vault at deploy time
* **`kubectl create secret`** — create secrets manually for simpler setups

### Using Individual Environment Variables

If you prefer to inject secrets as individual environment variables rather than from a Secret reference, use `extraEnvVars`:

```yaml theme={null}
extraEnvVars:
  - name: FLIPT_LICENSE_KEY
    valueFrom:
      secretKeyRef:
        name: flipt-license
        key: license-key
  - name: FLIPT_GIT_ACCESS_TOKEN
    valueFrom:
      secretKeyRef:
        name: flipt-git-creds
        key: access-token
```