Configuration - Khanh Docs

This guide covers how to configure the PostHog provider for Pulumi.

Overview#

The PostHog provider enables management of product analytics, feature flags, and event tracking resources. It requires an API key for authentication and supports both PostHog Cloud and self-hosted instances.

Provider Configuration#

Basic Setup#

import * as posthog from "pulumi-posthog";import * as pulumi from "@pulumi/pulumi";const config = new pulumi.Config("posthog");const apiKey = config.requireSecret("apiKey");const host = config.get("host") || "https://us.posthog.com";

Configuration Methods#

1. Pulumi Configuration (Recommended)#

# Set API key (encrypted)pulumi config set posthog:apiKey YOUR_API_KEY --secret# Set host (optional, defaults to https://us.posthog.com)pulumi config set posthog:host https://us.posthog.com

2. Environment Variables#

export POSTHOG_API_KEY="phx_your_api_key_here"export POSTHOG_HOST="https://us.posthog.com"

3. Provider Block#

const provider = new posthog.Provider("posthog", {    apiKey: config.requireSecret("apiKey"),    host: "https://us.posthog.com",});

Getting API Credentials#

Create Personal API Key#

Log in to your PostHog instance at app.posthog.com (or your self-hosted URL)
Navigate to Settings → User → Personal API Keys
Click Create Personal API Key
Copy the generated API key (starts with phx_)

Required Permissions#

The API key should have access to:

Feature flags (read/write)
Insights (read/write)
Dashboards (read/write)
Alerts (read/write)
Hog functions (read/write)

Self-Hosted PostHog#

If you're using a self-hosted PostHog instance, configure the custom host URL:

pulumi config set posthog:host https://posthog.yourcompany.com

Or using environment variables:

export POSTHOG_HOST="https://posthog.yourcompany.com"

Example with Self-Hosted Instance#

import * as pulumi from "@pulumi/pulumi";import * as posthog from "pulumi-posthog";const config = new pulumi.Config("posthog");// Configure provider for self-hosted instanceconst provider = new posthog.Provider("self-hosted", {    host: "https://posthog.yourcompany.com",    apiKey: config.requireSecret("apiKey"),});// Use the providerconst flag = new posthog.FeatureFlag("beta-feature", {    key: "new-feature",    name: "New Feature",    active: true,}, { provider });

Configuration Options#

Property	Type	Required	Default	Description
`apiKey`	string	Yes	-	PostHog Personal API Key (starts with `phx_`)
`host`	string	No	`https://us.posthog.com`	PostHog instance URL

Best Practices#

Security#

// ✅ DO: Use Pulumi secrets for API keysconst config = new pulumi.Config("posthog");const apiKey = config.requireSecret("apiKey");// ❌ DON'T: Hardcode API keysconst flag = new posthog.FeatureFlag("bad", {    key: "feature",    name: "Feature",    // Never include secrets in code!});

Multi-Environment Setup#

import * as pulumi from "@pulumi/pulumi";import * as posthog from "pulumi-posthog";const stack = pulumi.getStack();const config = new pulumi.Config("posthog");// Different API keys per environmentconst apiKey = config.requireSecret(`${stack}-apiKey`);// Environment-specific feature flagconst flag = new posthog.FeatureFlag(`${stack}-feature`, {    key: `${stack}-new-feature`,    name: `${stack} New Feature`,    active: stack === "production",});

Multi-Project Setup#

// Project Aconst projectAConfig = new pulumi.Config("posthog-project-a");const projectAProvider = new posthog.Provider("project-a", {    apiKey: projectAConfig.requireSecret("apiKey"),    host: "https://us.posthog.com",});// Project Bconst projectBConfig = new pulumi.Config("posthog-project-b");const projectBProvider = new posthog.Provider("project-b", {    apiKey: projectBConfig.requireSecret("apiKey"),    host: "https://eu.posthog.com",});

Troubleshooting#

Authentication Errors#

Error: 401 Unauthorized

Solution:

Verify your API key is correct and starts with phx_
Check that the API key hasn't expired
Ensure the API key has necessary permissions

# Test API keycurl -H "Authorization: Bearer phx_your_key_here" \     https://us.posthog.com/api/projects/@current/feature_flags/

Invalid Host Configuration#

Error: Connection refused

Solution:

Ensure your host URL is correct and includes the protocol (https://)
For PostHog Cloud, use https://us.posthog.com or https://eu.posthog.com
For self-hosted, use your instance URL

Permission Denied#

Error: 403 Forbidden

Solution:

Ensure your API key has appropriate project access
Personal API keys need appropriate permissions
Check that you're accessing resources in the correct project

Overview#

Provider Configuration#

Basic Setup#

Configuration Methods#

1. Pulumi Configuration (Recommended)#

2. Environment Variables#

3. Provider Block#

Getting API Credentials#

Create Personal API Key#

Required Permissions#

Self-Hosted PostHog#

Example with Self-Hosted Instance#

Configuration Options#

Best Practices#

Security#

Multi-Environment Setup#

Multi-Project Setup#

Troubleshooting#

Authentication Errors#

Invalid Host Configuration#

Permission Denied#

Additional Resources#