Skip to content

mixpanel_feature_flag (Resource)

Manages a Mixpanel feature flag — a configuration that controls feature rollout and variant delivery to users. Feature flags enable gradual rollouts, A/B testing, and instant kill-switches without code deployment.

Example Usage

resource "mixpanel_feature_flag" "new_checkout" {
  name           = "New Checkout Flow"
  key            = "new_checkout_flow"
  description    = "Gradual rollout of redesigned checkout"
  context        = "distinct_id"
  serving_method = "remote_or_local"
  desired_state  = "enabled"

  ruleset = {
    rollout = [
      {
        rollout_percentage = 0.1 # 10% of users
        variant_splits = {
          on = 1.0
        }
      }
    ]
    variants = [
      {
        is_control = false
        key        = "on"
        split      = 1.0
        value      = "true"
      }
    ]
  }
}

# Boolean feature gate (simple on/off)
resource "mixpanel_feature_flag" "beta_features" {
  name           = "Beta Features"
  key            = "beta_features"
  context        = "distinct_id"
  serving_method = "remote_or_local"
  desired_state  = "enabled"

  ruleset = {
    rollout = [
      {
        rollout_percentage = 1.0
        variant_splits = {
          on = 1.0
        }
      }
    ]
    variants = [
      {
        is_control = true
        key        = "on"
        split      = 1.0
        value      = "true"
      }
    ]
  }
}

# Multi-variant flag for A/B testing
resource "mixpanel_feature_flag" "hero_variant" {
  name           = "Homepage Hero Variant"
  key            = "hero_variant"
  context        = "distinct_id"
  serving_method = "remote_or_local"
  desired_state  = "enabled"

  ruleset = {
    rollout = [
      {
        rollout_percentage = 1.0
        variant_splits = {
          control   = 0.5
          variant_a = 0.5
        }
      }
    ]
    variants = [
      {
        is_control = true
        key        = "control"
        split      = 0.5
        value      = "original"
      },
      {
        is_control = false
        key        = "variant_a"
        split      = 0.5
        value      = "testimonials"
      }
    ]
  }
}

Lifecycle management (desired_state)

The desired_state attribute controls flag rollout status. Valid states:

  • enabled — The flag is active and serving variants to users according to the ruleset.
  • disabled — The flag is turned off. No variants are served.
  • archived — Soft-deletes the flag. The API requires flags to be disabled before archiving, so the provider automatically disables an enabled flag first. Setting desired_state to enabled or disabled restores an archived flag.

When desired_state is unset, the provider tracks the server-side state without performing transitions.

Important: If both desired_state and status are set in configuration, they must agree. For archival, leave status unset or set it to disabled.

Ruleset configuration

The ruleset block defines variant splits and rollout percentages:

  • rollout_percentage — Fraction of traffic to include (0.0–1.0). Example: 0.1 = 10% of users.
  • variant_splits — Map of variant keys to their traffic allocation within the rollout percentage. Values must sum to 1.0.
  • variants — List of possible values the flag can return. Each variant has:
  • key — Unique identifier matching a key in variant_splits.
  • value — The value returned to the client (boolean "true"/"false" string, or any JSON-serializable string).
  • split — Traffic fraction for this variant (0.0–1.0), matching the corresponding variant_splits value.
  • is_control — Whether this is the control/baseline variant.

Workspace membership

Feature-flag API calls use the project's workspace-scoped endpoint, which requires workspace membership. The provider automatically retries across the project's global, default, and first workspaces. If the service account is not a member of any workspace, operations fail with an explicit error. Add the service account to the project's global or default workspace to resolve this.

Schema

Required

  • context (String)
  • key (String)
  • name (String)
  • ruleset (Attributes) (see below for nested schema)
  • serving_method (String)

Optional

  • content_environments (String)
  • content_environments_id (String)
  • data_group_id (String)
  • description (String)
  • desired_state (String) Lifecycle state to drive the flag to: enabled, disabled, or archived. Enable/disable are applied through the flag status field; archived soft-deletes the flag via the archive endpoint (the provider disables an enabled flag first) and leaving archived restores it. When unset, tracks the server-side state.
  • experiment_id (String)
  • flag_id (String)
  • hash_salt (String)
  • is_experiment_active (Boolean)
  • reset_hash_salt (Boolean)
  • share_with_project (Boolean) Whether to share this entity with the whole project after creation. Entities created by a service account are otherwise visible only to that service account. Defaults to true. See the Entity sharing guide.
  • status (String)
  • tags (List of String)
  • workspace_id (Number)

Read-Only

  • allow_staff_override (Boolean)
  • can_pin (Boolean)
  • can_share (Boolean)
  • can_update_basic (Boolean)
  • can_view (Boolean)
  • content_type (String)
  • created (String)
  • creator_email (String)
  • creator_id (Number)
  • creator_name (String)
  • deleted (String)
  • enabled_at (String)
  • id (String) The ID of this resource.
  • is_favorited (Boolean)
  • is_shared_with_project (Boolean)
  • is_superadmin (Boolean)
  • last_modified_by_email (String)
  • last_modified_by_id (Number)
  • last_modified_by_name (String)
  • modified (String)
  • pinned_date (String)
  • project_id (Number)
  • project_name (String)

Nested Schema for ruleset

Required:

Nested Schema for ruleset.rollout

Required:

  • rollout_percentage (Number)
  • variant_splits (Map of Number)

Optional:

  • cohort_hash (String)
  • name (String)

Nested Schema for ruleset.variants

Required:

  • is_control (Boolean)
  • key (String)
  • split (Number)
  • value (String)

Optional:

  • description (String)
  • is_sticky (Boolean)
  • screenshot (String)

Import

Import uses a composite ID format: PROJECT_ID:FLAG_ID.

import {
  to = mixpanel_feature_flag.new_checkout
  id = "1234567:flag_abc123def456"
}

Retrieve the flag ID from the Mixpanel UI URL or via the mixpanel_feature_flag data source.

  • mixpanel_experiment — Experiments can drive feature flags to enable data-driven ship decisions and variant rollout.