@pulumi/kubernetes

What is @pulumi/kubernetes?

@pulumi/kubernetes is an npm package that allows you to manage Kubernetes resources using Pulumi, a modern infrastructure as code platform. With this package, you can define, deploy, and manage Kubernetes applications and infrastructure using familiar programming languages like JavaScript, TypeScript, and Python.

What are @pulumi/kubernetes's main functionalities?

Creating Kubernetes Resources

This feature allows you to create Kubernetes resources such as Deployments, Services, and ConfigMaps. The code sample demonstrates how to create a simple Nginx deployment with two replicas.

const pulumi = require('@pulumi/pulumi');
const k8s = require('@pulumi/kubernetes');

const appLabels = { app: 'nginx' };
const deployment = new k8s.apps.v1.Deployment('nginx-deployment', {
  spec: {
    selector: { matchLabels: appLabels },
    replicas: 2,
    template: {
      metadata: { labels: appLabels },
      spec: { containers: [{ name: 'nginx', image: 'nginx' }] }
    }
  }
});

exports.deploymentName = deployment.metadata.name;

Managing Kubernetes Configurations

This feature allows you to manage Kubernetes configurations such as ConfigMaps and Secrets. The code sample demonstrates how to create a ConfigMap with a key-value pair.

const pulumi = require('@pulumi/pulumi');
const k8s = require('@pulumi/kubernetes');

const configMap = new k8s.core.v1.ConfigMap('my-config', {
  metadata: { name: 'my-config' },
  data: { 'key': 'value' }
});

exports.configMapName = configMap.metadata.name;

Deploying Helm Charts

This feature allows you to deploy applications using Helm charts. The code sample demonstrates how to deploy an Nginx Helm chart from the Bitnami repository.

const pulumi = require('@pulumi/pulumi');
const k8s = require('@pulumi/kubernetes');

const nginx = new k8s.helm.v3.Chart('nginx', {
  chart: 'nginx',
  version: '1.0.0',
  fetchOpts: { repo: 'https://charts.bitnami.com/bitnami' }
});

exports.nginxServiceName = nginx.getResource('v1/Service', 'nginx').metadata.name;

Other packages similar to @pulumi/kubernetes

kubernetes

The 'kubernetes' npm package is a client library for interacting with the Kubernetes API. It allows you to manage Kubernetes resources programmatically. Unlike @pulumi/kubernetes, it does not provide infrastructure as code capabilities and is more focused on direct API interactions.

kubernetes-client

The 'kubernetes-client' npm package is another client library for the Kubernetes API. It provides a higher-level abstraction compared to the 'kubernetes' package and includes features like easy resource creation and management. However, it lacks the infrastructure as code features provided by @pulumi/kubernetes.

k8s

The 'k8s' npm package is a lightweight client for the Kubernetes API. It is designed for simplicity and ease of use, making it suitable for small scripts and automation tasks. It does not offer the comprehensive infrastructure as code capabilities of @pulumi/kubernetes.

README

Pulumi Kubernetes Resource Provider

The Kubernetes resource provider for Pulumi lets you create, deploy, and manage Kubernetes API resources and workloads in a running cluster. For a streamlined Pulumi walkthrough, including language runtime installation and Kubernetes configuration, select "Get Started" below.

• Introduction
  • Kubernetes API Version Support
  • How does API support for Kubernetes work?
• References
• Prerequisites
• Installing
• Quick Examples
  • Deploying a YAML Manifest
  • Deploying a Helm Chart
  • Deploying a Workload using the Resource API
• Contributing
• Code of Conduct

Introduction

pulumi-kubernetes provides an SDK to create any of the API resources available in Kubernetes.

This includes the resources you know and love, such as:

• Deployments
• ReplicaSets
• ConfigMaps
• Secrets
• Jobs etc.

Kubernetes API Version Support

The pulumi-kubernetes SDK closely tracks the latest upstream release, and provides access to the full API surface, including deprecated endpoints. The SDK API is 100% compatible with the Kubernetes API, and is schematically identical to what Kubernetes users expect.

We support Kubernetes clusters with version >=1.9.0.

How does API support for Kubernetes work?

Pulumi’s Kubernetes SDK is manufactured by automatically wrapping our library functionality around the Kubernetes resource OpenAPI spec as soon as a new version is released! Ultimately, this means that Pulumi users do not have to learn a new Kubernetes API model, nor wait long to work with the latest available versions.

Note: Pulumi also supports alpha and beta APIs.

Visit the FAQ for more details.

References

• Reference Documentation
• API Documentation
  • Node.js API
  • Python API
• All Examples
• How-to Guides

Prerequisites

1. Install Pulumi.
2. Install a language runtime such as Node.js, Python or .NET.
3. Install a package manager
   • For Node.js, use NPM or Yarn.
   • For Python, use pip.
   • For .NET, use Nuget which is integrated with the dotnet CLI.
4. Have access to a running Kubernetes cluster
   • If kubectl already works for your running cluster, Pulumi respects and uses this configuration.
   • If you do not have a cluster already running and available, we encourage you to explore Pulumi's SDKs for AWS EKS, Azure AKS, and GCP GKE. Visit the API reference docs in the Pulumi Registry for more details.
5. Install kubectl.

Installing

This package is available in many languages in the standard packaging formats.

For Node.js use either npm or yarn:

npm:

npm install @pulumi/kubernetes

yarn:

yarn add @pulumi/kubernetes

For Python use pip:

pip install pulumi-kubernetes

For .NET, dependencies will be automatically installed as part of your Pulumi deployments using dotnet build.

To use from Go, use go install to grab the latest version of the library

$ go install github.com/pulumi/pulumi-kubernetes/sdk/v4/go/kubernetes@latest

Quick Examples

The following examples demonstrate how to work with pulumi-kubernetes in a couple of ways.

Examples may include the creation of an AWS EKS cluster, although an EKS cluster is not required to use pulumi/kubernetes. It is simply used to ensure we have access to a running Kubernetes cluster to deploy resources and workloads into.

Deploying a YAML Manifest

This example deploys resources from a YAML manifest file path, using the transient, default kubeconfig credentials on the local machine, just as kubectl does.

import * as k8s from "@pulumi/kubernetes";

const myApp = new k8s.yaml.ConfigFile("app", {
    file: "app.yaml"
});

Deploying a Helm Chart

This example creates an EKS cluster with pulumi/eks, and then deploys a Helm chart from the stable repo using the kubeconfig credentials from the cluster's Pulumi provider.

import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";

// Create an EKS cluster.
const cluster = new eks.Cluster("my-cluster");

// Deploy Wordpress into our cluster.
const wordpress = new k8s.helm.v3.Chart("wordpress", {
    repo: "stable",
    chart: "wordpress",
    values: {
        wordpressBlogName: "My Cool Kubernetes Blog!",
    },
}, { providers: { "kubernetes": cluster.provider } });

// Export the cluster's kubeconfig.
export const kubeconfig = cluster.kubeconfig;

Deploying a Workload using the Resource API

This example creates a EKS cluster with pulumi/eks, and then deploys an NGINX Deployment and Service using the SDK resource API, and the kubeconfig credentials from the cluster's Pulumi provider.

import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";

// Create an EKS cluster with the default configuration.
const cluster = new eks.Cluster("my-cluster");

// Create a NGINX Deployment and Service.
const appName = "my-app";
const appLabels = { appClass: appName };
const deployment = new k8s.apps.v1.Deployment(`${appName}-dep`, {
    metadata: { labels: appLabels },
    spec: {
        replicas: 2,
        selector: { matchLabels: appLabels },
        template: {
            metadata: { labels: appLabels },
            spec: {
                containers: [{
                    name: appName,
                    image: "nginx",
                    ports: [{ name: "http", containerPort: 80 }]
                }],
            }
        }
    },
}, { provider: cluster.provider });

const service = new k8s.core.v1.Service(`${appName}-svc`, {
    metadata: { labels: appLabels },
    spec: {
        type: "LoadBalancer",
        ports: [{ port: 80, targetPort: "http" }],
        selector: appLabels,
    },
}, { provider: cluster.provider });

// Export the URL for the load balanced service.
export const url = service.status.loadBalancer.ingress[0].hostname;

// Export the cluster's kubeconfig.
export const kubeconfig = cluster.kubeconfig;

Contributing

If you are interested in contributing, please see the contributing docs.

Code of Conduct

You can read the code of conduct here.

Changelog

4.18.0 (September 3, 2024)

Added

• The new enableSecretMutable provider configuration option treats changes to Secrets as updates instead of replacements (similar to the enableConfigMapMutable option).

  The default replacement behavior can be preserved for a particular Secret by setting its immutable field to true. (https://github.com/pulumi/pulumi-kubernetes/issues/2291)

  Note: These options (enableSecretMutable and enableConfigMapMutable) may become the default behavior in a future v5 release of the provider. Programs that depend on the replacement of Secrets and ConfigMaps (e.g. to trigger updates for downstream dependencies like Deployments) are recommended to explicitly specify immutable: true.

• A warning is now emitted if an object has finalizers which might be blocking deletion. (https://github.com/pulumi/pulumi-kubernetes/issues/1418)

• EXPERIMENTAL: Generic await logic is now available as an opt-in feature. Running a program with PULUMI_K8S_AWAIT_ALL=true will now cause Pulumi to await readiness for all resources, including custom resources.

  Generic readiness is determined according to some well-known conventions (like the "Ready" condition) as determined by cli-utils.

  Pulumi's current behavior, without this feature enabled, is to assume some resources are immediately available, which can cause downstream resources to fail.

  Existing readiness logic is unaffected by this setting. (https://github.com/pulumi/pulumi-kubernetes/issues/2996)

• EXPERIMENTAL: The pulumi.com/waitFor annotation was introduced to allow for custom readiness checks. This override Pulumi's own await logic for the resource (however the pulumi.com/skipAwait annotation still takes precedence).

  The value of this annotation can take 3 forms:

  1. A string prefixed with jsonpath= followed by a JSONPath expression and an optional value.

     The JSONPath expression accepts the same syntax as kubectl get -o jsonpath={...}.

     If a value is provided, the resource is considered ready when the JSONPath expression evaluates to the same value. For example this resource expects its "phase" field to have a value of "Running":

     `pulumi.com/waitFor: "jsonpath={.status.phase}=Running"`
     

     If a value is not provided, the resource will be considered ready when any value exists at the given path, similar to kubectl wait --for jsonpath=.... This resource will wait until it has a webhook configured with a CA bundle:

     `pulumi.com/waitFor: "jsonpath={.webhooks[*].clientConfig.caBundle}"`
     

  2. A string prefixed with condition= followed by the type of the condition and an optional status. This matches the behavior of kubectl wait --for=condition=... and will wait until the resource has a matching condition. The expected status defaults to "True" if not specified.

     `pulumi.com/waitFor: "condition=Synced"`
     
     `pulumi.com/waitFor: "condition=Reconciling=False"`
     

  3. A string containing a JSON array of multiple jsonpath= and condition= expressions.

     `pulumi.com/waitFor: '["jsonpath={.foo}", "condition=Bar"]'` 
     

• Pulumi will now emit logs for any Kubernetes "Warning" Events associated with resources being created, updated or deleted. (https://github.com/pulumi/pulumi-kubernetes/pull/3135/files)

Fixed

• The immutable field is now respected for ConfigMaps when the provider is configured with enableConfigMapMutable. (https://github.com/pulumi/pulumi-kubernetes/issues/3181)

• Fixed a panic that could occur during deletion. (https://github.com/pulumi/pulumi-kubernetes/issues/3157)