Kubernetes is an open source platform for running containerized applications on a cluster of machines. Applications are managed through a RESTful API that exposes mechanisms to deploy, scale, and introspect on resources in the cluster.
- API-compatible with Kubernetes – users do not have to learn a new API to write Kubernetes applications with Pulumi. (See the Kubernetes and Pulumi API documentation for more details.)
- Compatible with Kubernetes YAML and Helm Charts. For example:
import * as k8s as "@pulumi/kubernetes"; new k8s.yaml.ConfigFile("app.yaml");
- Drop-in replacement for
kubectl apply. Anywhere you have a kubeconfig file, you can use Pulumi.
The remainder of this document will demonstrate how to use Pulumi for Kubernetes development, as illustrated through a series of use cases and tutorials.
Note: Pulumi supports any Kubernetes version that is currently supported by Kubernetes upstream. Typically a Kubernetes minor release is supported by upstream for a 9 month window, with all supported versions being listed in [the reference docs][reference]. If you have a more specific version requirement, please contact us.
In addition to being compatible with all existing Kubernetes workflows, Pulumi provides several
advantages over bare
kubectl. In the course of these tutorials, we will see:
- Proactive reports of errors if resource initialization fails. If Pulumi understands why a
resource failed to become healthy, it will tell you at provisioning time – no more guesswork
- Drift detection. Pulumi’s strong diffing features mean that it is easy to detect when a resource is out of sync with the spec in version control.
- Precise lifecycle tracking. Pulumi’s planning phase tells you explicitly which resources
will be deleted. No more accidentally destroying resources with
kubectl apply --prune.
- End-to-end planning. Unlike
kubectl diff, Pulumi’s planning features will show you how a change ripples through the app. For example, which
Pods will change when we update a
- Strong integration with managed Kubernetes offerings. Pulumi exposes SDKs for major cloud providers, so it is easy to provision a managed Kubernetes cluster (e.g., Elastic Kubernetes Service (EKS) on AWS), and in the same page of code, deploy Kubernetes resources to that cluster.
- Powerful integration with public cloud resources. Because Pulumi exposes an SDK for major cloud providers, we will see that it takes an order of magnitude fewer lines of code to reference a managed database (e.g., Aurora on AWS) vs. other infrastructure-as-code solutions.
- And more!
Kubernetes applications can be deployed in one of two ways. We will split tutorials along these lines:
- Using an existing cluster and kubeconfig file. Pulumi works anywhere
kubectlworks – it uses the official Kubernetes Go client under the hood.
- Using a Kubernetes cluster manged by Pulumi. Pulumi makes it easy to provision a managed Kubernetes cluster (e.g., Google Kubernetes Engine via the Pulumi Google Cloud Platform SDK), and then to provision Kubernetes resources onto that cluster, all in the same code.
- Install Node.js version 6 or later.
- Install a package manager for Node.js, such as npm or Yarn.
- Follow the directions here to install the Pulumi CLI.
Using an existing cluster
It is possible to use the Pulumi Kubernetes SDK entirely by itself, using a pre-provisioned cluster. These tutorials focus on this scenario. You will need:
- An existing Kubernetes cluster
- A kubeconfig file in an appropriate location.
Any cluster that is reachable from
kubectl should work. If you do not have both of these things,
you can obtain them by following this guide.
The tutorials are:
- [New to Pulumi] Getting started with Pulumi. This application shows the basics of managing a Kubernetes application with Pulumi. We will see how Pulumi’s diffing and planning features makes it easy to understand the blast radius of a change. We will also see how Pulumi proactively presents information about resources that fail to initialize during a rollout.
- [New to Pulumi] “Adopting” a Helm Chart. This tutorial deploys a simple Helm Chart on a Kubernetes cluster.
Using a cluster provisioned by Pulumi
It is also possible to provision a managed Kubernetes cluster (e.g., EKS on AWS), and then provision a Kubernetes application on top of the managed cluster. These examples apply to various clouds, so there is not a common “Prerequisites” section, except what you’ve already done to set up Pulumi.
- [Advanced Pulumi user] Standing up an AKS cluster, Mongo-flavored CosmosDB, and a Helm Chart that uses it for persistent data storage. This tutorial is similar in flavor to the lifecycle tutorial, except rollouts are staged, gated on Prometheus health checks. This allows us to roll out to a small canary ring, check Prometheus metrics, and then roll out to a larger prod ring only when that succeeds.
Kubernetes the Prod Way
Kubernetes the Prod Way is a tutorial aimed at users looking for guidance on how to set up a Kubernetes cluster for production workloads, including identity, managed infrastructure (e.g., databases, Kubernetes clusters).
You can find additional examples Kubernetes examples in the Pulumi examples repo.
The following packages are available in package managers:
Support will eventually expand to Go as well.
You can find a list of frequently-asked questions here.