Pulumi for Dart #

pulumi is the core SDK for defining and managing infrastructure in Dart. It provides the runtime primitives used by Pulumi programs, generated provider SDKs, Automation API clients, dynamic resources, and Dart-authored providers.

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

Verify all three parts of the toolchain before creating a stack:

dart --version
pulumi version
pulumi-language-dart -help

Install the Dart language host #

Install the latest language-host release for your operating system and architecture:

curl -fsSL https://rawgit.flutter-io.cn/kingwill101/pulumi-dart/pulumi-v3.1.0/scripts/install-pulumi-language-dart.sh | bash

The script downloads the host built by the repository's release workflow and installs it to $HOME/.local/bin. Add that directory to PATH if needed:

export PATH="$HOME/.local/bin:$PATH"
pulumi-language-dart -help

This package also ships a helper CLI that runs the same installer:

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
pulumi-dart install-language-host --ref pulumi-v3.1.1

By default, the CLI downloads the installer from its own immutable package release tag. Set PULUMI_DART_INSTALLER_REF or pass --ref to test another tag or branch; --ref takes precedence.

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

If Pulumi reports that it cannot find the Dart language plugin, confirm that pulumi-language-dart is executable and visible in the same process PATH as the pulumi command:

command -v pulumi-language-dart
pulumi-language-dart -help

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:
  • https://github.com/kingwill101/pulumi-dart
• issue tracker:
  • https://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