tessl/npm-pulumi--kubernetes

A comprehensive Pulumi resource provider for creating and managing Kubernetes resources and workloads in a running cluster

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Provider Configuration

Name: tessl/npm-pulumi--kubernetes
Author: tessl

The Kubernetes Provider class manages cluster connectivity, authentication, and global configuration options that affect how Kubernetes resources are deployed and managed by Pulumi.

Package Import

import { Provider, ProviderArgs } from "@pulumi/kubernetes";
import * as k8s from "@pulumi/kubernetes";

Provider Class

The Provider class extends pulumi.ProviderResource and manages the connection to Kubernetes clusters.

class Provider extends pulumi.ProviderResource {
    constructor(name: string, args?: ProviderArgs, opts?: pulumi.ResourceOptions)
    
    public static isInstance(obj: any): obj is Provider
}

ProviderArgs Interface

Comprehensive configuration options for the Kubernetes provider.

interface ProviderArgs {
    // Cluster Connection
    kubeconfig?: pulumi.Input<string>;               // Path to kubeconfig file or kubeconfig content
    context?: pulumi.Input<string>;                  // Kubeconfig context name
    cluster?: pulumi.Input<string>;                  // Kubeconfig cluster name
    
    // Cluster Identity and Lifecycle
    clusterIdentifier?: pulumi.Input<string>;        // Custom cluster identifier for provider replacement control
    
    // Namespace Management
    namespace?: pulumi.Input<string>;                // Default namespace for resources
    
    // Feature Toggles
    enableServerSideApply?: pulumi.Input<boolean>;   // Enable server-side apply (default: true)
    enableConfigMapMutable?: pulumi.Input<boolean>;  // Allow ConfigMap mutations (beta)
    enableSecretMutable?: pulumi.Input<boolean>;     // Allow Secret mutations (beta)
    
    // Error Handling
    deleteUnreachable?: pulumi.Input<boolean>;       // Delete unreachable cluster resources from state
    skipUpdateUnreachable?: pulumi.Input<boolean>;   // Skip updates to unreachable clusters
    
    // Development and Testing
    renderYamlToDirectory?: pulumi.Input<string>;    // Render manifests to directory instead of applying
    
    // Helm Integration
    helmReleaseSettings?: pulumi.Input<HelmReleaseSettings>; // Helm-specific configuration
    
    // Client Configuration
    kubeClientSettings?: pulumi.Input<KubeClientSettings>;  // Kubernetes client tuning
    
    // Logging and Warnings
    suppressDeprecationWarnings?: pulumi.Input<boolean>;     // Suppress API deprecation warnings
    suppressHelmHookWarnings?: pulumi.Input<boolean>;        // Suppress Helm hook warnings
}

HelmReleaseSettings

Configuration options for Helm integration when using the provider.

interface HelmReleaseSettings {
    driver?: pulumi.Input<"secret" | "configmap" | "memory">; // Helm storage driver
    pluginsPath?: pulumi.Input<string>;                       // Path to Helm plugins directory
    registryConfigPath?: pulumi.Input<string>;                // Path to registry config file
    repositoryConfigPath?: pulumi.Input<string>;              // Path to repository config file
    repositoryCache?: pulumi.Input<string>;                   // Path to repository cache directory
    
    // Helm client configuration
    maxHistory?: pulumi.Input<number>;                        // Maximum number of release revisions
    debug?: pulumi.Input<boolean>;                            // Enable debug logging
}

KubeClientSettings

Configuration options for tuning the Kubernetes client behavior.

interface KubeClientSettings {
    // Performance Tuning
    timeout?: pulumi.Input<number>;                          // Request timeout in seconds
    burst?: pulumi.Input<number>;                            // Burst rate for requests
    qps?: pulumi.Input<number>;                              // Queries per second rate limit
    
    // Retry Configuration
    backoff?: pulumi.Input<{
        delay?: pulumi.Input<number>;                        // Initial retry delay
        factor?: pulumi.Input<number>;                       // Backoff factor
        steps?: pulumi.Input<number>;                        // Maximum retry steps
    }>;
}

Basic Provider Configurations

Default Provider

// Use default kubeconfig and context
const defaultProvider = new k8s.Provider("default");

// Resources will use this provider automatically if it's the default
const pod = new k8s.core.v1.Pod("my-pod", {
    spec: {
        containers: [{
            name: "app",
            image: "nginx:latest",
        }],
    },
});

Explicit Kubeconfig

// Specify kubeconfig file path
const fileProvider = new k8s.Provider("file-provider", {
    kubeconfig: "~/.kube/config",
    context: "production-cluster",
});

// Kubeconfig content as string
const contentProvider = new k8s.Provider("content-provider", {
    kubeconfig: `
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTi...
    server: https://kubernetes.example.com
  name: production
contexts:
- context:
    cluster: production
    user: admin
  name: production
current-context: production
kind: Config
users:
- name: admin
  user:
    client-certificate-data: LS0tLS1CRUdJTi...
    client-key-data: LS0tLS1CRUdJTi...
`,
    context: "production",
});

Environment-Based Configuration

// Use environment variables for configuration
const envProvider = new k8s.Provider("env-provider", {
    kubeconfig: process.env.KUBECONFIG || "~/.kube/config",
    context: process.env.KUBE_CONTEXT,
    namespace: process.env.KUBE_NAMESPACE || "default",
});

// Conditional provider configuration
const environment = pulumi.getStack();
const provider = new k8s.Provider("stack-provider", {
    kubeconfig: environment === "production" 
        ? "/etc/kubernetes/prod-config"
        : "~/.kube/config",
    context: `${environment}-cluster`,
    namespace: `app-${environment}`,
    enableServerSideApply: environment === "production",
});

Advanced Provider Configurations

High-Performance Configuration

const performanceProvider = new k8s.Provider("performance", {
    kubeconfig: "~/.kube/config",
    enableServerSideApply: true,
    kubeClientSettings: {
        timeout: 60,      // 60 second timeout
        burst: 120,       // Allow burst of 120 requests
        qps: 50,          // 50 queries per second steady state
        backoff: {
            delay: 500,   // 500ms initial delay
            factor: 2,    // Double delay each retry
            steps: 5,     // Maximum 5 retries
        },
    },
});

Development Configuration

const devProvider = new k8s.Provider("development", {
    kubeconfig: "~/.kube/config",
    context: "docker-desktop",
    namespace: "development",
    
    // Development features
    enableConfigMapMutable: true,
    enableSecretMutable: true,
    suppressDeprecationWarnings: false, // Show warnings in development
    
    // Fast iteration
    kubeClientSettings: {
        timeout: 30,
        qps: 100, // Higher QPS for faster development
        burst: 200,
    },
});

Production Configuration

const prodProvider = new k8s.Provider("production", {
    kubeconfig: process.env.PROD_KUBECONFIG,
    context: "production-cluster",
    
    // Production settings
    enableServerSideApply: true,
    suppressDeprecationWarnings: true,
    suppressHelmHookWarnings: true,
    
    // Stability settings
    deleteUnreachable: false,        // Don't auto-delete unreachable resources
    skipUpdateUnreachable: true,     // Skip updates if cluster unreachable
    
    // Performance tuning for production
    kubeClientSettings: {
        timeout: 300,    // 5 minute timeout for large operations
        burst: 50,       // Conservative burst
        qps: 25,         // Conservative QPS
        backoff: {
            delay: 1000,  // 1 second initial delay
            factor: 1.5,  // Gradual backoff
            steps: 10,    // More retries for production
        },
    },
    
    // Cluster identity for proper lifecycle management
    clusterIdentifier: "prod-us-west-2-cluster-v1",
});

Multi-Cluster Configuration

// Primary cluster provider
const primaryProvider = new k8s.Provider("primary", {
    kubeconfig: "~/.kube/primary-config",
    context: "primary-cluster",
    clusterIdentifier: "primary-us-east-1",
});

// Secondary cluster provider
const secondaryProvider = new k8s.Provider("secondary", {
    kubeconfig: "~/.kube/secondary-config", 
    context: "secondary-cluster",
    clusterIdentifier: "secondary-us-west-2",
});

// Disaster recovery cluster
const drProvider = new k8s.Provider("disaster-recovery", {
    kubeconfig: "~/.kube/dr-config",
    context: "dr-cluster",
    clusterIdentifier: "dr-eu-west-1",
    
    // DR-specific settings
    skipUpdateUnreachable: true,
    deleteUnreachable: false,
});

// Deploy to multiple clusters
const primaryApp = new k8s.apps.v1.Deployment("app-primary", {
    spec: {
        replicas: 3,
        selector: { matchLabels: { app: "myapp" }},
        template: {
            metadata: { labels: { app: "myapp" }},
            spec: {
                containers: [{
                    name: "app",
                    image: "myapp:v1.0",
                }],
            },
        },
    },
}, { provider: primaryProvider });

const secondaryApp = new k8s.apps.v1.Deployment("app-secondary", {
    spec: {
        replicas: 2, // Fewer replicas in secondary
        selector: { matchLabels: { app: "myapp" }},
        template: {
            metadata: { labels: { app: "myapp" }},
            spec: {
                containers: [{
                    name: "app", 
                    image: "myapp:v1.0",
                }],
            },
        },
    },
}, { provider: secondaryProvider });

Testing and Development Features

// Provider for testing - renders to files instead of applying
const testProvider = new k8s.Provider("test-render", {
    renderYamlToDirectory: "./test-output",
    kubeconfig: "~/.kube/config", // Still needed for API discovery
});

// Resources created with this provider will be rendered to files
const testApp = new k8s.apps.v1.Deployment("test-app", {
    spec: {
        replicas: 1,
        selector: { matchLabels: { app: "test" }},
        template: {
            metadata: { labels: { app: "test" }},
            spec: {
                containers: [{
                    name: "test",
                    image: "nginx:latest",
                }],
            },
        },
    },
}, { provider: testProvider });

// Mutable resources provider for development
const mutableProvider = new k8s.Provider("mutable", {
    kubeconfig: "~/.kube/config",
    enableConfigMapMutable: true,
    enableSecretMutable: true,
});

// ConfigMaps and Secrets can be modified in-place with this provider
const devConfig = new k8s.core.v1.ConfigMap("dev-config", {
    data: {
        "app.properties": "debug=true\nlog.level=DEBUG",
    },
}, { provider: mutableProvider });

Helm Integration Configuration

const helmProvider = new k8s.Provider("helm-optimized", {
    kubeconfig: "~/.kube/config",
    
    // Helm-specific settings
    helmReleaseSettings: {
        driver: "secret",                              // Use secrets for Helm storage
        pluginsPath: "/opt/helm/plugins",             // Custom plugin location
        registryConfigPath: "~/.config/helm/registry.json",
        repositoryConfigPath: "~/.config/helm/repositories.yaml",
        repositoryCache: "~/.cache/helm/repository",
        maxHistory: 10,                               // Keep 10 release revisions
        debug: false,                                 // Disable debug logging
    },
    
    suppressHelmHookWarnings: true,
});

// Helm charts deployed with this provider will use the optimized settings
const helmChart = new k8s.helm.v4.Chart("optimized-chart", {
    chart: "nginx",
    repositoryOpts: {
        repo: "https://charts.bitnami.com/bitnami",
    },
}, { provider: helmProvider });

Provider Usage Patterns

Provider Factory Function

interface ClusterConfig {
    name: string;
    kubeconfig: string;
    context: string;
    namespace?: string;
    environment: "dev" | "staging" | "prod";
}

function createProvider(config: ClusterConfig): k8s.Provider {
    const baseSettings = {
        kubeconfig: config.kubeconfig,
        context: config.context,
        namespace: config.namespace || "default",
        clusterIdentifier: `${config.name}-${config.environment}`,
    };
    
    switch (config.environment) {
        case "dev":
            return new k8s.Provider(`${config.name}-dev`, {
                ...baseSettings,
                enableConfigMapMutable: true,
                enableSecretMutable: true,
                suppressDeprecationWarnings: false,
                kubeClientSettings: {
                    timeout: 30,
                    qps: 100,
                    burst: 200,
                },
            });
            
        case "staging":
            return new k8s.Provider(`${config.name}-staging`, {
                ...baseSettings,
                enableServerSideApply: true,
                suppressDeprecationWarnings: true,
                kubeClientSettings: {
                    timeout: 60,
                    qps: 50,
                    burst: 100,
                },
            });
            
        case "prod":
            return new k8s.Provider(`${config.name}-prod`, {
                ...baseSettings,
                enableServerSideApply: true,
                suppressDeprecationWarnings: true,
                suppressHelmHookWarnings: true,
                deleteUnreachable: false,
                skipUpdateUnreachable: true,
                kubeClientSettings: {
                    timeout: 300,
                    qps: 25,
                    burst: 50,
                    backoff: {
                        delay: 1000,
                        factor: 1.5,
                        steps: 10,
                    },
                },
            });
            
        default:
            throw new Error(`Unknown environment: ${config.environment}`);
    }
}

// Use the factory
const clusters = [
    {
        name: "us-east-1", 
        kubeconfig: process.env.US_EAST_1_KUBECONFIG!,
        context: "us-east-1-prod",
        environment: "prod" as const,
    },
    {
        name: "us-west-2",
        kubeconfig: process.env.US_WEST_2_KUBECONFIG!,
        context: "us-west-2-prod", 
        environment: "prod" as const,
    },
];

const providers = clusters.map(createProvider);

Resource Deployment with Providers

// Deploy the same application to multiple providers
function deployApp(name: string, provider: k8s.Provider) {
    const deployment = new k8s.apps.v1.Deployment(`${name}-deployment`, {
        spec: {
            replicas: 3,
            selector: {
                matchLabels: { app: name },
            },
            template: {
                metadata: {
                    labels: { app: name },
                },
                spec: {
                    containers: [{
                        name: "app",
                        image: `${name}:v1.0`,
                        ports: [{ containerPort: 8080 }],
                    }],
                },
            },
        },
    }, { provider });
    
    const service = new k8s.core.v1.Service(`${name}-service`, {
        spec: {
            selector: { app: name },
            ports: [{ port: 80, targetPort: 8080 }],
            type: "LoadBalancer",
        },
    }, { provider });
    
    return { deployment, service };
}

// Deploy to all providers
const deployments = providers.map((provider, index) => 
    deployApp(`myapp-region-${index}`, provider)
);

Best Practices