Ansible プレイブックを実行する関連付けの作成 - AWS Systems Manager
インストールされている依存関係についてAnsible プレイブックを実行する関連付けを作成する (コンソール)Ansible プレイブックを実行する関連付けを作成する (CLI)

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

AWS-ApplyAnsiblePlaybooks SSM ドキュメントを使用して、Ansible プレイブックを実行する State Manager の関連付けを作成できます。State Manager は AWS Systems Manager の一機能です。このドキュメントには、プレイブックを実行するための以下の利点があります。

  • 複雑なプレイブックの実行のサポート

  • GitHub と Amazon Simple Storage Service (Amazon S3) からのプレイブックのダウンロードをサポート

  • 圧縮されたプレイブック構造のサポート

  • 高度なログ記録

  • プレイブックがバンドルされているときに実行するプレイブックを指定する機能

注記

Systems Manager には、Ansible プレイブックを実行する State Manager の関連付けを作成できる、AWS-RunAnsiblePlaybook と AWS-ApplyAnsiblePlaybooks という 2 つの SSM ドキュメントが含まれています。AWS-RunAnsiblePlaybook ドキュメントは廃止されました。これは、従来の目的のために Systems Manager で引き続き使用できます。ここで説明する機能強化のため、AWS-ApplyAnsiblePlaybooks ドキュメントを使用することをお勧めします。

Ansible プレイブックを実行する関連付けは、macOS ではサポートされていません。

複雑なプレイブックの実行のサポート

AWS-ApplyAnsiblePlaybooks ドキュメントは、指定されたメインプレイブックを実行する前に、ファイル構造全体をローカルディレクトリにコピーするため、バンドルされた複雑なプレイブックをサポートします。ソースプレイブックは、Zip ファイルまたはディレクトリ構造で提供できます。Zip ファイルまたはディレクトリは、GitHub または Amazon S3 に保存できます。

GitHub からのプレイブックのダウンロードのサポート

AWS-ApplyAnsiblePlaybooks ドキュメントでは、aws:downloadContent プラグインを使用してプレイブックファイルをダウンロードします。ファイルは、単一のファイルで GitHub に保存することも、結合された一連のプレイブックファイルとして保存することもできます。GitHub からコンテンツをダウンロードするには、GitHub リポジトリに関する情報を JSON 形式で指定します。以下はその例です。

{
   "owner":"TestUser",
   "repository":"GitHubTest",
   "path":"scripts/python/test-script",
   "getOptions":"branch:master",
   "tokenInfo":"{{ssm-secure:secure-string-token}}"
}

Amazon S3 からのプレイブックのダウンロードのサポート

Ansible プレイブックは、単一の .zip ファイルまたはディレクトリ構造として Amazon S3 に保存およびダウンロードすることもできます。Amazon S3 からコンテンツをダウンロードするには、ファイルへのパスを指定します。これらはその 2 つの例です。

例 1: 特定のプレイブックファイルをダウンロードする

{
   "path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/playbook.yml"
}

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

{
   "path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/ansible/webservers/"
}
重要

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

圧縮されたプレイブック構造のサポート

AWS-ApplyAnsiblePlaybooks ドキュメントを使用すると、圧縮された .zip ファイルをダウンロードしたバンドルで実行できます。ドキュメントは、ダウンロードしたファイルに .zip 形式の圧縮ファイルが含まれているかどうかを確認します。.zip が見つかった場合、ドキュメントは自動的にファイルを解凍し、指定された Ansible 自動化を実行します。

高度なログ記録

AWS-ApplyAnsiblePlaybooks ドキュメントには、さまざまなレベルのログ記録を指定するためのオプションのパラメータが含まれています。詳細度が低い場合は -v、中程度の場合は -vv または -vvv、デバッグレベルのログ記録の場合は -vvvv を指定します。これらのオプションは、Ansible の詳細オプションに直接マッピングされます。

プレイブックがバンドルされているときに実行するプレイブックを指定する機能

AWS-ApplyAnsiblePlaybooks ドキュメントには、複数のプレイブックがバンドルされている場合に実行するプレイブックを指定するための必須パラメータが含まれています。このオプションでは、さまざまなユースケースをサポートするためにプレイブックを実行するための柔軟性が得られます。

インストールされている依存関係について

[InstallDependencies] パラメータに [True] を指定すると、Systems Manager は次の依存関係がノードにインストールされていることを確認します。

  • Ubuntu Server/Debian Server: Apt-get (パッケージ管理)、Python 3、Ansible、Unzip

  • Amazon Linux: Ansible

  • RHEL: Python 3、Ansible、Unzip

1 つまたは複数のこれらの依存関係が見つからない場合は、Systems Manager によって自動的にインストールされます。

Ansible プレイブックを実行する関連付けを作成する (コンソール)

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

Ansible プレイブックを実行する関連付けを作成するには (コンソール)

  1. AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。

  2. ナビゲーションペインで、[State Manager] を選択します。

  3. [State Manager] を選択してから、[関連付けの作成] を選択します。

  4. [名前] に、関連付けの目的を思い出すのに役立つ名前を指定します。

  5. [Document (ドキュメント)] リストで、[AWS-ApplyAnsiblePlaybooks] を選択します。

  6. [パラメータ] セクションの [ソースタイプ] リストで、[GitHub] または [S3] を選択します。

    GitHub

    [GitHub] を選択した場合は、リポジトリ情報を次の形式で指定します。

    {
   "owner":"user_name",
   "repository":"name",
   "path":"path_to_directory_or_playbook_to_download",
   "getOptions":"branch:branch_name",
   "tokenInfo":"{{(Optional)_token_information}}"
}

    S3

    [S3] を選択した場合は、パス情報を次の形式で指定します。

    {
   "path":"https://s3.amazonaws.com/path_to_directory_or_playbook_to_download"
}

  7. [依存関係のインストール] にオプションを選択します。

  8. （オプション）[プレイブックファイル] にファイル名を入力します。Zip ファイルにプレイブックが含まれている場合は、Zip ファイルへの相対パスを指定します。

  9. (オプション) [追加の変数] に、実行時に State Manager から Ansible に送信する変数を入力します。

  10. （オプション）[チェック] にオプションを選択します。

  11. （オプション）[詳細] にオプションを選択します。

  12. [Targets (ターゲット)] で、オプションを選択します。ターゲットの使用については、「State Manager 関連付けのターゲットとレート制御について」を参照してください。

  13. [Specify schedule (スケジュールの指定)] セクションで、[On schedule(スケジュールあり)] または [No schedule (スケジュールなし)] を選択します。[On Schedule (スケジュールあり)] を選択した場合は、関連付けの cron または rate スケジュールを作成するためのボタンを使用します。

  14. [詳細オプション] セクションの [Compliance severity (コンプライアンスの重要度)] で、関連付けの重要度レベルを選択します。コンプライアンスレポートには、ここで指定した重要度と共に関連付けの状態が準拠しているか準拠していないかが表示されます。詳細については、「State Manager 関連付けのコンプライアンスについて」を参照してください。

  15. [Rate control] (レート制御) セクションで、マネージドノードのフリート全体の State Manager 関連付けを実行するためのオプションを設定します。レート制御の使用については、「State Manager 関連付けのターゲットとレート制御について」を参照してください。

    [Concurrency (同時実行数)] セクションでオプションを選択します。

    • [targets (ターゲット)] を選択して、関連付けを同時に実行できるターゲットの絶対数を入力します。

    • [percentage (パーセント値)] を選択して、関連付けを同時に実行できるターゲットセットのパーセント値を入力します。

    [Error threshold (エラーのしきい値)] セクションでオプションを選択します。

    • State Manager が追加ターゲットでの関連付けの実行を停止する前に、[errors (エラー)] を選択して許可されるエラーの絶対数を入力します。

    • State Manager が追加ターゲットでの関連付けの実行を停止する前に、[percentage (パーセンテージ)] を選択して許可されるエラーの割合を入力します。

  16. (オプション) [出力オプション] で、コマンド出力をファイルに保存するには、[S3 への出力の書き込みを有効にします] ボックスをオンにします。ボックスにバケット名とプレフィックス (フォルダ) 名を入力します。

    注記

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

  17. [関連付けの作成] を選択します。

注記

タグを使用して 1 つまたは複数のターゲットノードで関連付けを作成した後、ノードからタグを削除すると、そのノードは関連付けを実行しなくなります。ノードは State Manager ドキュメントから関連付けを解除されます。

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

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

Ansible プレイブックを実行する関連付けを作成するには (CLI)

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

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

  2. タグを使ってノードをターゲットにし、Ansible プレイブックを実行する関連付けを作成する場合は、次のいずれかのコマンドを実行します。各リソースプレースホルダーの例をユーザー自身の情報に置き換えます。コマンド (A) は、ソースタイプとして GitHub を指定します。コマンド (B) は、ソースタイプとして Amazon S3 を指定します。

    (A) GitHub ソース

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"],"TimeoutSeconds":["3600"]}' \
    --association-name "name" \
    --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"], "TimeoutSeconds":["3600"]}' ^
    --association-name "name" ^
    --schedule-expression "cron_or_rate_expression"

    以下はその例です。

    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets "Key=tag:OS,Values=Linux" \
    --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
    --association-name "AnsibleAssociation" \
    --schedule-expression "cron(0 2 ? * SUN *)"

    (B) S3 ソース

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' \
    --association-name "name" \
    --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' ^
    --association-name "name" ^
    --schedule-expression "cron_or_rate_expression"

    以下はその例です。

    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets "Key=tag:OS,Values=Linux" \
    --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/amzn-s3-demo-bucket/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
    --association-name "AnsibleAssociation" \
    --schedule-expression "cron(0 2 ? * SUN *)"
    注記

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

    システムはノードで関連付けを作成し、状態を即時に適用しようとします。

  3. 作成した関連付けの最新のステータスを表示するには、次のコマンドを実行します。

    aws ssm describe-association --association-id "ID"