0
# Provider Configuration
1

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

4
## Package Import
5

6
```typescript { .api }
7
import { Provider, ProviderArgs } from "@pulumi/kubernetes";
8
import * as k8s from "@pulumi/kubernetes";
9
```
10

11
## Provider Class
12

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

15
```typescript { .api }
16
class Provider extends pulumi.ProviderResource {
17
    constructor(name: string, args?: ProviderArgs, opts?: pulumi.ResourceOptions)
18
    
19
    public static isInstance(obj: any): obj is Provider
20
}
21
```
22

23
## ProviderArgs Interface
24

25
Comprehensive configuration options for the Kubernetes provider.
26

27
```typescript { .api }
28
interface ProviderArgs {
29
    // Cluster Connection
30
    kubeconfig?: pulumi.Input<string>;               // Path to kubeconfig file or kubeconfig content
31
    context?: pulumi.Input<string>;                  // Kubeconfig context name
32
    cluster?: pulumi.Input<string>;                  // Kubeconfig cluster name
33
    
34
    // Cluster Identity and Lifecycle
35
    clusterIdentifier?: pulumi.Input<string>;        // Custom cluster identifier for provider replacement control
36
    
37
    // Namespace Management
38
    namespace?: pulumi.Input<string>;                // Default namespace for resources
39
    
40
    // Feature Toggles
41
    enableServerSideApply?: pulumi.Input<boolean>;   // Enable server-side apply (default: true)
42
    enableConfigMapMutable?: pulumi.Input<boolean>;  // Allow ConfigMap mutations (beta)
43
    enableSecretMutable?: pulumi.Input<boolean>;     // Allow Secret mutations (beta)
44
    
45
    // Error Handling
46
    deleteUnreachable?: pulumi.Input<boolean>;       // Delete unreachable cluster resources from state
47
    skipUpdateUnreachable?: pulumi.Input<boolean>;   // Skip updates to unreachable clusters
48
    
49
    // Development and Testing
50
    renderYamlToDirectory?: pulumi.Input<string>;    // Render manifests to directory instead of applying
51
    
52
    // Helm Integration
53
    helmReleaseSettings?: pulumi.Input<HelmReleaseSettings>; // Helm-specific configuration
54
    
55
    // Client Configuration
56
    kubeClientSettings?: pulumi.Input<KubeClientSettings>;  // Kubernetes client tuning
57
    
58
    // Logging and Warnings
59
    suppressDeprecationWarnings?: pulumi.Input<boolean>;     // Suppress API deprecation warnings
60
    suppressHelmHookWarnings?: pulumi.Input<boolean>;        // Suppress Helm hook warnings
61
}
62
```
63

64
## HelmReleaseSettings
65

66
Configuration options for Helm integration when using the provider.
67

68
```typescript { .api }
69
interface HelmReleaseSettings {
70
    driver?: pulumi.Input<"secret" | "configmap" | "memory">; // Helm storage driver
71
    pluginsPath?: pulumi.Input<string>;                       // Path to Helm plugins directory
72
    registryConfigPath?: pulumi.Input<string>;                // Path to registry config file
73
    repositoryConfigPath?: pulumi.Input<string>;              // Path to repository config file
74
    repositoryCache?: pulumi.Input<string>;                   // Path to repository cache directory
75
    
76
    // Helm client configuration
77
    maxHistory?: pulumi.Input<number>;                        // Maximum number of release revisions
78
    debug?: pulumi.Input<boolean>;                            // Enable debug logging
79
}
80
```
81

82
## KubeClientSettings
83

84
Configuration options for tuning the Kubernetes client behavior.
85

86
```typescript { .api }
87
interface KubeClientSettings {
88
    // Performance Tuning
89
    timeout?: pulumi.Input<number>;                          // Request timeout in seconds
90
    burst?: pulumi.Input<number>;                            // Burst rate for requests
91
    qps?: pulumi.Input<number>;                              // Queries per second rate limit
92
    
93
    // Retry Configuration
94
    backoff?: pulumi.Input<{
95
        delay?: pulumi.Input<number>;                        // Initial retry delay
96
        factor?: pulumi.Input<number>;                       // Backoff factor
97
        steps?: pulumi.Input<number>;                        // Maximum retry steps
98
    }>;
99
}
100
```
101

102
## Basic Provider Configurations
103

104
### Default Provider
105

106
```typescript { .api }
107
// Use default kubeconfig and context
108
const defaultProvider = new k8s.Provider("default");
109

110
// Resources will use this provider automatically if it's the default
111
const pod = new k8s.core.v1.Pod("my-pod", {
112
    spec: {
113
        containers: [{
114
            name: "app",
115
            image: "nginx:latest",
116
        }],
117
    },
118
});
119
```
120

121
### Explicit Kubeconfig
122

123
```typescript { .api }
124
// Specify kubeconfig file path
125
const fileProvider = new k8s.Provider("file-provider", {
126
    kubeconfig: "~/.kube/config",
127
    context: "production-cluster",
128
});
129

130
// Kubeconfig content as string
131
const contentProvider = new k8s.Provider("content-provider", {
132
    kubeconfig: `
133
apiVersion: v1
134
clusters:
135
- cluster:
136
    certificate-authority-data: LS0tLS1CRUdJTi...
137
    server: https://kubernetes.example.com
138
  name: production
139
contexts:
140
- context:
141
    cluster: production
142
    user: admin
143
  name: production
144
current-context: production
145
kind: Config
146
users:
147
- name: admin
148
  user:
149
    client-certificate-data: LS0tLS1CRUdJTi...
150
    client-key-data: LS0tLS1CRUdJTi...
151
`,
152
    context: "production",
153
});
154
```
155

156
### Environment-Based Configuration
157

158
```typescript { .api }
159
// Use environment variables for configuration
160
const envProvider = new k8s.Provider("env-provider", {
161
    kubeconfig: process.env.KUBECONFIG || "~/.kube/config",
162
    context: process.env.KUBE_CONTEXT,
163
    namespace: process.env.KUBE_NAMESPACE || "default",
164
});
165

166
// Conditional provider configuration
167
const environment = pulumi.getStack();
168
const provider = new k8s.Provider("stack-provider", {
169
    kubeconfig: environment === "production" 
170
        ? "/etc/kubernetes/prod-config"
171
        : "~/.kube/config",
172
    context: `${environment}-cluster`,
173
    namespace: `app-${environment}`,
174
    enableServerSideApply: environment === "production",
175
});
176
```
177

178
## Advanced Provider Configurations
179

180
### High-Performance Configuration
181

182
```typescript { .api }
183
const performanceProvider = new k8s.Provider("performance", {
184
    kubeconfig: "~/.kube/config",
185
    enableServerSideApply: true,
186
    kubeClientSettings: {
187
        timeout: 60,      // 60 second timeout
188
        burst: 120,       // Allow burst of 120 requests
189
        qps: 50,          // 50 queries per second steady state
190
        backoff: {
191
            delay: 500,   // 500ms initial delay
192
            factor: 2,    // Double delay each retry
193
            steps: 5,     // Maximum 5 retries
194
        },
195
    },
196
});
197
```
198

199
### Development Configuration
200

201
```typescript { .api }
202
const devProvider = new k8s.Provider("development", {
203
    kubeconfig: "~/.kube/config",
204
    context: "docker-desktop",
205
    namespace: "development",
206
    
207
    // Development features
208
    enableConfigMapMutable: true,
209
    enableSecretMutable: true,
210
    suppressDeprecationWarnings: false, // Show warnings in development
211
    
212
    // Fast iteration
213
    kubeClientSettings: {
214
        timeout: 30,
215
        qps: 100, // Higher QPS for faster development
216
        burst: 200,
217
    },
218
});
219
```
220

221
### Production Configuration
222

223
```typescript { .api }
224
const prodProvider = new k8s.Provider("production", {
225
    kubeconfig: process.env.PROD_KUBECONFIG,
226
    context: "production-cluster",
227
    
228
    // Production settings
229
    enableServerSideApply: true,
230
    suppressDeprecationWarnings: true,
231
    suppressHelmHookWarnings: true,
232
    
233
    // Stability settings
234
    deleteUnreachable: false,        // Don't auto-delete unreachable resources
235
    skipUpdateUnreachable: true,     // Skip updates if cluster unreachable
236
    
237
    // Performance tuning for production
238
    kubeClientSettings: {
239
        timeout: 300,    // 5 minute timeout for large operations
240
        burst: 50,       // Conservative burst
241
        qps: 25,         // Conservative QPS
242
        backoff: {
243
            delay: 1000,  // 1 second initial delay
244
            factor: 1.5,  // Gradual backoff
245
            steps: 10,    // More retries for production
246
        },
247
    },
248
    
249
    // Cluster identity for proper lifecycle management
250
    clusterIdentifier: "prod-us-west-2-cluster-v1",
251
});
252
```
253

254
### Multi-Cluster Configuration
255

256
```typescript { .api }
257
// Primary cluster provider
258
const primaryProvider = new k8s.Provider("primary", {
259
    kubeconfig: "~/.kube/primary-config",
260
    context: "primary-cluster",
261
    clusterIdentifier: "primary-us-east-1",
262
});
263

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

271
// Disaster recovery cluster
272
const drProvider = new k8s.Provider("disaster-recovery", {
273
    kubeconfig: "~/.kube/dr-config",
274
    context: "dr-cluster",
275
    clusterIdentifier: "dr-eu-west-1",
276
    
277
    // DR-specific settings
278
    skipUpdateUnreachable: true,
279
    deleteUnreachable: false,
280
});
281

282
// Deploy to multiple clusters
283
const primaryApp = new k8s.apps.v1.Deployment("app-primary", {
284
    spec: {
285
        replicas: 3,
286
        selector: { matchLabels: { app: "myapp" }},
287
        template: {
288
            metadata: { labels: { app: "myapp" }},
289
            spec: {
290
                containers: [{
291
                    name: "app",
292
                    image: "myapp:v1.0",
293
                }],
294
            },
295
        },
296
    },
297
}, { provider: primaryProvider });
298

299
const secondaryApp = new k8s.apps.v1.Deployment("app-secondary", {
300
    spec: {
301
        replicas: 2, // Fewer replicas in secondary
302
        selector: { matchLabels: { app: "myapp" }},
303
        template: {
304
            metadata: { labels: { app: "myapp" }},
305
            spec: {
306
                containers: [{
307
                    name: "app", 
308
                    image: "myapp:v1.0",
309
                }],
310
            },
311
        },
312
    },
313
}, { provider: secondaryProvider });
314
```
315

316
### Testing and Development Features
317

318
```typescript { .api }
319
// Provider for testing - renders to files instead of applying
320
const testProvider = new k8s.Provider("test-render", {
321
    renderYamlToDirectory: "./test-output",
322
    kubeconfig: "~/.kube/config", // Still needed for API discovery
323
});
324

325
// Resources created with this provider will be rendered to files
326
const testApp = new k8s.apps.v1.Deployment("test-app", {
327
    spec: {
328
        replicas: 1,
329
        selector: { matchLabels: { app: "test" }},
330
        template: {
331
            metadata: { labels: { app: "test" }},
332
            spec: {
333
                containers: [{
334
                    name: "test",
335
                    image: "nginx:latest",
336
                }],
337
            },
338
        },
339
    },
340
}, { provider: testProvider });
341

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

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

357
### Helm Integration Configuration
358

359
```typescript { .api }
360
const helmProvider = new k8s.Provider("helm-optimized", {
361
    kubeconfig: "~/.kube/config",
362
    
363
    // Helm-specific settings
364
    helmReleaseSettings: {
365
        driver: "secret",                              // Use secrets for Helm storage
366
        pluginsPath: "/opt/helm/plugins",             // Custom plugin location
367
        registryConfigPath: "~/.config/helm/registry.json",
368
        repositoryConfigPath: "~/.config/helm/repositories.yaml",
369
        repositoryCache: "~/.cache/helm/repository",
370
        maxHistory: 10,                               // Keep 10 release revisions
371
        debug: false,                                 // Disable debug logging
372
    },
373
    
374
    suppressHelmHookWarnings: true,
375
});
376

377
// Helm charts deployed with this provider will use the optimized settings
378
const helmChart = new k8s.helm.v4.Chart("optimized-chart", {
379
    chart: "nginx",
380
    repositoryOpts: {
381
        repo: "https://charts.bitnami.com/bitnami",
382
    },
383
}, { provider: helmProvider });
384
```
385

386
## Provider Usage Patterns
387

388
### Provider Factory Function
389

390
```typescript { .api }
391
interface ClusterConfig {
392
    name: string;
393
    kubeconfig: string;
394
    context: string;
395
    namespace?: string;
396
    environment: "dev" | "staging" | "prod";
397
}
398

399
function createProvider(config: ClusterConfig): k8s.Provider {
400
    const baseSettings = {
401
        kubeconfig: config.kubeconfig,
402
        context: config.context,
403
        namespace: config.namespace || "default",
404
        clusterIdentifier: `${config.name}-${config.environment}`,
405
    };
406
    
407
    switch (config.environment) {
408
        case "dev":
409
            return new k8s.Provider(`${config.name}-dev`, {
410
                ...baseSettings,
411
                enableConfigMapMutable: true,
412
                enableSecretMutable: true,
413
                suppressDeprecationWarnings: false,
414
                kubeClientSettings: {
415
                    timeout: 30,
416
                    qps: 100,
417
                    burst: 200,
418
                },
419
            });
420
            
421
        case "staging":
422
            return new k8s.Provider(`${config.name}-staging`, {
423
                ...baseSettings,
424
                enableServerSideApply: true,
425
                suppressDeprecationWarnings: true,
426
                kubeClientSettings: {
427
                    timeout: 60,
428
                    qps: 50,
429
                    burst: 100,
430
                },
431
            });
432
            
433
        case "prod":
434
            return new k8s.Provider(`${config.name}-prod`, {
435
                ...baseSettings,
436
                enableServerSideApply: true,
437
                suppressDeprecationWarnings: true,
438
                suppressHelmHookWarnings: true,
439
                deleteUnreachable: false,
440
                skipUpdateUnreachable: true,
441
                kubeClientSettings: {
442
                    timeout: 300,
443
                    qps: 25,
444
                    burst: 50,
445
                    backoff: {
446
                        delay: 1000,
447
                        factor: 1.5,
448
                        steps: 10,
449
                    },
450
                },
451
            });
452
            
453
        default:
454
            throw new Error(`Unknown environment: ${config.environment}`);
455
    }
456
}
457

458
// Use the factory
459
const clusters = [
460
    {
461
        name: "us-east-1", 
462
        kubeconfig: process.env.US_EAST_1_KUBECONFIG!,
463
        context: "us-east-1-prod",
464
        environment: "prod" as const,
465
    },
466
    {
467
        name: "us-west-2",
468
        kubeconfig: process.env.US_WEST_2_KUBECONFIG!,
469
        context: "us-west-2-prod", 
470
        environment: "prod" as const,
471
    },
472
];
473

474
const providers = clusters.map(createProvider);
475
```
476

477
### Resource Deployment with Providers
478

479
```typescript { .api }
480
// Deploy the same application to multiple providers
481
function deployApp(name: string, provider: k8s.Provider) {
482
    const deployment = new k8s.apps.v1.Deployment(`${name}-deployment`, {
483
        spec: {
484
            replicas: 3,
485
            selector: {
486
                matchLabels: { app: name },
487
            },
488
            template: {
489
                metadata: {
490
                    labels: { app: name },
491
                },
492
                spec: {
493
                    containers: [{
494
                        name: "app",
495
                        image: `${name}:v1.0`,
496
                        ports: [{ containerPort: 8080 }],
497
                    }],
498
                },
499
            },
500
        },
501
    }, { provider });
502
    
503
    const service = new k8s.core.v1.Service(`${name}-service`, {
504
        spec: {
505
            selector: { app: name },
506
            ports: [{ port: 80, targetPort: 8080 }],
507
            type: "LoadBalancer",
508
        },
509
    }, { provider });
510
    
511
    return { deployment, service };
512
}
513

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

520
## Best Practices
521

522
### Provider Configuration Best Practices
523

524
1. **Cluster Identification**: Always set `clusterIdentifier` for production clusters to control provider replacement behavior
525
2. **Environment Separation**: Use different providers for different environments with appropriate settings
526
3. **Performance Tuning**: Adjust client settings based on cluster size and network conditions
527
4. **Security**: Never hardcode credentials; use environment variables or secure credential providers
528
5. **Error Handling**: Configure appropriate error handling for unreachable clusters
529

530
### Resource Management Best Practices
531

532
1. **Provider Scoping**: Use explicit providers for multi-cluster deployments
533
2. **Feature Flags**: Enable beta features only when needed and in appropriate environments
534
3. **Monitoring**: Monitor provider performance and adjust settings as needed
535
4. **Documentation**: Document provider configurations and their purposes
536
5. **Testing**: Test provider configurations in development before production use
537

538
### Operations Best Practices
539

540
1. **Backup Strategies**: Ensure proper backup strategies for cluster configurations
541
2. **Access Control**: Implement proper RBAC and access controls for cluster access
542
3. **Monitoring**: Monitor cluster health and provider connectivity
543
4. **Disaster Recovery**: Plan for cluster failures and provider failover scenarios
544
5. **Updates**: Keep provider configurations updated with cluster changes
545

546
The Provider configuration system provides comprehensive control over how Pulumi interacts with Kubernetes clusters, enabling flexible deployment strategies, performance optimization, and robust error handling across diverse Kubernetes environments.