トップ > AWS Control Tower > re:Invent2023 AWS Control Tower に新たな API が追加されました

re:Invent2023 AWS Control Tower に新たな API が追加されました

AWS Control Tower AWS re:Invent 2023 Serverworks Advent Calendar 2023
記事タイトルとURLをコピーする

みなさん、こんにちは。
AWS CLI が好きなテクニカルサポート課の市野です。

今日は re:Invent 2023 で発表された内容の中から、AWS Control Tower に新たな API が追加されたという発表について、私が好きな AWS CLI の観点から深掘りしていきたいと思います。

クリックで目次を表示します。

発表内容

aws.amazon.com

クリックで What's New 記事全文を表示します。

Automate AWS Control Tower landing zone operations using APIs

Posted On: Nov 26, 2023

AWS Control Tower customers can now programmatically set up and manage their landing zones. Customers can discover, create, update, and reset their landing zones, as well as manage landing zone customizations, using APIs. A landing zone is a well-architected, multi-account AWS environment based on security and compliance best practices. AWS Control Tower automates the setup of a new landing zone using best-practices blueprints for identity, federated access, logging, and account structure. The landing zone APIs include AWS CloudFormation support, allowing customers to manage their landing zone with infrastructure as code (IaC).

The landing zone APIs enable customers to automate their AWS multi-account environment and adopt best practices programmatically. The APIs are available for customers who want to set up a new landing zone or use an existing landing zone. New customers can get started today by following the steps in the API Reference to create the pre-requisite AWS Organization, shared accounts, and service roles. After setting up their resources customers can create their landing zone with a single API call. Existing customers can start managing their landing zone programmatically today with existing permissions and resources. API actions include:

  • GetLandingZone/ListLandingZones - discover your landing zone configuration options
  • CreateLandingZone/UpdateLandingZone/DeleteLandingZone - manage your landing zone resources
  • ResetLandingZone - repair landing zone drift
  • GetLandingZoneOperation - monitor in-progress changes

For a full list of landing zone API calls, see the API References in the AWS Control Tower User Guide. For a full list of AWS Regions where AWS Control Tower is available, see the AWS Region Table.

まとめ

今回のリリースでは AWS Control Tower に対する各種 CRUD 操作のうち、以下の操作が AWS API 経由から行えるようになりました。

合計 7つの API アクションが追加となりましたが、主にランディングゾーンに関する操作を API 経由で行えるようになったと理解して良さそうです。

操作種別 API アクション アクション概要
CREATE CreateLandingZone ランディングゾーンの作成を行います
READ GetLandingZone 特定の ARN を持つランディングゾーン情報を取得します
READ ListLandingZones ランディングゾーン一覧を取得します
READ GetLandingZoneOperation ランディングゾーンの作成、更新、リセット、および廃止操作実行時に返却される OperationIdentifier を指定することにより、ランディングゾーン操作の詳細を取得します。
なお、この詳細は直近 60 日間入手可能となっています。
UPDATE UpdateLandingZone ランディングゾーンの更新を行います
UPDATE ResetLandingZone ランディングゾーンをリセットします
具体的にはランディングゾーン内のドリフトを解決する際に利用する API アクションとなります
DELETE DeleteLandingZone ランディングゾーンを廃止します

追加されたアクションが利用できる AWS CLI バージョン

AWS CLI の GitHub リポジトリの CHANGELOG を見る限り、本実装が適用されている AWS CLI バージョンは以下の通りとなります。

そもそも AWS Control Tower とは？

AWS の利用において、開発ステージごと、あるいは用途ごとなど、異なる目的や用途のための環境を混在した AWS アカウント運用を避ける "マルチアカウント運用" を推奨する傾向が年々強まっています。

背景としては、誤って実行した操作の結果、意図しない適用が行われるなど、混在環境での対象の取り違えによる影響を極小化する観点や、職務やロールに応じたアクセス制御や権限付与の目的がありますが、企業内での AWS 利用が推進されればされるほど煩雑になる各アカウントに対する統制の一元化を目的として、2019年 にリリースされ、東京リージョンでは 2021年 から利用できるようになりました。

そして、AWS アカウント環境全体に対して提供されるガバナンスルールである各種ガードレール群を一元管理するための仕組みとしてランディングゾーンと呼ばれる管理手法が用意されています。

aws.amazon.com

弊社が提供する AWS 請求代行サービスにおきましても、「AWS請求代行 + AWS Control Tower」オプションとして提供しており、お申し込みによりご利用可能なサービスとして展開しております。

やってみた

今回は、既存のランディングゾーンを変更する処理の流れとして考えてみたいと思います。

0. 実行環境の確認

今回は、CloudShell 環境を利用します。

[cloudshell-user@ip-10-134-30-110 ~]$ cat /etc/os-release 
NAME="Amazon Linux"
VERSION="2"
ID="amzn"
ID_LIKE="centos rhel fedora"
VERSION_ID="2"
PRETTY_NAME="Amazon Linux 2"
ANSI_COLOR="0;33"
CPE_NAME="cpe:2.3:o:amazon:amazon_linux:2"
HOME_URL="https://amazonlinux.com/"

[cloudshell-user@ip-10-134-30-110 ~]$ bash --version
GNU bash, version 4.2.46(2)-release (x86_64-koji-linux-gnu)
Copyright (C) 2011 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software; you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

[cloudshell-user@ip-10-134-30-110 ~]$ aws --version
aws-cli/2.14.5 Python/3.11.6 Linux/6.1.59-84.139.amzn2023.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off

1. ランディングゾーンの取得

ListLandingZones アクションに呼応したcontroltower list-landing-zones サブコマンドで取得が可能となります。

aws controltower list-landing-zones
{
    "landingZones": [
        {
            "arn": "arn:aws:controltower:ap-northeast-1:123456789012:landingzone/XXXXXXXXXXXXXXXX"
        }
    ]
}

docs.aws.amazon.com

1-1. ランディングゾーン ARN の取得

上記のようなレスポンスが得られることが分かりましたので、以下のようにランディングゾーン ARN を変数に格納します。

LANDING_ZONE_ARN=$(aws controltower list-landing-zones \
  --query 'landingZones[].arn' \
  --output text)

2. ランディングゾーン設定の取得

GetLandingZone アクションに呼応した controltower get-landing-zone サブコマンドで取得が可能となります。

＜1-1＞で取得したランディングゾーンの ARN を指定して、以下の要領で実行することにより現在のランディングゾーンの設定状況を取得できます。

また、AWS CLI をはじめとした API 経由でのランディングゾーンの設定では、各種ランディングゾーンオプション項目の指定を目的として、マニフェストファイルとしてパラメータ投入する必要があります。
get-landing-zone サブコマンドを実行することにより、そのマニフェストファイルの内容の取得も可能となりますので、マニフェストファイルの書式を確認する目的でも利用可能なコマンドといえそうです。

aws controltower get-landing-zone \
  --landing-zone-identifier ${LANDING_ZONE_ARN}
{
    "landingZone": {
        "arn": "arn:aws:controltower:ap-northeast-1:123456789012:landingzone/XXXXXXXXXXXXXXXX",
        "driftStatus": {
            "status": "IN_SYNC"
        },
        "latestAvailableVersion": "3.2",
        "manifest": {
            "accessManagement": {
                "enabled": false
            },
            "securityRoles": {
                "accountId": "234567890123"
            },
            "governedRegions": [
                "ap-northeast-1"
            ],
            "organizationStructure": {
                "sandbox": {
                    "name": "Sandbox"
                },
                "security": {
                    "name": "Security"
                }
            },
            "centralizedLogging": {
                "accountId": "345678901234",
                "configurations": {
                    "loggingBucket": {
                        "retentionDays": 365
                    },
                    "accessLoggingBucket": {
                        "retentionDays": 3650
                    }
                },
                "enabled": true
            }
        },
        "status": "ACTIVE",
        "version": "3.2"
    }
}

docs.aws.amazon.com

マニフェストファイルの注意点（本エントリ執筆時点）

UpdateLandingZone API や aws controltower update-landing-zone コマンド等のリファレンスには以下のような記載があります。

The manifest.yaml file is a text file that describes your Amazon Web Services resources. For examples, review The manifest file.

上記では、YAML 形式でのマニフェストファイルのアップロードの必要性と、記載方法の案内がありますが、AWS サポートへ確認したところ、当該のドキュメントは "AWS Control Tower のカスタマイズ (CfCT)" 向けのドキュメントであり、不適切なドキュメントに誘導されているとのことです。（AWS サポートより担当部署へフィードバック済）

そのため執筆時点においては、上記のような get-landing-zone サブコマンドを実行し、得られた manifest 部分を参考にし、以下の手法でマニフェストファイルを作成する手順とします。

3. マニフェストファイルの作成

ここでは、管理する追加の AWS リージョンに大阪リージョン（ap-northeast-3）を追加してみます。

具体的には、＜2＞のステップで取得できた manifest キーの値をベースに以下のような LandingZoneManifest.json ファイルを作成します。

cat << EOF > LandingZoneManifest.json
{
    "accessManagement": {
        "enabled": false
    },
    "securityRoles": {
        "accountId": "234567890123"
    },
    "governedRegions": ["ap-northeast-1", "ap-northeast-3"],
    "organizationStructure": {
        "sandbox": { "name": "Sandbox" },
        "security": { "name": "Security" }
    },
    "centralizedLogging": {
        "accountId": "345678901234",
        "configurations": {
            "loggingBucket": { "retentionDays": 365 },
            "accessLoggingBucket": { "retentionDays": 3650 }
        },
        "enabled": true
    }
}
EOF

4. ランディングゾーンの変更

＜1-1＞で取得したランディングゾーンの ARN、＜3＞で作成したマニフェストファイルを指定し、controltower update-landing-zone サブコマンドを実行します。

なお、--landing-zone-identifier オプション、--manifest オプションに加えて、--landing-zone-version オプションでのランディングゾーンバージョンの指定も必須項目となっています。

aws controltower update-landing-zone \
  --landing-zone-version 3.2 \
  --landing-zone-identifier "${LANDING_ZONE_ARN}" \
  --manifest file://LandingZoneManifest.json

docs.aws.amazon.com

上記のコマンドを実行後、問題がなければ以下のように operationIdentifier が返却されます。

{
    "operationIdentifier": "f867d65c-xxxx-xxxx-xxxx-4672843516ad"
}

なお、ランディングゾーンの変更には 45〜60 分前後かかりますので、CLI では少し状況が読みにくいところです。
この点のわかりやすさは、プログレスバーが表示される GUI 操作にはかなわないところですね。
（CLI のセッションが切れる可能性はあり実現は難しいかもしれませんが、aws ec2 wait image-available のような wait 系のサブコマンドがあると嬉しいところです。）

5. 進捗状況の確認

＜4＞ で実行した aws controltower update-landing-zone サブコマンドで返却される operationIdentifier を指定し、GetLandingZoneOperation API アクションを実行することで、特定のランディングゾーン変更作業の詳細を確認することができます。

また、ドキュメントにもある通り、operationType として返却されうる値は、DELETE、CREATE、UPDATE、RESET の4パターン、status として返却されうる値は SUCCEEDED、IN_PROGRESS、FAILED の3パターンです。

5-1. ランディングゾーン変更中の実施

aws controltower get-landing-zone-operation \
  --operation-identifier f867d65c-xxxx-xxxx-xxxx-4672843516ad
{
    "operationDetails": {
        "operationType": "UPDATE",
        "startTime": "2023-12-02T05:33:52+00:00",
        "status": "IN_PROGRESS"
    }
}

5-2. ランディングゾーン変更 完了後の実施

aws controltower get-landing-zone-operation \
  --operation-identifier f867d65c-xxxx-xxxx-xxxx-4672843516ad
{
    "operationDetails": {
        "endTime": "2023-12-02T06:05:47+00:00",
        "operationType": "UPDATE",
        "startTime": "2023-12-02T05:33:52+00:00",
        "status": "SUCCEEDED"
    }
}

検証時は 40 分ほど待って、無事に SUCCEEDED となりました。

docs.aws.amazon.com

「AWS 請求代行 + AWS Control Tower」オプション をご利用のお客様向けのご案内

ランディングゾーン変更時の注意事項

弊社提供の「AWS 請求代行 + AWS Control Tower」オプションをご利用の場合、サービス仕様上ランディングゾーン設定の変更時に一定のご留意事項がございます。（マネジメントコンソールによる GUI 操作、今回発表された API 経由での操作を問わず。）

詳細は下記情報をご覧ください。（情報閲覧にはマイスターズポータルへのログインが必要です。）

おわりに

もともとマネジメントコンソールでできていた作業範囲ではあるものの、GUI から解放されて API レベルで実行できるようになったことで、UI の変更にも強い手順書の作成や、変更管理のコード化の観点で有益かと思います。

今回のエントリがどなたかの参考になれば幸いです。

ではまた。

市野 和明 (記事一覧)

マネージドサービス部・テクニカルサポート課

お客様から寄せられたご質問や技術検証を通じて得られた気づきを投稿していきます。

情シスだった前職までの経験で、UI がコロコロ変わる AWS においては GUI で手順を残していると画面構成が変わってしまって後々まごつくことが多かった経験から、極力変わりにくい AWS CLI での記事が多めです。

X（Twitter）：@kazzpapa3（AWS Community Builder）