Package Exports

cdk-env-manager

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cdk-env-manager) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

cdk-env-manager

aws-cdk で複数環境（production, development, etc...）を管理するための CLI ツールです。 TypeScript 対応。

https://qiita.com/ronny/items/c53c79a770fd12ae6786

デプロイ時の Parameter や Output は、AWS の Parameter Store で管理します。そのため、
- config.dev.json など、環境毎にファイルを作成する必要はありません。
- パラメータが増える毎に、環境変数や aws-cdk の Context を増やす必要はありません。
- 機密情報を Git で管理する必要がありません。
cdk diffしてからcdk deployするなど、デプロイ時の手順が統一されます。

Demo

デプロイ時の interactive CLI のイメージ

CDK

Install

yarn add aws-sdk @aws-cdk/core @aws-cdk/aws-ssm # install peer dependencies
yarn add cdk-env-manager

Usage

initialize

cdk プロジェクトを作成しておいてください。

cdk init --language typescript

// cdk.json
{
  "app": "node -r dotenv/config -r ts-node/register cdk/MyApp.ts"
}

Stack のコーディング

cdk-env-manager から CdkStackBase を import して継承してください。
createResources メソッドを実装してください。

// S3Stack.ts
import * as cdk from '@aws-cdk/core'
import * as s3 from '@aws-cdk/aws-s3'
import { CdkStackBase } from 'cdk-env-manager'

type Input = { removalPolicy: cdk.RemovalPolicy }
type Export = { myBucketArn: string }

export class S3Stack extends CdkStackBase<Input, Export> {
  createResources() {
    const myBucket = new s3.Bucket(this, this.name('MyBucket'), {
      removalPolicy: this.props.removalPolicy,
    })

    this.createOutputsSsmParameters({ myBucketName: myBucket.bucketName })

    return {
      myBucketArn: myBucket.bucketArn,
    }
  }
}

Input はこの Stack が受け取るパラメータです。
Export はこの Stack が出力するパラメータです。他の Stack に渡したい場合に使います。
createOutputsSsmParameters(...)は値を SSM のパラメータストアに書き出します。アプリ側から参照したい設定値などを、SSM に書き出してください。（アプリ側からの参照方法は後述）
this.name("MyBucket")は、"DevMyBucket"のように環境名の prefix をつけてくれるヘルパーメソッドです。

App のコーディング

複数の Stack をまとめる cdk app を作成します。

cdk-env-manager から CdkAppBase を import して継承してください。
createStacks メソッドを実装してください。
末尾２行は必須です。

// MyApp.ts
import * as cdk from '@aws-cdk/core'
import { CdkAppBase } from 'cdk-env-manager'
import { RoleStack } from './stacks/RoleStack'
import { S3Stack } from './stacks/S3Stack'

type DeployParameter = { removalPolicy: cdk.RemovalPolicy }

export class MyApp extends CdkAppBase<DeployParameter> {
  async createStacks() {
    const s3Stack = new S3Stack(this, 'S3Stack', {
      removalPolicy: this.deployParameters.removalPolicy,
    })

    new RoleStack(this, 'RoleBucket', {
      bucketArn: s3Stack.exports.myBucketArn,
    })
  }
}

const app = new MyApp()
app.synth()

詳細は example フォルダを参照してください。

Default Parameter の定義

デプロイ時にパラメータを渡すことができます。パラメータは環境毎に設定できます。パラメータの既定値をファイルに記載しておく必要があります。プロジェクトのルートに cdk.parameters.default.env を作成し、パラメータの既定値を key=value 形式で指定してください。

REMOVAL_POLICY=retain
XXX=xxx

環境変数の設定

デプロイ時に必要な以下の環境変数を設定してください。aws-cdk が参照する環境変数となります。

AWS_DEFAULT_REGION
AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY のペア、または AWS_PROFILE

デプロイ実行

npx cdk-env-manager

# .envファイルを読み込んで実行する場合は
# npx -n '-r dotenv/config' cdk-env-manager

詳細は以下を参照。

https://qiita.com/ronny/items/c53c79a770fd12ae6786#デプロイ方法

CLI OPTIONS

--skip-diff

cdk diffの実行をスキップします。

other options

aws-cdk の cli options が使用できます。 cdk diff, cdk deploy実行時に指定された option を渡します。

npx cdk-env-manager --trace # Print trace for stack warnings

アプリケーションから Stack Outputs の参照

with webpack

SSM に書き出された設定値を、webpack で読み込んでビルドする方法です。

環境変数CDK_ENV_KEYに、利用したい環境のキーを設定してください。

// webpack.config.ts
import webpack from 'webpack'
import { loadStackParameters } from 'cdk-env-manager/lib/util'

const configFunction: () => Promise<webpack.Configuration> = async () => {
  // load stack parameters from ssm
  const params = await loadStackParameters()

  return {
    entry: 'src/index.ts',
    // ...省略
    plugins: [
      new webpack.DefinePlugin({
        ...Object.keys(params).reduce(
          (payload, key) => ({ ...payload, [key]: JSON.stringify(params[key]) }),
          {}
        ),
      }),
    ],
  }
}

export default configFunction

# .env
AWS_DEFAULT_REGION=ap-northeast-1
AWS_PROFILE=my-profile
CDK_ENV_KEY=Dev # SSMから取得する環境のKEYを指定

// package.json
{
  "scripts": {
    "build": "node -r dotenv/config -r ts-node/register webpack.config.ts"
  }
}

Singleton Stack

HOSTED ZONE など、各環境で共通で利用したいリソースは、CdkSingletonStackBaseを継承して Stack を作成してください。各環境でこの Stack を共有して利用します。

1 つの AWS アカウント内に複数の CdkApp を持ちたい場合

環境変数CDK_APP_KEYを設定することで、 AWS アカウント内で参照する CdkApp を切り替えることができます。

License

MIT