Kubernetes Troubleshooting

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:

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+):

helm install flipt flipt/flipt-v2 -f values.yaml --skip-schema-validation

Or for upgrades:

helm upgrade flipt flipt/flipt-v2 -f values.yaml --skip-schema-validation

--skip-schema-validation bypasses chart schema checks entirely. Use it as a temporary workaround while tracking upstream schema fixes in flipt-io/helm-charts — typos in your values.yaml will no longer be caught automatically when this flag is set.

Machine ID Not Found (License Validation)

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

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:

/var/lib/dbus/machine-id
/etc/machine-id
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: Configure a Stable Machine ID

Set license.machine_id or the FLIPT_LICENSE_MACHINE_ID environment variable to a stable value for the deployment. Use the same value across restarts for the same licensed deployment. For Helm deployments, set the environment variable from a Kubernetes Secret:

extraEnvVars:
  - name: FLIPT_LICENSE_MACHINE_ID
    valueFrom:
      secretKeyRef:
        name: flipt-license
        key: machine-id

See Licensing for more details.

Legacy Workaround: Mount the Host Machine ID

If you cannot configure FLIPT_LICENSE_MACHINE_ID, you can mount the Kubernetes node’s /etc/machine-id into the Flipt container by adding these values to your values.yaml:

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.

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). Prefer FLIPT_LICENSE_MACHINE_ID when possible.

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:

persistence:
  enabled: true
  storageClass: "standard" # Use your cluster's storage class
  size: 10Gi

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

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:

flipt:
  config:
    storage:
      my-storage:
        backend:
          type: local
          path: /var/opt/flipt

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.

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 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:

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 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:

envFrom:
  - secretRef:
      name: flipt-secrets

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

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 — syncs secrets from GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault
Sealed Secrets — encrypt secrets client-side, commit encrypted SealedSecret resources to Git
ArgoCD Vault Plugin — 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:

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

Getting Started

Pro Features

Configuration

Integration

CLI

Guides

Tooling

Kubernetes Troubleshooting

Helm Schema Validation Errors

Machine ID Not Found (License Validation)

Why This Happens

Solution: Configure a Stable Machine ID

Legacy Workaround: Mount the Host Machine ID

Affected Environments

Persistent Volume Configuration

Enable Persistence

Match the Storage Backend Path

Secrets Management with GitOps

Using Kubernetes Secrets with Environment Variable Substitution

Compatible Secret Management Tools

Using Individual Environment Variables

​Helm Schema Validation Errors

​Machine ID Not Found (License Validation)

​Why This Happens

​Solution: Configure a Stable Machine ID

​Legacy Workaround: Mount the Host Machine ID

​Affected Environments

​Persistent Volume Configuration

​Enable Persistence

​Match the Storage Backend Path

​Secrets Management with GitOps

​Using Kubernetes Secrets with Environment Variable Substitution

​Compatible Secret Management Tools

​Using Individual Environment Variables

Helm Schema Validation Errors

Machine ID Not Found (License Validation)

Why This Happens

Solution: Configure a Stable Machine ID

Legacy Workaround: Mount the Host Machine ID

Affected Environments

Persistent Volume Configuration

Enable Persistence

Match the Storage Backend Path

Secrets Management with GitOps

Using Kubernetes Secrets with Environment Variable Substitution

Compatible Secret Management Tools

Using Individual Environment Variables