翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
CodePipeline でカスタムアクションを作成および追加する
AWS CodePipeline には、自動リリースプロセスのリソースのビルド、テスト、デプロイの設定に役立つアクションが多数含まれています。社内で開発したビルドプロセスやテストスイート等、デフォルトアクションに含まれていないアクティビティがリリースプロセスに含まれる場合、その目的のためにカスタムアクションを作成し、パイプラインに含めることができます。を使用して AWS CLI 、 AWS アカウントに関連付けられたパイプラインにカスタムアクションを作成できます。
次のアクションカテゴリのカスタム AWS CodePipeline アクションを作成できます。
-
項目を構築または変換するカスタムビルドアクション
-
項目を 1 つ以上のサーバー、ウェブサイトまたはリポジトリにデプロイするカスタムデプロイアクション
-
自動テストを設定して実行するカスタムテストアクション
-
関数を実行するカスタム呼び出しアクション
カスタムアクションを作成する際、このカスタムアクションのジョブリクエストの CodePipeline をポーリングするジョブワーカーを作成し、ジョブを実行してステータス結果を CodePipeline に返す必要があります。 このジョブワーカーは、CodePipeline のパブリックエンドポイントにアクセスできる限り、どのコンピュータまたはリソースにあっても構いません。簡単にアクセスおよびセキュリティを管理するために、ジョブワーカーを Amazon EC2 インスタンスにホストすることを考慮してください。
次の図では、カスタム構築アクションを含むパイプラインの高レベルビューを示します:
パイプラインにステージの一部としてカスタムアクションが含まれる場合、パイプラインはジョブリクエストを作成します。カスタムジョブワーカーはそのリクエストを検出し、そのジョブを実行します (この例では、サードパーティー構築ソフトウェアを使用するカスタムプロセス)。アクションが完了すると、ジョブワーカーは成功結果または失敗結果を返します。成功結果を受け取ると、パイプラインはリビジョンと次のアクションのアーティファクトを提供します。失敗が返された場合、パイプラインはリビジョンを次のアクションに渡しません。
注記
これらの手順では、すでにCodePipeline の使用開始のステップを完了していることを前提としています。
カスタムアクションを作成する
を使用してカスタムアクションを作成するには AWS CLI
-
テキストエディタを開き、アクションカテゴリ、アクションプロバイダー、およびカスタムアクションで必要な設定を含む、カスタムアクションの JSON ファイルを作成します。例えば、1 つのプロパティのみを必要とするカスタムビルドアクションを作成する場合、JSON ファイルは次のようになります。
{ "category": "Build", "provider": "My-Build-Provider-Name", "version": "1", "settings": { "entityUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/", "executionUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/lastSuccessfulBuild/{ExternalExecutionId}/" }, "configurationProperties": [{ "name": "ProjectName", "required": true, "key": true, "secret": false, "queryable": false, "description": "The name of the build project must be provided when this action is added to the pipeline.", "type": "String" }], "inputArtifactDetails": { "maximumCount":integer, "minimumCount":integer}, "outputArtifactDetails": { "maximumCount":integer, "minimumCount":integer}, "tags": [{ "key": "Project", "value": "ProjectA" }] }この例では、カスタムアクションで
ProjectタグキーとProjectA値を含めることで、カスタムアクションにタグ付けを追加します。CodePipeline の リソースのタグ付けの詳細については、リソースのタグ付け を参照してください。2 つのプロパティ
entityUrlTemplateおよびexecutionUrlTemplateが JSON ファイルに含まれています。設定プロパティが必須で、かつシークレットではない限り、{Config:形式に従って、URL テンプレート内のカスタムアクションの設定プロパティで名前を参照できます。例えば、上の例では、name}entityUrlTemplateの値は設定プロパティProjectNameを参照します。-
entityUrlTemplate: アクションのサービスプロバイダーに関する情報を提供する静的リンク。この例では、ビルドシステムには、各ビルドプロジェクトへの静的リンクが含まれます。リンク形式は、ビルドプロバイダー (または、テストなど別のアクションタイプを作成する場合はその他のサービスプロバイダー) に応じて変わります。このリンク形式を指定し、カスタムアクションが追加されたときに、ユーザーはこのリンクを選択してブラウザを開き、ビルドプロジェクト (またはテスト環境) の詳細を提供するウェブサイト上のページに移動できるようにする必要があります。 -
executionUrlTemplate: アクションの現在の実行または最新の実行に関する情報で更新される動的リンク。カスタムジョブワーカーがジョブのステータス (成功、失敗、進行中など) を更新するときに、リンクを完了するために使用されるexternalExecutionIdも提供されます。このリンクを使用して、アクションの実行に関する詳細を提供できます。
例えば、パイプラインでアクションを表示すると、次の 2 つのリンクが表示されます。
この静的リンクは、カスタムアクションを追加し、entityUrlTemplateでアドレスを指した後で表示されます (カスタムアクションを作成するときに指定します)。
この動的なリンクは、アクションを実行し、executionUrlTemplateでアドレスを指すたびに更新されます (カスタムアクションを作成するときに指定します)。これらのリンクタイプ、および
RevisionURLTemplateとThirdPartyURLの詳細については、「 CodePipeline API リファレンス」の「ActionTypeSettings」および「CreateCustomActionType」を参照してください。アクション構造の要件とアクションの作成方法の詳細については、「CodePipeline パイプライン構造リファレンス」を参照してください。 -
-
JSON ファイルを保存し、簡単に覚えることができる名前 (例えば
MyCustomActionなど) を付けます。 -
AWS CLIをインストールしたコンピュータで、ターミナルセッション (Linux、OS X、Unix) またはコマンドプロンプト (Windows) を開きます。
-
AWS CLI を使用して aws codepipeline create-custom-action-type コマンドを実行し、先ほど作成した JSON ファイルの名前を指定します。
例えば、ビルドカスタムアクションを作成するには以下のようにします。
重要
ファイル名の前に必ず
file://を含めてください。このコマンドでは必須です。aws codepipeline create-custom-action-type --cli-input-json file://MyCustomAction.json -
このコマンドは、作成したカスタムアクションの構造全体、および追加された
JobListアクション設定プロパティを返します。パイプラインにカスタムアクションを追加するときは、JobListを使用して、プロバイダーからのプロジェクトのうちジョブをポーリングできるものを指定できます。これを設定しない場合、カスタムジョブワーカーがジョブをポーリングするときに、使用可能なすべてのジョブが返されます。例えば、前のコマンドは、次のような構造を返します。
{ "actionType": { "inputArtifactDetails": { "maximumCount": 1, "minimumCount": 1 }, "actionConfigurationProperties": [ { "secret": false, "required": true, "name": "ProjectName", "key": true, "description": "The name of the build project must be provided when this action is added to the pipeline." } ], "outputArtifactDetails": { "maximumCount": 0, "minimumCount": 0 }, "id": { "category": "Build", "owner": "Custom", "version": "1", "provider": "My-Build-Provider-Name" }, "settings": { "entityUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/", "executionUrlTemplate": "https://my-build-instance/job/mybuildjob/lastSuccessfulBuild/{ExternalExecutionId}/" } } }注記
create-custom-action-type コマンドの出力の一部として、
idセクションには"owner": "Custom"が含まれます。CodePipeline は、カスタムアクションタイプの所有者として自動的にCustomを割り当てます。create-custom-action-type コマンドまたは update-pipeline コマンドを使用する場合、この値を割り当てまたは変更することはできません。
カスタムアクションのジョブワーカーを作成する
カスタムアクションは、カスタムアクションのジョブリクエストに CodePipeline をポーリングし、ジョブを実行して、 CodePipeline にステータス結果を返すジョブワーカーが必要です。 ジョブワーカーは、 CodePipeline のパブリックエンドポイントにアクセスできる限り、どのコンピュータまたはリソースにあっても構いません。
ジョブワーカーを設計する方法は複数あります。次のセクションでは、 CodePipeline のカスタムジョブワーカーを開発するための、実践的なガイダンスを提供します。
ジョブワーカー用にアクセス許可管理戦略を選択して設定する
CodePipeline でカスタムアクションのカスタムジョブワーカーを開発するには、ユーザーやアクセス権限管理を統合するための戦略が必要になります。
最も簡単な戦略は、 IAM インスタンスロールで Amazon EC2 インスタンスを作成することでカスタムジョブワーカーに必要なインフラストラクチャを追加することです。これは、統合に必要なリソースを簡単にスケールアップすることを可能にします。との組み込み統合を使用して AWS 、カスタムジョブワーカーと CodePipeline 間のやり取りを簡素化できます。
Amazon EC2 インスタンスをセットアップする
-
Amazon EC2 の詳細を参照し、統合に適しているかどうかを判断します。詳細については、「 Amazon EC2 - 仮想サーバーのホスティング
」を参照してください。 -
Amazon EC2 インスタンスの作成を開始します。詳細については、「Amazon EC2 Linux インスタンスの開始方法」を参照してください。
他に考慮すべき戦略は、ID フェデレーションと IAM を使用した既存の ID プロバイダーシステムおよびリソースとの統合です。この戦略は、お客様がすでに企業 ID プロバイダーを持っているか、ウェブ ID プロバイダーを使用するユーザーをサポートできるよう設定されている場合に、特に便利です。ID フェデレーションを使用すると、IAM ユーザーを作成または管理することなく、CodePipeline などの AWS リソースへの安全なアクセスを許可できます。パスワードのセキュリティ要件や認証情報の更新に機能やポリシーを活用できます。サンプルアプリケーションをお客様自身の設計のテンプレートとして使用できます。
ID フェデレーションをセットアップするには
-
IAM 認証フェデレーションの詳細について学習します。詳細については、「フェデレーションの管理
」を参照してください。 -
「一時的なアクセス権を付与するシナリオ」の例を参照して、カスタムアクションのニーズに最適な一時アクセスのシナリオを確認します。
-
インフラストラクチャに関連する ID フェデレーションのコード例を確認します。例えば、以下の参照先をご覧ください。
-
ID フェデレーションの設定を開始します。詳細については、「IAM ユーザーガイド」の「ID プロバイダーとフェデレーション」を参照してください。
カスタムアクションとジョブワーカーを実行するときに、使用する次のいずれかを AWS アカウント で作成します。
ユーザーが の AWS 外部で を操作する場合は、プログラムによるアクセスが必要です AWS Management Console。プログラムによるアクセスを許可する方法は、 がアクセスするユーザーのタイプによって異なります AWS。
ユーザーにプログラマチックアクセス権を付与するには、以下のいずれかのオプションを選択します。
| プログラマチックアクセス権を必要とするユーザー | 目的 | 方法 |
|---|---|---|
|
ワークフォースアイデンティティ (IAM アイデンティティセンターで管理されているユーザー) |
一時的な認証情報を使用して AWS CLI、、 AWS SDKs、または AWS APIs。 |
使用するインターフェイスの指示に従ってください。
|
| IAM | 一時的な認証情報を使用して AWS CLI、、 AWS SDKs、または AWS APIs。 | 「IAM ユーザーガイド」の「 AWS リソースでの一時的な認証情報の使用」の手順に従います。 |
| IAM | (非推奨) 長期認証情報を使用して AWS CLI、、 AWS SDKs、または AWS APIs。 |
使用するインターフェイスの指示に従ってください。
|
次は、カスタムジョブワーカーで使用するために作成する可能性があるポリシーの例です。このポリシーは例に過ぎず、そのまま提供されています。
注記
AWSCodePipelineCustomActionAccess マネージドポリシーの使用を検討してください。
カスタムアクションのジョブワーカーを開発する
アクセス権限管理戦略を選択した後、ジョブワーカーが CodePipeline とどう相互作用するかを考慮した方が良いでしょう。次の概要図は、ビルドプロセスのカスタムアクションおよびジョブワーカーのワークフローを示します。
-
ジョブワーカーは、
PollForJobsを使用するジョブに CodePipeline をポーリングします。 -
パイプラインがソースステージでの変更によってトリガーされる際 (例えば、開発者が変更をコミットした際)、自動リリースプロセスが開始します。プロセスは、カスタムアクションが設定されたステージまで継続します。このステージのアクションに達すると、 CodePipeline はジョブをキューにいれます。このジョブは、ジョブワーカーがステータスを取得するために
PollForJobsを再度呼び出すと、表示されます。PollForJobsからジョブ詳細を取得し、ジョブワーカーに渡します。 -
ジョブワーカーが
AcknowledgeJobCodePipeline にジョブの確認応答を送信します。CodePipeline は、ジョブワーカーがジョブを継続中であることを示す確認 (InProgress) を返します。または、複数のジョブワーカーがジョブをポーリングしていて、別のジョブワーカーがジョブを登録済みである場合は、エラーInvalidNonceExceptionが返されます。確認InProgressの後、 CodePipeline は結果が返されるまで待機します。 -
ジョブワーカーはリビジョンでカスタムアクションを開始し、その後にアクションが実行されます。他のアクションとともに、カスタムアクションは結果をジョブワーカーに返します。ビルドカスタムアクションの例では、アクションが Amazon S3 バケットからアーティファクトを引き出し、構築して、構築されたアーティファクトを Amazon S3 バケットに正常にプッシュします。
-
そのアクションが実行されている間、ジョブワーカーは、継続トークン (ジョブワーカーによって生成されたジョブの状態のシリアル化、例えば JSON 形式のビルド識別子や Amazon S3 オブジェクトキー) を使用して
PutJobSuccessResultを呼び出すことができ、さらにExternalExecutionId情報（executionUrlTemplateのリンクの入力に使用される) も呼び出すことができます。これは、進行中に特定のアクション詳細への有効なリンクとともにパイプラインのコンソールビューを更新します。必要ではありませんが、ユーザーがカスタムアクションの実行中にそのステータスを確認することを可能にするため、ベストプラクティスです。PutJobSuccessResultが呼び出されると、ジョブは完了したと見なされます。継続トークンが含まれる新しいジョブが CodePipeline に作成されます。このジョブは、ジョブワーカーが再度PollForJobsを呼び出すと表示されます。この新しいジョブは、アクションの状態を確認するために使用でき、継続トークンを伴って返すか、アクションが完了すると、継続トークンを伴わずに返します。注記
ジョブワーカーがカスタムアクションの処理をすべて行っている場合、ジョブワーカーの処理を少なくとも 2 つのステップに分割することを考慮した方が良いでしょう。最初のステップでは、アクションの詳細ページを確立します。詳細ページを作成すると、ジョブワーカーの状態をシリアル化し、サイズ制限の対象である継続トークンとして返します。 (AWS CodePipeline のクォータを参照してください)。例えば、継続トークンとして使用する文字列に、アクションの状態を書き込むことができます。ジョブワーカーの処理の 2 番目のステップ (およびその後のステップ) が、アクションの実際の作業を実行します。最終ステップは、最終ステップの継続トークンなしで成功または失敗を CodePipeline に返します。
継続トークンの使用方法の詳細については、
PutJobSuccessResultの仕様のCodePipeline API を参照してください。 -
カスタムアクションが完了すると、ジョブワーカーは 2 つの内 1 つの API を呼び出すことでカスタムアクションの結果を CodePipeline に返します:
-
カスタムアクションの実行が成功したことを示す、継続トークンなしの
PutJobSuccessResult。 -
PutJobFailureResultのカスタムアクションが成功しなかったことを示す
結果によって、パイプラインは次のアクションに継続 (成功) するか、停止 (失敗) します。
-
カスタムジョブワーカーのアーキテクチャと例
高レベルワークフローを綿密に計画した後、ジョブワーカーを作成できます。最終的にはカスタムアクションの仕様がジョブワーカーに必要なものを決定しますが、カスタムアクションのジョブワーカーの多くは以下の機能を含みます:
-
PollForJobsを使用して CodePipeline からジョブをポーリングする。 -
ジョブを確認し、 CodePipeline に
AcknowledgeJob、PutJobSuccessResultおよびPutJobFailureResultを使用して結果を返す。 -
パイプラインの Amazon S3 バケットからアーティファクトを取得する、またはアーティファクトを配置する。Amazon S3 バケットからアーティファクトをダウンロードするには、署名バージョン 4 の署名 (Sig V4) を使用する Amazon S3 クライアントを作成する必要があります。Sig V4 は に必要です AWS KMS。
Amazon S3 バケットにアーティファクトをアップロードするには、さらに Amazon S3 リクエスト
PutObjectが暗号化を使用するよう設定する必要があります。現在、Encryption. AWS KMS uses では AWS Key Management Service (AWS KMS) のみがサポートされています AWS KMS keys。 AWS マネージドキー またはカスタマーマネージドキーを使用してアーティファクトをアップロードするかどうかを知るには、カスタムジョブワーカーがジョブデータを調べ、暗号化キープロパティを確認する必要があります。プロパティが設定されている場合は、設定時にそのカスタマーマネージドキー ID を使用する必要があります AWS KMS。key プロパティが null の場合は、 AWS マネージドキーを使用します。CodePipeline は、特に設定 AWS マネージドキー されていない限り、 を使用します。Java または .NET で AWS KMS パラメータを作成する方法を示す例については、「SDK を使用した Amazon S3 AWS Key Management Service での の指定 AWS SDKs」を参照してください。CodePipeline 用の Amazon S3 バケットの詳細については、CodePipeline の概念 を参照してください。
カスタムジョブワーカーのさらに複雑な例が GitHub から入手可能です。このサンプルは、オープンソースコードであり、現状のまま提供されています。
-
CodePipeline のサンプルジョブワーカー
: GitHub リポジトリからサンプルをダウンロードしてください。
パイプラインにカスタムアクションを追加する
ジョブワーカーを作成したら、新しいアクションを作成してパイプラインの作成ウィザードの使用時に選択するか、既存のパイプラインを編集してカスタムアクションを追加するか AWS CLI、、、 SDKs、または APIs を使用して、カスタムアクションをパイプラインに追加できます。
注記
ビルドまたはデプロイアクションであれば、パイプラインの作成ウィザードでカスタムアクションを含むパイプラインを作成できます。カスタムアクションがテスト カテゴリーにある場合は、既存のパイプラインを編集して追加する必要があります。
既存のパイプラインにカスタムアクションを追加する (CLI)
を使用して AWS CLI 、既存のパイプラインにカスタムアクションを追加できます。
-
ターミナルセッション (Linux、macOSまたはUnix) またはコマンドプロンプト (Windows) を開き、get-pipeline コマンドを実行して、編集するパイプライン構造を JSON ファイルにコピーします。例えば、
MyFirstPipelineという名前のパイプラインの場合は、以下のコマンドを入力します。aws codepipeline get-pipeline --nameMyFirstPipeline>pipeline.jsonこのコマンドは何も返しませんが、作成したファイルは、コマンドを実行したディレクトリにあります。
-
任意のテキストエディタで JSON ファイルを開き、ファイルの構造を変更して、カスタムアクションを既存のステージに追加します。
注記
そのステージでアクションを別のアクションと並行して実行する場合は、そのアクションと同じ
runOrder値を割り当てます。例えば、Build という名前のステージを追加し、パイプラインの構造を変更してそのステージにビルドカスタムアクションを追加する場合は次のように JSON を変更して、デプロイステージの前にビルドステージを追加します。
, { "name": "MyBuildStage", "actions": [ { "inputArtifacts": [ { "name": "MyApp" } ], "name": "MyBuildCustomAction", "actionTypeId": { "category": "Build", "owner": "Custom", "version": "1", "provider": "My-Build-Provider-Name" }, "outputArtifacts": [ { "name": "MyBuiltApp" } ], "configuration": { "ProjectName": "MyBuildProject" }, "runOrder": 1 } ] }, { "name": "Staging", "actions": [ { "inputArtifacts": [ { "name": "MyBuiltApp" } ], "name": "Deploy-CodeDeploy-Application", "actionTypeId": { "category": "Deploy", "owner": "AWS", "version": "1", "provider": "CodeDeploy" }, "outputArtifacts": [], "configuration": { "ApplicationName": "CodePipelineDemoApplication", "DeploymentGroupName": "CodePipelineDemoFleet" }, "runOrder": 1 } ] } -
変更を適用するには、以下のように、パイプライン JSON ファイルを指定して、 update-pipeline コマンドを実行します。
重要
ファイル名の前に必ず
file://を含めてください。このコマンドでは必須です。aws codepipeline update-pipeline --cli-input-json file://pipeline.jsonこのコマンドは、編集したパイプラインの構造全体を返します。
-
CodePipeline コンソールを開き、編集したパイプラインの名前を選択します。
そのパイプラインには、行った変更が示されます。ソース場所を次に変更すると、修正した構造のパイプラインによりそのリビジョンが実行されます。
