デプロイの前後にフックを実行する

このドキュメントでは、デプロイ前またはデプロイ後に任意のプログラムまたはオペレーションを実行する方法について説明します。

デプロイ前のアクションまたはデプロイ後のアクション、あるいはその両方を対象としたアクションを実行するように、Cloud Deploy と Skaffold を構成できます。これらのプログラムは、「フック」と呼ばれます。 デプロイ前フックとデプロイ後フックは、ロールアウトでデプロイ前とデプロイ後のジョブとして実行されます。

各フックは、指定した Cloud Deploy 実行環境で実行されるように構成できますが、Google Kubernetes Engine にデプロイする場合は、アプリケーションをデプロイする GKE クラスタで実行されるよう構成できます。

デプロイフックはべき等と見なされます。特定のアクションが複数回実行された場合、追加の効果はありません。

デプロイフックの仕組み

以下では、デプロイフックを構成する手順と、そのフックを実行するための Skaffold と Cloud Deploy のプロセスについて説明します。

  1. 特定のリリースに使用する skaffold.yaml には、フックの実行に使用するコンテナ イメージまたはコンテナを識別する customActions と、各コンテナで実行する特定のコマンドまたはスクリプトが含まれるように構成します。

  2. デリバリー パイプラインの進行状況の 1 つ以上のステージでフックを構成します。各ステージは、skaffold.yaml で構成した customActions の 1 つを参照します。

  3. ロールアウトのデプロイジョブの実行の前に、Skaffold は、skaffold.yaml に構成された、パイプライン進行の predeploy スタンザで参照される任意のコマンドを実行します。

    predeploy フックは常にフェーズの最初のジョブとして実行されます。

  4. ロールアウトのデプロイジョブが実行されると、Cloud Deploy は、skaffold.yaml に構成され、パイプライン進行の postdeploy スタンザで参照される任意のコマンドを実行します。

デプロイフックは、デフォルトの Cloud Deploy 実行環境または指定された代替実行環境で実行されます。GKE と GKE Enterprise へのデプロイでは、アプリケーションがデプロイされている同じクラスタでフックを実行することもできます。

カナリア デプロイでのデプロイフックの使用

カナリア デプロイのデプロイフックを構成する場合は、いくつかの点に注意してください。

  • デリバリー パイプライン ステージでは、フックの構成（predeploy と postdeploy）は、strategy.standard ではなく strategy.canary.canaryDeploymentまたは strategy.canary.customCanaryDeployment.phaseConfigs の下にあります。

  • 自動カナリアの場合、predeploy フックは最初のフェーズのみでデプロイの前に実行され、postdeploy フックは最後のフェーズでデプロイ後（安定）にのみ実行されます。

Skaffold でアクションを構成する

skaffold.yaml ファイルでは、customActions スタンザが 1 つ以上の customActions スタンザを取得し、以下のように構成されます。

customActions
- name: ACTION_NAME
  containers:
  - name: CONTAINER_NAME
    image: IMAGE
    command: [COMMANDS_TO_RUN]
    args: [LIST_OF_ARGS]

この customerActions スタンザでは:

  • ACTION_NAME

    このアクションの名前。この名前は任意ですが、この skaffold.yaml 内で一意である必要があります。これは、デリバリー パイプライン ステージで定義されたデプロイ前とデプロイ後のアクションから参照される名前です。

  • CONTAINER_NAME

    特定のコンテナの名前。この名前には任意の名前を付けることができますが、この skaffold.yaml 内で一意にする必要があります。

  • IMAGE

    コマンドを実行するコンテナ イメージの名前。

  • COMMANDS_TO_RUN

    そのコンテナで実行するエントリポイントのリスト。通常、ここで指定する "/bin/sh" はシェルを呼び出すコマンドであり、そのシェルで実行するコマンドを引数に含めます。

  • LIST_OF_ARGS

    コマンドに指定する引数のリスト。これはカンマ区切りのリストで、各引数は引用符で囲まれます。COMMAND_TO_RUN が "/bin/sh" の場合、ここでの引数の 1 つは "-c" になり、別の引数は呼び出したシェルで実行するコマンドの全体です。

    次に例を示します。

    command: ["/bin/sh"]
args: ["-c", `echo "This command ran!"`]

Skaffold のカスタム アクションの詳細については、Skaffold のドキュメントをご覧ください。

アクションを参照するようにパイプラインを構成する

デプロイフックの構成を完了するには、skaffold.yaml ファイルで定義したカスタム アクションを参照するようにデリバリー パイプラインを構成します。デプロイ前とデプロイ後のアクションは、パイプラインで進行中の 1 つ以上の特定のステージで構成されます。

standard デプロイ戦略を使用する場合に、パイプライン ステージでデプロイ前とデプロイ後のフックを構成する方法は以下のとおりです。

serialPipeline:
  stages:
  - targetId: hooks-staging
    profiles: []
    strategy:
      standard:
        predeploy:
          actions: ["PREDEPLOY-ACTION"]
        postdeploy:
          actions: ["POSTDEPLOY-ACTION"]

この yaml では:

  • PREDEPLOY_ACTION

    デプロイ前に実行するカスタム アクションを定義するために skaffold.yaml で使用した ACTION_NAME と同じです。

  • POSTDEPLOY_ACTION

    デプロイ後に実行するカスタム アクションを定義するために skaffold.yaml で使用した ACTION_NAME と同じです。

predeploy と postdeploy に複数のアクションをカンマで区切って指定できます。複数のアクションを指定すると、指定された順序で順番に実行されます。ジョブ（デプロイ前またはデプロイ後）は、失敗した最初のアクションで失敗し、残りのアクションは実行されません。

デフォルトでは、複数のコンテナを実行している場合に並列にジョブが失敗すると、両方のコンテナが停止します。この動作は、Skaffold カスタム アクション失敗戦略を使用して構成できます。

アプリケーション クラスタでフックを実行する

デフォルトでは、デプロイフックは Cloud Deploy 実行環境で実行されます。また、Skaffold を構成して、アプリケーションが実行されている同じクラスタでこれらのカスタム アクションを実行することもできます。skaffold.yaml でカスタム アクションを構成し、パイプライン ステージでアクションを有効にすると、そのアクションは対象のクラスタで自動的に実行されます。

この機能は、GKE と GKE Enterprise へのデプロイでのみ使用できます。Cloud Run では使用できません。Cloud Run へのデプロイについては、Cloud Deploy 実行環境でのみフックを実行できます。

クラスタでフックを実行するには、skaffold.yaml 構成ファイルの executionMode.kubernetesCluster スタンザを、特定のカスタム アクションの customActions スタンザ内に含めます。

customActions
- name: ACTION_NAME
  containers:
  - name: CONTAINER_NAME
    image: IMAGE
    command: [COMMANDS_TO_RUN]
    args: [LIST_OF_ARGS]
  executionMode:
    kubernetesCluster: {}

次に、アプリケーション クラスタでフックコンテナを呼び出す executionMode を含む customActions スタンザの例を示します。

customActions:
- name: predeploy-action
  containers:
  - name: predeploy-echo
    image: ubuntu
    command: ["/bin/sh"]
    args: ["-c", 'echo "this is a predeploy action"' ]
  executionMode:
    kubernetesCluster: {}

executionMode スタンザの使用は任意です。省略すると、Skaffold は Cloud Deploy 実行環境でカスタム アクション コンテナを実行します。

使用可能な環境変数

Cloud Deploy では、フックに使用できる 実行環境で、次の環境変数を指定し、入力します。

  • ANTHOS_MEMBERSHIP

    タイプが ANTHOS のターゲットの場合、Anthos メンバーシップの完全なリソース名。

  • CLOUD_RUN_LOCATION

    RUN タイプのターゲットに対して、Cloud Run サービスがデプロイされているリージョン。

  • CLOUD_RUN_PROJECT

    タイプが RUN のターゲットの場合、Cloud Run サービスが作成されたプロジェクト。

  • CLOUD_RUN_SERVICE

    タイプが RUN のターゲットの場合、デプロイされた Cloud Run サービスの名前。

  • CLOUD_RUN_SERVICE_URLS

    タイプが RUN のターゲットの場合、エンドユーザーがサービスへのアクセスに使用する 1 つまたは複数の URL（カンマ区切りのリスト）。これは、サービスの Cloud Run サービスの詳細（Google Cloud コンソール）で確認できます。

  • CLOUD_RUN_REVISION

    タイプが RUN のターゲットの場合、Cloud Run サービスの特定のリビジョン。

  • GKE_CLUSTER

    タイプが GKE のターゲットの場合、Google Kubernetes Engine クラスタの完全なリソース名。例: projects/p/locations/us-central1/clusters/dev。

  • TARGET_TYPE

    ターゲットの特定のランタイム タイプ。GKE、ANTHOS、RUN のいずれか。 カスタム ターゲットでは設定されません。

  • CLOUD_DEPLOY_LOCATION

    Cloud Deploy リソースを含むリージョン。

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    デリバリー パイプラインの ID。

  • CLOUD_DEPLOY_TARGET

    ターゲットの ID。

  • CLOUD_DEPLOY_PROJECT

    Cloud Deploy リソースを含む Google Cloud プロジェクト。

  • CLOUD_DEPLOY_RELEASE

    フックが実行されるリリースの ID。

  • CLOUD_DEPLOY_ROLLOUT

    フックのジョブを含むロールアウトの ID。

  • CLOUD_DEPLOY_JOB_RUN

    ジョブの現在の実行を表すジョブ実行の ID。

  • CLOUD_DEPLOY_PHASE

    フックのジョブを含むロールアウトのフェーズ。

次のステップ