Pulumi for Dart

pulumi is the core SDK for building infrastructure with Pulumi and Dart.

This package provides the runtime primitives used by Pulumi programs and by generated provider SDKs.

Requirements

• Dart SDK >=3.11.0 <4.0.0
• Pulumi CLI
• pulumi-language-dart available on your PATH

Install

Add the runtime package:

dart pub add pulumi

Add a provider SDK as needed:

dart pub add pulumi_random

Install the Dart language host

This package ships a small helper CLI for installing pulumi-language-dart:

dart pub global activate pulumi
pulumi-dart install-language-host

Pub-generated executable launchers require dart to be available on PATH. A shell alias such as alias dart="fvm dart" is not inherited by the launcher. When using FVM, run the installed command in FVM's SDK environment instead:

fvm exec pulumi-dart install-language-host

Alternatively, invoke the package executable directly through FVM:

fvm dart pub global run pulumi:pulumi_dart install-language-host

Useful options:

pulumi-dart install-language-host --version v3.0.0
pulumi-dart install-language-host --install-dir "$HOME/bin"
pulumi-dart install-language-host --repo kingwill101/pulumi-dart

Minimal Pulumi program

import 'package:pulumi/pulumi.dart';

class MyStack extends Stack {
  late final Output<Object?> message;

  MyStack() {
    final config = Config();
    final name = config.get('name') ?? 'world';
    message = Output.create<Object?>('hello-$name');
  }

  @override
  List<OutputProperty> getOutputProperties() {
    return [OutputProperty('message', message)];
  }
}

Future<void> main() async {
  await Deployment.runOrThrow(() => MyStack());
}

Example with a provider SDK

import 'package:pulumi/pulumi.dart' as pulumi;
import 'package:pulumi_random/index.dart' as random;

class AppStack extends pulumi.Stack {
  late final pulumi.Output<Object?> petName;

  AppStack() {
    final pet = random.RandomPet(
      'pet',
      args: random.RandomPetArgs(prefix: 'dart'),
    );
    petName = pet.id;
  }

  @override
  List<pulumi.OutputProperty> getOutputProperties() {
    return [pulumi.OutputProperty('petName', petName)];
  }
}

Future<void> main() async {
  await pulumi.Deployment.runOrThrow(() => AppStack());
}

Running with Pulumi CLI

After creating a Pulumi project and adding dependencies:

pulumi stack init dev
pulumi config set name dart
pulumi preview
pulumi up

Destroy when finished:

pulumi destroy

Core concepts

Input and Output

• Use Input<T> for resource arguments that can accept either plain values or computed values from other resources.
• Use Output<T> for values produced by resources and invokes.
• Compose outputs with apply, Output.tuple, and the collection helpers instead of trying to extract values eagerly.

Stack

• A Pulumi Dart program typically defines one Stack subclass.
• Resources are created in the constructor.
• Exported stack outputs are returned from getOutputProperties().

Config

• Config() reads values from the current project namespace.
• Config('pkg') targets another namespace.
• Use require, getBoolean, getNumber, and related helpers to validate config at the edge of your program.

ResourceOptions

Use ResourceOptions to control:

• parent
• dependsOn
• provider
• protect
• ignoreChanges
• deleteBeforeReplace
• aliases, transforms, and hooks for advanced component/library code

Additional libraries in this package

Automation API

Import:

import 'package:pulumi/automation.dart' as automation;

Use it to drive Pulumi CLI workflows from Dart applications.

See example/automation_cli_example.dart.

Dynamic resource APIs

Import:

import 'package:pulumi/dynamic.dart' as dynamic;

Use this when you need provider-like behavior inside a Pulumi program without publishing a separate provider plugin.

See example/dynamic_resource_example.dart.

Provider authoring APIs

Import:

import 'package:pulumi/provider.dart';

Use this when you are implementing a Pulumi provider plugin in Dart.

See:

• example/provider_authoring_example.dart
• integration_tests/provider_authoring/dart/bin/provider_plugin.dart

More examples

• raw invoke example:
  • example/raw_invoke_example.dart
• raw provider/custom resource example:
  • example/pulumi_dart_example.dart

Repository

• source:
  • github.com/kingwill101/pulumi-dart
• issue tracker:
  • github.com/kingwill101/pulumi-dart/issues

Using generated provider SDKs directly from Git

This repository houses generated provider SDK packages under:

• packages/sdks/<provider>/

Examples:

• packages/sdks/random/
• packages/sdks/aws/
• packages/sdks/gcp/

If a provider package has not been published to pub.flutter-io.cn yet, you can depend on it directly from this repository.

Example:

dependencies:
  pulumi:
    git:
      url: https://github.com/kingwill101/pulumi-dart.git
      path: packages/pulumi-dart
  pulumi_random:
    git:
      url: https://github.com/kingwill101/pulumi-dart.git
      path: packages/sdks/random

This is the recommended approach for unreleased or not-yet-published provider SDKs while the initial pub.flutter-io.cn release set is still intentionally small.

Development

dart pub get
dart analyze
dart test