CtrlK
BlogDocsLog inGet started
Tessl Logo

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

core-resources.mddocs/

Core Resources (core/v1)

The Core API group provides fundamental Kubernetes resources for workload management, configuration storage, and cluster operations. These resources form the foundation of most Kubernetes applications.

Package Import

import { core } from "@pulumi/kubernetes";
import * as k8s from "@pulumi/kubernetes";

// Direct core imports
import { Pod, Service, ConfigMap, Secret, Namespace } from "@pulumi/kubernetes/core/v1";

Pod

Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts.

class Pod extends pulumi.CustomResource {
    constructor(name: string, args?: PodArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): Pod
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"Pod">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.PodSpec>;
    public readonly status!: pulumi.Output<outputs.core.v1.PodStatus>;
}

interface PodArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"Pod">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    spec?: pulumi.Input<inputs.core.v1.PodSpec>;
}

Pod Lifecycle Management

The Pod resource waits until its status is ready before registering success for create/update:

  1. The Pod is scheduled ("PodScheduled" condition is true)
  2. The Pod is initialized ("Initialized" condition is true)
  3. The Pod is ready ("Ready" condition is true) and phase is "Running"
  4. Or (for Jobs): The Pod succeeded (phase set to "Succeeded")

Default timeout is 10 minutes, configurable via customTimeouts option.

Pod Usage Examples

// Basic pod with auto-naming
const pod = new k8s.core.v1.Pod("nginx-pod", {
    spec: {
        containers: [{
            name: "nginx",
            image: "nginx:1.21",
            ports: [{
                containerPort: 80,
            }],
        }],
    },
});

// Pod with explicit name and configuration
const configuredPod = new k8s.core.v1.Pod("web-server", {
    metadata: {
        name: "web-server",
        labels: {
            app: "web",
            tier: "frontend",
        },
    },
    spec: {
        containers: [{
            name: "nginx",
            image: "nginx:1.21",
            ports: [{
                containerPort: 80,
                protocol: "TCP",
            }],
            env: [{
                name: "ENV_VAR",
                value: "production",
            }],
            resources: {
                requests: {
                    cpu: "100m",
                    memory: "128Mi",
                },
                limits: {
                    cpu: "500m",
                    memory: "512Mi",
                },
            },
        }],
        restartPolicy: "Always",
    },
});

Service

Service is a named abstraction of software service consisting of local port that the proxy listens on, and the selector that determines which pods will answer requests sent through the proxy.

class Service extends pulumi.CustomResource {
    constructor(name: string, args?: ServiceArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): Service
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"Service">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.ServiceSpec>;
    public readonly status!: pulumi.Output<outputs.core.v1.ServiceStatus>;
}

interface ServiceArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"Service">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    spec?: pulumi.Input<inputs.core.v1.ServiceSpec>;
}

Service Types

// Service type enumeration
type ServiceType = "ClusterIP" | "NodePort" | "LoadBalancer" | "ExternalName";

// Session affinity options
type SessionAffinity = "ClientIP" | "None";

Service Usage Examples

// ClusterIP service (default)
const clusterService = new k8s.core.v1.Service("app-service", {
    spec: {
        selector: {
            app: "my-app",
        },
        ports: [{
            port: 80,
            targetPort: 8080,
            protocol: "TCP",
        }],
        type: "ClusterIP",
    },
});

// LoadBalancer service
const loadBalancerService = new k8s.core.v1.Service("lb-service", {
    spec: {
        selector: {
            app: "web-app",
        },
        ports: [{
            port: 80,
            targetPort: 80,
            protocol: "TCP",
        }, {
            port: 443,
            targetPort: 443,
            protocol: "TCP",
        }],
        type: "LoadBalancer",
    },
});

// NodePort service
const nodePortService = new k8s.core.v1.Service("nodeport-service", {
    spec: {
        selector: {
            app: "api",
        },
        ports: [{
            port: 3000,
            targetPort: 3000,
            nodePort: 30000,
            protocol: "TCP",
        }],
        type: "NodePort",
    },
});

ConfigMap

ConfigMap holds configuration data for pods to consume.

class ConfigMap extends pulumi.CustomResource {
    constructor(name: string, args?: ConfigMapArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): ConfigMap
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"ConfigMap">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly binaryData!: pulumi.Output<{[key: string]: string}>;
    public readonly data!: pulumi.Output<{[key: string]: string}>;
    public readonly immutable!: pulumi.Output<boolean>;
}

interface ConfigMapArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"ConfigMap">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    binaryData?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;
    data?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;
    immutable?: pulumi.Input<boolean>;
}

ConfigMap Usage Examples

// Basic configuration data
const appConfig = new k8s.core.v1.ConfigMap("app-config", {
    data: {
        "database.url": "postgresql://localhost:5432/mydb",
        "redis.host": "redis-service",
        "app.env": "production",
        "feature.flags": JSON.stringify({
            enableNewFeature: true,
            debugMode: false,
        }),
    },
});

// Configuration from file content
const configFile = new k8s.core.v1.ConfigMap("nginx-config", {
    data: {
        "nginx.conf": `
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    
    server {
        listen 80;
        server_name localhost;
        
        location / {
            root /usr/share/nginx/html;
            index index.html;
        }
    }
}`,
    },
});

// Immutable ConfigMap for better performance
const immutableConfig = new k8s.core.v1.ConfigMap("static-config", {
    immutable: true,
    data: {
        "version": "1.2.3",
        "build": "20231201-1500",
    },
});

Secret

Secret holds secret data of a certain type. The total bytes of the values in the Data field must be less than MaxSecretSize bytes.

class Secret extends pulumi.CustomResource {
    constructor(name: string, args?: SecretArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): Secret
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"Secret">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly data!: pulumi.Output<{[key: string]: string}>;
    public readonly immutable!: pulumi.Output<boolean>;
    public readonly stringData!: pulumi.Output<{[key: string]: string}>;
    public readonly type!: pulumi.Output<string>;
}

interface SecretArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"Secret">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    data?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;
    immutable?: pulumi.Input<boolean>;
    stringData?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;
    type?: pulumi.Input<string>;
}

Secret Types

// Common secret types
type SecretType = 
    | "Opaque"                                    // Default arbitrary user-defined data
    | "kubernetes.io/service-account-token"       // Service account token
    | "kubernetes.io/dockercfg"                   // Dockercfg file
    | "kubernetes.io/dockerconfigjson"            // Docker config.json file
    | "kubernetes.io/basic-auth"                  // Basic authentication credentials
    | "kubernetes.io/ssh-auth"                    // SSH authentication credentials
    | "kubernetes.io/tls"                         // TLS certificate and key
    | "bootstrap.kubernetes.io/token";            // Bootstrap token

Secret Usage Examples

// Basic opaque secret
const dbSecret = new k8s.core.v1.Secret("db-credentials", {
    type: "Opaque",
    stringData: {
        username: "admin",
        password: "super-secret-password",
        host: "database.example.com",
        port: "5432",
    },
});

// TLS certificate secret
const tlsSecret = new k8s.core.v1.Secret("tls-cert", {
    type: "kubernetes.io/tls",
    stringData: {
        "tls.crt": "-----BEGIN CERTIFICATE-----\n...",
        "tls.key": "-----BEGIN PRIVATE KEY-----\n...",
    },
});

// Docker registry secret
const dockerSecret = new k8s.core.v1.Secret("docker-registry", {
    type: "kubernetes.io/dockerconfigjson",
    stringData: {
        ".dockerconfigjson": JSON.stringify({
            auths: {
                "https://index.docker.io/v1/": {
                    username: "myuser",
                    password: "mypassword",
                    email: "myuser@example.com",
                    auth: Buffer.from("myuser:mypassword").toString("base64"),
                },
            },
        }),
    },
});

// SSH authentication secret
const sshSecret = new k8s.core.v1.Secret("ssh-key", {
    type: "kubernetes.io/ssh-auth",
    stringData: {
        "ssh-privatekey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
    },
});

Namespace

Namespace provides a mechanism for isolating groups of resources within a single cluster.

class Namespace extends pulumi.CustomResource {
    constructor(name: string, args?: NamespaceArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): Namespace
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"Namespace">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.NamespaceSpec>;
    public readonly status!: pulumi.Output<outputs.core.v1.NamespaceStatus>;
}

interface NamespaceArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"Namespace">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    spec?: pulumi.Input<inputs.core.v1.NamespaceSpec>;
}

Namespace Usage Examples

// Basic namespace
const appNamespace = new k8s.core.v1.Namespace("app-namespace", {
    metadata: {
        name: "my-application",
        labels: {
            environment: "production",
            team: "backend",
        },
    },
});

// Namespace with resource quotas and labels
const devNamespace = new k8s.core.v1.Namespace("development", {
    metadata: {
        name: "development",
        labels: {
            environment: "dev",
            "pod-security.kubernetes.io/enforce": "baseline",
            "pod-security.kubernetes.io/audit": "restricted",
            "pod-security.kubernetes.io/warn": "restricted",
        },
        annotations: {
            "description": "Development environment namespace",
            "contact": "dev-team@example.com",
        },
    },
});

PersistentVolume

PersistentVolume (PV) is a piece of storage in the cluster that has been provisioned by an administrator or dynamically provisioned using Storage Classes.

class PersistentVolume extends pulumi.CustomResource {
    constructor(name: string, args?: PersistentVolumeArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): PersistentVolume
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"PersistentVolume">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.PersistentVolumeSpec>;
    public readonly status!: pulumi.Output<outputs.core.v1.PersistentVolumeStatus>;
}

interface PersistentVolumeArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"PersistentVolume">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    spec?: pulumi.Input<inputs.core.v1.PersistentVolumeSpec>;
}

PersistentVolumeClaim

PersistentVolumeClaim (PVC) is a request for storage by a user.

class PersistentVolumeClaim extends pulumi.CustomResource {
    constructor(name: string, args?: PersistentVolumeClaimArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): PersistentVolumeClaim
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"PersistentVolumeClaim">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.PersistentVolumeClaimSpec>;
    public readonly status!: pulumi.Output<outputs.core.v1.PersistentVolumeClaimStatus>;
}

interface PersistentVolumeClaimArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"PersistentVolumeClaim">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    spec?: pulumi.Input<inputs.core.v1.PersistentVolumeClaimSpec>;
}

Storage Usage Examples

// PersistentVolumeClaim for database storage
const dbStorage = new k8s.core.v1.PersistentVolumeClaim("db-storage", {
    spec: {
        accessModes: ["ReadWriteOnce"],
        storageClassName: "fast-ssd",
        resources: {
            requests: {
                storage: "10Gi",
            },
        },
    },
});

// Static PersistentVolume
const staticPv = new k8s.core.v1.PersistentVolume("static-pv", {
    spec: {
        capacity: {
            storage: "5Gi",
        },
        accessModes: ["ReadWriteOnce"],
        persistentVolumeReclaimPolicy: "Retain",
        hostPath: {
            path: "/data/static",
        },
    },
});

ServiceAccount

ServiceAccount binds together a name, a principal that can be authenticated and authorized, and a set of secrets.

class ServiceAccount extends pulumi.CustomResource {
    constructor(name: string, args?: ServiceAccountArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): ServiceAccount
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"ServiceAccount">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly automountServiceAccountToken!: pulumi.Output<boolean>;
    public readonly imagePullSecrets!: pulumi.Output<outputs.core.v1.LocalObjectReference[]>;
    public readonly secrets!: pulumi.Output<outputs.core.v1.ObjectReference[]>;
}

interface ServiceAccountArgs {
    apiVersion?: pulumi.Input<"v1">;
    kind?: pulumi.Input<"ServiceAccount">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    automountServiceAccountToken?: pulumi.Input<boolean>;
    imagePullSecrets?: pulumi.Input<pulumi.Input<inputs.core.v1.LocalObjectReference>[]>;
    secrets?: pulumi.Input<pulumi.Input<inputs.core.v1.ObjectReference>[]>;
}

ServiceAccount Usage Examples

// Basic service account
const appServiceAccount = new k8s.core.v1.ServiceAccount("app-sa", {
    metadata: {
        name: "my-app-service-account",
        annotations: {
            "eks.amazonaws.com/role-arn": "arn:aws:iam::123456789012:role/MyAppRole",
        },
    },
});

// Service account with image pull secrets
const serviceAccountWithSecrets = new k8s.core.v1.ServiceAccount("sa-with-secrets", {
    imagePullSecrets: [{
        name: "docker-registry-secret",
    }],
    automountServiceAccountToken: false,
});

Additional Core Resources

Endpoints

Endpoints is a collection of endpoints that implement the actual service.

class Endpoints extends pulumi.CustomResource {
    constructor(name: string, args?: EndpointsArgs, opts?: pulumi.CustomResourceOptions)
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"Endpoints">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly subsets!: pulumi.Output<outputs.core.v1.EndpointSubset[]>;
}

Event

Event is a report of an event somewhere in the cluster.

class Event extends pulumi.CustomResource {
    constructor(name: string, args?: EventArgs, opts?: pulumi.CustomResourceOptions)
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"Event">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly action!: pulumi.Output<string>;
    public readonly count!: pulumi.Output<number>;
    public readonly eventTime!: pulumi.Output<string>;
    public readonly firstTimestamp!: pulumi.Output<string>;
    public readonly lastTimestamp!: pulumi.Output<string>;
    public readonly message!: pulumi.Output<string>;
    public readonly reason!: pulumi.Output<string>;
    public readonly type!: pulumi.Output<string>;
}

LimitRange

LimitRange sets resource usage limits for objects in a namespace.

class LimitRange extends pulumi.CustomResource {
    constructor(name: string, args?: LimitRangeArgs, opts?: pulumi.CustomResourceOptions)
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"LimitRange">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.LimitRangeSpec>;
}

ResourceQuota

ResourceQuota sets aggregate quota restrictions enforced per namespace.

class ResourceQuota extends pulumi.CustomResource {
    constructor(name: string, args?: ResourceQuotaArgs, opts?: pulumi.CustomResourceOptions)
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"v1">;
    public readonly kind!: pulumi.Output<"ResourceQuota">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly spec!: pulumi.Output<outputs.core.v1.ResourceQuotaSpec>;
    public readonly status!: pulumi.Output<outputs.core.v1.ResourceQuotaStatus>;
}

ResourceQuota and LimitRange Usage Examples

// Resource quota for namespace
const namespaceQuota = new k8s.core.v1.ResourceQuota("namespace-quota", {
    spec: {
        hard: {
            "requests.cpu": "4",
            "requests.memory": "8Gi",
            "limits.cpu": "8", 
            "limits.memory": "16Gi",
            "pods": "10",
            "persistentvolumeclaims": "4",
        },
    },
});

// Limit range for containers
const containerLimits = new k8s.core.v1.LimitRange("container-limits", {
    spec: {
        limits: [{
            type: "Container",
            default: {
                cpu: "500m",
                memory: "512Mi",
            },
            defaultRequest: {
                cpu: "100m",
                memory: "128Mi",
            },
            max: {
                cpu: "2",
                memory: "2Gi",
            },
            min: {
                cpu: "50m",
                memory: "64Mi",
            },
        }],
    },
});

Resource Variants

All core resources include the following variants:

List Resources

For batch operations and collection management:

  • PodList, ServiceList, ConfigMapList, SecretList, etc.

Patch Resources

For strategic merge patch operations:

  • PodPatch, ServicePatch, ConfigMapPatch, SecretPatch, etc.
// Example patch operation
const podPatch = new k8s.core.v1.PodPatch("pod-update", {
    metadata: {
        name: "existing-pod",
        labels: {
            "updated": "true",
        },
    },
    spec: {
        containers: [{
            name: "nginx",
            image: "nginx:1.22", // Update image version
        }],
    },
});

The Core v1 API group provides the essential building blocks for any Kubernetes application, offering type-safe resource management with comprehensive lifecycle control and configuration options.

Install with Tessl CLI

npx tessl i tessl/npm-pulumi--kubernetes

docs

core-resources.md

helm-integration.md

index.md

kustomize-integration.md

networking-resources.md

provider-configuration.md

rbac-resources.md

storage-resources.md

workload-resources.md

yaml-deployment.md

tile.json