匯入現有 AWS CloudFormation 範本

焦點模式

匯入現有 AWS CloudFormation 範本 - AWS Cloud Development Kit (AWS CDK) v2

這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 cloudformation-include.CfnInclude 建構將資源轉換為 L1 建構，將資源從 AWS CloudFormation 範本匯入您的 AWS Cloud Development Kit (AWS CDK) 應用程式。

匯入後，您可以在應用程式中使用這些資源，方式與最初在 AWS CDK 程式碼中定義這些資源的方式相同。您也可以在更高層級的建構中使用這些 L1 AWS CDK 建構。例如，這可讓您將 L2 許可授予方法與其定義的資源搭配使用。

建構基本上會將 AWS CDK API cloudformation-include.CfnInclude 包裝函式新增至 AWS CloudFormation 範本中的任何資源。使用此功能一次將現有 AWS CloudFormation 範本匯入 AWS CDK 至物件。透過執行此操作，您可以使用 AWS CDK 建構來管理現有的資源，以利用更高層級抽象的優勢。您也可以使用此功能，藉由提供 AWS CDK 建構 API 來將 AWS CloudFormation 範本提供給 AWS CDK 開發人員。

注意

AWS CDK v1 也包含 aws-cdk-lib.CfnInclude，先前用於相同的一般用途。不過，它缺少的大部分功能cloudformation-include.CfnInclude。

匯入 AWS CloudFormation 範本

以下是範例 AWS CloudFormation 範本，我們將使用此範本在本主題中提供範例。複製並儲存範本my-template.json作為後續操作。完成這些範例之後，您可以使用任何現有的部署 AWS CloudFormation 範本進一步探索。您可以從主控台取得它們 AWS CloudFormation 。


{
  "Resources": {
    "amzn-s3-demo-bucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "amzn-s3-demo-bucket",
      }
    }
  }
}

您可以使用 JSON 或 YAML 範本。如果可用，我們建議您使用 JSON，因為 YAML 剖析器接受的內容可能略有不同。

以下是如何使用將範例範本匯入 AWS CDK 應用程式的範例cloudformation-include。範本會在 CDK 堆疊的內容中匯入。

TypeScript


import * as cdk from 'aws-cdk-lib';
import * as cfninc from 'aws-cdk-lib/cloudformation-include';
import { Construct } from 'constructs';

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const template = new cfninc.CfnInclude(this, 'Template', { 
      templateFile: 'my-template.json',
    });
  }
}

JavaScript


const cdk = require('aws-cdk-lib');
const cfninc = require('aws-cdk-lib/cloudformation-include');

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    const template = new cfninc.CfnInclude(this, 'Template', { 
      templateFile: 'my-template.json',
    });
  }
}

module.exports = { MyStack }

Python


import aws_cdk as cdk
from aws_cdk import cloudformation_include as cfn_inc
from constructs import Construct

class MyStack(cdk.Stack):

    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        template = cfn_inc.CfnInclude(self, "Template",  
            template_file="my-template.json")

Java


import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.cloudformation.include.CfnInclude;
import software.constructs.Construct;

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        CfnInclude template = CfnInclude.Builder.create(this, "Template")
        	.templateFile("my-template.json")
        	.build();
    }
}

C#


using Amazon.CDK;
using Constructs;
using cfnInc = Amazon.CDK.CloudFormation.Include;

namespace MyApp
{
    public class MyStack : Stack
    {
        internal MyStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
        {
            var template = new cfnInc.CfnInclude(this, "Template", new cfnInc.CfnIncludeProps
            {
                TemplateFile = "my-template.json"
            });
        }
    }
}

anchor anchor anchor anchor anchor


import * as cdk from 'aws-cdk-lib';
import * as cfninc from 'aws-cdk-lib/cloudformation-include';
import { Construct } from 'constructs';

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const template = new cfninc.CfnInclude(this, 'Template', { 
      templateFile: 'my-template.json',
    });
  }
}

根據預設，匯入資源會保留範本中資源的原始邏輯 ID。此行為適用於將 AWS CloudFormation 範本匯入 AWS CDK，其中邏輯 IDs 必須保留。 AWS CloudFormation 需要此資訊，才能將這些匯入的資源辨識為 AWS CloudFormation 範本中的相同資源。

如果您正在開發範本的建構包裝函式，以便其他 AWS CDK 開發人員可以使用，請改為讓 AWS CDK AWS CDK 產生新的資源 IDs。如此一來，建構就可在堆疊中使用多次，而不會發生名稱衝突。若要執行此操作，請在匯入範本false時將 preserveLogicalIds 屬性設為。以下是範例：

anchor anchor anchor anchor anchor


const template = new cfninc.CfnInclude(this, 'MyConstruct', {
  templateFile: 'my-template.json',
  preserveLogicalIds: false
});

若要在您的 AWS CDK 應用程式控制下放置匯入的資源，請將堆疊新增至 App：

anchor anchor anchor anchor anchor


import * as cdk from 'aws-cdk-lib';
import { MyStack } from '../lib/my-stack';

const app = new cdk.App();
new MyStack(app, 'MyStack');

若要確認堆疊中的 AWS 資源不會有任何意外的變更，您可以執行 diff。使用 AWS CDK CLI cdk diff命令並省略任何 AWS CDK特定的中繼資料。以下是範例：


cdk diff --no-version-reporting --no-path-metadata --no-asset-metadata

匯入 AWS CloudFormation 範本之後， AWS CDK 應用程式應該會成為匯入資源的真實來源。若要變更資源，請在 AWS CDK 應用程式中修改它們，並使用 cdk deploy命令部署 AWS CDK CLI。

存取匯入的資源

範例程式碼template中的名稱代表匯入的 AWS CloudFormation 範本。若要從中存取資源，請使用物件的 getResource()方法。若要以特定類型的資源存取傳回的資源，請將結果轉換為所需的類型。這在 Python 或 JavaScript 中並非必要。以下是範例：

anchor anchor anchor anchor anchor


const cfnBucket = template.getResource('amzn-s3-demo-bucket') as s3.CfnBucket;

在此範例中，現在cfnBucket是 aws-s3.CfnBucket類別的執行個體。這是代表對應 AWS CloudFormation 資源的 L1 建構。您可以將其視為其類型的任何其他資源。例如，您可以使用 bucket.attrArn 屬性取得其 ARN 值。

若要改為在 L2 執行個體中包裝 L1 CfnBucket 資源，請使用靜態方法 fromBucketArn()、 fromBucketAttributes()或 fromBucketName()。 L2 aws-s3.Bucket 通常， fromBucketName()方法最方便。以下是範例：

anchor anchor anchor anchor anchor


const bucket = s3.Bucket.fromBucketName(this, 'Bucket', cfnBucket.ref);

其他 L2 建構具有從現有資源建立建構的類似方法。

當您在 L2 建構中包裝 L1 建構時，不會建立新的資源。 L2 從我們的範例中，我們不會建立第二個 S3；儲存貯體。反之，新的Bucket執行個體會封裝現有的 CfnBucket。

從範例中，現在bucket是 L2 Bucket 建構，其運作方式與任何其他 L2 建構相同。例如，您可以使用儲存貯體的便利grantWrite()方法，將 AWS Lambda 函數寫入存取權授予儲存貯體。您不需要手動定義必要的 AWS Identity and Access Management (IAM) 政策。以下是範例：

anchor anchor anchor anchor anchor


bucket.grantWrite(lambdaFunc);

取代參數

如果您的 AWS CloudFormation 範本包含參數，您可以使用 parameters 屬性，在匯入時將它們取代為建置時間值。在下列範例中，我們將 UploadBucket 參數取代為 AWS CDK 程式碼中其他位置定義的儲存貯體 ARN。

anchor anchor anchor anchor anchor


const template = new cfninc.CfnInclude(this, 'Template', {
  templateFile: 'my-template.json',
  parameters: {
    'UploadBucket': bucket.bucketArn,
  },
});

匯入其他範本元素

您可以匯入任何 AWS CloudFormation 範本元素，而不只是資源。匯入的 AWS CDK 元素會成為堆疊的一部分。若要匯入這些元素，請使用 CfnInclude 物件的下列方法：

getCondition() – AWS CloudFormation 條件。
getHook() –藍/綠部署 AWS CloudFormation 掛鉤。
getMapping() – AWS CloudFormation 映射。
getOutput() – AWS CloudFormation 輸出。
getParameter() – AWS CloudFormation 參數。
getRule() – 範本 AWS CloudFormation 規則 AWS Service Catalog 。

每個方法都會傳回代表特定 AWS CloudFormation 元素類型的類別執行個體。這些物件是可變的。您對它們所做的變更，會顯示在從 AWS CDK 堆疊產生的範本中。以下是從範本匯入參數並修改其預設值的範例：

anchor anchor anchor anchor anchor


const param = template.getParameter('MyParameter');
param.default = "AWS CDK"

匯入巢狀堆疊

您可以匯入巢狀堆疊，方法是在匯入主要範本時指定它們，或稍後再指定它們。巢狀範本必須存放在本機檔案中，但在主要範本中做為NestedStack資源參考。此外， AWS CDK 程式碼中使用的資源名稱必須符合主要範本中巢狀堆疊所使用的名稱。

鑑於主要範本中的此資源定義，下列程式碼顯示如何以兩種方式匯入參考的巢狀堆疊。


"NestedStack": {
  "Type": "AWS::CloudFormation::Stack",
  "Properties": {
    "TemplateURL": "https://my-s3-template-source.s3.amazonaws.com/nested-stack.json"
  }

TypeScript


// include nested stack when importing main stack
const mainTemplate = new cfninc.CfnInclude(this, 'MainStack', {
  templateFile: 'main-template.json',
  loadNestedStacks: {
    'NestedStack': {
      templateFile: 'nested-template.json',
    },
  },
});

// or add it some time after importing the main stack
const nestedTemplate = mainTemplate.loadNestedStack('NestedTemplate', {
  templateFile: 'nested-template.json',
});

JavaScript


// include nested stack when importing main stack
const mainTemplate = new cfninc.CfnInclude(this, 'MainStack', {
  templateFile: 'main-template.json',
  loadNestedStacks: {
    'NestedStack': {
      templateFile: 'nested-template.json',
    },
  },
});

// or add it some time after importing the main stack
const nestedTemplate = mainTemplate.loadNestedStack('NestedStack', {
  templateFile: 'my-nested-template.json',
});

Python


# include nested stack when importing main stack
main_template = cfn_inc.CfnInclude(self, "MainStack",  
    template_file="main-template.json",
    load_nested_stacks=dict(NestedStack=
        cfn_inc.CfnIncludeProps(template_file="nested-template.json")))

# or add it some time after importing the main stack
nested_template = main_template.load_nested_stack("NestedStack", 
    template_file="nested-template.json")

Java


CfnInclude mainTemplate = CfnInclude.Builder.create(this, "MainStack")
	.templateFile("main-template.json")
	.loadNestedStacks(java.util.Map.of(    // Map.of requires Java 9+
	   "NestedStack", CfnIncludeProps.builder()
				.templateFile("nested-template.json").build()))
	.build();

// or add it some time after importing the main stack
IncludedNestedStack nestedTemplate = mainTemplate.loadNestedStack("NestedTemplate", CfnIncludeProps.builder()
		.templateFile("nested-template.json")
		.build());

C#


// include nested stack when importing main stack
var mainTemplate = new cfnInc.CfnInclude(this, "MainStack", new cfnInc.CfnIncludeProps
{
    TemplateFile = "main-template.json",
    LoadNestedStacks = new Dictionary<string, cfnInc.ICfnIncludeProps>
    {
        { "NestedStack", new cfnInc.CfnIncludeProps { TemplateFile = "nested-template.json" } }
    }
});

// or add it some time after importing the main stack
var nestedTemplate = mainTemplate.LoadNestedStack("NestedTemplate", new cfnInc.CfnIncludeProps {
    TemplateFile = 'nested-template.json'
});

anchor anchor anchor anchor anchor


// include nested stack when importing main stack
const mainTemplate = new cfninc.CfnInclude(this, 'MainStack', {
  templateFile: 'main-template.json',
  loadNestedStacks: {
    'NestedStack': {
      templateFile: 'nested-template.json',
    },
  },
});

// or add it some time after importing the main stack
const nestedTemplate = mainTemplate.loadNestedStack('NestedTemplate', {
  templateFile: 'nested-template.json',
});

您可以使用任一方法匯入多個巢狀堆疊。匯入主要範本時，您可以在每個巢狀堆疊的資源名稱及其範本檔案之間提供映射。此映射可以包含任意數量的項目。若要在初始匯入後執行此操作，請針對每個巢狀堆疊呼叫 loadNestedStack() 一次。

匯入巢狀堆疊之後，您可以使用主要範本的 getNestedStack()方法存取它。

anchor anchor anchor anchor anchor


const nestedStack = mainTemplate.getNestedStack('NestedStack').stack;

getNestedStack() 方法會傳回IncludedNestedStack執行個體。從此執行個體，您可以透過 stack 屬性存取 AWS CDK NestedStack執行個體，如範例所示。您也可以透過存取原始 AWS CloudFormation 範本物件includedTemplate，您可以從中載入資源和其他 AWS CloudFormation 元素。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 CloudFormation 參數

取得 SSM 值

在本頁面

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定

匯入現有 AWS CloudFormation 範本

注意

主題

匯入 AWS CloudFormation 範本

存取匯入的資源

取代參數

匯入其他範本元素

匯入巢狀堆疊

在本頁面

此頁面是否有幫助？

下一個主題：

上一個主題：

需要協助？