問題解決のためAWSドキュメントをどう追従するか
はじめに
私は普段、AWSのcloudtrailのログを取得したりSecurity Hubの分析するインシデントレスポンス・監査人の立場で仕事をすることがある。ログを分析する際も、アラートを裁く際も、ドキュメントを追って各種リソースの使われ方がどのようになっているかを追求する。開発者だったらリソースを組み立てるために各種サービスのドキュメントを追っていくことがよくあるだろう。
一方、AWSを勉強しようとなって思いつくのが資格取得であるが、AWSの認定資格などで得られるであろう知識情報のみでは、直接的に業務での問題解決に直結させることが難しい場合も多々ある。
問題解決のためには、AWSのAPIの働きをしっかり理解する必要があるのだが、暗記ゲーの資格試験ではその部分にフォーカスできているわけではないので応用させるのが難しくなっている。
そこでAWSのAPIの働きを理解できるようにどうドキュメントを読もうとしているかをいう話をする。あくまで1つの参考になれれば幸いです。
公式ドキュメントと有償のサポート
zennやqiitaなどに流れてくる記事はあくまで2次情報, 3次情報であることを考えると、1次情報を効果的に辿っている人に勝つことはできない。かなりユーザーに近いところでどのように考えたのかという思考のプロセスが参考になることはあるので完全に切り捨てることはできないが、どのような勉強の仕方をしても、公式ドキュメントから学んで実践している人に「知識の正確さ」の観点で勝つことは難しいのだ。
有償のサポートに関してはやはり「実務しか勝たん」ということにはなるんだが、若干のコミュニケーションコストが生じることを考えると、自力でドキュメントを読みといて解決できることが望ましい。ちなみに、サポートケースを起票するという所作は、やはり外部の人間と話すことになるためコミュニケーションの観点で距離感がある。
社内の詳しい方に聞くなどもっとソリューションを間に挟むことができることは頭においておく。
ドキュメントの全体像とその詳細
1枚のBig Pictureにまとめると以下のようになる。
サービス公式ガイド
サービスのセールス用のページだと思うのがいいだろう。
どのようなサービスなのか、概要をサクッと理解するために役に立てる。
ユーザーガイド
サービスの各機能の概念やその詳細などを解説している。
Amazon EC2 とは - Amazon Elastic Compute Cloud
後述するが分量が多いのがネックになっている。
CLIリファレンス
APIリファレンスのCLIサブセットという位置付けでAPIのアクションがCLIのサブコマンドに値するようになっている。
ec2 — AWS CLI 1.36.32 Command Reference
APIリファレンス
API仕様のマスター情報という位置付けである。この部分がわかってくると例えばサーバーサイドのコードを読んで理解できていなかったAWSのAPIを使って作り込んでいる部分の詳細がわかってくるはずだ。
とりわけ注目するべきはActionsとData Typesである。
Actions - Amazon Elastic Compute Cloud
Data Types - Amazon Elastic Compute Cloud
手を抜くためChatGPTに説明してもらおう。軽く自分の言葉で説明すると
ActionsはAPIへのインプット仕様なので、操作の内容そのものを表し、ユーザーがAPIを通じて実行するアクションを定義している。
Data TypesはAPIからのアウトプット仕様なので、そのアクションで使用されるデータの形式や構造を定義している。
以下、AIによる説明です。
1. Actions
-
概要:
Actionsは、AWSのサービスに対して実行できる操作や機能を示しています。これらはAPIエンドポイントを介してリクエストとして送信され、AWSが処理するアクションを定義します。 -
特徴:
- 操作対象: サービス固有のリソース（例: EC2インスタンス、S3バケット、DynamoDBテーブルなど）。
- リクエストとレスポンス: 各アクションには、リクエストパラメータとレスポンス要素が定義されています。
- 目的: アクションを使用してリソースを作成、読み取り、更新、または削除（CRUD操作）できます。
-
例:
-
S3:
PutObject,GetObject,DeleteObject -
EC2:
RunInstances,StopInstances,DescribeInstances
-
S3:
-
ドキュメントの構成例:
- アクション名（例:
CreateBucket） - 必須パラメータとオプションパラメータ
- アクションのレスポンス構造
- 使用例（SDKやCLIでの実行例）
- アクション名（例:
2. Data Types
-
概要:
Data Typesは、アクションやレスポンスで使用されるデータ構造やフォーマットを定義しています。これにより、リクエストやレスポンスがどのような形式を持つべきかが分かります。 -
特徴:
- 構造的な詳細: リクエストやレスポンスで使用されるフィールドの型や属性を記述。
- 再利用可能: 複数のアクションで共通して使用されるデータ構造もあります。
-
例:
-
S3:
Bucket（バケットの名前や作成日時を含む） -
EC2:
Instance（インスタンスID、タイプ、状態などを含む）
-
S3:
-
ドキュメントの構成例:
- データタイプ名（例:
Bucket） - フィールドとその説明（例:
Name- バケットの名前,CreationDate- 作成日時） - フィールドの型（例:
String,Integer,Boolean） - フィールドがオプションか必須か
- データタイプ名（例:
ActionsとData Typesの違い
| 項目 | Actions | Data Types |
|---|---|---|
| 定義内容 | AWSサービスで実行可能な操作やリクエスト | アクションやレスポンスに使用されるデータ構造 |
| 用途 | リソースに対する具体的な操作を実行するため | リクエストパラメータやレスポンスデータの形式を記述 |
| ドキュメントの焦点 | リクエストパラメータ、レスポンスの結果、操作の具体例 | データフィールドの型、必須/オプション、構造 |
| 例 |
CreateBucket, DescribeInstances, PutItem
|
Bucket, Instance, Tag
|
| 関連性 |
Actionsは、Data Typesを使ってリクエストやレスポンスを構成 |
Data Typesは、Actionsで利用される基本的なデータ構造を提供 |
完璧だあ。この調子で僕の仕事を奪い続けてほしい。
ドキュメントを紐解く順番
前述のBig Pictureの順番でいうと、この通りに見ていくのが系統だっていて良いと思われるが、プロにとっては必ずしもそうではないということを主張しておきたい。
まず、ユーザーガイドはボリュームがあまりにもデカすぎる。すでに「問題が発生していてそれを解決することにフォーカスする」ということを考えた場合、ユーザーガイドをゆっくり読んでサービスに対する教養を身につけている暇はないだろう。
あとAPIの仕様を捉えるという点ではAPIリファレンスは前述のようにAPI仕様のマスター情報なので時間があるときに抑えるものであることを考えるとCLIリファレンスよりも優先度が落ちる。
CLIリファレンスは「API callを最もシンプルに列挙した形態」であることを考えて、まず早期のタイミングではこれで何ができるかを押さえてしまうのが早い気がしている。
紐解く順番として順序を入れ替えたバージョンのBig Pictureは以下のようになるだろう。
S3での例ーAWSドキュメントをどう追従するか
読み方がわかったタイミングで具体的なサービスにおいてどのようにドキュメントを追従するか「S3」を例に紹介する。
サービスの公式ガイド
ざっくりどのようなサービスなのかを理解する。
✔ Amazon S3 は、業界最高水準のスケーラビリティ、データ可用性、セキュリティ、およびパフォーマンスを提供するオブジェクトストレージサービスです。
✔ データレイク、ウェブサイト、クラウドネイティブアプリケーション、バックアップ、アーカイブ、機械学習、分析など、さまざまなユースケースのあらゆる量のデータを保存および保護します。
✔ Amazon S3 は 99.999999999% (9 x 11) の耐久性を実現するように設計されており、世界中の何百万ものお客様のデータを保存しています。
完全に理解した。
CLIリファレンス
眺めてみよう。
どういうことができるかをざっくりchat GPTをかませながら解釈させてみよう。
-
コマンド概要
- Amazon S3に対するAWS CLIコマンドには、高レベル（
s3コマンド）と低レベル（s3apiコマンド）の2種類があるんだなあ。 - 高レベルの
aws s3コマンドでは、なるほどcp,ls,mb,mv,presign,rb,rm,sync,website`などを叩けるんだなあ。
- Amazon S3に対するAWS CLIコマンドには、高レベル（
-
パス引数の種類
-
LocalPath（ローカルファイルやディレクトリへのパス） -
S3Uri（S3オブジェクトやバケットのURI。形式例：s3://mybucket/mykey）
-
-
主要コマンドの使い方
-
単一ファイル操作：
cp、mv、rmは単一のローカルファイルやS3オブジェクトに対して実行される（--recursiveオプションなしの場合） -
ディレクトリ操作：
syncやlsなどはディレクトリ全体またはS3プレフィックスを操作。 -
パターンマッチング：
--excludeや--includeオプションで特定のファイル/オブジェクトをフィルタリング可能
-
単一ファイル操作：
-
フィルターの使用方法
-
*や?を使った柔軟なマッチングが可能。 - 排他的フィルタリングがデフォルト（例：
--exclude "*"→全て除外）。
-
できることがコンパクトに理解できた。上記わかりにくいと感じた場合は、こっちがわかりやすい。
APIで叩きたいことがある場合は低レベルコマンドを叩く。
APIリファレンス
IAM policyでs3:GetObject などを見たり書いたりすることがあると思う。これの詳細について書いてあるのが API Referenceである。API の各アクションごとに、インプットやアウトプットまた関連する情報が書かれている。
例えばs3:GetObjectの説明
例えばs3:ListBucketsの説明
ユーザーガイド
単純に量が多かったり、用語がわからなくて読めないみたいな感じのことが多い。やはり後回しであるが、慣れていって読めるようになるしかない。まずググって出てくるDevelopersIOあたりの平易な記事を読んで雰囲気を掴んでからユーザーガイドを読むといいとされている。
その他のドキュメント
General Reference
各サービスのエンドポイントやIPアドレス、そしてクォータなどがまとまっているもの。
Service Authorization Reference
アクションテーブルやリソースタイプテーブルについて記載がある。IAM Policy にどのように記載すれば良いか気になった場合などに確認するとよいとされている。
Terraformのproviderのドキュメント
Terraform の provider を見ると今向き合っているリソースに必要な情報が端的にまとまっていたりするので分かりやすいが、初手で読んでも分かりにくいため、あくまで補助的な役割を持つとされている。
s3:bucket に関するterraformのドキュメントは以下である。
おわりに
AWSドキュメントの追従の仕方について述べた。どのタイミングやフェーズでどのように追っていくかの所作をコンパクトに認識して目線を移していくことで脳のリソースを「課題解決」により多く割くことができるようにしていきたい。
Discussion