Migrating to Pulumi

If you’ve fallen in love with Pulumi, it might not be obvious how to adopt it. For new projects, write your infrastructure as code using Pulumi from the start. But what if you already have infrastructure stood up? And perhaps even actively serving a critical business need? In these cases, you may wonder, is it even possible to adopt Pulumi, without downtime or a major disturbance to your existing infrastructure? The answer is yes!

This user guide offers a tour of tried-and-true tools and techniques that can be used to migrate any infrastructure to Pulumi, regardless of how that infrastructure was originally provisioned in the cloud tooling ecosystem. These techniques range from coexisting with this infrastructure — either temporarily or permanently — to adopting infrastructure and converting existing infrastructure as code projects.

This page reviews some basic concepts. To go straight to a specific guide, choose one of the following:

• Importing infrastructure: for any cloud, no matter how it’s provisioned
• From Terraform or CDKTF: coexist with existing workspaces or convert your HCL
• From AWS CDK: migrate with Neo, coexist via stack outputs, or use the Pulumi CDK adapter
• From AWS CloudFormation: coexist with, deploy, or convert your templates and stacks
• From Azure Resource Manager (ARM): coexist with, deploy, or convert your templates and deployments
• From Kubernetes YAML or Helm: coexist with, deploy, or convert your configuration
• From Serverless Framework: coexist with, import, or rewrite your Serverless Framework applications

Concepts

The three basic concepts for how to adopt Pulumi and deal with existing infrastructure are coexistence, importing, and conversion. In short, coexistence lets you provision new infrastructure alongside existing infrastructure, importing lets you adopt control of existing infrastructure into a new Pulumi program, and conversion converts existing infrastructure as code to Pulumi.

Support for these techniques differs based on how your existing infrastructure was provisioned:

Coexistence

Suppose you already have infrastructure provisioned by an existing tool, such as Terraform, AWS CloudFormation, or Azure Resource Manager (ARM) templates, but don’t want to convert it right now. This could be for any number of reasons:

• Maybe you aren’t ready to take on that effort yet and want to focus on new infrastructure.
• Perhaps that infrastructure is managed by a different team who will keep using their own tool.
• Or it could be that this infrastructure is slated to be retired after your current project anyway.

In these cases, new infrastructure can coexist with old infrastructure in three ways, letting you keep your existing infrastructure as-is while building new infrastructure under Pulumi’s management. The following techniques can be used:

• Resource getters available on every resource let you read all the details for a resource from the cloud provider using only its ID.

• Stack references let you reference outputs of another Pulumi stack for use as inputs to a stack, which is useful for organizing projects and stacks.

• External state references let you reference outputs from a non-Pulumi stack for use as inputs to a Pulumi stack. Many infrastructure as code tools have the notion of “outputs,” which are values a stack exports for others to use. This might be VPC IDs, auto-assigned IP addresses, and so on. Examples include Terraform state files and workspaces, AWS CloudFormation stacks, and Azure Resource Manager (ARM) deployments.

Together, these let you reference existing infrastructure regardless of which tool provisioned it, without Pulumi taking over control of its ongoing management.

Importing infrastructure

Pulumi can adopt existing infrastructure so that Pulumi controls it going forward. This process is called importing. It lets you adopt Pulumi fully without needing to perturb or recreate existing infrastructure.

In the coexistence scenarios above, Pulumi reads your existing infrastructure but doesn’t assume control of managing it, so Pulumi never modifies or deletes infrastructure that is still managed outside of Pulumi. Importing is different: after the import process, all resources are entirely managed by Pulumi.

Furthermore, Pulumi doesn’t care where the infrastructure originally came from. You could have manually provisioned it in your cloud’s console UI, from the CLI, using Terraform, your cloud’s built-in templating mechanism, and so on. In all cases, after the import process, you’ll be left with a working Pulumi program, and all future infrastructure updates can be made with Pulumi. You can then retire the old way of managing your infrastructure. This works even if you’ve lost the original scripts or templates that created the infrastructure.

To learn more about how to import resources in this manner, refer to the import guide.

Conversion

The final approach is to convert an existing infrastructure as code program to Pulumi. This largely preserves existing program structure — which may be important if you carefully designed the names, modules, and configurability of your existing infrastructure as code layout. This can be difficult if not impossible to reverse-engineer automatically during the import process. How much of that structure carries over varies by converter.

Conversion takes care of the static program structure and automatically generates a new Pulumi program based on the source infrastructure as code program. This is usually still combined with importing so that you not only get a new program that provisions the right infrastructure, but also adopt existing infrastructure under the management of Pulumi too.

Conversion tools are available for Terraform HCL, Kubernetes YAML, and Azure Resource Manager (ARM) templates. For AWS CDK, AWS CloudFormation, and Serverless Framework, see the conversion options in each guide.