【AWS CLI】コマンドの統一!?新しくリリースされたCloud Control APIを使ってみた

こんにちは。AWS CLIが好きな福島です。

はじめに
Cloud Control APIとは
詳細
触る前に
- AWS CLIのバージョンアップ
- 権限設定
触ってみた
終わりに

はじめに

今回は、AWS CLIまたはAWS SDKを使ってCloud Control APIが操作できるようになり、実際に触ってみたため、ブログに記載いたします。

AWS announces the general availability of AWS Cloud Control API

Cloud Control APIとは

一言でいうと、統一されたAWSのAPI操作が提供され、 AWSのAPIをもっと便利に使えるようになったというアップデートになります。

詳細

今回は、AWS CLIを使って、Cloud Control APIを操作しましたので、AWS CLIを例に詳細を記載いたします。

まず、AWS CLIの構造は以下の通りとなります。

aws <command> <subcommand> [options and parameters]

そして、今までは、AWS CLIを使って各種サービスを操作する場合、<command>の箇所がサービスごとに異なっておりました。

例えば、EC2を操作したい場合は、

aws ec2 <subcommand> [options and parameters]

RDSを操作したい場合は、

aws rds <subcommand> [options and parameters]

となっておりました。
※上記「<subcommand>」の箇所もサービスによって異なっておりました。

それが今回のアップデートで「<command> <subcommand> [options]」( ［parameters]は、サービスによって変わる)が統一されるようになりました。

EC2の場合

aws cloudcontrol <subcommand> --type-name AWS::EC2::Instance [options and parameters]

RDSの場合

aws cloudcontrol <subcommand> --type-name AWS::RDS::DBInstance [options and parameters]

のように、--type-nameの引数にリソースを指定し、操作するイメージとなりました。

触る前に

AWS CLIのバージョンアップ

触る前にまずは、AWS CLIのバージョンアップを行いましょう。

v2の場合、2.2.43以上にする必要があります。
※v1は使ってないため不明ですが、最新版にすれば利用できると思います。

AWS CLI のインストール、更新、アンインストール - AWS Command Line Interface

また、cloudcontrolのhelpを確認すると、<subcommand>は、以下が使えることが分かります。

aws cloudcontrol help

AVAILABLE COMMANDS
       o cancel-resource-request

       o create-resource

       o delete-resource

       o get-resource

       o get-resource-request-status

       o help

       o list-resource-requests

       o list-resources

       o update-resource

       o wait

今回は、チュートリアルの通り、コマンドを実行してみました。また、チュートリアルでは、CloudWatchのロググループに対する操作が記載されておりました。

Getting started with Cloud Control API - Cloud Control API

権限設定

Cloud Control APIを使うためには、IAM権限が必要になります。以下はAWSのドキュメントに記載のポリシーですが、リソースアクションの作成、読み取り、更新、および一覧表示（削除は不可）を許可します。
※IAMのドキュメントに記載がなかったため、推測ですが、削除の権限は、cloudformation:DeleteResourceを付与すればいけると思います。

--type-nameに指定する値(AWS::EC2::Instanceなど)からも分かりますが、権限をよく見るとcloudformationのアクションが必要になるため、 Cloud Control APIの裏側では、CloudFormationの機能と同様の機能が使われているようです。

https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/security.html

{
    "Version":"2012-10-17",
    "Statement":[{
        "Effect":"Allow",
        "Action":[
            "cloudformation:CreateResource",
            "cloudformation:GetResource",
            "cloudformation:UpdateResource",
            "cloudformation:ListResources"
        ],
        "Resource":"*"
    }]
}

また、CloudTrailには、イベントソースが「cloudcontrolapi.amazonaws.com」と残るようです。順番が前後しますが、今回触った際にCloudTrailのイベントは以下の通りです。

触ってみた

①create-resource

実行コマンド

aws cloudcontrol create-resource --type-name AWS::Logs::LogGroup --desired-state "{\"LogGroupName\": \"CloudControlExample\",\"RetentionInDays\":90}"

--desired-stateの引数にサービスごとに必要な設定を追加するようです。今回は、ロググループ名とログの保持期間を指定しています。

実行結果

{
    "ProgressEvent": {
        "TypeName": "AWS::Logs::LogGroup",
        "Identifier": "CloudControlExample",
        "RequestToken": "68df508e-f283-4103-a1c3-e4be89fd1498",
        "Operation": "CREATE",
        "OperationStatus": "IN_PROGRESS",
        "EventTime": "2021-10-01T20:18:32.609000+09:00"
    }
}

create-resourceは非同期の処理になるため、以下のコマンドで処理の結果を確認する必要があります。

②get-resource-request-status

実行コマンド

aws cloudcontrol get-resource-request-status --request-token 68df508e-f283-4103-a1c3-e4be89fd1498

実行結果

{
    "ProgressEvent": {
        "TypeName": "AWS::Logs::LogGroup",
        "Identifier": "CloudControlExample",
        "RequestToken": "68df508e-f283-4103-a1c3-e4be89fd1498",
        "Operation": "CREATE",
        "OperationStatus": "SUCCESS",
        "EventTime": "2021-10-01T20:18:33.514000+09:00"
    }
}

OperationStatusがSUCCESSとなっているため、無事にリソースを作成できたことが分かります。

③get-resource

実行コマンド

aws cloudcontrol get-resource --type-name AWS::Logs::LogGroup --identifier CloudControlExample

--identifierにリソースの識別子を入力するようです。ロググループの場合、ロググループ名を指定します。

実行結果

{
    "TypeName": "AWS::Logs::LogGroup",
    "ResourceDescription": {
        "Identifier": "CloudControlExample",
        "Properties": "{\"RetentionInDays\":90,\"LogGroupName\":\"CloudControlExample\",\"Arn\":\"arn:aws:logs:ap-northeast-1:XXXXXXXXXXXX:log-group:CloudControlExample:*\"}"
    }
}

④update-resource

実行コマンド

aws cloudcontrol update-resource --type-name AWS::Logs::LogGroup --identifier CloudControlExample --patch-document "[{\"op\":\"replace\",\"path\":\"/RetentionInDays\",\"value\":180}]"

get-resourceと同様に--identifierの引数に識別子を入力し、--patch-documentに更新内容を記載します。 --patch-documentは、以下の2つのプロパティが必要となり、ドキュメントに以下の通り記載されております。

op：操作タイプ。 Cloud Control APIは、RFC 6902で定義されているすべての操作（add, remove, replace, move, copy, and test.）をサポートします。
path：リソーススキーマのプロパティセクションに関連する、リソースプロパティへのパス。

Updating a resource - Cloud Control API

pathは、CloudFormationの各リソースで使えるPropertiesに指定できる値を設定するようです。

今回の場合は、「AWS::Logs::LogGroup」のPropertiesで指定できる「RetentionInDays」を指定しています。

◆「AWS::Logs::LogGroup」のProperties の詳細
AWS::Logs::LogGroup - AWS CloudFormation

また、--patch-documentで指定した値は、順番に実行され、途中で処理が失敗するとロールバックしない仕様となっているため、指定する順番も考慮する必要がありそうです。

実行結果

{
    "ProgressEvent": {
        "TypeName": "AWS::Logs::LogGroup",
        "Identifier": "CloudControlExample",
        "RequestToken": "568014bf-5ccc-4359-8647-e907d48c37ab",
        "Operation": "UPDATE",
        "OperationStatus": "IN_PROGRESS",
        "EventTime": "2021-10-01T20:25:26.249000+09:00",
        "ResourceModel": "{\"RetentionInDays\":180,\"LogGroupName\":\"CloudControlExample\"}"
    }
}

更新も非同期のため、get-resource-request-statusで処理結果を確認します。

実行コマンド

aws cloudcontrol get-resource-request-status --request-token 568014bf-5ccc-4359-8647-e907d48c37ab

実行結果

{
    "ProgressEvent": {
        "TypeName": "AWS::Logs::LogGroup",
        "Identifier": "CloudControlExample",
        "RequestToken": "568014bf-5ccc-4359-8647-e907d48c37ab",
        "Operation": "UPDATE",
        "OperationStatus": "SUCCESS",
        "EventTime": "2021-10-01T20:25:27.082000+09:00"
    }
}

⑤list-resources

実行コマンド

aws cloudcontrol list-resources --type-name AWS::Logs::LogGroup

実行結果

{
    "TypeName": "AWS::Logs::LogGroup",
    "ResourceDescription": [
            "Identifier": "CloudControlExample",
            "Properties": "{\"RetentionInDays\":180,\"LogGroupName\":\"CloudControlExample\",\"Arn\":\"arn:aws:logs:ap-northeast-1:XXXXXXXXXXXX:log-group:CloudControlExample:*\"}"
        }
    ]
}

⑥delete-resource

実行コマンド

aws cloudcontrol delete-resource --type-name AWS::Logs::LogGroup --identifier CloudControlExample

実行結果

{
    "ProgressEvent": {
        "TypeName": "AWS::Logs::LogGroup",
        "Identifier": "CloudControlExample",
        "RequestToken": "da49eab0-bae9-4c03-9db8-d095e257ed82",
        "Operation": "DELETE",
        "OperationStatus": "IN_PROGRESS",
        "EventTime": "2021-10-01T20:30:03.034000+09:00"
    }
}

削除も非同期のため、get-resource-request-statusで処理結果を確認します。

実行コマンド

aws cloudcontrol get-resource-request-status --request-token da49eab0-bae9-4c03-9db8-d095e257ed82

実行結果

{
    "ProgressEvent": {
        "TypeName": "AWS::Logs::LogGroup",
        "Identifier": "CloudControlExample",
        "RequestToken": "da49eab0-bae9-4c03-9db8-d095e257ed82",
        "Operation": "DELETE",
        "OperationStatus": "SUCCESS",
        "EventTime": "2021-10-01T20:30:04.161000+09:00"
    }
}

終わりに

実際に触ってみた感想ですが、コマンド操作が分かりやすく使いやすいなと思いました。ただし、EC2やRDSのリストするコマンドを実行してみましたが、まだサポートされていないようでした。

個人的には、各リソースの情報を抜き出すことをAWS CLIで実施することが多いため、まだ、今まで使っていたコマンドを使う場面が多いかなと思いつつ、今後も、Cloud Control APIも積極的に使い、ブログなどで良さをお伝え出来たらなと思います。

また、サービス全体で既存のAWSリソースのサポートを今後数か月間追加していくとのことのため、アップデートに期待したいと思います！！