Install & Compatibility
Where this runs
tested against v4.34.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.564s · 142.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.7s · import 0.864s · 128MB
139MB installed
● package 139MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Provider
✓ from pulumi_kubernetes import Provider
Deployment
✓ from pulumi_kubernetes.apps.v1 import Deployment
Namespace
✓ from pulumi_kubernetes.core.v1 import Namespace
Service
✓ from pulumi_kubernetes.core.v1 import Service
Chart
✓ from pulumi_kubernetes.helm.v3 import Chart
Resource
✓ from pulumi_kubernetes.yaml import ConfigFile, ConfigGroup
This quickstart demonstrates how to create a basic Kubernetes Namespace resource using the Pulumi Kubernetes provider. It sets up a new namespace and exports its name. Ensure your kubeconfig is correctly set up for Pulumi to access your Kubernetes cluster.
import pulumi
import pulumi_kubernetes as kubernetes
# Create a Kubernetes Namespace
my_namespace = kubernetes.core.v1.Namespace(
"my-namespace",
metadata={
"name": "test-ns-from-pulumi",
"labels": {"environment": "dev"}
}
)
# Export the name of the namespace
pulumi.export("namespace_name", my_namespace.metadata["name"])
# To run:
# 1. Ensure KUBECONFIG is set or your ~/.kube/config is configured.
# 2. pulumi new python --dir my-k8s-project
# 3. cd my-k8s-project
# 4. pip install pulumi-kubernetes
# 5. Replace __main__.py content with this code.
# 6. pulumi up
pulumi --version
Debug
Known issues
breakingThe `pulumi.com/waitFor` annotation's JSONPath parser was updated to an RFC9535-compliant standard in v4.24.0. Users relying on specific, non-compliant JSONPath expressions for resource waiting might experience changes in behavior or failures.fixReview existing `pulumi.com/waitFor` annotations and update JSONPath expressions to be RFC9535 compliant, especially for complex conditions.
affects: >=4.24.0
gotchaEnabling both `alwaysRender` and `renderYAMLtoDirectory` in the provider configuration (v4.26.0) can lead to every `pulumi up` showing diffs for YAML manifests, even if the underlying resources haven't logically changed. This opt-in behavior can increase noise during updates.fixBe aware of the `alwaysRender` option's implications when rendering YAML. Use it only when idempotent generation and showing diffs on every update is explicitly desired. For most cases, rely on Pulumi's default diffing.
affects: >=4.26.0
gotchaThe provider frequently updates its underlying Kubernetes schemas and client libraries (e.g., to v1.33.0 in v4.23.0). This can introduce changes in resource specifications, deprecations of older API versions, or new required fields. Ensure your resource definitions are compatible with the target Kubernetes API server version.fixRegularly check the Pulumi Kubernetes documentation for API changes and deprecations. Test upgrades in a staging environment before deploying to production. Pin provider version if strict schema stability is required.
affects: All versions, especially with major K8s schema updates
gotchaThe provider has addressed multiple race conditions related to resource awaiting and deletion (e.g., StatefulSet rollout, Deleted condition in v4.26.0, v4.22.1, v4.22.0). This indicates that resource readiness and cleanup might behave unexpectedly or be unreliable in older versions, potentially leading to 'stuck' updates or resources.fixUpgrade to the latest provider version to benefit from race condition fixes. If experiencing issues with resource readiness or deletion, verify the provider version and consult release notes for relevant fixes.
affects: <4.26.0
gotchaHelm resource fields, such as `valueYamlFiles` (fixed in v4.22.2 for panic on nil) or `plainHttp` (added in v4.24.0 to `v4.Chart`), can have specific behaviors or edge cases. Misconfiguration or reliance on older versions might lead to unexpected errors or deployment failures.fixAlways refer to the official Pulumi Kubernetes API documentation for the exact behavior and accepted values of Helm chart parameters. Ensure provider version is updated to resolve known issues.
affects: <4.24.0 for `plainHttp`, <4.22.2 for `valueYamlFiles` panic
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pulumi' (or 'pulumi_kubernetes')
The Pulumi SDK or the pulumi-kubernetes package is not installed in the Python environment where the Pulumi program is being executed, often due to virtual environment issues or incorrect installation.
fixEnsure you are in the correct Python virtual environment (if using one) and install the necessary packages: `pip install pulumi pulumi-kubernetes`.
configured Kubernetes cluster is unreachable: unable to load schema information from the API server
Pulumi cannot connect to the specified Kubernetes cluster, often due to an invalid or missing kubeconfig file, network issues, or incorrect cluster context.
fixVerify your `KUBECONFIG` environment variable points to a valid kubeconfig file, ensure the cluster is running and accessible, and check network connectivity. You can also explicitly pass the kubeconfig to the `kubernetes.Provider` constructor.
error: Preview failed: resource 'resource-name' does not exist
This error typically occurs during a `pulumi import` operation when the specified Kubernetes resource either does not exist in the cluster or the import command does not correctly specify its unique identifier (e.g., missing namespace for a namespaced resource).
fixConfirm the resource exists and is spelled correctly. For namespaced resources, ensure you include the namespace in the resource ID, e.g., `pulumi import kubernetes:core/v1:Service my-service my-namespace/my-service`.
Default provider for 'kubernetes' disabled. 'urn:...' must use an explicit provider.
This happens when you have disabled the default Kubernetes provider or are managing resources across multiple Kubernetes clusters and Pulumi cannot implicitly determine which provider to use for a given resource.
fixExplicitly pass a `kubernetes.Provider` instance to the `opts` argument of your resources or `Chart` definitions. For example: `Deployment('my-app', ..., opts=pulumi.ResourceOptions(provider=my_k8s_provider))`. global error: failed to parse kubeconfig: couldn't load kubeconfig: no configuration has been provided
Pulumi failed to find or parse the kubeconfig file. This can be due to an incorrect path in the `KUBECONFIG` environment variable, malformed YAML in the kubeconfig, or if the `kubernetes:kubeconfig` stack configuration is invalid.
fixEnsure the `KUBECONFIG` environment variable is set to a valid path, or provide the kubeconfig content directly via `pulumi config set kubernetes:kubeconfig <content>` or by passing it to the provider. Validate the kubeconfig file's YAML structure.
Upgrade
Version history
4.34.0latest on PyPI · released Aug 27, 2026
Audit
Dependencies
pulumirequiredThe core Pulumi SDK is required to define and deploy resources.