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

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

デプロイ前のアクションまたはデプロイ後のアクション、あるいはその両方を対象としたアクションを実行するように、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" は、シェルを呼び出すためにここで指定する一般的なコマンドです。そのシェルで実行するコマンドは args に含めます。

  • 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（カンマ区切りのリスト）。これらは、Google Cloud コンソールで、サービスの Cloud Run サービスの詳細で確認できます。

  • 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

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

パラメータを環境変数としてデプロイする

このセクションに記載されている環境変数に加えて、設定したデプロイ パラメータが Cloud Deploy からカスタム コンテナに渡されます。

詳細。

次のステップ