Skip to main content
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:
  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: 
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).
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 to ship.

​
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