Kubernetes: Installation & Configuration
Your Pulumi program is required to import the pulumi/kubernetes provider package to allow the Pulumi CLI to authenticate and interact with a running Kubernetes cluster.
kubeconfig available, Pulumi communicates with the API Server using the official Kubernetes client-go library, just like
The Kubernetes provider is available as a package in all Pulumi languages:
If you do not have a cluster set up and running yet, you’ll need to do the following steps.
- Install the Pulumi CLI.
- Install a package manager for your Pulumi program language runtime, such as npm or Yarn for Node.js, or PyPI for Python.
- Provision a Kubernetes cluster. For a new managed Kubernetes cluster, check out the guides.
By default, Pulumi will look for a kubeconfig file in the following locations,
- The environment variable:
- Or in current user’s default kubeconfig 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. Set one of these locations to a valid kubeconfig file, if you have not done so already.
Verify the cluster is configured and up by running
kubectl get pods.
Note: Pulumi never sends any authentication secrets or credentials to the Pulumi service. See the FAQ for more detail.
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).
Your Kubernetes implementation may have already written out an appropriate kubeconfig.
minikube start does this, unless you specified
Moreover, multiple sources of kubeconfig are merged and the result may surprise you.
Therefore, check your current kubeconfig using:
$ kubectl \ config \ view
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
Mind that e.g.,
minikube uses the same name for the context and the cluster in it.
If you have completed your kubeconfig configuration, and are using the default kubeconfig file, you will be able to set the
kubernetes:context in the Kubernetes provider to the given context name:
$ pulumi stack init new-kube-stack $ pulumi config set kubernetes:context my-context
If you don’t want to select a context, you can always make it the operating system user-wide 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 many configuration settings.
These can be provided to the default Kubernetes provider via
pulumi config set kubernetes:<option>, or passed
to the constructor of a
new kubernetes.Provider to construct a specific instance of the Kubernetes provider for your requests.
Each Kubernetes resource managed by Pulumi will have a link in the Pulumi Service
to view the resource in the cluster. These links are local, and require the client run
kubectl proxy beforehand to access the resource.
To learn more about
kubectl proxy check out the reference docs.
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.
See the Provider configuration docs for a complete list of options.
Server-Side Apply (SSA) is a resource management strategy that was introduced in Kubernetes
v1.18. Clients using SSA can safely share the management of Kubernetes resources by making the API Server responsible for computing diffs and resolving conflicts.
The v3.20.0 release of the Pulumi Kubernetes provider added support for managing resources using SSA. This feature is currently opt-in using the
enableServerSideApply Provider option, but will become the default in the next major release. Using SSA provides the following benefits:
- Kubernetes resources may be safely managed by more than one controller.
- It is now possible to “Upsert” resources; create the resource if it does not exist, or apply the configuration to an existing resource.
- It is now possible to patch resources with the Patch resource types in the SDK. Each resource type in the SDK has a corresponding Patch resource.
last-applied-configurationannotation is no longer used.
A few Pulumi-specific annotations can be applied to Kubernetes resources managed by Pulumi to control aspects of how Pulumi deploys and manages the Kubernetes resource:
pulumi.com/patchFieldManager: Server-Side Apply option: Specify the
FieldManagername to use for the Server-Side Apply operation.
pulumi.com/patchForce: Server-Side Apply option: Force override any conflicts for the specified resource.
pulumi.com/replaceUnready: If the resource failed to become ready in the previous Pulumi update, replace the resource rather than continuing to wait for it to become ready. Only
batch/v1/Jobcurrently supports this annotation.
pulumi.com/skipAwait: Disables Pulumi’s default await logic that waits for a Kubernetes resource to become “ready” before marking the resource as having created or updated succesfully.
pulumi.com/timeoutSeconds: Specifies the number of seconds that the Pulumi Kubernetes provider will wait for the resource to become “ready”.
In addition, the Pulumi provider may write the following annotations onto resources it manages:
app.kubernetes.io/managed-by: Indicates the controller managing a Kubernetes resource. This annotation is not set when using the Server-Side Apply mode.
pulumi.com/autonamed: Indicates that the Pulumi Kubernetes provider decided to autoname the resource (instead of using an explicitly provided