CodePipeline でカスタムアクションを作成および追加する - AWS CodePipeline

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CodePipeline でカスタムアクションを作成および追加する

AWS CodePipeline には、自動リリースプロセスのビルド、テスト、およびデプロイリソースの設定に役立つ複数のアクションが含まれています。社内で開発したビルドプロセスやテストスイート等、デフォルトアクションに含まれていないアクティビティがリリースプロセスに含まれる場合、その目的のためにカスタムアクションを作成し、パイプラインに含めることができます。AWS CLI を使って、AWS アカウントに関連付けられたパイプラインにカスタムアクションを作成できます。

以下の AWS CodePipeline アクションカテゴリについては、カスタムアクションを作成できます。

  • 項目を構築または変換するカスタムビルドアクション

  • 項目を 1 つ以上のサーバー、ウェブサイトまたはリポジトリにデプロイするカスタムデプロイアクション

  • 自動テストを設定して実行するカスタムテストアクション

  • 関数を実行するカスタム呼び出しアクション

カスタムアクションを作成する際、このカスタムアクションのジョブリクエストの CodePipeline をポーリングするジョブワーカーを作成し、ジョブを実行してステータス結果を CodePipeline に返す必要があります。​ このジョブワーカーは、CodePipeline のパブリックエンドポイントにアクセスできる限り、どのコンピュータまたはリソースにあっても構いません。簡単にアクセスおよびセキュリティを管理するために、ジョブワーカーを Amazon EC2 インスタンスにホストすることを考慮してください。

次の図では、カスタム構築アクションを含むパイプラインの高レベルビューを示します:


            カスタム構築アクションを含むパイプラインの高レベルビュー。

パイプラインにステージの一部としてカスタムアクションが含まれる場合、パイプラインはジョブリクエストを作成します。カスタムジョブワーカーはそのリクエストを検出し、そのジョブを実行します (この例では、サードパーティ構築ソフトウェアを使用するカスタムプロセス)。アクションが完了すると、ジョブワーカーは成功結果または失敗結果を返します。成功結果を受け取ると、パイプラインはリビジョンと次のアクションのアーティファクトを提供します。失敗が返された場合、パイプラインはリビジョンを次のアクションに渡しません。

注記

これらの手順では、すでにCodePipeline の使用開始のステップを完了していることを前提としています。

カスタムアクションを作成する

AWS CLI を使用してカスタムアクションを作成するには

  1. テキストエディタを開き、アクションカテゴリ、アクションプロバイダー、およびカスタムアクションで必要な設定を含む、カスタムアクションの 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:name} 形式に従って、URL テンプレート内のカスタムアクションの設定プロパティで名前を参照できます。例えば、上の例では、entityUrlTemplate の値は設定プロパティ ProjectName を参照します。

    • entityUrlTemplate: アクションのサービスプロバイダーに関する情報を提供する静的リンク。この例では、ビルドシステムには、各ビルドプロジェクトへの静的リンクが含まれます。リンク形式は、ビルドプロバイダー (または、テストなど別のアクションタイプを作成する場合はその他のサービスプロバイダー) に応じて変わります。このリンク形式を指定し、カスタムアクションが追加されたときに、ユーザーはこのリンクを選択してブラウザを開き、ビルドプロジェクト (またはテスト環境) の詳細を提供するウェブサイト上のページに移動できるようにする必要があります。

    • executionUrlTemplate: アクションの現在の実行または最新の実行に関する情報で更新される動的リンク。カスタムジョブワーカーがジョブのステータス (成功、失敗、進行中など) を更新するときに、リンクを完了するために使用される externalExecutionId も提供されます。このリンクを使用して、アクションの実行に関する詳細を提供できます。

    例えば、パイプラインでアクションを表示すると、次の 2 つのリンクが表示されます。

    
                        CodePipeline コンソールのリンクを使用して、パイプラインの実行に関する詳細情報を参照できます。

    この静的リンクは、カスタムアクションを追加し、entityUrlTemplate でアドレスを指した後で表示されます (カスタムアクションを作成するときに指定します)。

    この動的なリンクは、アクションを実行し、executionUrlTemplate でアドレスを指すたびに更新されます (カスタムアクションを作成するときに指定します)。

    これらのリンクタイプ、および RevisionURLTemplateThirdPartyURL の詳細については、「 CodePipeline API リファレンス」の「ActionTypeSettings」および「CreateCustomActionType」を参照してください。アクション構造の要件とアクションの作成方法の詳細については、「CodePipeline パイプライン構造リファレンス」を参照してください。

  2. JSON ファイルを保存し、簡単に覚えることができる名前 (例えばMyCustomAction など) を付けます。

  3. AWS CLI をインストールしたコンピュータで、ターミナルセッション (Linux、OS X、Unix) またはコマンドプロンプト (Windows) を開きます。

  4. AWS CLI を使用して、aws codepipeline create-custom-action-type コマンドを実行して、先ほど作成した JSON ファイルの名前を指定します。

    例えば、ビルドカスタムアクションを作成するには以下のようにします。

    重要

    ファイル名の前に必ず file:// を含めてください。このコマンドでは必須です。

    aws codepipeline create-custom-action-type --cli-input-json file://MyCustomAction.json
  5. このコマンドは、作成したカスタムアクションの構造全体、および追加された 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 インスタンスをセットアップする

  1. Amazon EC2 の詳細を参照し、統合に適しているかどうかを判断します。詳細については、「 Amazon EC2 - 仮想サーバーのホスティング」を参照してください。

  2. Amazon EC2 インスタンスの作成を開始します。詳細については、「Amazon EC2 Linux インスタンスの開始方法」を参照してください。

他に考慮すべき戦略は、ID フェデレーションと IAM を使用した既存の ID プロバイダーシステムおよびリソースとの統合です。この戦略は、お客様がすでに企業 ID プロバイダーを持っているか、ウェブ ID プロバイダーを使用するユーザーをサポートできるよう設定されている場合に、特に便利です。ID フェデレーションは、 IAM ユーザーを作成または管理することなく、 CodePipeline を含めた AWS リソースへの安全なアクセスを可能とします。パスワードのセキュリティ要件や認証情報の更新に機能やポリシーを活用できます。サンプルアプリケーションをお客様自身の設計のテンプレートとして使用できます。

ID フェデレーションをセットアップするには

  1. IAM 認証フェデレーションの詳細について学習します。詳細については、「フェデレーションの管理」を参照してください。

  2. 一時的なアクセス権を付与するシナリオ」の例を参照して、カスタムアクションのニーズに最適な一時アクセスのシナリオを確認します。

  3. インフラストラクチャに関連する ID フェデレーションのコード例を確認します。例えば、以下の参照先をご覧ください。

  4. ID フェデレーションの設定を開始します。詳細については、「IAM ユーザーガイド」の「ID プロバイダーとフェデレーション」を参照してください。

考慮すべき 3 つ目の戦略は、カスタムアクションおよびジョブワーカーを実行する際に AWS アカウントの下で使用する IAM​ ユーザーの作成です。

IAM ユーザーを設定するには

  1. IAM のベストプラクティスとユースケースの詳細については、「IAM ベストプラクティスとユースケース」を参照してください。

  2. AWS アカウント内でのIAM ユーザーの作成」のステップに従って、IAM ユーザーの作成を開始します。

次は、カスタムジョブワーカーで使用するために作成する可能性があるポリシーの例です。このポリシーは例に過ぎず、そのまま提供されています。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codepipeline:PollForJobs", "codepipeline:AcknowledgeJob", "codepipeline:GetJobDetails", "codepipeline:PutJobSuccessResult", "codepipeline:PutJobFailureResult" ], "Resource": [ "arn:aws:codepipeline:us-east-2::actionType:custom/Build/MyBuildProject/1/" ] } ] }
注記

ユーザーには AWSCodePipelineCustomActionAccess に管理ポリシーの使用を考慮してください。

カスタムアクションのジョブワーカーを開発する

アクセス権限管理戦略を選択した後、ジョブワーカーが CodePipeline とどう相互作用するかを考慮した方が良いでしょう。次の概要図は、ビルドプロセスのカスタムアクションおよびジョブワーカーのワークフローを示します。


                    ビルドプロセスのカスタムアクションおよびジョブワーカーのワークフロー。
  1. ジョブワーカーは、PollForJobs を使用するジョブに CodePipeline をポーリングします。

  2. パイプラインがソースステージでの変更によってトリガーされる際 (例えば、開発者が変更をコミットした際)、自動リリースプロセスが開始します。プロセスは、カスタムアクションが設定されたステージまで継続します。このステージのアクションに達すると、 CodePipeline はジョブをキューにいれます。このジョブは、ジョブワーカーがステータスを取得するために PollForJobs を再度呼び出すと、表示されます。PollForJobs からジョブ詳細を取得し、ジョブワーカーに渡します。

  3. ジョブワーカーが AcknowledgeJob CodePipeline にジョブの確認応答を送信します。CodePipeline は、ジョブワーカーがジョブを継続中であることを示す確認 (InProgress) を返します。または、複数のジョブワーカーがジョブをポーリングしていて、別のジョブワーカーがジョブを登録済みである場合は、エラー InvalidNonceException が返されます。確認 InProgress の後、 CodePipeline は結果が返されるまで待機します。

  4. ジョブワーカーはリビジョンでカスタムアクションを開始し、その後にアクションが実行されます。他のアクションとともに、カスタムアクションは結果をジョブワーカーに返します。ビルドカスタムアクションの例では、アクションが Amazon S3 バケットからアーティファクトを引き出し、構築して、構築されたアーティファクトを Amazon S3 バケットに正常にプッシュします。

  5. そのアクションが実行されている間、ジョブワーカーは、継続トークン (ジョブワーカーによって生成されたジョブの状態のシリアル化、例えば JSON 形式のビルド識別子や Amazon S3 オブジェクトキー) を使用して PutJobSuccessResult を呼び出すことができ、さらに ExternalExecutionId 情報(executionUrlTemplate のリンクの入力に使用される) も呼び出すことができます。これは、進行中に特定のアクション詳細への有効なリンクとともにパイプラインのコンソールビューを更新します。必要ではありませんが、ユーザーがカスタムアクションの実行中にそのステータスを確認することを可能にするため、ベストプラクティスです。

    PutJobSuccessResult が呼び出されると、ジョブは完了したと見なされます。継続トークンが含まれる新しいジョブが CodePipeline に作成されます。このジョブは、ジョブワーカーが再度 PollForJobs を呼び出すと表示されます。この新しいジョブは、アクションの状態を確認するために使用でき、継続トークンを伴って返すか、アクションが完了すると、継続トークンを伴わずに返します。

    注記

    ジョブワーカーがカスタムアクションの処理をすべて行っている場合、ジョブワーカーの処理を少なくとも 2 つのステップに分割することを考慮した方が良いでしょう。最初のステップでは、アクションの詳細ページを確立します。詳細ページを作成すると、ジョブワーカーの状態をシリアル化し、サイズ制限の対象である継続トークンとして返します。 (AWS の CodePipeline 中のクォータを参照してください)。例えば、継続トークンとして使用する文字列に、アクションの状態を書き込むことができます。ジョブワーカーの処理の 2 番目のステップ (およびその後のステップ) が、アクションの実際の作業を実行します。最終ステップは、最終ステップの継続トークンなしで成功または失敗を CodePipeline に返します。

    継続トークンの使用方法の詳細については、 PutJobSuccessResult の仕様のCodePipeline API を参照してください。

  6. カスタムアクションが完了すると、ジョブワーカーは 2 つの内 1 つの API を呼び出すことでカスタムアクションの結果を CodePipeline に返します:

    • カスタムアクションの実行が成功したことを示す、継続トークンなしの PutJobSuccessResult

    • PutJobFailureResult のカスタムアクションが成功しなかったことを示す

    結果によって、パイプラインは次のアクションに継続 (成功) するか、停止 (失敗) します。

カスタムジョブワーカーのアーキテクチャと例

高レベルワークフローを綿密に計画した後、ジョブワーカーを作成できます。最終的にはカスタムアクションの仕様がジョブワーカーに必要なものを決定しますが、カスタムアクションのジョブワーカーの多くは以下の機能を含みます:

  • PollForJobs を使用して CodePipeline からジョブをポーリングする。

  • ジョブを確認し、 CodePipeline に AcknowledgeJobPutJobSuccessResult および PutJobFailureResultを使用して結果を返す。

  • パイプラインの Amazon S3 バケットからアーティファクトを取得する、またはアーティファクトを配置する。Amazon S3 バケットからアーティファクトをダウンロードするには、署名バージョン 4 の署名 (Sig V4) を使用する Amazon S3 クライアントを作成する必要があります。AWS KMS には Sig V4 が必要です。

    Amazon S3 バケットにアーティファクトをアップロードするには、さらに Amazon S3 リクエスト PutObject が暗号化を使用するよう設定する必要があります。現在 AWS キー管理サービス(AWS KMS)のみが暗号化でsupportされています。 AWS KMS は AWS KMS keys を使用します。使用するかどうかを知るためにAWS マネージドキーアーティファクトをアップロードするために、カスタマー管理型のキーの場合、ジョブのワーカーはジョブのデータをチェックし暗号化キープロパティ。プロパティが設定されている場合、構成時にそのカスタマー管理型のキー ID を使用する必要があります。AWS KMS。key プロパティが null の場合は、AWS マネージドキー を使用します。特に設定されていない限り、CodePipeline は AWS マネージドキー を使用します。

    Java または .NET で AWS KMS パラメータの作成する方法の例については、Amazon S3 の特定の AWS Key Management Service でAWSSDKsを使用している箇所を参照してください。CodePipeline 用の Amazon S3 バケットの詳細については、CodePipeline の概念 を参照してください。

カスタムジョブワーカーのさらに複雑な例が GitHub から入手可能です。このサンプルは、オープンソースコードであり、現状のまま提供されています。

パイプラインにカスタムアクションを追加する

ジョブワーカーを入手した後、カスタムアクションをパイプラインに追加できます。追加するには、[パイプラインの作成] ウィザードを使用し、新しいパイプラインを作成して選択するか、既存のパイプラインを編集してカスタムアクションを追加します。または 、AWS CLI 、SDK、API を使用します。

注記

ビルドまたはデプロイアクションであれば、パイプラインの作成ウィザードでカスタムアクションを含むパイプラインを作成できます。カスタムアクションがテスト カテゴリーにある場合は、既存のパイプラインを編集して追加する必要があります。

パイプラインにカスタムアクションを追加する (コンソール)

CodePipeline コンソールを使用してカスタムアクションでパイプラインを作成するには、CodePipeline でパイプラインを作成します。 のステップに従い、必要な数だけテストしたいステージからカスタムアクションを選択します。CodePipeline コンソールを使用して既存のパイプラインにカスタムアクションを追加するには、 CodePipeline でパイプラインを編集する のステップに従い、パイプラインの 1 つ以上のステージにカスタムアクションを追加します。

既存のパイプラインにカスタムアクションを追加する (CLI)

AWS CLI を使用して既存のパイプラインにカスタムアクション追加します。

  1. ターミナルセッション (Linux、macOSまたはUnix) またはコマンドプロンプト (Windows) を開き、get-pipeline コマンドを実行して、編集するパイプライン構造を JSON ファイルにコピーします。例えば、MyFirstPipeline という名前のパイプラインの場合は、以下のコマンドを入力します。

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

    このコマンドは何も返しませんが、作成したファイルは、コマンドを実行したディレクトリにあります。

  2. 任意のテキストエディタで 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 } ] } ] }
  3. 変更を適用するには、以下のように、パイプライン JSON ファイルを指定して、 update-pipeline コマンドを実行します。

    重要

    ファイル名の前に必ず file:// を含めてください。このコマンドでは必須です。

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json

    このコマンドは、編集したパイプラインの構造全体を返します。

  4. CodePipeline コンソールを開き、編集したパイプラインの名前を選択します。

    そのパイプラインには、行った変更が示されます。ソース場所を次に変更すると、修正した構造のパイプラインによりそのリビジョンが実行されます。