The Pulumi Kubernetes provider authenticates and connects to a Kubernetes cluster using a local kubeconfig file. This logic is implemented using the official Kubernetes Go client library, so Pulumi’s behavior is identical to
kubectl. If you have already provisioned a Kubernetes cluster and set up
kubectl to connect to it, the Pulumi CLI should “just work.”
Note: If you don’t already have a Kubernetes cluster, you can create one with Pulumi. This allows you to manage the full stack, from the Kubernetes cluster to the workloads running on it! GKE, EKS and AKS are supported.
If you’re not yet set up, you’ll need to do two things:
- Provision a Kubernetes cluster. There are several popular guides for each of the major public clouds:
kubectl, the Kubernetes CLI. There is an extensive tutorial available in the Kubernetes docs. If you’re using Homebrew on macOS, you can install the community-managed
brew install kubectl.
kubectl and Pulumi will both look for a kubeconfig file in:
$KUBECONFIG, the environment variable
~/.kube/config, in the current user’s home directory
If the kubeconfig file is not in either of these locations, Pulumi will not find it, and it will fail to authenticate against the cluster.
Pulumi never sends your Kubernetes authentication secrets or credentials to the Pulumi service. Because the Pulumi client uses the Kubernetes Go client to connect to the cluster and execute operations on your behalf, your credentials are only ever stored where you left them (typically in the local kubeconfig file,
~/.ssh, and so on).
The kubeconfig file defines some number of contexts. Each context is a name that is associated with a cluster, namespace, and a “user” (a local-only name that’s associated with a credential that allows access to the cluster).
To create a context, for example, you can run the
kubectl set-context command as follows:
$ kubectl config \ set-context my-context \ --cluster=my-cluster \ --user=my-user
If you have done this and are using the default context file, you will be able to set the
kubernetes:context to the given context name:
$ pulumi stack init new-kube-stack $ pulumi config set kubernetes:context my-context
If you don’t want to need to select a context everywhere, you can always make it the default:
$ kubectl config \ use-context my-context
Note: Depending on a default context is a bad idea if you’re going to share your stack with others; it makes your stack dependent on ambient information not known to Pulumi, an anti-pattern that leads to unrepeatable deployments.
Additionally, the Kubernetes provider accepts the following configuration settings. These can be
provided to the default Kubernetes provider via
pulumi config set kubernetes:<option>, or passed
to the constructor of
new kubernetes.Provider to construct a specific instance of the Kubernetes provider.
kubeconfig: (Optional) The kubeconfig file to use for all resource operations.
context: (Optional) Override the context to use. This works with both kubeconfig files that are taken from the system, and those that are supplied with the
cluster: (Optional) Override the cluster to use. This works with both kubeconfig files that are taken from the system, and those that are supplied with the
namespace: (Optional) Override the namespace to use. This works with both kubeconfig files that are taken from the system, and those that are supplied with the
Pulumi Service Dashboard Links
Each Kubernetes resource managed by Pulumi will have a link on the corresponding Pulumi Service webpage to view the Kubernetes Dashboard page for that resource. These links are only valid after the following prerequisite steps are taken: