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

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

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

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

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

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

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

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

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

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

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


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

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

注記

これらの手順では、すでにコードパイプラインの使用のステップを完了していることを前提としています。

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

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 でアドレスを指すたびに更新されます (カスタムアクションを作成するときに指定します)。

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

  2. JSON ファイルを保存し、簡単に覚えることができる名前 (Myカスタムアクション.json)。

  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カスタムアクションタイプの所有者としての 1 つです。create-custom-action-type コマンドまたは update-pipeline コマンドを使用する場合、この値を割り当てまたは変更することはできません。

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

カスタムアクションは、CodePipeline にカスタムアクションのジョブリクエストの CodePipeline をポーリングし、ジョブを実行して、ステータス結果を CodePipeline に返す必要があります。ジョブワーカーは、CodePipeline のパブリックエンドポイントにアクセスできる限り、どのコンピュータまたはリソースにあってもかまいません。

ジョブワーカーを設計する方法は複数あります。次のセクションでは、CodePipeline のカスタムジョブワーカーを開発するための、実践的なガイダンスを提供します。

ジョブワーカー用にアクセス許可管理戦略を選択して設定する

CodePipeline でカスタムアクションのカスタムジョブワーカーを開発するには、ユーザーやアクセス権限管理を統合するための戦略が必要になります。

最も簡単な戦略は、IAM インスタンスロールで Amazon EC2 インスタンスを作成することでカスタムジョブワーカーに必要なインフラストラクチャを追加することです。これは、統合に必要なリソースを簡単にスケールアップすることを可能にします。組み込み統合とAWSカスタムジョブワーカーと CodePipeline の間の相互作用を簡素化できます。

Amazon EC2 インスタンスをセットアップするには

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

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

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

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

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

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

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

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

考慮すべき 3 つ目の戦略は、AWSアカウントを使用して、カスタムアクションとジョブワーカーを実行するときに使用します。

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

  1. IAM のベストプラクティスとユースケースの詳細については、IAM のベストプラクティスとユースケース

  2. IAM ユーザーの作成を開始するには、での IAM ユーザーの作成AWSアカウント

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

{ "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. ジョブワーカーは CodePipeline をPollForJobs

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

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

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

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

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

    注記

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

    継続トークンの使用方法の詳細については、PutJobSuccessResultCodePipeline API リファレンス

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

    • PutJobSuccessResult継続トークンなしで、これはカスタムアクションが正常に実行されたことを示す

    • PutJobFailureResultカスタムアクションが正常に実行されなかったことを示す、

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

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

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

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

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

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

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

    を作成する方法を示す例については、AWS KMSパラメータの詳細については、指定するAWS Key Management ServiceAmazon S3 のAWSSDK。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 コンソールを開き、編集したパイプラインの名前を選択します。

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