Pulumi

Use the Pulumi Infrastructure as Code framework with LocalStack

Pulumi logo

Overview

Pulumi’s infrastructure-as-code SDK helps you create, deploy, and manage AWS containers, serverless functions, and infrastructure using familiar programming languages. The endpoints configuration environment of Pulumi allows us to easily point Pulumi to LocalStack. This guide follows the instructions from Pulumi’s Get Started with Pulumi and AWS guide, with additional explanations of how to make it work with LocalStack.

Quickstart

Create a new Pulumi stack

First, run the following commands and follow the instructions in the CLI to create a new project.

  1. $ mkdir quickstart && cd quickstart
  2. $ pulumi new aws-typescript

We use the default configuration values:

  1. This command will walk you through creating a new Pulumi project.
  3. Enter a value or leave blank to accept the (default), and press <ENTER>.
  4. Press ^C at any time to quit.
  6. project name: (quickstart) 
  7. project description: (A minimal AWS TypeScript Pulumi program) 
  8. Created project 'quickstart'
  10. Please enter your desired stack name.
  11. To create a stack in an organization, use the format <org-name>/<stack-name> (e.g. `acmecorp/dev`).
  12. stack name: (dev) 
  13. Created stack 'dev'
  15. aws:region: The AWS region to deploy into: (us-east-1) 
  16. Saved config
  18. Installing dependencies...

This will create the following directory structure.

  1. $ tree -L 1
  2. .
  3. ├── index.ts
  4. ├── node_modules
  5. ├── package.json
  6. ├── package-lock.json
  7. ├── Pulumi.dev.yaml
  8. ├── Pulumi.yaml
  9. └── tsconfig.json

Now edit your stack configuration Pulumi.dev.yaml as follows:

  1. config:
  2.   aws:accessKey: test
  3.   aws:secretKey: test
  4.   aws:s3ForcePathStyle: 'true'
  5.   aws:skipCredentialsValidation: 'true'
  6.   aws:skipRequestingAccountId: 'true'
  7.   aws:endpoints:
  8.     - accessanalyzer: http://localhost:4566
  9.       account: http://localhost:4566
  10.       acm: http://localhost:4566
  11.       acmpca: http://localhost:4566
  12.       alexaforbusiness: http://localhost:4566
  13.       amp: http://localhost:4566
  14.       amplify: http://localhost:4566
  15.       amplifybackend: http://localhost:4566
  16.       apigateway: http://localhost:4566
  17.       apigatewayv2: http://localhost:4566
  18.       appautoscaling: http://localhost:4566
  19.       appconfig: http://localhost:4566
  20.       appflow: http://localhost:4566
  21.       appintegrations: http://localhost:4566
  22.       appintegrationsservice: http://localhost:4566
  23.       applicationautoscaling: http://localhost:4566
  24.       applicationcostprofiler: http://localhost:4566
  25.       applicationdiscovery: http://localhost:4566
  26.       applicationdiscoveryservice: http://localhost:4566
  27.       applicationinsights: http://localhost:4566
  28.       appmesh: http://localhost:4566
  29.       appregistry: http://localhost:4566
  30.       apprunner: http://localhost:4566
  31.       appstream: http://localhost:4566
  32.       appsync: http://localhost:4566
  33.       athena: http://localhost:4566
  34.       auditmanager: http://localhost:4566
  35.       augmentedairuntime: http://localhost:4566
  36.       autoscaling: http://localhost:4566
  37.       autoscalingplans: http://localhost:4566
  38.       backup: http://localhost:4566
  39.       batch: http://localhost:4566
  40.       braket: http://localhost:4566
  41.       budgets: http://localhost:4566
  42.       chime: http://localhost:4566
  43.       cloud9: http://localhost:4566
  44.       cloudcontrol: http://localhost:4566
  45.       cloudcontrolapi: http://localhost:4566
  46.       clouddirectory: http://localhost:4566
  47.       cloudformation: http://localhost:4566
  48.       cloudfront: http://localhost:4566
  49.       cloudhsm: http://localhost:4566
  50.       cloudhsmv2: http://localhost:4566
  51.       cloudsearch: http://localhost:4566
  52.       cloudsearchdomain: http://localhost:4566
  53.       cloudtrail: http://localhost:4566
  54.       cloudwatch: http://localhost:4566
  55.       cloudwatchevents: http://localhost:4566
  56.       cloudwatchlogs: http://localhost:4566
  57.       codeartifact: http://localhost:4566
  58.       codebuild: http://localhost:4566
  59.       codecommit: http://localhost:4566
  60.       codedeploy: http://localhost:4566
  61.       codeguruprofiler: http://localhost:4566
  62.       codegurureviewer: http://localhost:4566
  63.       codepipeline: http://localhost:4566
  64.       codestar: http://localhost:4566
  65.       codestarconnections: http://localhost:4566
  66.       codestarnotifications: http://localhost:4566
  67.       cognitoidentity: http://localhost:4566
  68.       cognitoidentityprovider: http://localhost:4566
  69.       cognitoidp: http://localhost:4566
  70.       cognitosync: http://localhost:4566
  71.       comprehend: http://localhost:4566
  72.       comprehendmedical: http://localhost:4566
  73.       config: http://localhost:4566
  74.       configservice: http://localhost:4566
  75.       connect: http://localhost:4566
  76.       connectcontactlens: http://localhost:4566
  77.       connectparticipant: http://localhost:4566
  78.       costandusagereportservice: http://localhost:4566
  79.       costexplorer: http://localhost:4566
  80.       cur: http://localhost:4566
  81.       databasemigration: http://localhost:4566
  82.       databasemigrationservice: http://localhost:4566
  83.       dataexchange: http://localhost:4566
  84.       datapipeline: http://localhost:4566
  85.       datasync: http://localhost:4566
  86.       dax: http://localhost:4566
  87.       detective: http://localhost:4566
  88.       devicefarm: http://localhost:4566
  89.       devopsguru: http://localhost:4566
  90.       directconnect: http://localhost:4566
  91.       dlm: http://localhost:4566
  92.       dms: http://localhost:4566
  93.       docdb: http://localhost:4566
  94.       ds: http://localhost:4566
  95.       dynamodb: http://localhost:4566
  96.       dynamodbstreams: http://localhost:4566
  97.       ec2: http://localhost:4566
  98.       ec2instanceconnect: http://localhost:4566
  99.       ecr: http://localhost:4566
  100.       ecrpublic: http://localhost:4566
  101.       ecs: http://localhost:4566
  102.       efs: http://localhost:4566
  103.       eks: http://localhost:4566
  104.       elasticache: http://localhost:4566
  105.       elasticbeanstalk: http://localhost:4566
  106.       elasticinference: http://localhost:4566
  107.       elasticsearch: http://localhost:4566
  108.       elasticsearchservice: http://localhost:4566
  109.       elastictranscoder: http://localhost:4566
  110.       elb: http://localhost:4566
  111.       elbv2: http://localhost:4566
  112.       emr: http://localhost:4566
  113.       emrcontainers: http://localhost:4566
  114.       es: http://localhost:4566
  115.       eventbridge: http://localhost:4566
  116.       events: http://localhost:4566
  117.       finspace: http://localhost:4566
  118.       finspacedata: http://localhost:4566
  119.       firehose: http://localhost:4566
  120.       fis: http://localhost:4566
  121.       fms: http://localhost:4566
  122.       forecast: http://localhost:4566
  123.       forecastquery: http://localhost:4566
  124.       forecastqueryservice: http://localhost:4566
  125.       forecastservice: http://localhost:4566
  126.       frauddetector: http://localhost:4566
  127.       fsx: http://localhost:4566
  128.       gamelift: http://localhost:4566
  129.       glacier: http://localhost:4566
  130.       globalaccelerator: http://localhost:4566
  131.       glue: http://localhost:4566
  132.       gluedatabrew: http://localhost:4566
  133.       greengrass: http://localhost:4566
  134.       greengrassv2: http://localhost:4566
  135.       groundstation: http://localhost:4566
  136.       guardduty: http://localhost:4566
  137.       health: http://localhost:4566
  138.       healthlake: http://localhost:4566
  139.       honeycode: http://localhost:4566
  140.       iam: http://localhost:4566
  141.       identitystore: http://localhost:4566
  142.       imagebuilder: http://localhost:4566
  143.       inspector: http://localhost:4566
  144.       iot: http://localhost:4566
  145.       iot1clickdevices: http://localhost:4566
  146.       iot1clickdevicesservice: http://localhost:4566
  147.       iot1clickprojects: http://localhost:4566
  148.       iotanalytics: http://localhost:4566
  149.       iotdataplane: http://localhost:4566
  150.       iotdeviceadvisor: http://localhost:4566
  151.       iotevents: http://localhost:4566
  152.       ioteventsdata: http://localhost:4566
  153.       iotfleethub: http://localhost:4566
  154.       iotjobsdataplane: http://localhost:4566
  155.       iotsecuretunneling: http://localhost:4566
  156.       iotsitewise: http://localhost:4566
  157.       iotthingsgraph: http://localhost:4566
  158.       iotwireless: http://localhost:4566
  159.       kafka: http://localhost:4566
  160.       kafkaconnect: http://localhost:4566
  161.       kendra: http://localhost:4566
  162.       kinesis: http://localhost:4566
  163.       kinesisanalytics: http://localhost:4566
  164.       kinesisanalyticsv2: http://localhost:4566
  165.       kinesisvideo: http://localhost:4566
  166.       kinesisvideoarchivedmedia: http://localhost:4566
  167.       kinesisvideomedia: http://localhost:4566
  168.       kinesisvideosignalingchannels: http://localhost:4566
  169.       kms: http://localhost:4566
  170.       lakeformation: http://localhost:4566
  171.       lambda: http://localhost:4566
  172.       lexmodelbuilding: http://localhost:4566
  173.       lexmodelbuildingservice: http://localhost:4566
  174.       lexmodels: http://localhost:4566
  175.       lexmodelsv2: http://localhost:4566
  176.       lexruntime: http://localhost:4566
  177.       lexruntimeservice: http://localhost:4566
  178.       lexruntimev2: http://localhost:4566
  179.       licensemanager: http://localhost:4566
  180.       lightsail: http://localhost:4566
  181.       location: http://localhost:4566
  182.       lookoutequipment: http://localhost:4566
  183.       lookoutforvision: http://localhost:4566
  184.       lookoutmetrics: http://localhost:4566
  185.       machinelearning: http://localhost:4566
  186.       macie: http://localhost:4566
  187.       macie2: http://localhost:4566
  188.       managedblockchain: http://localhost:4566
  189.       marketplacecatalog: http://localhost:4566
  190.       marketplacecommerceanalytics: http://localhost:4566
  191.       marketplaceentitlement: http://localhost:4566
  192.       marketplaceentitlementservice: http://localhost:4566
  193.       marketplacemetering: http://localhost:4566
  194.       mediaconnect: http://localhost:4566
  195.       mediaconvert: http://localhost:4566
  196.       medialive: http://localhost:4566
  197.       mediapackage: http://localhost:4566
  198.       mediapackagevod: http://localhost:4566
  199.       mediastore: http://localhost:4566
  200.       mediastoredata: http://localhost:4566
  201.       mediatailor: http://localhost:4566
  202.       memorydb: http://localhost:4566
  203.       mgn: http://localhost:4566
  204.       migrationhub: http://localhost:4566
  205.       migrationhubconfig: http://localhost:4566
  206.       mobile: http://localhost:4566
  207.       mobileanalytics: http://localhost:4566
  208.       mq: http://localhost:4566
  209.       mturk: http://localhost:4566
  210.       mwaa: http://localhost:4566
  211.       neptune: http://localhost:4566
  212.       networkfirewall: http://localhost:4566
  213.       networkmanager: http://localhost:4566
  214.       nimblestudio: http://localhost:4566
  215.       opsworks: http://localhost:4566
  216.       opsworkscm: http://localhost:4566
  217.       organizations: http://localhost:4566
  218.       outposts: http://localhost:4566
  219.       personalize: http://localhost:4566
  220.       personalizeevents: http://localhost:4566
  221.       personalizeruntime: http://localhost:4566
  222.       pi: http://localhost:4566
  223.       pinpoint: http://localhost:4566
  224.       pinpointemail: http://localhost:4566
  225.       pinpointsmsvoice: http://localhost:4566
  226.       polly: http://localhost:4566
  227.       pricing: http://localhost:4566
  228.       prometheus: http://localhost:4566
  229.       prometheusservice: http://localhost:4566
  230.       proton: http://localhost:4566
  231.       qldb: http://localhost:4566
  232.       qldbsession: http://localhost:4566
  233.       quicksight: http://localhost:4566
  234.       ram: http://localhost:4566
  235.       rds: http://localhost:4566
  236.       rdsdata: http://localhost:4566
  237.       rdsdataservice: http://localhost:4566
  238.       redshift: http://localhost:4566
  239.       redshiftdata: http://localhost:4566
  240.       rekognition: http://localhost:4566
  241.       resourcegroups: http://localhost:4566
  242.       resourcegroupstagging: http://localhost:4566
  243.       resourcegroupstaggingapi: http://localhost:4566
  244.       robomaker: http://localhost:4566
  245.       route53: http://localhost:4566
  246.       route53domains: http://localhost:4566
  247.       route53recoverycontrolconfig: http://localhost:4566
  248.       route53recoveryreadiness: http://localhost:4566
  249.       route53resolver: http://localhost:4566
  250.       s3: http://localhost:4566
  251.       s3control: http://localhost:4566
  252.       s3outposts: http://localhost:4566
  253.       sagemaker: http://localhost:4566
  254.       sagemakeredgemanager: http://localhost:4566
  255.       sagemakerfeaturestoreruntime: http://localhost:4566
  256.       sagemakerruntime: http://localhost:4566
  257.       savingsplans: http://localhost:4566
  258.       schemas: http://localhost:4566
  259.       sdb: http://localhost:4566
  260.       secretsmanager: http://localhost:4566
  261.       securityhub: http://localhost:4566
  262.       serverlessapplicationrepository: http://localhost:4566
  263.       serverlessapprepo: http://localhost:4566
  264.       serverlessrepo: http://localhost:4566
  265.       servicecatalog: http://localhost:4566
  266.       servicediscovery: http://localhost:4566
  267.       servicequotas: http://localhost:4566
  268.       ses: http://localhost:4566
  269.       sesv2: http://localhost:4566
  270.       sfn: http://localhost:4566
  271.       shield: http://localhost:4566
  272.       signer: http://localhost:4566
  273.       simpledb: http://localhost:4566
  274.       sms: http://localhost:4566
  275.       snowball: http://localhost:4566
  276.       sns: http://localhost:4566
  277.       sqs: http://localhost:4566
  278.       ssm: http://localhost:4566
  279.       ssmcontacts: http://localhost:4566
  280.       ssmincidents: http://localhost:4566
  281.       sso: http://localhost:4566
  282.       ssoadmin: http://localhost:4566
  283.       ssooidc: http://localhost:4566
  284.       stepfunctions: http://localhost:4566
  285.       storagegateway: http://localhost:4566
  286.       sts: http://localhost:4566
  287.       support: http://localhost:4566
  288.       swf: http://localhost:4566
  289.       synthetics: http://localhost:4566
  290.       textract: http://localhost:4566
  291.       timestreamquery: http://localhost:4566
  292.       timestreamwrite: http://localhost:4566
  293.       transcribe: http://localhost:4566
  294.       transcribeservice: http://localhost:4566
  295.       transcribestreaming: http://localhost:4566
  296.       transcribestreamingservice: http://localhost:4566
  297.       transfer: http://localhost:4566
  298.       translate: http://localhost:4566
  299.       waf: http://localhost:4566
  300.       wafregional: http://localhost:4566
  301.       wafv2: http://localhost:4566
  302.       wellarchitected: http://localhost:4566
  303.       workdocs: http://localhost:4566
  304.       worklink: http://localhost:4566
  305.       workmail: http://localhost:4566
  306.       workmailmessageflow: http://localhost:4566
  307.       workspaces: http://localhost:4566
  308.       xray: http://localhost:4566

Deploy the stack to LocalStack

Make sure your LocalStack is running. For the example stack, the only required service is S3. After updating the stack configuration, and starting localstack, you can run:

  1. $ pulumi up

once the stack update was performed, you can run:

  1. $ awslocal s3 ls

Where you should see something like

  1. 2021-09-30 11:50:59 my-bucket-6c21027

Pulumilocal

pulumilocal is a wrapper script and drop-in replacement for the pulumi CLI, that also provides commands to better interface Pulumi with LocalStack. You can find the source code repository here: https://github.com/localstack/pulumi-local

Install

pulumilocal requires that you already have the pulumi command in your path. Then, simply run

  1. $ pip install pulumi-local

then,

  1. pulumi version
  2. pulumilocal version

should output the same value.

Use

Instead of manually editing a stack configuration as explained earlier, you can run

  1. $ pulumilocal init

which will create a Pulumi.localstack.yaml stack configuration, and initialize an additional stack named localstack.

You can now run

  1. $ pulumilocal up

to start the localstack stack.

Configuration

You can configure the integration between pulumi-local and LocalStack by adding these environment variables before running pulumilocal:

VariableDefault valueDescription
PULUMI_CMDpulumiThe Pulumi command that is being delegated to
PULUMI_STACK_NAMElocalstackThe Pulumi stack name used for looking up the stack file (Pulumi.<stack>.yaml)
LOCALSTACK_HOSTNAMElocalhostThe name of the host LocalStack is reachable at
EDGE_PORT4566The port LocalStack is reachable at
USE_SSL0A truthy (1, true) string that indicates whether to use SSL when connecting to LocalStack

Community resources

Articles

Last modified May 17, 2022: fix capitalization of LocalStack in affected files (#157) (6206611c)