Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท Concepts and Stacks

Pulumi Providers: Packages, Versions and Explicit Providers

Learn how Pulumi providers work: native and bridged packages, plugin versions, default versus explicit providers, multiple regions or accounts, and the provider resource option.

A provider is the plugin that knows how to create, read, update and delete resources in one cloud or service. The engine itself knows nothing about S3 buckets or Kubernetes deployments; providers do. This lesson explains how providers are installed, versioned and configured, and how to use several of them side by side (two regions, two accounts).

Providers and SDK packages

Using a provider takes two pieces that you normally install in a single step:

  • a language SDK package, such as @pulumi/aws (npm), pulumi_aws (PyPI), github.com/pulumi/pulumi-aws/sdk/v6 (Go) or Pulumi.Aws (NuGet);
  • a provider plugin, a separate program (pulumi-resource-aws) that the CLI downloads automatically on first use and caches under ~/.pulumi/plugins.
Terminal
npm install @pulumi/aws          # the SDK
pulumi plugin ls                  # installed plugins
pulumi plugin install resource aws 6.50.0   # install a specific version by hand

The SDK version selects the plugin version. Upgrade by changing the package version in your lock file, not by editing plugin folders.

Kinds of providers

Kind Examples Notes
Native Azure Native, Google Cloud Native, AWS Native, Kubernetes Generated from the cloud's own API definitions, day-one coverage
Bridged AWS (classic), Azure (classic), Google Cloud (classic), Cloudflare, Datadog Built from Terraform providers; very broad coverage
Pulumi-written Command, Random, TLS, Docker Build Utility and orchestration providers
Component packages AWSx, EKS Higher-level, reusable building blocks (Components)

Resource type tokens show the package: aws:s3/bucketV2:BucketV2 is the aws package, module s3/bucketV2, type BucketV2.

The default provider

If you write new aws.s3.BucketV2("assets"), Pulumi creates a hidden default provider for the aws package, configured from your stack's aws:* config keys and the standard credential sources. Configuration for it is set like this:

Terminal
pulumi config set aws:region eu-west-1
pulumi config set aws:profile staging

Every AWS resource in the program uses that default provider unless you say otherwise.

Explicit providers

An explicit provider is a resource you create yourself, giving it its own configuration. You then hand it to resources with the provider option.

TypeScript
import * as aws from "@pulumi/aws";

const usEast = new aws.Provider("us-east", { region: "us-east-1" });

// CloudFront certificates must live in us-east-1
const cert = new aws.acm.Certificate("site-cert", {
  domainName: "example.com",
  validationMethod: "DNS",
}, { provider: usEast });

// This one uses the default provider (the stack's region)
const bucket = new aws.s3.BucketV2("site");

Another common use: an assume-role provider for a second account.

TypeScript
const prod = new aws.Provider("prod-account", {
  region: "eu-central-1",
  assumeRoles: [{ roleArn: "arn:aws:iam::111111111111:role/deploy" }],
});

A resource's children inherit its provider through parent; a component can pass providers: { aws: usEast } so that everything below uses it (Components).

Kubernetes providers

For Kubernetes the explicit provider is how you pick a cluster:

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

const k8sProvider = new k8s.Provider("cluster", { kubeconfig: kubeconfigOutput });
new k8s.apps.v1.Deployment("web", { spec: { /* ... */ } }, { provider: k8sProvider });

When the kubeconfig comes from a cluster resource created in the same program, the Output dependency ensures the cluster exists before any workload.

Provider versions and pinning

Pin the SDK version through your package manager ("@pulumi/aws": "^6.50.0" with a lock file). To pin a plugin version on a single resource, the version option exists but is rarely needed. Upgrading a provider across a major version can change resource names or defaults, so read its migration guide and run pulumi preview before up.

Stand-in: provider registry and routing

This stand-in shows the core idea: each resource is routed to a provider instance, either the package default or an explicit one, and that instance carries its own configuration.

JS Stand-in: routing resources to providers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: plugin version resolution

JS Stand-in: pick the plugin version

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging provider problems

  • pulumi preview --logtostderr -v=9 2> trace.txt writes detailed logs (these can contain sensitive data; do not share them blindly).
  • pulumi about prints versions of the CLI, plugins and language host.
  • Authentication errors come straight from the cloud SDK inside the provider, so test with the cloud's own CLI first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between an SDK package and a provider plugin?

    You import the SDK; the CLI downloads and runs the matching plugin.
  2. 2. When do you need an explicit provider?

    The default provider covers the common case; explicit providers handle variations.
  3. 3. How do you tell a resource to use a particular provider instance?

    Pass { provider: myProvider } as the resource options.
  4. 4. Where is the default provider configured?

    Keys in the provider's namespace configure the default instance.

Summary

  • Providers are plugins; you install an SDK package and the CLI fetches the matching plugin.
  • There are native, bridged and utility providers; type tokens name the package.
  • The default provider is configured from stack config; explicit providers add regions, accounts or clusters.
  • Use the provider option (or providers on components) to choose one.
  • Pin versions with lock files and preview after upgrades.

Next: Stack Outputs and Stack References