Back to Details

pulumi-terraform-to-pulumi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrating from Terraform to Pulumi

从Terraform迁移到Pulumi

First establish scope and plan the migration by working out with the user:
  • where the Terraform sources are (
    ${terraform_dir}
    )
  • where the migrated Pulumi project lives (
    ${pulumi_dir}
    )
  • what is the target Pulumi language (such as TypeScript, Python, YAML)
  • whether migration aims to setup Pulumi stack states, or only translate source code
Confirm the plan with the user before proceeding.
Create a new Pulumi project in 
${pulumi_dir}
in the chosen language. Edit sources to be empty and not declare any resources. Ensure a Pulumi stack exists.
You must run 
pulumi_up
tool before proceeding to ensure initial stack state is written.
Now produce a draft Pulumi state translation:
pulumi plugin run terraform-migrate -- stack \
    --from ${terraform_dir} \
    --to ${pulumi_dir} \
    --out /tmp/pulumi-state.json \
    --plugins /tmp/required-providers.json
Do NOT install the plugin as it will auto-install as needed.
Sometimes terraform-migrate plugin fails because 
tofu refresh
is not authorized. DO NOT skip this step. Work with the user to find or build a Pulumi ESC environment to run the command in to make it succeed.
Read the generated 
/tmp/required-providers.json
and install all these Pulumi providers into the new project, respecting the suggested versions even if they downgrade an already installed provider. The file will contain records such as 
[{"name":"aws","version":"7.12.0"}]
.
Install providers as project dependencies using the language-specific package manager (NOT 
pulumi plugin install
, which only downloads plugins without adding dependencies):
# TypeScript/JavaScript
npm install @pulumi/aws@7.12.0

# Python
pip install pulumi_aws==7.12.0

# Go
go get github.com/pulumi/pulumi-aws/sdk/v7@v7.12.0

# C#
dotnet add package Pulumi.Aws --version 7.12.0
Import the translated state draft (
/tmp/pulumi-state.json
) into the Pulumi stack:
pulumi stack import --file /tmp/pulumi-state.json
Translate source code to match both the Terraform source and the translated state. Aim for exact match. You can consult the state draft 
/tmp/pulumi-state.json
for Pulumi resource types and names to use.
Iterate on fixing the source code until 
pulumi_preview
tool confirms that there are no changes to make and the diff is empty or almost empty. Provider diffs or diffs on tags may be OK.
Offer the user to link an ESC environment to the stack so that each Pulumi stack can seamlessly have access to the provider credentials it needs.
When all looks good, create a Pull Request with the migrated source code.
IMPORTANT:
  • when creating a Pulumi project, do NOT use /workspace, create one under the checked out project
  • do NOT run 
    pulumi convert
    , instead use the terraform-migrate plugin
  • do NOT run 
    pulumi package add terraform-module
首先与用户协作确定迁移范围并制定计划：
  • Terraform源文件的位置（
    ${terraform_dir}
    ）
  • 迁移后的Pulumi项目存放位置（
    ${pulumi_dir}
    ）
  • 目标Pulumi语言（如TypeScript、Python、YAML）
  • 迁移目标是设置Pulumi栈状态，还是仅转换源代码
在开始执行前与用户确认计划。
在
${pulumi_dir}
目录中使用选定语言创建一个新的Pulumi项目。修改源文件使其为空，不声明任何资源。确保Pulumi栈已存在。
在继续操作前必须运行
pulumi_up
工具，以确保写入初始栈状态。
现在生成Pulumi状态转换草稿：
pulumi plugin run terraform-migrate -- stack \
    --from ${terraform_dir} \
    --to ${pulumi_dir} \
    --out /tmp/pulumi-state.json \
    --plugins /tmp/required-providers.json
请勿安装插件，它会根据需要自动安装。
有时terraform-migrate插件会因
tofu refresh
未授权而失败。请勿跳过此步骤。与用户协作查找或构建Pulumi ESC环境来运行该命令，以确保操作成功。
读取生成的
/tmp/required-providers.json
文件，并将所有这些Pulumi提供程序安装到新项目中，即使会降级已安装的提供程序，也要遵循建议的版本。该文件将包含类似
[{"name":"aws","version":"7.12.0"}]
的记录。
使用语言特定的包管理器将提供程序作为项目依赖项安装（请勿使用
pulumi plugin install
，该命令仅下载插件而不添加依赖项）：
# TypeScript/JavaScript
npm install @pulumi/aws@7.12.0

# Python
pip install pulumi_aws==7.12.0

# Go
go get github.com/pulumi/pulumi-aws/sdk/v7@v7.12.0

# C#
dotnet add package Pulumi.Aws --version 7.12.0
将转换后的状态草稿（
/tmp/pulumi-state.json
）导入到Pulumi栈中：
pulumi stack import --file /tmp/pulumi-state.json
转换源代码以匹配Terraform源文件和转换后的状态。目标是完全匹配。你可以参考状态草稿
/tmp/pulumi-state.json
来确定要使用的Pulumi资源类型和名称。
反复修改源代码，直到
pulumi_preview
工具确认无需进行任何更改，且差异为空或几乎为空。提供程序差异或标签差异是可接受的。
为用户提供将ESC环境链接到栈的选项，以便每个Pulumi栈都能无缝访问所需的提供程序凭据。
当所有内容确认无误后，创建包含迁移后源代码的Pull Request。
重要提示：
  • 创建Pulumi项目时，请勿使用/workspace目录，应在已检出的项目下创建
  • 请勿运行
    pulumi convert
    ，请改用terraform-migrate插件
  • 请勿运行
    pulumi package add terraform-module