Azure Pipelines の再利用と統制|テンプレート・変数グループ・環境と承認/ブランチ制御/必須テンプレートを実機で検証(DevOps 編 7)

DevOps

はじめに

DevOps 編の 7 回目は、Azure Pipelines の再利用と統制。
パイプラインが増えてくると、同じ YAML のコピー、パイプラインごとに散らばる設定値、誰でも本番にデプロイできる状態が問題になる。
今回は、テンプレート、変数グループとセキュア ファイル、環境とデプロイ ジョブ、承認とチェック、パイプラインの権限を押さえ、本番の環境を承認・ブランチ制御・必須テンプレートで守るところまで実機で確かめる。

前回:Azure Pipelines の基本

Azure Pipelines の基本|トリガー・変数・条件・マトリックス・キャッシュと PR のビルド検証を実機で検証(DevOps 編 6)
Azure Pipelines の YAML の書き方を、トリガー、変数と式、条件、マトリックスと並列ジョブ、キャッシュと成果物に分けて整理。パス フィルター、ランタイム パラメーター、キャッシュの復元、PR のビルド検証を実機で確かめた。

テンプレート

テンプレートは、YAML パイプラインの中で再利用するコンテンツ、ロジック、パラメーターを定義する仕組み。
使い方は「挿入(include)」と「拡張(extends)」の 2 つ。

テンプレートの 2 つの使い方
種類書き方向いている用途
挿入steps / jobs / stages / variables の中で template: ファイル名同じステップやジョブを、複数のパイプラインや複数の場所で使う
拡張パイプラインのルートで extends: template: ファイル名パイプラインの外側の構造を決め、セキュリティや組織の標準を守らせる

テンプレートは別のリポジトリに置くこともできる。
resources の repositories でリポジトリを宣言し、「ファイル名@リソース名」で参照する。
ref でタグやブランチを指定すると、テンプレートの版を固定できる。

テンプレートの展開には上限があり、読み込む YAML ファイルは 100 個まで、入れ子は 100 階層まで、解析に使うメモリは 20 MB まで。

公式ドキュメント:
再利用可能で安全なプロセスのためにパイプラインで YAML テンプレートを使用する | Microsoft Learn
セキュリティ用のテンプレート | Microsoft Learn

変数グループとセキュア ファイル

パイプラインの「ライブラリ」には、変数グループとセキュア ファイルを置ける。
どちらも、複数のパイプラインで使う値やファイルをパイプラインの外で管理するためのもの。

ライブラリ
項目変数グループセキュア ファイル
入れるもの値とシークレット署名証明書、SSH キー、プロビジョニング プロファイルなどのファイル
YAML での使い方variables の中で – group: 名前DownloadSecureFile などのタスク
保護シークレット変数は保護されたリソース。
シークレットでない変数は、承認・チェック・パイプラインのアクセス許可では制限されない
保護されたリソース。
サーバーに暗号化して保存され、1 ファイル 10 MB まで

シークレット変数はログで *** に置き換わるが、部分文字列はマスクされない。
また、通常の変数と違ってスクリプトの環境変数には自動で入らないので、env で明示的に渡す。

Key Vault とリンクした変数グループでは、サービス接続を通して Key Vault のシークレットを変数として使える。
実行時に最新の値を取りに行くが、Key Vault にシークレットを追加・削除しても変数グループには自動で反映されない。
使えるのはシークレットだけで、キーと証明書は対象外。

公式ドキュメント:
変数グループの管理 | Microsoft Learn
Azure Key Vault で変数グループをシークレットにリンクする | Microsoft Learn
セキュア ファイルの使用 | Microsoft Learn
シークレット変数を設定する | Microsoft Learn

環境とデプロイ ジョブ

環境(environment)は、パイプラインのデプロイ先を表す論理的なまとまり。
Dev、Test、Staging、Production のような単位で作り、デプロイ履歴、コミットと作業項目の追跡、承認とチェックによる保護に使う。
リソースとして Kubernetes と仮想マシンを登録できる。

YAML から存在しない環境を参照すると、実行したユーザーがわかる場合は環境が自動で作られる。
環境は YAML パイプラインのための仕組みで、クラシック パイプラインでは使えない(代わりにデプロイ グループを使う)。

環境にデプロイするには、通常のジョブではなくデプロイ ジョブ(- deployment:)を使う。

項目デプロイ ジョブ
書き方jobs の中で – deployment: 名前、environment: 環境名、strategy にデプロイ手順
戦略runOnce、rolling、canary(ライフサイクル フックで前処理・デプロイ・後処理を分けられる)
ソースの取得自動ではチェックアウトしない。必要なら – checkout: self
成果物deploy フックでは成果物のダウンロードが自動で入る。
止めるなら – download: none
履歴環境の Deployments に、どの実行がデプロイしたかが残る

公式ドキュメント:
Azure DevOps環境の作成とターゲット設定 | Microsoft Learn
デプロイ ジョブ | Microsoft Learn

承認とチェック

承認とチェックは、保護されたリソース(環境、サービス接続、リポジトリ、変数グループ、セキュア ファイル、エージェント プール)に付ける。
YAML には書かず、リソースの「Approvals and checks」で設定する。
そのため、YAML を書き換えられる人でも、チェックを外すことはできない。

リソースを使うステージは、そのステージで使うすべてのリソースのチェックを満たすまで始まらない。
チェックは 5 つのカテゴリの順に実行される。

承認とチェックの実行順
チェック主な設定と動き
承認承認者(ユーザーかグループ)、承認者への指示、自分の実行を承認してよいか、タイムアウト。
グループなら 1 人の承認で進む。
タイムアウトまでに承認がないとステージはスキップ
ブランチ コントロール許可するブランチ(refs/heads/main のような完全な名前、カンマ区切り)。
ブランチの保護(ポリシー)を必須にもできる
必須テンプレートリポジトリ、参照(ブランチやタグ)、テンプレートのパス。
指定のテンプレートから拡張していないと失敗
営業時間指定した時間帯に入るまで待つ
Azure 関数 / REST API の呼び出し外部のサービスを定期的に呼び、成功の応答で進む
Azure Monitor アラートのクエリアラート ルールがアクティブでなければ成功
排他ロック同時に 1 つの実行だけを進める。
lockBehavior は runLatest(既定)か sequential

リソースの管理者は、承認・営業時間・Azure 関数・REST API のチェックを「バイパス」できる(修正プログラムを急いで出すときなど)。
バイパスした人はチェックのパネルに記録される。

公式ドキュメント:承認とチェックを定義する | Microsoft Learn

パイプラインの権限

保護されたリソースは、パイプラインのアクセス許可で「使ってよいパイプライン」を決める。
許可されていないパイプラインが使おうとすると、実行が「Permission needed」で止まり、許可されるまで進まない。
すべてのパイプラインに開放する「オープン アクセス」は、セキュリティのために使わないことが推奨されている。

パイプラインの各ジョブは、実行のたびに作られるジョブ アクセス トークンで、リポジトリやフィードなどにアクセスする。
ジョブ承認スコープがコレクション(組織)のままだと、パイプラインは組織内のすべてのプロジェクトのリポジトリにアクセスできる。
組織の設定でスコープを現在のプロジェクトに制限しておくのが推奨。

設定(Project Settings ⇒ Pipelines ⇒ Settings)内容
Limit job authorization scope to current project for non-release pipelinesYAML とクラシック ビルドのジョブのアクセスを、同じプロジェクトに限る
Limit job authorization scope to current project for release pipelinesクラシック リリースのジョブのアクセスを、同じプロジェクトに限る

公式ドキュメント:
リソースのセキュリティ | Microsoft Learn
リポジトリ、成果物、およびその他のリソースにアクセスする | Microsoft Learn

構築手順

今回の構成と実施すること

今回の構成
手順実施すること確かめること
①変数グループ cicd-shared と環境 staging / production を作る—
②production に承認のチェックを付ける—
③パイプラインをテンプレートに分け、extends で組んで push する初回はリソースの使用許可を求められる。
シークレットは *** になる。
承認で production に進む
④もう一度実行して、承認を却下するproduction が動かない
⑤production にブランチ コントロールを付け、作業ブランチから実行するproduction に進めない
⑥production に必須テンプレートを付け、テンプレートを使わないパイプラインで production を使うテンプレートを使わないパイプラインは進めず、使うパイプラインは進む

リポジトリとパイプラインは前回の cicd-demo を使い、デプロイの中身は echo だけにした(Azure のリソースは作らない)。

① 変数グループと環境を作る

「Pipelines」⇒「Library」⇒「+ Variable group」で、変数グループ cicd-shared を作った。
appName は通常の変数、apiKey は鍵のアイコンを押してシークレットにした。

変数グループ
番号項目説明
1Variable group nameYAML から – group: cicd-shared で参照する名前
2Link secrets from an Azure key vault as variablesオンにすると、Key Vault のシークレットを変数として使う変数グループになる
3apiKeyシークレットにした変数。
保存後は値が ******** と表示され、画面からも読めない
4Pipeline permissions / Approvals and checks使ってよいパイプラインと、変数グループに付けるチェックの設定

「Pipelines」⇒「Environments」⇒「Create environment」で、環境 staging を作った。
production も同じように作った。

環境の作成
番号項目説明
1NameYAML の environment: で指定する名前
2ResourceNone にした。
Kubernetes と仮想マシンは、あとからリソースとして追加できる

② production に承認を付ける

環境 production の「Approvals and checks」で「+」を押すと、付けられるチェックの一覧が出る。

チェックの種類
番号項目説明
1Required template必須テンプレート(⑥で使う)
2Approvals承認(ここで使う)
3Post-check approvalsほかのチェックが終わったあとに求める承認。
Pre-check approvals はその前
4Exclusive Lock排他ロック

「Approvals」を選び、承認者に自分を入れて作成した。

承認の設定
番号項目説明
1Approvers承認するユーザーかグループ
2Instructions to approvers承認の画面に出る指示
3Allow approvers to approve their own runs既定でオン。オフにすると、実行した本人は承認できない
4Timeout既定は 30 日。過ぎるとステージはスキップされる

③ テンプレートに分けて push する

テストのステップを templates/test-steps.yml に切り出した。
Node.js のバージョンはパラメーターで受け取る。

parameters:
  - name: nodeVersion
    type: string

steps:
  - task: UseNode@1
    inputs:
      version: ${{ parameters.nodeVersion }}
    displayName: Node.js ${{ parameters.nodeVersion }} を入れる
  - task: Cache@2
    inputs:
      key: 'npm | "$(Agent.OS)" | src/package-lock.json'
      restoreKeys: |
        npm | "$(Agent.OS)"
      path: $(Pipeline.Workspace)/.npm
    displayName: npm のキャッシュ
  - script: npm ci && npm run lint && npm test
    workingDirectory: src
    env:
      npm_config_cache: $(Pipeline.Workspace)/.npm
    displayName: インストール・ESLint・テスト

パイプライン全体の形は templates/pipeline.yml に書いた。
Test ステージのジョブは、object 型のパラメーター nodeVersions を ${{ each }} で回して作る。
Staging と Production はデプロイ ジョブで、Staging だけで変数グループのシークレットを env で渡している。

parameters:
  - name: nodeVersions
    type: object
    default: ['24.x']

stages:
  - stage: Test
    jobs:
      - ${{ each v in parameters.nodeVersions }}:
          - job: test_${{ replace(v, '.x', '') }}
            displayName: test node ${{ v }}
            pool:
              vmImage: ubuntu-latest
            steps:
              - template: test-steps.yml
                parameters:
                  nodeVersion: ${{ v }}

  - stage: Staging
    dependsOn: Test
    variables:
      - group: cicd-shared
    jobs:
      - deployment: deploy
        displayName: staging へデプロイ
        pool:
          vmImage: ubuntu-latest
        environment: staging
        strategy:
          runOnce:
            deploy:
              steps:
                - download: none
                - script: |
                    echo "app: $(appName) / env: staging"
                    echo "apiKey: $(apiKey)"
                    echo "API_KEY の長さ: ${#API_KEY}"
                  env:
                    API_KEY: $(apiKey)
                  displayName: デプロイ(staging)

  - stage: Production
    dependsOn: Staging
    variables:
      - group: cicd-shared
    jobs:
      - deployment: deploy
        displayName: production へデプロイ
        pool:
          vmImage: ubuntu-latest
        environment: production
        strategy:
          runOnce:
            deploy:
              steps:
                - download: none
                - script: |
                    echo "app: $(appName) / env: production / branch: $(Build.SourceBranch)"
                  displayName: デプロイ(production)

azure-pipelines.yml は、トリガーと extends だけになった。

trigger:
  branches:
    include:
      - main
  paths:
    include:
      - src
      - templates
      - azure-pipelines.yml

extends:
  template: templates/pipeline.yml
  parameters:
    nodeVersions:
      - '22.x'
      - '24.x'

push すると Test ステージが通ったあと、Staging の手前で止まった。
このパイプラインは、まだ環境 staging と変数グループ cicd-shared を使う許可をもらっていないため。

使用許可を待つ実行
番号項目説明
1This pipeline needs permission to access 2 resources許可が必要なリソースが 2 つある
2StagingWaiting、Permission needed。
Test ステージは許可がなくても動いた

「View」を押すと、許可を求めているリソースが一覧になる。

許可を求めるリソース
番号項目説明
1Environment staging環境の使用許可
2Variable group cicd-shared変数グループの使用許可

「Permit」を押すと確認が出る。
許可は今回の実行だけでなく、このパイプラインのこれからの実行すべてに効く。

許可の確認
番号項目説明
1for all waiting and future runs of this pipeline待っている実行とこれからの実行に、このリソースの使用を許可する

両方を許可すると Staging が動き、production の手前で同じように production の使用許可を求められた。
許可すると、今度は承認待ちになった。

承認待ちの実行
番号項目説明
11 approval needs your reviewproduction の承認が必要
2ProductionWaiting、1 check in progress

「Review」で承認の画面を開くと、①で書いた指示が表示される。
コメントを書いて「Approve」を押した。

承認
番号項目説明
1指示Instructions to approvers に書いた文
2Reject / Approve却下か承認か。コメントは任意
承認後に完了した実行
番号項目説明
1Production1 job completed、1 checks passed

Staging のログでは、シークレットの apiKey は *** に置き換わっていた。
env で渡した環境変数 API_KEY の長さは 17 文字で、値はスクリプトに届いている。

シークレットのマスク
番号項目説明
1apiKey: ***$(apiKey) を echo した行。ログではマスクされる
2API_KEY の長さ: 17env で渡すと、スクリプトから値を使える

デプロイ ジョブのステップは「Initialize job」「デプロイ(staging)」「Finalize Job」だけで、チェックアウトは行われていなかった。

④ 承認を却下する

main からもう一度実行し、production の承認でコメントを書いて「Reject」を押した。
Production ステージは「1/2 checks failed」で失敗し、デプロイ ジョブは動かなかった。

却下された承認
番号項目説明
1Rejected誰がいつ却下したかと、コメントが残る

⑤ ブランチ コントロールで作業ブランチを止める

production の「Approvals and checks」で「Branch control」を追加し、許可するブランチを refs/heads/main だけにした。

ブランチ コントロールの設定
番号項目説明
1Display nameチェックの名前(main だけ許可)
2Allowed branches許可するブランチ。refs/heads/ から書く。既定は *(すべて)
3Verify branch protectionオンにすると、ブランチにポリシーが付いていることも求める

作業ブランチ feature/try-prod から実行すると、Test と Staging は通ったが、Production は「1/2 checks failed」で失敗した。
承認より先にブランチ コントロールが評価され、承認は Canceled になった。

ブランチ コントロールで止まった実行
番号項目説明
1feature/try-prod実行したブランチ
2Production1/2 checks failed。デプロイ ジョブは動いていない
ブランチ コントロールのログ
番号項目説明
1Check inputs許可するブランチ(refs/heads/main)と、保護の確認をしない設定
2Result for evaluation: Unsuccessfulself(cicd-demo)のブランチが refs/heads/feature/try-prod で、許可に一致しなかった

⑥ 必須テンプレートでテンプレートを強制する

production に「Required template」を追加し、templates/pipeline.yml を指定した。

必須テンプレートの設定
番号項目説明
1Repositoryテンプレートがあるリポジトリ。
Azure Repos ならリポジトリ名(cicd-demo)。
画面では最初「プロジェクト名/リポジトリ名」と入れたが、これではチェックが通らなかった(「実機でつまずいた点」)
2Refテンプレートのブランチやタグ。
既定は refs/heads/master なので refs/heads/main に変えた
3Path to required YAML templateテンプレートのパス
production のチェック
番号項目説明
1Order 1ブランチ コントロールと必須テンプレート(静的チェック)
2Order 2承認(動的チェック)。静的チェックのあとに評価される

テンプレートを使わずに production へデプロイする direct-deploy.yml を用意し、別のパイプラインとして実行した。

trigger: none

pool:
  vmImage: ubuntu-latest

stages:
  - stage: Production
    jobs:
      - deployment: deploy
        displayName: production へデプロイ(テンプレートなし)
        environment: production
        strategy:
          runOnce:
            deploy:
              steps:
                - download: none
                - script: echo "テンプレートを使わずに production へ"
                  displayName: デプロイ(production)

production の使用許可を出すと、ブランチ コントロールは通ったが、必須テンプレートで失敗した。

テンプレートなしのパイプライン
番号項目説明
1Pipeline run failed due to 1 failed check.チェックの失敗で実行が失敗
2Production1 checks passed(ブランチ コントロール)だが、ステージは失敗
必須テンプレートの失敗
番号項目説明
1Required templateFailed

cicd-demo(extends でテンプレートを使う)を main から実行すると、ブランチ コントロールと必須テンプレートが Passed になり、承認待ちに進んだ。
承認すると production へのデプロイが成功した。

チェックを通過した実行
番号項目説明
1main だけ許可 / Required templateどちらも Passed
2Approval承認待ち

環境 production の「Deployments」には、承認されてデプロイした 2 回の実行だけが残った。
却下やチェックで止まった実行は、デプロイとしては記録されていない。

production のデプロイ履歴
番号項目説明
1#20261114.10 / #20261114.14どの実行がデプロイしたか。リンクから実行に移れる

プロジェクト設定の「Pipelines」⇒「Settings」では、ジョブ承認スコープの制限がオンになっていた。
スイッチはグレーで、このプロジェクトの画面からは切り替えられない表示だった(組織レベルでプロジェクトに制限していると、プロジェクトごとには変えられない)。

パイプラインの設定
番号項目説明
1Limit job authorization scope to current project非リリースとリリースのパイプラインで、ジョブ アクセス トークンの範囲を同じプロジェクトに限る

実機でつまずいた点

Mapping values are not allowed in this context.

最初の push では、パイプラインが始まらずにエラーになった。
テンプレートの - script: echo "app: $(appName) / env: production ..." の 1 行で、「: 」(コロンと空白)が YAML のキーと値の区切りとして読まれたため。
script: | のブロック形式に書き直すと通った。
エラーにはファイル名と行・列が出るので、テンプレートのどこかがすぐわかる。

YAML のエラー
コロンを含む 1 行のスクリプト

Required template が Failed になる

必須テンプレートのチェックで、Repository に「boards-demo/cicd-demo」(プロジェクト名/リポジトリ名)と入れたところ、テンプレートを extends で使っている cicd-demo の実行まで Required template が Failed になった。
Repository をリポジトリ名だけ(cicd-demo)に直すと、同じパイプラインが Passed になった。
Ref の既定値も refs/heads/master なので、main を使うリポジトリでは書き換える。

テンプレートを使っているのに通らない

推奨構成

項目推奨
テンプレート共通の手順は挿入テンプレート、本番に届くパイプラインは extends テンプレートで形を固定する
テンプレートの置き場所別のリポジトリに置き、ref でタグに固定する。書き換えられる人を絞る
シークレット変数グループのシークレット(できれば Key Vault とリンク)。
スクリプトには env で渡す
環境デプロイ先ごとに環境を作り、デプロイ ジョブでデプロイする
項目推奨
本番の環境承認、ブランチ コントロール(main だけ)、必須テンプレートを付ける
パイプラインの権限オープン アクセスにせず、使うパイプラインだけに許可する
ジョブ承認スコープ組織の設定で現在のプロジェクトに制限する
承認者必要なら「自分の実行を承認できる」をオフにして、作った人と承認する人を分ける

注意事項

項目内容
チェックの場所承認とチェックは YAML ではなくリソース側の設定。
リソースの管理者が管理する
承認のタイムアウト既定は 30 日。過ぎるとステージはスキップされる
承認者の変更承認者のリストはチェックが始まった時点で固定され、あとから変えても反映されない
ブランチ名ブランチ コントロールでは refs/heads/main のように完全な名前で書く
項目内容
シークレットのマスク部分文字列はマスクされない。
構造化データ(JSON など)をシークレットに入れない
シークレットでない変数変数グループの承認・チェック・パイプラインの許可では守られない
環境の自動作成存在しない環境を YAML で参照すると、自動で作られることがある
デプロイ ジョブソースは自動でチェックアウトされない。
成果物は deploy フックで自動ダウンロードされる

公式ドキュメント:
承認とチェックを定義する | Microsoft Learn
リソースのセキュリティ | Microsoft Learn
変数グループの管理 | Microsoft Learn

まとめ

・テンプレートは、部品を挿入する使い方と、extends でパイプラインの形を決める使い方がある。
・変数グループのシークレットはログで *** になり、スクリプトには env で渡す。
・環境とデプロイ ジョブで、どの実行がどこにデプロイしたかの履歴が残る。
・production に付けた承認で、承認すれば進み、却下すれば止まった。
・ブランチ コントロールで作業ブランチからの本番デプロイを止め、必須テンプレートでテンプレートを使わないパイプラインを止めた。
・保護されたリソースは、初めて使うパイプラインに使用許可を求めてくる。

次回:GitHub Actions

GitHub Actions とは|再利用可能ワークフロー・環境の承認・OpenID Connect で Azure にサインインを実機で検証(DevOps 編 8)
GitHub Actions のワークフロー構造、トリガー、キャッシュ、再利用可能ワークフロー、環境の保護ルールを整理。承認で進む本番デプロイと、OpenID Connect によるシークレットなしの Azure サインインを実機で確認。

コメント

タイトルとURLをコピーしました