0
# @pulumi/kubernetes
1

2
The Pulumi Kubernetes provider enables declarative management of Kubernetes resources using familiar programming languages. This provider offers comprehensive coverage of the Kubernetes API with type-safe resource management, advanced deployment abstractions, and seamless integration with the Pulumi ecosystem.
3

4
## Package Information
5

6
- **Package Name**: `@pulumi/kubernetes`
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Version**: 4.23.0
10
- **License**: Apache-2.0
11
- **Installation**: `npm install @pulumi/kubernetes`
12
- **Repository**: [pulumi/pulumi-kubernetes](https://github.com/pulumi/pulumi-kubernetes)
13

14
## Core Imports
15

16
### Basic Provider Import
17

18
```typescript { .api }
19
import * as kubernetes from "@pulumi/kubernetes";
20
import * as k8s from "@pulumi/kubernetes"; // Common alias
21
```
22

23
### API Group Imports
24

25
```typescript { .api }
26
// Core resources (Pod, Service, ConfigMap, etc.)
27
import { core } from "@pulumi/kubernetes";
28

29
// Workload resources (Deployment, StatefulSet, etc.)
30
import { apps } from "@pulumi/kubernetes";
31

32
// Networking resources (Ingress, NetworkPolicy, etc.)
33
import { networking } from "@pulumi/kubernetes";
34

35
// RBAC resources (Role, ClusterRole, etc.)
36
import { rbac } from "@pulumi/kubernetes";
37

38
// Storage resources (StorageClass, PersistentVolume, etc.)
39
import { storage } from "@pulumi/kubernetes";
40

41
// Special capabilities
42
import { helm, yaml, kustomize } from "@pulumi/kubernetes";
43
```
44

45
### Provider Class Import
46

47
```typescript { .api }
48
import { Provider, ProviderArgs } from "@pulumi/kubernetes";
49
```
50

51
## Basic Usage
52

53
### Quick Start Example
54

55
```typescript
56
import * as k8s from "@pulumi/kubernetes";
57

58
// Create a deployment
59
const deployment = new k8s.apps.v1.Deployment("nginx", {
60
    spec: {
61
        replicas: 3,
62
        selector: {
63
            matchLabels: { app: "nginx" },
64
        },
65
        template: {
66
            metadata: {
67
                labels: { app: "nginx" },
68
            },
69
            spec: {
70
                containers: [{
71
                    name: "nginx",
72
                    image: "nginx:1.21",
73
                    ports: [{ containerPort: 80 }],
74
                }],
75
            },
76
        },
77
    },
78
});
79

80
// Create a service to expose the deployment
81
const service = new k8s.core.v1.Service("nginx-service", {
82
    spec: {
83
        selector: { app: "nginx" },
84
        ports: [{ port: 80, targetPort: 80 }],
85
        type: "LoadBalancer",
86
    },
87
});
88
```
89

90
### Using YAML Manifests
91

92
```typescript
93
import * as k8s from "@pulumi/kubernetes";
94

95
// Deploy from YAML files
96
const app = new k8s.yaml.v2.ConfigFile("app", {
97
    files: ["./k8s-manifests.yaml"],
98
});
99
```
100

101
### Using Helm Charts
102

103
```typescript
104
import * as k8s from "@pulumi/kubernetes";
105

106
// Deploy a Helm chart
107
const chart = new k8s.helm.v4.Chart("nginx", {
108
    chart: "nginx",
109
    repositoryOpts: {
110
        repo: "https://charts.bitnami.com/bitnami",
111
    },
112
    values: {
113
        replicaCount: 3,
114
        service: { type: "LoadBalancer" },
115
    },
116
});
117
```
118

119
## Architecture
120

121
The @pulumi/kubernetes package provides comprehensive access to the Kubernetes API through several key components:
122

123
### Resource Coverage
124
- **166+ Kubernetes resource types** across 24 API groups
125
- **Complete type system** with strongly-typed input/output interfaces
126
- **Resource variants** including standard, List, and Patch operations
127
- **Multiple API versions** with automatic deprecation handling
128

129
### Provider System
130
- **Flexible authentication** supporting kubeconfig, service accounts, and cloud providers
131
- **Advanced features** like server-side apply, resource transformations, and custom timeouts
132
- **Multi-cluster support** with provider instances and configuration inheritance
133

134
### Deployment Abstractions
135
- **Native Resources**: Direct Kubernetes API resource management
136
- **YAML Integration**: Deploy existing manifests with Pulumi orchestration
137
- **Helm Charts**: Full Helm ecosystem integration without Tiller
138
- **Kustomize**: Native Kustomize directory processing
139

140
## Capabilities
141

142
### Core Kubernetes Resources
143

144
Fundamental Kubernetes resources for basic cluster operations including workload management, configuration, storage, and networking.
145

146
```typescript { .api }
147
// Essential resource constructors
148
class Pod extends pulumi.CustomResource {
149
    constructor(name: string, args: PodArgs, opts?: pulumi.ResourceOptions);
150
}
151

152
class Service extends pulumi.CustomResource {
153
    constructor(name: string, args: ServiceArgs, opts?: pulumi.ResourceOptions);
154
}
155

156
class ConfigMap extends pulumi.CustomResource {
157
    constructor(name: string, args: ConfigMapArgs, opts?: pulumi.ResourceOptions);
158
}
159

160
class Secret extends pulumi.CustomResource {
161
    constructor(name: string, args: SecretArgs, opts?: pulumi.ResourceOptions);
162
}
163
```
164

165
**Key Resources**: Pod, Service, ConfigMap, Secret, Namespace, PersistentVolume, PersistentVolumeClaim, ServiceAccount, Endpoints, Event, LimitRange, Node, PodTemplate, ReplicationController, ResourceQuota
166

167
[Core Resources Documentation](./core-resources.md)
168

169
### Application Workload Resources
170

171
High-level controllers for managing scalable applications, batch processing, and daemon processes across the cluster.
172

173
```typescript { .api }
174
// Workload management resources
175
class Deployment extends pulumi.CustomResource {
176
    constructor(name: string, args: DeploymentArgs, opts?: pulumi.ResourceOptions);
177
}
178

179
class StatefulSet extends pulumi.CustomResource {
180
    constructor(name: string, args: StatefulSetArgs, opts?: pulumi.ResourceOptions);
181
}
182

183
class Job extends pulumi.CustomResource {
184
    constructor(name: string, args: JobArgs, opts?: pulumi.ResourceOptions);
185
}
186

187
class CronJob extends pulumi.CustomResource {
188
    constructor(name: string, args: CronJobArgs, opts?: pulumi.ResourceOptions);
189
}
190
```
191

192
**Key Resources**: Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, CronJob, ControllerRevision
193

194
[Workload Resources Documentation](./workload-resources.md)
195

196
### Networking Resources
197

198
Network traffic management, ingress routing, and connectivity policies for secure and scalable cluster networking.
199

200
```typescript { .api }
201
// Network management resources
202
class Ingress extends pulumi.CustomResource {
203
    constructor(name: string, args: IngressArgs, opts?: pulumi.ResourceOptions);
204
}
205

206
class NetworkPolicy extends pulumi.CustomResource {
207
    constructor(name: string, args: NetworkPolicyArgs, opts?: pulumi.ResourceOptions);
208
}
209

210
class IngressClass extends pulumi.CustomResource {
211
    constructor(name: string, args: IngressClassArgs, opts?: pulumi.ResourceOptions);
212
}
213
```
214

215
**Key Resources**: Ingress, NetworkPolicy, IngressClass, IPAddress, ServiceCIDR, ClusterCIDR
216

217
[Networking Resources Documentation](./networking-resources.md)
218

219
### Storage Resources
220

221
Dynamic volume provisioning, storage class management, and Container Storage Interface (CSI) driver integration.
222

223
```typescript { .api }
224
// Storage management resources
225
class StorageClass extends pulumi.CustomResource {
226
    constructor(name: string, args: StorageClassArgs, opts?: pulumi.ResourceOptions);
227
}
228

229
class VolumeAttachment extends pulumi.CustomResource {
230
    constructor(name: string, args: VolumeAttachmentArgs, opts?: pulumi.ResourceOptions);
231
}
232

233
class CSIDriver extends pulumi.CustomResource {
234
    constructor(name: string, args: CSIDriverArgs, opts?: pulumi.ResourceOptions);
235
}
236
```
237

238
**Key Resources**: StorageClass, VolumeAttachment, CSIDriver, CSINode, CSIStorageCapacity, VolumeAttributesClass
239

240
[Storage Resources Documentation](./storage-resources.md)
241

242
### RBAC Security Resources
243

244
Role-based access control for cluster security, authentication, and authorization management.
245

246
```typescript { .api }
247
// Security and access control resources
248
class Role extends pulumi.CustomResource {
249
    constructor(name: string, args: RoleArgs, opts?: pulumi.ResourceOptions);
250
}
251

252
class RoleBinding extends pulumi.CustomResource {
253
    constructor(name: string, args: RoleBindingArgs, opts?: pulumi.ResourceOptions);
254
}
255

256
class ClusterRole extends pulumi.CustomResource {
257
    constructor(name: string, args: ClusterRoleArgs, opts?: pulumi.ResourceOptions);
258
}
259

260
class ClusterRoleBinding extends pulumi.CustomResource {
261
    constructor(name: string, args: ClusterRoleBindingArgs, opts?: pulumi.ResourceOptions);
262
}
263
```
264

265
**Key Resources**: Role, RoleBinding, ClusterRole, ClusterRoleBinding
266

267
[RBAC Resources Documentation](./rbac-resources.md)
268

269
### Helm Chart Integration
270

271
Deploy and manage Helm charts as Pulumi resources with full lifecycle management and value customization.
272

273
```typescript { .api }
274
// Helm Chart v4 (recommended)
275
class Chart extends pulumi.ComponentResource {
276
    constructor(name: string, args: ChartArgs, opts?: pulumi.ComponentResourceOptions);
277
}
278

279
// Helm Release v3 (legacy)
280
class Release extends pulumi.CustomResource {
281
    constructor(name: string, args: ReleaseArgs, opts?: pulumi.ResourceOptions);
282
}
283

284
interface ChartArgs {
285
    chart: pulumi.Input<string>;
286
    version?: pulumi.Input<string>;
287
    values?: pulumi.Input<any>;
288
    repositoryOpts?: pulumi.Input<RepositoryOptsArgs>;
289
    fetchOpts?: pulumi.Input<FetchOptsArgs>;
290
}
291
```
292

293
[Helm Integration Documentation](./helm-integration.md)
294

295
### YAML Manifest Deployment
296

297
Deploy Kubernetes resources from existing YAML files and directories with full Pulumi integration and transformation support.
298

299
```typescript { .api }
300
// YAML ConfigFile for single files
301
class ConfigFile extends pulumi.ComponentResource {
302
    constructor(name: string, args: ConfigFileArgs, opts?: pulumi.ComponentResourceOptions);
303
}
304

305
// YAML ConfigGroup for multiple files
306
class ConfigGroup extends pulumi.ComponentResource {
307
    constructor(name: string, args: ConfigGroupArgs, opts?: pulumi.ComponentResourceOptions);
308
}
309

310
interface ConfigFileArgs {
311
    files: pulumi.Input<string[]>;
312
    transformations?: ((o: any, opts: pulumi.CustomResourceOptions) => void)[];
313
    resourcePrefix?: pulumi.Input<string>;
314
}
315
```
316

317
[YAML Deployment Documentation](./yaml-deployment.md)
318

319
### Kustomize Integration
320

321
Deploy applications using Kustomize directory configurations with full customization and multi-environment support.
322

323
```typescript { .api }
324
// Kustomize Directory processing
325
class Directory extends pulumi.ComponentResource {
326
    constructor(name: string, args: DirectoryArgs, opts?: pulumi.ComponentResourceOptions);
327
}
328

329
interface DirectoryArgs {
330
    directory: pulumi.Input<string>;
331
    transformations?: ((o: any, opts: pulumi.CustomResourceOptions) => void)[];
332
    resourcePrefix?: pulumi.Input<string>;
333
}
334
```
335

336
[Kustomize Integration Documentation](./kustomize-integration.md)
337

338
### Provider Configuration
339

340
Configure Kubernetes cluster connections, authentication, and advanced provider features for production deployments.
341

342
```typescript { .api }
343
class Provider extends pulumi.ProviderResource {
344
    constructor(name: string, args?: ProviderArgs, opts?: pulumi.ResourceOptions);
345
}
346

347
interface ProviderArgs {
348
    kubeconfig?: pulumi.Input<string>;
349
    context?: pulumi.Input<string>;
350
    cluster?: pulumi.Input<string>;
351
    namespace?: pulumi.Input<string>;
352
    enableServerSideApply?: pulumi.Input<boolean>;
353
    enableConfigMapMutable?: pulumi.Input<boolean>;
354
    deleteUnreachable?: pulumi.Input<boolean>;
355
    helmReleaseSettings?: pulumi.Input<HelmReleaseSettings>;
356
    kubeClientSettings?: pulumi.Input<KubeClientSettings>;
357
}
358
```
359

360
[Provider Configuration Documentation](./provider-configuration.md)
361

362
## Type System
363

364
The package provides comprehensive TypeScript definitions with:
365

366
- **Input Types**: Strongly-typed resource arguments with Pulumi Input wrappers
367
- **Output Types**: Resource state and status information
368
- **Enumerations**: Kubernetes API enums for consistent value usage
369
- **Patch Types**: Strategic merge patch support for resource updates
370

371
```typescript { .api }
372
// Type system imports
373
import * as inputs from "@pulumi/kubernetes/types/input";
374
import * as outputs from "@pulumi/kubernetes/types/output";
375
import * as enums from "@pulumi/kubernetes/types/enums";
376

377
// Example usage
378
const deployment: k8s.apps.v1.Deployment = new k8s.apps.v1.Deployment("app", {
379
    spec: {
380
        replicas: 3,
381
        selector: { matchLabels: { app: "nginx" } },
382
        template: {
383
            metadata: { labels: { app: "nginx" } },
384
            spec: {
385
                containers: [{
386
                    name: "nginx",
387
                    image: "nginx:1.21",
388
                    ports: [{ containerPort: 80 }],
389
                }],
390
                restartPolicy: enums.core.v1.RestartPolicy.Always,
391
            },
392
        },
393
    },
394
});
395
```
396

397
## Getting Started
398

399
1. **Install the package**:
400
   ```bash
401
   npm install @pulumi/kubernetes
402
   ```
403

404
2. **Configure cluster access**:
405
   ```typescript
406
   import * as k8s from "@pulumi/kubernetes";
407
   
408
   const provider = new k8s.Provider("k8s", {
409
       kubeconfig: "~/.kube/config",
410
   });
411
   ```
412

413
3. **Deploy your first resource**:
414
   ```typescript
415
   const namespace = new k8s.core.v1.Namespace("my-app", {
416
       metadata: { name: "my-application" },
417
   });
418
   ```
419

420
4. **Use deployment abstractions**:
421
   ```typescript
422
   // YAML deployment
423
   const app = new k8s.yaml.v2.ConfigFile("app", {
424
       files: ["./manifests/*.yaml"],
425
   });
426
   
427
   // Helm chart deployment
428
   const chart = new k8s.helm.v4.Chart("nginx", {
429
       chart: "nginx",
430
       repositoryOpts: { repo: "https://charts.bitnami.com/bitnami" },
431
   });
432
   ```
433

434
This comprehensive Kubernetes provider enables you to manage any Kubernetes resource with the full power of Pulumi's programming model, type safety, and infrastructure-as-code capabilities.