DevOpsを加速するAkamai CLI - CLI を使用したキャッシュの purge
こんにちは、Akamai Solutions Engineer のYuhki です。
以前から AKamai では、Akamai の製品を HTTP リクエスト経由で使用できる Web APIを提供してきましたが、一昨年からさらにそれらを使いやすくした Akamai CLI (Command Line Interface) の提供を開始しました。
Akamai CLI とは、これまで Akamai {OPEN} API で提供していたプリミティブなレベルの複数の操作を組み合わせ、まとめた形で簡単なコマンドとして実行できるようしたものです。
Akamai {OPEN} API では簡単な操作をするにもある程度のプログラミングが必用でしたが、Akamai CLI ではより簡単な手順で Akamai のサービスの機能をコマンドラインから取り扱う事ができるようになります。開発・運用局面の自動化プロセスへの Akamai サービスの取り込みがより簡単にできるようになり DevOps への取り込みも楽になっています。
コマンドですのでバイナリ形式で提供されていますが、ソースコードは、 GitHub で公開されています。
この記事では Akamai CLI のパッケージ構造、実際にインストールして purge 作業を実行するまでの具体的な作業について解説致します。
1. Akamai {OPEN} API と Akamai CLI
これまで、Akamai {OPEN} API を使用してキャッシュの purge を行う場合は、自分で、こちらの記事のようなスクリプトを書く必要がありました。
一方で、CLI を使用する場合は、https://www.example.com/test.txt というファイルのキャッシュを delete したい場合は
| C:>akamai purge delete https://www.example.com/test.txt |
と、たった一行のコマンドを実行するだけで、キャッシュの削除が完了します。
2. Akamai CLI のパッケージ構造
Akamai CLIは、CLIの基本となるベース部分(akamai コマンド) と、機能毎の追加パッケージ( purge, dns, property 等の機能別にパッケージされたコマンド群) から成り立っています。
Akamai CLIベース部分は、CLIツールとしての管理機能部分 (追加パッケージのinstall や、update / upgrade) を担当しています。
パッケージ部分は、機能別のコマンド群を提供します。
"purge" のパッケージであれば、purge 用の delete や、invalidate 等のコマンドを提供します。
"dns" のパッケージであれば、 Akamai のクラウド DNSサービスである FastDNS を操作するためのコマンド群(dns レコードの追加や zone 情報の表示等)を提供します。
Akamai CLI は、追加でパッケージを install する事で、実行できるコマンドの種類を増やしていく構造になっています。
例えば Akamai CLI を使用してキャッシュのクリアを行いたい時は、Akamai CLI のベースを導入した環境に、"purge" パッケージを追加で install します。
どのようなパッケージがあるかは、GitHubの akamai-cli のタグで Repository を検索してみて下さい。
また Akammai CLI のベース部分のパッケージと、機能毎の追加パッケージは別の言語でかかれている場合があり、追加のパッケージによっては、実行環境のインストールを必用とする場合があります。GitHub の解説を参考にするか、インストール時のエラーメッセージに追加で必用な実行環境が指示されている事があるのでご注意下さい。
3.Client と Client に紐付く Credential の作成
ここからは、Akamai CLI の "purge" パッケージを使える環境を実際に構築してみます。
Client と Client に紐付く Credential の作成
Akamai CLIは、Akamai {OPEN} API の一連の操作を使いやすいようにまとめてバイナリ化したものなので、Akamai CLIの実行権限の考え方は Akamai {OPEN} API と共通です。
そのため、このセクションで解説している「Clientの作成」と、Clientに紐付く「Credentialの作成」の手順は、CLIを使う時もAPIを使う時も共通です。
最初にACC(Akamai Control Center)から、"Client"を作成します。Client は、特定の操作権限のテンプレートのような役割をし、この Client をベースにして複数の"Credential" を発行する事ができます。Client は、Credential のテンプレートのような物なので、オブジェクト指向言語を学んだ事がある方は、Client と Credential の関係は、クラスとインスタンスのような関係だと考えるとわかり易いかもしれません。
ACCのメニューから「IDおよびアクセス」を選択します。
"New API Client for me" をクリックします。
操作を許可する契約に対してアクセス権を設定します。複数契約がある場合は契約毎にアクセス権を設定できます。
次に、Client に名前を付けます。 この例では、purge 用の権限を持った Client を作成するので「OPEN CCU / Fast Purge APIs」のラジオボタンを選択します。 (もし Property の操作や FastDNS 等の purge 以外の作業で使用する Client を作成する場合は、「General OPEN APIs」を選びます） "READ-WRITE" の権限を与えます。
さらに「Allow purge by Cache Tag」と「Allow purge by CP code」を選択して「送信」ボタンをクリックします。 (Tag による purge は、 Fast Purge API v3 から追加された、Edge-Cache-Tag レスポンス・ヘッダーに 同じラベル(Tag)を持つコンテンツを、一回のリクエストで一括 purge できる機能です。)
「送信」を押したら以下の画面になります。「New credential」をクリックします。
以下のような画面が表示されるので、表示内容をコピペするか、「Download client tokens」でテキストファイルにダウンロードします。 この情報は画面を閉じると再び表示させる事はできません。 この情報を CLI 実行時に読み込ませる事で CLI が実行できるようになります。
Client の設定画面に戻ると、今作成されたCredential が表示されているはずです。
前述したように、一つの Clientについて、複数の Credential が作成できます。 そのため、もし、ある Credential が流出してしまった時には、該当する Credential のみを "deactivate" して使えなくする事が可能です。
.edgerc ファイルの作成
筆者のテスト環境は、Windows 10 なので、ここからは Windows 用の手順になりますが、基本的な流れと考え方は mac でも Linux でも同じです。
前述の手順でダウンロードした Credential 情報を .edgerc というファイル名にして、ユーザーの Home Directory に保存します。
Windows の場合の Home Directoryは、C:\Users\<ユーザー名> のようになるはずです。もしくは、echo %HomePath% でも、そのユーザーの Home Directory が確認できます。
Akamai CLI では、各機能が "property", "dns", "purge" の様な機能別のパッケージに分かれており、各CLI パッケージは自分用の Credential を .edgerc ファイル中のタグを見て確認します。
例えば、
- property パッケージに対するタグは [papi]
- dns パッケージに対するタグは [dns]
- purge パッケージに対するタグは [ccu]
の様に CLI パッケージ毎にタグが決まっています。
purge パッケージ用の Credential であれば、[ccu]というタグが必用です。そのため、以下のような .edgerc を作成して、ユーザーの Home Directory に保存します。
| [ccu] host = akab-wdvtyngabdedemh-fhsoh24vszwvw7b3.purge.akamaiapis.net client_token = akab-allkdieadrqwsxs-smru4dftroxv2g33 client_secret = mLfVyebHv/Sc6ObadeadeadFEYdPqW3Rqh0vq0e0= access_token = akab-xjofjk4a9fwzx2szd-ri2znts53ownosh7 |
もし上記の purge 用の Credential 以外に FastDNS 用の Credential ([dns] のタグが必用）、Propertyの編集用の Credential ([papi]のタグが必用）がある場合は、以下のように .edgerc に追記できます。
| [ccu] host = akab-wdvtyngabdedemh-fhsoh24vszwvw7b3.purge.akamaiapis.net client_token = akab-allkdieadrqwsxs-smru4dftroxv2g33 client_secret = mLfVyebHv/Sc6ObadeadeadFEYdPqW3Rqh0vq0e0= access_token = akab-xjofjk4a9fwzx2szd-ri2znts53ownosh7 [dns] client_secret = 6Ekd39agdHJEXld9juqgVfXVgxzeDTvhkPn41s/DMpdyM= host = akab-rnxj66m7moaebade q-53reno6y2w43hx64.luna.akamaiapis.net access_token = akab-6xcfntaklba093dt46eal-i3kyhdc2uungn4fl client_token = akab-xdfrlyz5fadaedcq-vta46aongmc4bb4s [papi] client_secret = 6EwF7qkdeabd23gVfXVgxzeDTvhkPn41s/DMpdyM= host = akab-rnxj66m7mopewnfq-5gafero6y2w43hx64.luna.akamaiapis.net access_token = akab-6xcfnedbbkdaeeal-i3kyhdc2uungn4fl client_token = akab-xdfrlyz5feadedzcq-vta46aongmc4bb4s |
4.Akamai CLI のインストール
Akamai CLI のベース部分のインストール
Akamai CLIの最新バイナリは GitHub で公開されており、以下からダウンロードしてインストールします。
筆者のマシンは Intel Core7 の Windows 10 64bit ですので、"akamai-1.1.3-windows386.exe" が対応するバイナリになります。これをダウンロードして実行します。
ンストーラーを起動すると以下のように複数のインストール箇所を選択肢として提示してきます。
ここにリストされる情報は PATH 環境変数を読み込んできているので、もしこの中に自分のインストールしたいディレクトリが無い場合は、ここで一旦、インストーラーを終了し、インストール先のディレクトリを作成し、PATH 環境変数に追加した後、再度インストーラーを起動させます。
このパスを選ぶ作業だけで、インストールは終了です。コマンドラインを起動して"akamai" と入力してリターンが返ってくる事を確認してみてください。もしコマンドが見つからない場合は、コマンドまでのパスが通っているか確認してみてください。
| C:\>akamai Usage: akamai [global flags] command [command flags] [arguments...] <省略> Copyright © Akamai Technologies, Inc C:\> |
CLI の purge パッケージのインストール
上記まででインストールしたのは、Akamai CLI のベースのパッケージだけなので、自分の使用したい追加パッケージをインストールします。ここでは、purge をCLI で実行できるようにしたいので、 "purge" パッケージをインストールします。パッケージのインストールは、CLI から行う事ができます。
| C:\>akamai install purge Attempting to fetch command from https://github.com/akamai/cli-purge.git...... [OK] Installing...... [WARN] Unable to locate package manager (dep) in PATH Binary command(s) found, would you like to download and install it? (Y/n): Y Downloading binary...... [OK] <省略> See "akamai.exe help [command]" for details. C:\> |
ここでは、"purge" パッケージをインストールしましたが、他のパッケージも "akamai install <パッケージ名>" で簡単にインストールできます。
例えば "property" パッケージをインストールするには以下のようにコマンドを実行します。
| C:\>akamai install property |
5. Akamai CLI での Purge 実行
いよいよ CLI で purge を実行してみます。
CLI を実行する前に、ユーザーの Home Directory にコマンドの実行に必用な Credential が格納されている .edgerc ファイルがある事を確認して下さい。もし、.edgerc 内に適切な Credential が存在しないとコマンドの実行に失敗します。
使用できるコマンドの種類の確認
"purge" パッケージにどのようなコマンドが用意されているかは、"list"コマンドで確認できます。
| c:\>akamai purge list Commands: invalidate delete list help Displays help information c:\> |
invalidate、 delete、list、help が使用できる事がわかります。list と help は、purge パッケージの 管理コマンドなので、実質的に invalidate と delete が purge 用のコマンドです。
help コマンドは、それほど記載が詳細では無い場合いがあるので、GitHub の Readme.md も合わせて参照する事をおすすめします。
キャッシュの削除(delete)
https://www.example.com/test.txt というURLのキャッシュを削除 (delete) するには、以下を実行します。
| C:\>akamai purge delete https://www.example.com/test.txt Purging...... [OK] Purged 1 objects (ETA: 5 seconds) C:\> |
キャッシュの無効化 (invalidate)
Akamai では、キャッシュを完全に削除 (delete) するのでは無く、無効化する事を invalidte と呼んでいます。
invalidate は、現在のキャッシュを無効化（期限切れ）にします。
キャッシュが期限切れになるため、次にコンテンツにアクセスがあった時、Akamai Edge Server は、オリジンに最新のキャッシュを確認に行きます。もし、オリジン側でキャッシュされているコンテンツの変更が無い場合は、現在のキャッシュをそのまま使用します。そのため、delete と違ってキャッシュ更新が無かった場合は、オリジンとEdge Server間のトラフィックを抑える事ができます。
キャッシュの無効化については、幾つかのオプションを試して見ます。
https://www.example.com/test.txt のキャッシュを無効化 (invalidate) するには、以下を実行します。
| c:\>akamai purge invalidate https://www.yuhkih.work/test.txt Purging...... [OK] Purged 1 objects (ETA: 5 seconds) c:\> |
CP Code を使用した無効化 (invalidate)
"CP Code" は、Akamai の配信設定(キャッシュ設定)内で使用される、トラフィックを測定するための管理番号です。一般的には一つの配信設定に対して一つの CP Code をアサインする事が多いため、CP Code に対する purge を行う事で、ある配信設定が管理するキャッシュ全体を purge する事ができます。
CP Code "816636" に紐付いたキャッシュを無効化するには以下のようにします。
| C:\>akamai purge invalidate --cpcode 816636 Purging...... [OK] Purged 1 objects (ETA: 5 seconds) C:\> |
tag を使用した無効化 (invalidate)
"Edge-Cache-Tag" という HTTPヘッダー内に値(Tag) をセットする事で、 "Edge-Cache-Tag" に同じ値を持つキャッシュを一斉に purge する事ができます。
例として、/blog/20190401/ のような日付毎のディレクトリにコンテンツが格納されるブログを考えます。
Nginx を使用して、nginx.conf 内の location ディレクティブで以下のような指定をします。
| location ~ /blog/([0-9]*)/ { add_header 'Edge-Cache-Tag' $1; add_header 'X-Edge-Cache-Tag-At-Origin' $1; # for debug } |
先頭の~(チルダ) は、case sensitive (大文字と小文字を区別)である事を意味します。
その後の設定では、 /blog/(0～9の数字の任意の繰り返し)/ のパスにマッチし、( ) 括弧でくくられた数字の繰り返し部分を、$1 で Edge-Cache-Tag にセットしています。
Nginx にこの設定をして http://www.example.com/blog/20190401/index.html のようなパスにアクセスすると、browser の debug ツールで /blog/20190401/ 配下のコンテンツには以下のようなヘッダーが付いてくる事が確認できます。
実際に Tag purge に必用な、"Edge-Cache-Tag" ヘッダーは、Akamai Edge Server からクライアントまで届かない仕様になっています。
そのため直接は確認できませんが、別途 debug 用につけた "X-Edge-Cache-Tag-At-Oring" ヘッダーに 20190401 というタグ値が付いているので、このコンテンツは、Edge-Cache-Tag: 20190401 というヘッダー：タグ値 が付いた状態で、Akamai Edge Server にキャッシュされている事がわかります。
この時、以下のようにすると、Edge-Cache-Tag 値に 20190401 という値を持った /blog/20190401/ 配下のコンテンツのキャッシュを一斉に無効化できます。
| C:\>akamai purge invalidate --tag 20190401 Purging...... [OK] Purged 1 objects (ETA: 5 seconds) C:> |
尚、CP Code purgeも、tag purge も、delete でも使用可能です。一方で、CP Code purge も tag purge も、広範囲にキャッシュを消す可能性があり、オリジンへの急激な負荷に繋がる場合があるので、ここでは invalidate の例として取り上げています。
運用時に必用になるコマンド
パッケージは、時々アップデートされています。パッケージのアップデートを確認するには "update"コマンドを使用します。
| c:\>akamai update purge Attempting to update "purge" command...... [OK] command "purge" already up-to-date c:\> |
6. まとめ
Akamai CLI は、一般的な単純な作業を効率化するために作成されており、複雑な作業は Akamai OPEN API と組み合わせて使用する必用がありますが、Akamai CLI のみの使用でも適用作業によっては日々のオペレーションを自動化し、運用効率を上げる事ができます。
API と CLI 共々、現在進行形で拡張を続けているので、今後にご期待下さい。
7. 参考リンク
