これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS CDK で使用する環境を設定する
AWS Cloud Development Kit (AWS CDK) で使用する際、AWS 環境は複数の方法で設定できます。AWS 環境の最適な管理方法は、各自のニーズに応じて異なります。
アプリケーション内の各 CDK スタックは、デプロイ先を決定するために、必ず環境に関連付けなければなりません。
AWS 環境の概要については、「[AWS CDK の環境](environments.md)」を参照してください。
## どこから環境を指定できるか
環境は、認証情報と設定ファイルで指定することも、AWS コンストラクトライブラリの `Stack` コンストラクトの ` [env](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#env) ` プロパティを使用して指定することもできます。
### 認証情報と設定ファイル
AWS Command Line Interface (AWS CLI) を使用して、AWS 環境情報を保存、整理、管理する `credentials` ファイルおよび `config` ファイルを作成できます。これらのファイルの詳細については、「*AWS コマンドラインインターフェイスユーザーガイド*」の「[設定と認証情報ファイルの設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)」を参照してください。
これらのファイルに保存されている値は、*プロファイル*によって整理されます。これらのファイル内でプロファイルやキーと値のペアをどのように名付けるかは、プログラムによるアクセスを設定する方法によって異なります。さまざまな方法の詳細については、「[AWS CDK CLI のセキュリティ認証情報を設定する](configure-access.md)」を参照してください。
一般に、AWS CDK は AWS アカウント情報を `credentials` ファイルから、また AWS リージョン情報を `config` ファイルから解決します。
`credentials` および `config` ファイルを設定した後は、AWS CDK CLI および環境変数を使用して、利用する環境を指定できます。
### スタックコンストラクトの env プロパティ
`Stack` コンストラクトの ` [env](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#env) ` プロパティを使用することで、各スタックの環境を指定できます。このプロパティは、使用するアカウントとリージョンを定義します。このプロパティには、ハードコードされた値を渡すことや、CDK が提供する環境変数を渡すことができます。
環境変数を渡すには、`AWS_DEFAULT_ACCOUNT` および `AWS_DEFAULT_REGION` の環境変数を使用します。これらの環境変数は、`credentials` および `config` ファイルからの値を渡すことができます。また、CDK コード内のロジックを使用して、これらの環境変数の値を決定することもできます。
## AWS CDK での環境の優先順位
環境の指定方法を複数使用する場合、AWS CDK は以下の優先順位に従います。
1. `Stack` コンストラクトの `env` プロパティで指定された、ハードコードされた値。
1. `Stack` コンストラクトの `env` プロパティで指定された、`AWS_DEFAULT_ACCOUNT` および `AWS_DEFAULT_REGION` の環境変数。
1. `credentials` および `config` ファイルからのプロファイルに関連付けられ、`--profile` オプションを使用して CDK CLI に渡される環境情報。
1. `credentials` および `config` ファイルからの `default` プロファイル。
## 環境を指定するタイミング
CDK を使用して開発するときは、まず、AWS リソースを表すコンストラクトを含む CDK スタックを定義します。次に、各 CDK スタックを AWS CloudFormation テンプレートに合成します。その後、CloudFormation テンプレートを環境にデプロイします。環境をどう指定するかによって、環境情報が適用されて CDK の動作と結果に影響を与えるタイミングが決まります。
### テンプレート合成で環境を指定する
`Stack` コンストラクトの `env` プロパティを使用して環境情報を指定すると、環境情報がテンプレート合成に適用されます。`cdk synth` または `cdk deploy` を実行すると、環境固有の CloudFormation テンプレートが生成されます。
`env` プロパティ内で環境変数を使用する場合は、CDK CLI コマンドで `--profile` オプションを使用して、認証情報と設定ファイルからの環境情報を含むプロファイルを渡す必要があります。その後、この情報はテンプレート合成に適用され、環境固有のテンプレートが作成されます。
CloudFormation テンプレート内の環境情報は、他のメソッドよりも優先されます。たとえば、`cdk deploy --profile ` で別の環境を指定しても、そのプロファイルは無視されます。
このように環境情報を提供すると、CDK アプリ内で環境依存のコードとロジックを使用できます。これはまた、合成されたテンプレートは、合成されるマシン、ユーザー、またはセッションによって異なる可能性があることを意味します。このアプローチは、開発時にはしばしば受け入れられるか望まれる場合もありますが、本番稼働用には推奨されません。
### スタックデプロイ時の環境を指定する
`Stack` コンストラクトの `env` プロパティを使用して環境を指定していない場合、CDK CLI は合成時に環境に依存しない CloudFormation テンプレートを生成します。その後は、`cdk deploy --profile ` を使用してデプロイ先の環境を指定できます。
環境に依存しないテンプレートをデプロイするときにプロファイルを指定していない場合、CDK CLI はデプロイ時に `credentials` および `config` ファイルの `default` プロファイルから環境値を使用しようとします。
デプロイ時に環境情報が利用できない場合、AWS CloudFormation はデプロイ時に、`stack.account`、`stack.region`、`stack.availabilityZones` などの環境関連の属性を使用して環境情報の解決を試みます。
環境に依存しないスタックの場合、スタック内のコンストラクトは環境情報を使用できず、環境情報を必要とするロジックを使用することはできません。たとえば、`if (stack.region ==== 'us-east-1')` のようなコードを記述することや、` [Vpc.fromLookup](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#static-fromwbrlookupscope-id-options) ` などの環境情報を必要とするコンストラクトメソッドを使用することはできません。これらの機能を使用するには、`env` プロパティで環境を指定する必要があります。
環境に依存しないスタックの場合、アベイラビリティーゾーンを使用するすべてのコンストラクトには 2 つのアベイラビリティーゾーンが表示され、スタックを任意のリージョンにデプロイできます。
## AWS CDK で環境を指定する方法
### スタックごとにハードコードされた環境を指定する
`Stack` コンストラクトの `env` プロパティを使用して、スタックの AWS 環境値を指定します。以下に例を示します。
**Example**
```
const envEU = { account: '2383838383', region: 'eu-west-1' };
const envUSA = { account: '8373873873', region: 'us-west-2' };
new MyFirstStack(app, 'first-stack-us', { env: envUSA });
new MyFirstStack(app, 'first-stack-eu', { env: envEU });
```
```
const envEU = { account: '2383838383', region: 'eu-west-1' };
const envUSA = { account: '8373873873', region: 'us-west-2' };
new MyFirstStack(app, 'first-stack-us', { env: envUSA });
new MyFirstStack(app, 'first-stack-eu', { env: envEU });
```
```
env_EU = cdk.Environment(account="8373873873", region="eu-west-1")
env_USA = cdk.Environment(account="2383838383", region="us-west-2")
MyFirstStack(app, "first-stack-us", env=env_USA)
MyFirstStack(app, "first-stack-eu", env=env_EU)
```
```
public class MyApp {
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
return Environment.builder()
.account(account)
.region(region)
.build();
}
public static void main(final String argv[]) {
App app = new App();
Environment envEU = makeEnv("8373873873", "eu-west-1");
Environment envUSA = makeEnv("2383838383", "us-west-2");
new MyFirstStack(app, "first-stack-us", StackProps.builder()
.env(envUSA).build());
new MyFirstStack(app, "first-stack-eu", StackProps.builder()
.env(envEU).build());
app.synth();
}
}
```
```
Amazon.CDK.Environment makeEnv(string account, string region)
{
return new Amazon.CDK.Environment
{
Account = account,
Region = region
};
}
var envEU = makeEnv(account: "8373873873", region: "eu-west-1");
var envUSA = makeEnv(account: "2383838383", region: "us-west-2");
new MyFirstStack(app, "first-stack-us", new StackProps { Env=envUSA });
new MyFirstStack(app, "first-stack-eu", new StackProps { Env=envEU });
```
```
env_EU := awscdk.Environment{
Account: jsii.String("8373873873"),
Region: jsii.String("eu-west-1"),
}
env_USA := awscdk.Environment{
Account: jsii.String("2383838383"),
Region: jsii.String("us-west-2"),
}
MyFirstStack(app, "first-stack-us", &awscdk.StackProps{
Env: &env_USA,
})
MyFirstStack(app, "first-stack-eu", &awscdk.StackProps{
Env: &env_EU,
})
```
本番環境では、この手順をおすすめします。この方法で環境を明示的に指定することで、スタックが常に特定の環境にデプロイされるようにできます。
### 環境変数を使用して環境を指定する
AWS CDK には、CDK コード内で使用できる `CDK_DEFAULT_ACCOUNT` と `CDK_DEFAULT_REGION` の 2 つの環境変数が用意されています。スタックインスタンスの `env` プロパティ内でこれらの環境変数を使用する場合、CDK CLI の `--profile` オプションを使用して、認証情報と設定ファイルから環境情報を渡すことができます。
以下に、これらの環境変数を指定する方法の例を示します。
**Example**
ノードの `process` オブジェクトを介して環境変数にアクセスします。
TypeScript で `process` を使用するには `DefinitelyTyped` モジュールが必要です。`cdk init` はこのモジュールをインストールします。ただし、追加前に作成されたプロジェクトを使用している場合、または `cdk init` を使用してプロジェクトを設定していない場合は、このモジュールを手動でインストールする必要があります。
```
npm install @types/node
```
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION
}});
```
ノードの `process` オブジェクトを介して環境変数にアクセスします。
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION
}});
```
`os` モジュールの `environ` ディクショナリを使用して環境変数にアクセスします。
```
import os
MyDevStack(app, "dev", env=cdk.Environment(
account=os.environ["CDK_DEFAULT_ACCOUNT"],
region=os.environ["CDK_DEFAULT_REGION"]))
```
`System.getenv()` を使用して環境変数の値を取得します。
```
public class MyApp {
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account;
region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region;
return Environment.builder()
.account(account)
.region(region)
.build();
}
public static void main(final String argv[]) {
App app = new App();
Environment envEU = makeEnv(null, null);
Environment envUSA = makeEnv(null, null);
new MyDevStack(app, "first-stack-us", StackProps.builder()
.env(envUSA).build());
new MyDevStack(app, "first-stack-eu", StackProps.builder()
.env(envEU).build());
app.synth();
}
}
```
`System.Environment.GetEnvironmentVariable()` を使用して環境変数の値を取得します。
```
Amazon.CDK.Environment makeEnv(string account=null, string region=null)
{
return new Amazon.CDK.Environment
{
Account = account ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"),
Region = region ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION")
};
}
new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
```
```
import "os"
MyDevStack(app, "dev", &awscdk.StackProps{
Env: &awscdk.Environment{
Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")),
Region: jsii.String(os.Getenv("CDK_DEFAULT_REGION")),
},
})
```
環境変数を使用して環境を指定することで、同じ CDK スタックを異なる環境の AWS CloudFormation テンプレートに合成できます。つまり、CDK コードを変更しなくても、同じ CDK スタックを異なる AWS 環境にデプロイできます。`cdk synth` を実行するとき必要なのは、使用するプロファイルを指定することのみです。
このアプローチは、同じスタックを異なる環境にデプロイする場合の開発環境に最適です。ただし、合成されるマシン、ユーザー、またはセッションに応じて、同じ CDK コードから異なるテンプレートが合成される場合があるため、本番環境ではこのアプローチはお勧めしません。
### CDK CLI を使用して認証情報と設定ファイルから環境を指定する
環境に依存しないテンプレートをデプロイする場合は、任意の CDK CLI コマンドで `--profile` オプションを使用して、使用するプロファイルを指定します。以下は、`credentials` および `config` ファイルで定義されている `prod` プロファイルを使用して、`myStack` という名前の CDK スタックをデプロイする例です。
```
$ cdk deploy --profile
```
`--profile` オプションと、その他の CDK CLI コマンドやオプションの詳細については、「[AWS CDK CLI コマンドリファレンス](ref-cli-cmd.md)」を参照してください。
## AWS CDK で環境を設定する際の考慮事項
スタック内でコンストラクトを使用して定義するサービスは、デプロイ先のリージョンをサポートする必要があります。リージョンごとにサポートされている AWS のサービスのリストについては、「[AWS のサービス (リージョン別)](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)」を参照してください。
指定した環境に AWS CDK を使用してスタックデプロイを実行するには、有効な AWS Identity and Access Management (IAM) 認証情報が必要です。
## 例
### CDK スタックから環境に依存しない CloudFormation テンプレートを合成する
この例では、CDK スタックから環境に依存しない CloudFormation テンプレートを作成します。その後、このテンプレートを任意の環境にデプロイできます。
CDK スタックの例を以下に示します。このスタックは、Amazon S3 バケットと、そのバケットのリージョンに関する CloudFormation スタックの出力を定義します。この例では `env` は定義されていません。
**Example**
```
export class CdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Create the S3 bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
});
// Create an output for the bucket's Region
new cdk.CfnOutput(this, 'BucketRegion', {
value: bucket.env.region,
});
}
}
```
```
class CdkAppStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Create the S3 bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
});
// Create an output for the bucket's Region
new cdk.CfnOutput(this, 'BucketRegion', {
value: bucket.env.region,
});
}
}
```
```
class CdkAppStack(cdk.Stack):
def __init__(self, scope: cdk.Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Create the S3 bucket
bucket = s3.Bucket(self, 'amzn-s3-demo-bucket',
removal_policy=cdk.RemovalPolicy.DESTROY
)
# Create an output for the bucket's Region
cdk.CfnOutput(self, 'BucketRegion',
value=bucket.env.region
)
```
```
public class CdkAppStack extends Stack {
public CdkAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Create the S3 bucket
Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
.removalPolicy(RemovalPolicy.DESTROY)
.build();
// Create an output for the bucket's Region
CfnOutput.Builder.create(this, "BucketRegion")
.value(this.getRegion())
.build();
}
}
```
```
namespace MyCdkApp
{
public class CdkAppStack : Stack
{
public CdkAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Create the S3 bucket
var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps
{
RemovalPolicy = RemovalPolicy.DESTROY
});
// Create an output for the bucket's Region
new CfnOutput(this, "BucketRegion", new CfnOutputProps
{
Value = this.Region
});
}
}
}
```
```
func NewCdkAppStack(scope constructs.Construct, id string, props *CdkAppStackProps) awscdk.Stack {
stack := awscdk.NewStack(scope, &id, &props.StackProps)
// Create the S3 bucket
bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
RemovalPolicy: awscdk.RemovalPolicy_DESTROY,
})
// Create an output for the bucket's Region
awscdk.NewCfnOutput(stack, jsii.String("BucketRegion"), &awscdk.CfnOutputProps{
Value: stack.Region(),
})
return stack
}
```
`cdk synth` を実行すると、CDK CLI は、バケットのリージョンの出力値として擬似パラメータ ` AWS::Region` を含む CloudFormation テンプレートを生成します。このパラメータはデプロイ時に解決されます。
```
Outputs:
BucketRegion:
Value:
Ref: AWS::Region
```
このスタックを認証情報と設定ファイルの `dev` プロファイルで指定された環境にデプロイするには、以下を実行します。
```
$ cdk deploy CdkAppStack --profile dev
```
プロファイルを指定しない場合、CDK CLI は認証情報と設定ファイルの `default` プロファイルからの環境情報の使用を試みます。
### ロジックを使用してテンプレート合成時の環境情報を決定する
この例では、有効な式を使用するように `stack` インスタンスの `env` プロパティを設定します。追加の環境変数として `CDK_DEPLOY_ACCOUNT` と `CDK_DEPLOY_REGION` の 2 つを指定します。これらの環境変数が存在する場合、合成時のデフォルトを上書きできます。
**Example**
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION
}});
```
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION
}});
```
```
MyDevStack(app, "dev", env=cdk.Environment(
account=os.environ.get("CDK_DEPLOY_ACCOUNT", os.environ["CDK_DEFAULT_ACCOUNT"]),
region=os.environ.get("CDK_DEPLOY_REGION", os.environ["CDK_DEFAULT_REGION"])
)
)
```
```
public class MyApp {
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
account = (account == null) ? System.getenv("CDK_DEPLOY_ACCOUNT") : account;
region = (region == null) ? System.getenv("CDK_DEPLOY_REGION") : region;
account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account;
region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region;
return Environment.builder()
.account(account)
.region(region)
.build();
}
public static void main(final String argv[]) {
App app = new App();
Environment envEU = makeEnv(null, null);
Environment envUSA = makeEnv(null, null);
new MyDevStack(app, "first-stack-us", StackProps.builder()
.env(envUSA).build());
new MyDevStack(app, "first-stack-eu", StackProps.builder()
.env(envEU).build());
app.synth();
}
}
```
```
Amazon.CDK.Environment makeEnv(string account=null, string region=null)
{
return new Amazon.CDK.Environment
{
Account = account ??
System.Environment.GetEnvironmentVariable("CDK_DEPLOY_ACCOUNT") ??
System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"),
Region = region ??
System.Environment.GetEnvironmentVariable("CDK_DEPLOY_REGION") ??
System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION")
};
}
new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
```
```
var account, region string
var b bool
if account, b = os.LookupEnv("CDK_DEPLOY_ACCOUNT"); !b || len(account) == 0 {
account = os.Getenv("CDK_DEFAULT_ACCOUNT")
}
if region, b = os.LookupEnv("CDK_DEPLOY_REGION"); !b || len(region) == 0 {
region = os.Getenv("CDK_DEFAULT_REGION")
}
MyDevStack(app, "dev", &awscdk.StackProps{
Env: &awscdk.Environment{
Account: &account,
Region: ®ion,
},
})
```
スタックの環境をこのように宣言すると、短いスクリプトまたはバッチファイルを記述し、コマンドライン引数から変数を設定して、`cdk deploy` を呼び出すことができます。以下に例を示します。最初の 2 つの後に続く引数は、コマンドラインオプションまたは引数を指定するために `cdk deploy` に渡されます。
**Example**
```
#!/usr/bin/env bash
if [[ $# -ge 2 ]]; then
export CDK_DEPLOY_ACCOUNT=$1
export CDK_DEPLOY_REGION=$2
shift; shift
npx cdk deploy "$@"
exit $?
else
echo 1>&2 "Provide account and region as first two args."
echo 1>&2 "Additional args are passed through to cdk deploy."
exit 1
fi
```
スクリプトを `cdk-deploy-to.sh` として保存し、`chmod +x cdk-deploy-to.sh` を実行して実行可能にします。
```
@findstr /B /V @ %~dpnx0 > %~dpn0.ps1 && powershell -ExecutionPolicy Bypass %~dpn0.ps1 %*
@exit /B %ERRORLEVEL%
if ($args.length -ge 2) {
$env:CDK_DEPLOY_ACCOUNT, $args = $args
$env:CDK_DEPLOY_REGION, $args = $args
npx cdk deploy $args
exit $lastExitCode
} else {
[console]::error.writeline("Provide account and region as first two args.")
[console]::error.writeline("Additional args are passed through to cdk deploy.")
exit 1
}
```
Windows バージョンのスクリプトは PowerShell を使用することで、macOS /Linux バージョンと同じ機能を提供できます。またこれには、コマンドラインから簡単に呼び出せるように、バッチファイルとして実行できるようにする手順も含まれています。これは `cdk-deploy-to.bat` として保存する必要があります。バッチファイルが呼び出されると、`cdk-deploy-to.ps1` ファイルが作成されます。
その後、`cdk-deploy-to` スクリプトを使用して特定の環境にデプロイする、追加のスクリプトを記述します。以下に例を示します。
**Example**
```
#!/usr/bin/env bash
# cdk-deploy-to-test.sh
./cdk-deploy-to.sh 123457689 us-east-1 "$@"
```
```
@echo off
rem cdk-deploy-to-test.bat
cdk-deploy-to 135792469 us-east-1 %*
```
`cdk-deploy-to` スクリプトを使用して複数の環境にデプロイする例を以下に示します。最初のデプロイが失敗すると、プロセスは停止します。
**Example**
```
#!/usr/bin/env bash
# cdk-deploy-to-prod.sh
./cdk-deploy-to.sh 135792468 us-west-1 "$@" || exit
./cdk-deploy-to.sh 246813579 eu-west-1 "$@"
```
```
@echo off
rem cdk-deploy-to-prod.bat
cdk-deploy-to 135792469 us-west-1 %* || exit /B
cdk-deploy-to 245813579 eu-west-1 %*
```