CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pulumi--aws

A Pulumi package for creating and managing Amazon Web Services (AWS) cloud resources with infrastructure-as-code.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

provider.mddocs/core/

Provider Configuration

The Provider class configures AWS authentication, regions, endpoints, and global settings for all AWS resources created with Pulumi.

Common Tasks

Quick examples for the most frequent provider configuration scenarios:

// Basic setup with region
const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
});

// Multi-account with role assumption
const prodProvider = new aws.Provider("prod", {
    region: "us-west-2",
    assumeRoles: [{
        roleArn: "arn:aws:iam::123456789012:role/ProdRole",
    }],
});

// Default tags for all resources
const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
    defaultTags: {
        tags: {
            Environment: "production",
            ManagedBy: "pulumi",
        },
    },
});

// LocalStack or testing
const localProvider = new aws.Provider("local", {
    region: "us-east-1",
    skipCredentialsValidation: true,
    endpoints: [{
        s3: "http://localhost:4566",
        dynamodb: "http://localhost:4566",
    }],
});

Capabilities

Provider Class

The main provider configuration class.

/**
 * The AWS provider configures access to Amazon Web Services.
 * It must be configured with credentials and region before resources can be created.
 */
class Provider extends pulumi.ProviderResource {
    /**
     * Create a new AWS provider
     * @param name - The name of the provider resource
     * @param args - Provider configuration arguments
     * @param opts - Resource options
     */
    constructor(name: string, args?: ProviderArgs, opts?: pulumi.ResourceOptions);
}

interface ProviderArgs {
    // Authentication
    accessKey?: pulumi.Input<string>;
    secretKey?: pulumi.Input<string>;
    token?: pulumi.Input<string>;
    profile?: pulumi.Input<string>;
    sharedCredentialsFiles?: pulumi.Input<pulumi.Input<string>[]>;
    sharedConfigFiles?: pulumi.Input<pulumi.Input<string>[]>;

    // Region and Endpoints
    region?: pulumi.Input<string>;
    endpoints?: pulumi.Input<pulumi.Input<EndpointConfig>[]>;
    useDualstackEndpoint?: pulumi.Input<boolean>;
    useFipsEndpoint?: pulumi.Input<boolean>;
    s3UsEast1RegionalEndpoint?: pulumi.Input<string>;
    s3UsePathStyle?: pulumi.Input<boolean>;
    stsRegion?: pulumi.Input<string>;

    // Role Assumption
    assumeRoles?: pulumi.Input<pulumi.Input<AssumeRole>[]>;
    assumeRoleWithWebIdentity?: pulumi.Input<AssumeRoleWithWebIdentity>;

    // Account Control
    allowedAccountIds?: pulumi.Input<pulumi.Input<string>[]>;
    forbiddenAccountIds?: pulumi.Input<pulumi.Input<string>[]>;

    // Tagging
    defaultTags?: pulumi.Input<DefaultTags>;
    ignoreTags?: pulumi.Input<IgnoreTags>;
    tagPolicyCompliance?: pulumi.Input<string>;

    // Retry and Performance
    maxRetries?: pulumi.Input<number>;
    retryMode?: pulumi.Input<string>;
    tokenBucketRateLimiterCapacity?: pulumi.Input<number>;

    // Validation
    skipCredentialsValidation?: pulumi.Input<boolean>;
    skipRegionValidation?: pulumi.Input<boolean>;
    skipMetadataApiCheck?: pulumi.Input<boolean>;
    skipRequestingAccountId?: pulumi.Input<boolean>;

    // Networking
    httpProxy?: pulumi.Input<string>;
    httpsProxy?: pulumi.Input<string>;
    noProxy?: pulumi.Input<string>;
    customCaBundle?: pulumi.Input<string>;
    insecure?: pulumi.Input<boolean>;

    // Metadata Service
    ec2MetadataServiceEndpoint?: pulumi.Input<string>;
    ec2MetadataServiceEndpointMode?: pulumi.Input<string>;
}

interface EndpointConfig {
    [serviceName: string]: pulumi.Input<string>;
}

interface AssumeRole {
    roleArn: pulumi.Input<string>;
    sessionName?: pulumi.Input<string>;
    externalId?: pulumi.Input<string>;
    policy?: pulumi.Input<string>;
    policyArns?: pulumi.Input<pulumi.Input<string>[]>;
    tags?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;
    transitiveTagKeys?: pulumi.Input<pulumi.Input<string>[]>;
    duration?: pulumi.Input<string>;
}

interface AssumeRoleWithWebIdentity {
    roleArn?: pulumi.Input<string>;
    sessionName?: pulumi.Input<string>;
    policy?: pulumi.Input<string>;
    policyArns?: pulumi.Input<pulumi.Input<string>[]>;
    duration?: pulumi.Input<string>;
    webIdentityToken?: pulumi.Input<string>;
    webIdentityTokenFile?: pulumi.Input<string>;
}

interface DefaultTags {
    tags?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;
}

interface IgnoreTags {
    keys?: pulumi.Input<pulumi.Input<string>[]>;
    keyPrefixes?: pulumi.Input<pulumi.Input<string>[]>;
}

Usage Examples

Basic Configuration

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

// Use default credentials and region from environment
const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
});

// Create resources with this provider
const bucket = new aws.s3.BucketV2("my-bucket", {}, {
    provider: provider,
});

Explicit Credentials

const provider = new aws.Provider("my-provider", {
    region: "us-east-1",
    accessKey: "AKIAIOSFODNN7EXAMPLE",
    secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
});

Profile-Based Authentication

const provider = new aws.Provider("my-provider", {
    region: "eu-west-1",
    profile: "production",
});

Assuming a Role

const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
    assumeRoles: [{
        roleArn: "arn:aws:iam::123456789012:role/MyRole",
        sessionName: "pulumi-session",
        externalId: "external-id",
    }],
});

Multi-Account Setup

// Development account provider
const devProvider = new aws.Provider("dev", {
    region: "us-west-2",
    allowedAccountIds: ["111111111111"],
});

// Production account provider
const prodProvider = new aws.Provider("prod", {
    region: "us-west-2",
    assumeRoles: [{
        roleArn: "arn:aws:iam::222222222222:role/ProdRole",
    }],
    forbiddenAccountIds: ["111111111111"], // Prevent accidental dev access
});

// Create resources in different accounts
const devBucket = new aws.s3.BucketV2("dev-bucket", {}, { provider: devProvider });
const prodBucket = new aws.s3.BucketV2("prod-bucket", {}, { provider: prodProvider });

Default Tags

const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
    defaultTags: {
        tags: {
            Environment: "production",
            ManagedBy: "pulumi",
            CostCenter: "engineering",
        },
    },
});

// All resources created with this provider will have these tags
const bucket = new aws.s3.BucketV2("my-bucket", {}, { provider: provider });

Custom Endpoints

// For LocalStack or custom AWS-compatible services
const provider = new aws.Provider("localstack", {
    region: "us-east-1",
    accessKey: "test",
    secretKey: "test",
    skipCredentialsValidation: true,
    skipMetadataApiCheck: true,
    skipRequestingAccountId: true,
    endpoints: [{
        s3: "http://localhost:4566",
        dynamodb: "http://localhost:4566",
        lambda: "http://localhost:4566",
    }],
    s3UsePathStyle: true,
});

FIPS Endpoints

const provider = new aws.Provider("fips-provider", {
    region: "us-gov-west-1",
    useFipsEndpoint: true,
});

Retry Configuration

const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
    maxRetries: 10,
    retryMode: "adaptive", // or "standard"
});

Proxy Configuration

const provider = new aws.Provider("proxy-provider", {
    region: "us-west-2",
    httpProxy: "http://proxy.example.com:8080",
    httpsProxy: "http://proxy.example.com:8443",
    noProxy: "169.254.169.254", // Exclude metadata service
});

Web Identity Token

// For EKS service accounts or OIDC providers
const provider = new aws.Provider("my-provider", {
    region: "us-west-2",
    assumeRoleWithWebIdentity: {
        roleArn: "arn:aws:iam::123456789012:role/MyRole",
        webIdentityTokenFile: "/var/run/secrets/eks.amazonaws.com/serviceaccount/token",
        sessionName: "pulumi-eks-session",
    },
});

Authentication Methods

The provider supports multiple authentication methods, checked in the following order:

  1. Explicit credentials - accessKey and secretKey in provider config
  2. Environment variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  3. Shared credentials file - ~/.aws/credentials (or custom path)
  4. Shared config file - ~/.aws/config
  5. IAM role from EC2 metadata - For EC2 instances
  6. IAM role from ECS task - For ECS tasks
  7. IAM role from EKS service account - For Kubernetes pods

Region Configuration

Region can be specified via:

  1. Provider config - region parameter
  2. Environment variable - AWS_REGION or AWS_DEFAULT_REGION
  3. Shared config file - ~/.aws/config

Tag Policy Compliance

The tagPolicyCompliance option enforces organizational tag policies:

  • "error" - Fail resource creation if tags don't comply
  • "warning" - Warn but allow creation
  • "disabled" - No tag policy enforcement (default)

Best Practices

  1. Use named profiles - Store credentials in ~/.aws/credentials and reference by profile name
  2. Use IAM roles - Prefer role assumption over long-lived credentials
  3. Enable default tags - Apply common tags to all resources automatically
  4. Set allowed account IDs - Prevent accidental resource creation in wrong accounts
  5. Use explicit providers - Create named providers for multi-account or multi-region deployments
  6. Skip validation for testing - Use skip options with LocalStack or testing environments
  7. Configure retries - Adjust retry settings based on your API usage patterns

Related Topics

  • Top-Level Utility Functions - Global AWS utility functions
  • Core Concepts - Understanding Pulumi AWS patterns
  • Multi-Account Strategies - Managing multiple AWS accounts
  • Security Best Practices - Secure provider configuration

Install with Tessl CLI

npx tessl i tessl/npm-pulumi--aws

docs

core

cloudwatch.md

concepts.md

functions.md

provider.md

sns.md

index.md

quickstart.md

README.md

tile.json