[Tips] AWS CLI v2 の YAML Skeleton はコメント付きでちょっと親切！

大阪オフィスのちゃだいん（@chazuke4649）です。

AWS CLI v2 の YAML Skeleton がコメント付きでちょっと親切になってました！

タイトルをもう一度言いましたが、AWS CLI のドキュメントをながめていると気づいたのでご紹介したいと思います。

前提

公式ドキュメントはこちらです。

JSON または YAML 入力ファイルからの AWS CLI スケルトンと入力パラメータの生成 - AWS Command Line Interface

そもそも Skeleton とは？

AWS CLI は--cli-input-jsonおよび--cli-input-yamlオプションを指定すると、ファイルに記述したパラメータを入力することができます。それを行うためにあらかじめ --generate-cli-skeletonでパラメータのテンプレートを出力できます。
そのテンプレートのことを Skeleton と呼んでいます。詳細は下記ブログをどうぞ。

AWS CLI v2 とは？

AWS CLI v2 より --generate-cli-skeleton によるテンプレートのYAML出力、 --cli-input-yaml によるパラメータのYAML入力ができるようになりました。AWS CLI v2については下記ブログをどうぞ。

YAML Skeleton とは？

本エントリでは、AWS CLI v2 より可能になった --generate-cli-skeleton yaml-input で出力されるYAML形式のテンプレートをYAML Skeleton と呼んでいます。

実際どう変わったのか見てみましょう。
aws lambda create-functionの Sketeton を JSON形式と YAML形式で出してみます。

JSONの場合

% aws lambda create-function --generate-cli-skeleton  
  
{
    "FunctionName": "",
    "Runtime": "provided",
    "Role": "",
    "Handler": "",
    "Code": {
        "ZipFile": null,
        "S3Bucket": "",
        "S3Key": "",
        "S3ObjectVersion": ""
    },
    "Description": "",
    "Timeout": 0,
    "MemorySize": 0,
    "Publish": true,
    "VpcConfig": {
        "SubnetIds": [
            ""
        ],
        "SecurityGroupIds": [
            ""
        ]
    },
    "DeadLetterConfig": {
        "TargetArn": ""
    },
    "Environment": {
        "Variables": {
            "KeyName": ""
        }
    },
    "KMSKeyArn": "",
    "TracingConfig": {
        "Mode": "Active"
    },
    "Tags": {
        "KeyName": ""
    },
    "Layers": [
        ""
    ]
}

YAMLの場合

% aws lambda create-function --generate-cli-skeleton yaml-input  

FunctionName: ''  # [REQUIRED] The name of the Lambda function.
Runtime: nodejs8.10 # [REQUIRED] The identifier of the function's runtime. Valid values are: nodejs, nodejs4.3, nodejs6.10, nodejs8.10, nodejs10.x, nodejs12.x, java8, java11, python2.7, python3.6, python3.7, python3.8, dotnetcore1.0, dotnetcore2.0, dotnetcore2.1, nodejs4.3-edge, go1.x, ruby2.5, ruby2.7, provided.
Role: '' # [REQUIRED] The Amazon Resource Name (ARN) of the function's execution role.
Handler: '' # [REQUIRED] The name of the method within your code that Lambda calls to execute your function.
Code: # [REQUIRED] The code for the function.
  ZipFile: !!binary ''  # The base64-encoded contents of the deployment package.
  S3Bucket: '' # An Amazon S3 bucket in the same AWS Region as your function.
  S3Key: '' # The Amazon S3 key of the deployment package.
  S3ObjectVersion: '' # For versioned objects, the version of the deployment package object to use.
Description: '' # A description of the function.
Timeout: 0 # The amount of time that Lambda allows a function to run before stopping it.
MemorySize: 0 # The amount of memory that your function has access to.
Publish: true # Set to true to publish the first version of the function during creation.
VpcConfig: # For network connectivity to AWS resources in a VPC, specify a list of security groups and subnets in the VPC.
  SubnetIds:  # A list of VPC subnet IDs.
  - ''
  SecurityGroupIds: # A list of VPC security groups IDs.
  - ''
DeadLetterConfig: # A dead letter queue configuration that specifies the queue or topic where Lambda sends asynchronous events when they fail processing.
  TargetArn: ''  # The Amazon Resource Name (ARN) of an Amazon SQS queue or Amazon SNS topic.
Environment: # Environment variables that are accessible from function code during execution.
  Variables:  # Environment variable key-value pairs.
    KeyName: ''
KMSKeyArn: '' # The ARN of the AWS Key Management Service (AWS KMS) key that's used to encrypt your function's environment variables.
TracingConfig: # Set Mode to Active to sample and trace a subset of incoming requests with AWS X-Ray.
  Mode: PassThrough  # The tracing mode. Valid values are: Active, PassThrough.
Tags: # A list of tags to apply to the function.
  KeyName: ''
Layers: # A list of function layers to add to the function's execution environment.
- ''

見比べるとこんなことがわかります。

• YAMLでコンパクトになった
• コメントが付いている！

YAML Skeleton のコメントについて

ググってみると下記プルリクエストにやりとりがありました。

[v2] Add support for yaml for skeleton generation and input #4700 · aws/aws-cli - gitjhub

コメントに関しては、ざっとこんな風に読み取れました。

• APIリファレンスのようなドキュメントから、各パラメータ説明の一文目を追加している
• 有効な列挙型の値がある場合も追加している（Create-functionの場合だとRuntime）
• 引数が必要な場合は、[REQUIRED]を挿入している

というワケで、コメント付きでちょっと親切になってます。ありがとうございます。

※ただし、[REQUIRED]については、サービス単位やコマンド単位によって、いわゆる「必須のパラメータ（パラメータの指定は任意ではなく、ないとエラーになる≒入れさえすればコマンドは通る）」というワケではないことがわかりました。なので一旦は「必要なケースが多いパラメータ」くらいに捉えておくのが良いかなと思ってます。（認識間違ってたら教えてください...）

終わりに

個人的にはJSON苦手人間なので、YAMLは人間フレンドリーで嬉しいのと、コメントのおかげでhelpやドキュメント見にいく回数減らせるのはありがたいと感じました。
と同時に、みんなどんな風に使っているのかが気になりました。「私は Skeleton こんな風に使ってるよ〜」などあったらぜひ教えてください！

それでは今日はこの辺で。大阪オフィスのちゃだいん（@chazuke4649）でした。