使用開始 recipe の実行時におけるターゲットへの JSON 属性の適用 Git をクックブックのソースとして使用するクックブックのソースとして GitHub を使用するクックブックのソースとして HTTP を使用する Amazon S3 をクックブックソースとして使用する Chef recipe を実行する関連付けを作成する (コンソール)Chef recipe を実行する関連付けの作成 (CLI)Chef リソースコンプライアンスの詳細の表示

Chef recipe を実行する関連付けの作成

AWS-ApplyChefRecipes SSM ドキュメントを使用して、Chef recipe を実行する State Manager の関連付けを作成できます。State Manager は AWS Systems Manager の一機能です。AWS-ApplyChefRecipes SSM ドキュメントを使用して Linux ベースのSystems Manager マネージドノードをターゲットにすることができます。このドキュメントには、Chef recipe の実行に関して次の利点があります。

Chef の複数のリリース (Chef 11 から Chef 18) をサポートします。
ターゲットノードに Chef クライアントソフトウェアを自動的にインストールします。
オプションで、ターゲットノードの Systems Manager コンプライアンスチェックを実行し、コンプライアンスチェックの結果を Amazon Simple Storage Service (Amazon S3) バケットに保存します。
ドキュメントの 1 回の実行で複数のクックブックと recipe を実行します。
オプションで、recipe を why-run モードで実行して、どの recipe がターゲットノードに変更を加えるかを、変更せずに確認します。
オプションで、カスタム JSON 属性を chef-client 実行に適用します。
オプションで、指定した場所に保存されているソースファイルからカスタム JSON 属性を適用します。

Git、GitHub、HTTP、または Amazon S3 バケットを、AWS-ApplyChefRecipes ドキュメントで指定する Chef のクックブックと recipe のダウンロードソースとして使用できます。

注記

Chef recipe を実行する関連付けは、macOS ではサポートされていません。

使用開始

AWS-ApplyChefRecipes ドキュメントを作成する前に、Chef クックブックとクックブックリポジトリを準備します。使用する Chef クックブックがまだない場合は、AWS に用意されているテスト用の HelloWorld クックブックを使用して開始できます。デフォルトでは、AWS-ApplyChefRecipes ドキュメントは既にこのクックブックを指しています。クックブックは、次のディレクトリ構造と同様にセットアップする必要があります。以下の例では、jenkins および nginx は Chef ウェブサイトの Chef Supermarket で入手可能な Chef クックブックの例です。

AWS は、Chef Supermarket ウェブサイトのクックブックを正式にサポートすることはできませんが、その多くは AWS-ApplyChefRecipes ドキュメントで使用できます。コミュニティクックブックをテストするときに確認する基準の例を次に示します。

クックブックは、ターゲットとする Systems Manager マネージドノードの Linux ベースのオペレーティングシステムをサポートしている必要があります。
クックブックは、使用する Chef クライアントバージョン (Chef 11 から Chef 18) に対して有効である必要があります。
クックブックは Chef Infra Client と互換性があるため、Chef サーバーは必要ありません。

Chef.io ウェブサイトにアクセスできることを確認し、Systems Manager ドキュメント (SSM ドキュメント) の実行時に実行リストに指定したクックブックをインストールできるようにします。ネストされた cookbooks フォルダはサポートされていますが、必須ではありません。クックブックはルートレベルに直接保存できます。


<Top-level directory, or the top level of the archive file (ZIP or tgz or tar.gz)>
    └── cookbooks (optional level)
        ├── jenkins
        │   ├── metadata.rb
        │   └── recipes
        └── nginx
            ├── metadata.rb
            └── recipes

重要

Chef recipe を実行する State Manager の関連付けを作成する前に注意すべき点は、[Chef クライアントのバージョン] の値を None に設定していないと、ドキュメントを実行したときに、Chef クライアントソフトウェアが Systems Manager マネージドノードにインストールされることです。このオペレーションでは、Chef のインストールスクリプトを使用して、ユーザーに代わって Chef コンポーネントをインストールします。AWS-ApplyChefRecipes ドキュメントを実行する前に、Chef ソフトウェアの使用に適用されるライセンス条項など、適用される法的要件を企業が準拠していることを確認してください。詳細については、Chef のウェブサイトを参照してください。

Systems Manager は、コンプライアンスレポートを S3 バケットや Systems Manager コンソールに配信したり、Systems Manager API コマンドに応答してコンプライアンス結果を利用できるようにしたりできます。Systems Manager コンプライアンスレポートを実行するには、Systems Manager マネージドノードにアタッチされたインスタンスプロファイルに、S3 バケットへ書き込むためのアクセス許可が必要です。インスタンスプロファイルには、Systems Manager PutComplianceItem API を使用するためのアクセス許可が必要です。Systems Manager のコンプライアンスの詳細については、「AWS Systems Manager のコンプライアンス」を参照してください。

ドキュメント実行のログ記録

State Manager の関連付けを使用してSystems Manager ドキュメント (SSM ドキュメント) を実行する場合、ドキュメント実行の出力を選択するように関連付けを設定し、その出力を Amazon S3 または Amazon CloudWatch Logs (CloudWatch Logs) に送信できます。関連付けの実行が終了したときのトラブルシューティングを容易にするために、コマンド出力を Amazon S3 バケットまたは CloudWatch Logs に書き込むように関連付けが設定されていることを確認します。詳細については、「Systems Manager の関連付けの使用」を参照してください。

recipe の実行時におけるターゲットへの JSON 属性の適用

Chef クライアントの JSON 属性を指定して、関連付けの実行中にターゲットノードに適用できます。関連付けを設定する際には、Raw JSON を指定することも、Amazon S3 に保存されている JSON ファイルへのパスを指定することもできます。

recipe 自体を変更せずに recipe の実行方法をカスタマイズする場合は、JSON 属性を使用します。次に例を示します。

少数の属性の上書き

カスタム JSON を使用すると、軽微な違いに対応するために recipe の複数のバージョンを維持する必要がなくなります。
変数の値の指定

カスタム JSON を使用して、実行ごとに変更される可能性のある値を指定します。例えば、Chef クックブックで支払いを受け付けるサードパーティアプリケーションを設定する場合、カスタム JSON を使用してエンドポイントの支払い URL を指定できます。

Raw JSON での属性の指定

Chef recipe のカスタム JSON 属性を指定するために使用できる形式の例を次に示します。


{"filepath":"/tmp/example.txt", "content":"Hello, World!"}

JSON ファイルへのパスの指定

Chef recipe のカスタム JSON 属性へのパスを指定するために使用できる形式の例を次に示します。


{"sourceType":"s3", "sourceInfo":"someS3URL1"}, {"sourceType":"s3", "sourceInfo":"someS3URL2"}

Git をクックブックのソースとして使用する

AWS-ApplyChefRecipes ドキュメントは、aws:downloadContent プラグインを使用して Chef クックブックをダウンロードします。Git からコンテンツをダウンロードするには、次の例で示すように、Git リポジトリに関する情報を JSON 形式で指定します。各 example-resource-placeholder を、ユーザー自身の情報に置き換えます。


{
   "repository":"GitCookbookRepository",
   "privateSSHKey":"{{ssm-secure:ssh-key-secure-string-parameter}}",
   "skipHostKeyChecking":"false",
   "getOptions":"branch:refs/head/main",
   "username":"{{ssm-secure:username-secure-string-parameter}}",
   "password":"{{ssm-secure:password-secure-string-parameter}}"
}

クックブックのソースとして GitHub を使用する

AWS-ApplyChefRecipes ドキュメントは、aws:downloadContent プラグインを使用してクックブックをダウンロードします。GitHub からコンテンツをダウンロードするには、次の例で示すように、GitHub リポジトリに関する情報を JSON 形式で指定します。各 example-resource-placeholder を、ユーザー自身の情報に置き換えます。


{
   "owner":"TestUser",
   "repository":"GitHubCookbookRepository",
   "path":"cookbooks/HelloWorld",
   "getOptions":"branch:refs/head/main",
   "tokenInfo":"{{ssm-secure:token-secure-string-parameter}}"
}

クックブックのソースとして HTTP を使用する

Chef クックブックは、単一の .zip や tar.gz ファイル、あるいはディレクトリ構造としてカスタム HTTP の場所に保存できます。HTTP からコンテンツをダウンロードするには、次の例のように、ファイルまたはディレクトリへのパスを JSON 形式で指定します。各 example-resource-placeholder を、ユーザー自身の情報に置き換えます。


{
   "url":"https://my.website.com/chef-cookbooks/HelloWorld.zip",
   "allowInsecureDownload":"false",
   "authMethod":"Basic",
   "username":"{{ssm-secure:username-secure-string-parameter}}",
   "password":"{{ssm-secure:password-secure-string-parameter}}"
}

Amazon S3 をクックブックソースとして使用する

Chef クックブックは、単一の .zip や tar.gz ファイル、あるいはディレクトリ構造として Amazon S3 に保存およびダウンロードすることもできます。Amazon S3 からコンテンツをダウンロードするには、次の例のように、ファイルへのパスを JSON 形式で指定します。各 example-resource-placeholder を、ユーザー自身の情報に置き換えます。

例 1: 特定のクックブックをダウンロードする


{
   "path":"https://s3.amazonaws.com/chef-cookbooks/HelloWorld.zip"
}

例 2: ディレクトリの内容をダウンロードする


{
   "path":"https://s3.amazonaws.com/chef-cookbooks-test/HelloWorld"
}

重要

Amazon S3 を指定した場合、マネージドノードの AWS Identity and Access Management (IAM) インスタンスプロファイルを AmazonS3ReadOnlyAccess ポリシーで設定する必要があります。詳細については、「Systems Manager に必要なインスタンスのアクセス許可を設定する」を参照してください。

Chef recipe を実行する関連付けを作成する (コンソール)

以下の手順では、Systems Manager コンソールを使用し、AWS-ApplyChefRecipes ドキュメントを使って Chef クックブックを実行する State Manager の関連付けを作成する方法について説明します。

AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。
ナビゲーションペインで、[State Manager] を選択します。
[State Manager] を選択してから、[関連付けの作成] を選択します。
[Name (名前)] に、関連付けの目的を思い出すのに役立つ名前を入力します。
[Document (ドキュメント)] リストで、[AWS-ApplyChefRecipes] を選択します。
[パラメータ] の [ソースタイプ] で、Git、GitHub、HTTP、または S3 のいずれかを選択します。
[ソース情報] で、ステップ 6 で選択した [ソースタイプ] に適切な形式を使用してクックブックのソース情報を入力します。詳細については、以下の各トピックを参照してください。
[Run list] (リストの実行) で、実行する recipe を次の形式で一覧表示します。各 recipe はカンマで区切ります。コンマの後にスペースを入れないでください。各 example-resource-placeholder を、ユーザー自身の情報に置き換えます。
```
recipe[cookbook-name1::recipe-name],recipe[cookbook-name2::recipe-name]
```
(オプション) Chef クライアントからターゲットノードに渡すカスタム JSON 属性を指定します。
1. [JSON 属性のコンテンツ] で、Chef クライアントからターゲットノードに渡す属性を追加します。
2. [JSON 属性のソース] で、Chef クライアントからターゲットノードに渡す属性へのパスを追加します。
詳細については、「recipe の実行時におけるターゲットへの JSON 属性の適用」を参照してください。
[Chef クライアントバージョン] には、Chef のバージョンを指定します。有効な値は、11～18、または None です。11 から 18 まで (両端の値を含む) の数値を指定すると、Systems Manager はターゲットノードに正しい Chef クライアントバージョンをインストールします。None を指定すると、Systems Manager はドキュメントの recipe を実行する前にターゲットノードに Chef クライアントをインストールしません。
(オプション) [Chef クライアント引数] には、使用している Chef のバージョンでサポートされている追加の引数を指定します。サポートされている引数の詳細については、Chef クライアントを実行しているノードで chef-client -h を実行してください。
(オプション) recipe を実行する場合に、ターゲットノードを実際に変更せずに、ターゲットノードに対して行われる変更を表示するには、[Why-run] をオンにします。
[Compliance severity (コンプライアンスの重要度)] で、レポートする Systems Manager コンプライアンスの結果の重要度を選択します。コンプライアンスレポートには、ここで指定した重要度と共に関連付けの状態が準拠しているか準拠していないかが表示されます。コンプライアンスレポートは、[Compliance report bucket (コンプライアンスレポートバケット)] パラメータの値として指定する S3 バケットに保存されます (ステップ 14)。コンプライアンスの詳細については、このガイドの「コンプライアンスの詳細について」を参照してください。

コンプライアンススキャンでは、Chef recipe で指定された設定とノードリソース間のずれを測定します。有効な値は Critical、High、Medium、Low、Informational、Unspecified、None です。コンプライアンスレポートをスキップするには、None を選択します。
[コンプライアンスタイプ] で、結果をレポートするコンプライアンスタイプを指定します。有効な値は、State Manager の関連付けについては Association、または Custom:custom-type です。デフォルト値は Custom:Chef です。
[コンプライアンスレポートバケット] に、リソース設定やコンプライアンスの結果など、このドキュメントで実行されるすべての Chef 実行に関する情報を保存する S3 バケットの名前を入力します。
[Rate control] (レート制御) で、マネージドノードのフリート全体に State Manager の関連付けを実行するためのオプションを設定します。レート制御の使用については、「State Manager 関連付けのターゲットとレート制御について」を参照してください。

[Concurrency (同時実行)] で、次のいずれかのオプションを選択します。
- [targets (ターゲット)] を選択して、関連付けを同時に実行できるターゲットの絶対数を入力します。
- [percentage (パーセント値)] を選択して、関連付けを同時に実行できるターゲットセットのパーセント値を入力します。
[Error threshold (エラーのしきい値)] で、オプションを選択します。
- State Manager が追加ターゲットでの関連付けの実行を停止する前に、[errors (エラー)] を選択して許可されるエラーの絶対数を入力します。
- State Manager が追加ターゲットでの関連付けの実行を停止する前に、[percentage (パーセンテージ)] を選択して許可されるエラーの割合を入力します。
(オプション) [出力オプション] で、コマンド出力をファイルに保存するには、[S3 への出力の書き込みを有効にします] ボックスをオンにします。ボックスにバケット名とプレフィックス (フォルダ) 名を入力します。

注記
S3 バケットにデータを書き込む機能を許可する S3 アクセス許可は、このタスクを実行する IAM ユーザーのものではなく、マネージドノードに割り当てられたインスタンスプロファイルのものです。詳細については、「Systems Manager に必要なインスタンスのアクセス許可を設定する」または「ハイブリッド環境に IAM サービスロールを作成する」を参照してください。さらに、指定された S3 バケットが別の AWS アカウントにある場合は、マネージドノードに関連付けられたインスタンスプロファイルまたは IAM サービスロールに、そのバケットへの書き込みに必要なアクセス許可があることを確認してください。
[関連付けの作成] を選択します。

Chef recipe を実行する関連付けの作成 (CLI)

以下の手順では、AWS Command Line Interface (AWS CLI) を使用して、AWS-ApplyChefRecipes ドキュメントを使用し、Chef クックブックを実行する State Manager の関連付けを作成する方法について説明します。

まだ AWS Command Line Interface (AWS CLI) をインストールして設定していない場合は、インストールして設定します。

詳細については、「AWS CLI の最新バージョンをインストールまたは更新します。」を参照してください。

次のコマンドのいずれかを実行して、指定されたタグを持つターゲットノードで Chef クックブックを実行する関連付けを作成します。クックブックのソースタイプとオペレーティングシステムに適したコマンドを使用します。各 example-resource-placeholder を、ユーザー自身の情報に置き換えます。

Git ソース

Linux & macOS


aws ssm create-association --name "AWS-ApplyChefRecipes" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" \
    --schedule-expression "cron-or-rate-expression"

Windows


aws ssm create-association --name "AWS-ApplyChefRecipes" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' ^
    --association-name "name" ^
    --schedule-expression "cron-or-rate-expression"

GitHub ソース

以下はその例です。

HTTP ソース

Linux & macOS


aws ssm create-association --name "AWS-ApplyChefRecipes" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" \
    --schedule-expression "cron-or-rate-expression"

Windows


aws ssm create-association --name "AWS-ApplyChefRecipes" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" ^
    --schedule-expression "cron-or-rate-expression"

Amazon S3 ソース

以下はその例です。

システムは関連付けを作成し、指定した cron または rate 式によって妨げられない限り、システムはターゲットノードで関連付けを実行します。

注記

State Manager の関連付けは､すべての cron および rate 式をサポートしていません。関連付けの cron および rate 式の作成の詳細については、「リファレンス: Systems Manager の Cron 式および rate 式」を参照してください｡

作成した関連付けのステータスを表示するには、次のコマンドを実行します。
```
aws ssm describe-association --association-id "ID"
```

Chef リソースコンプライアンスの詳細の表示

Systems Manager は、AWS-ApplyChefRecipes ドキュメントの実行時に指定した Amazon S3 の [コンプライアンスレポートバケット] 値で、Chef で管理されているリソースに関するコンプライアンス情報をキャプチャします。S3 バケット内の Chef リソース障害に関する情報を検索するには、時間がかかる場合があります。代わりに、この情報を [Systems Manager Compliance] ページに表示できます。

Systems Manager コンプライアンススキャンを使用すると、最新の Chef 実行で作成またはチェックされたマネージドノード上のリソースに関する情報を収集できます。リソースには、ファイル、ディレクトリ、systemd サービス、yum パッケージ、テンプレート化されたファイル、gem パッケージ、依存クックブックなどが含まれます。

[コンプライアンスリソースの概要] セクションには、失敗したリソース数が表示されます。次の例では、[ComplianceType] は [Custom:Chef] であり、1 つのリソースは準拠していません。

注記

Custom:Chef は、AWS-ApplyChefRecipes ドキュメントのデフォルトの ComplianceType 値です。この値はカスタマイズすることができます。

[コンプライアンス] ページの [コンプライアンスリソースの概要] セクションのカウントの表示。

[Details overview for resources] (リソースの詳細の概要) セクションには、準拠していない AWS リソースに関する情報が表示されます。このセクションには、コンプライアンスが実行された Chef リソースタイプ、問題の重要度、コンプライアンスのステータス、および詳細情報へのリンク (該当する場合) も含まれます。

[出力の表示] には、詳細ステータスの最後の 4,000 文字が表示されます。Systems Manager は、最初の要素としてまず例外を表示した後、詳細メッセージを検索して、4,000 文字のクォータに達するまで表示します。このプロセスでは、例外がスローされる前に出力されたログメッセージが表示されます。表示されるメッセージは、トラブルシューティングに最もよく関連しています。

コンプライアンス情報の表示方法については、「AWS Systems Manager のコンプライアンス」を参照してください。

重要

State Manager の関連付けが失敗すると、コンプライアンスデータはレポートされません。例えば、Systems Manager が、ノードにアクセス許可が付与されていない S3 バケットから Chef クックブックをダウンロードしようとすると、関連付けは失敗し、Systems Manager でコンプライアンスデータはレポートされません。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Ansible プレイブックを実行する関連付けの作成

チュートリアル: AWS CLI で SSM Agent を自動的に更新する