Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

CLI と VCS を使った設定ファイルのポリシー管理

1 week ago1 min read
クラウド
このページの内容

CircleCI CLI を使ってプログラム上で組織のポリシーを管理することができます。 ポリシーの管理機能を実行するためのサブコマンドは、policy コマンドの配下にグループされます。

設定ポリシーの管理において、 CLI では現在以下のサブコマンドをサポートしています。

  • diff : ローカルポリシーバンドルとリモートポリシーバンドルとの相違点を示します。

  • fetch : ポリシーバンドルを (または 1 つのポリシーを名前に基づき) リモートからフェッチします。

  • push : ポリシーバンドルをプッシュ (アクティブ化) します 。

    たとえば、以下のコマンドを実行することにより、./policy_bundle_dir_path に保存されたポリシーバンドルがアクティブ化されます。

    circleci policy push ./policy_bundle_dir_path --owner-id <your-organization-ID>
  • settings : 必要に応じて設定ファイルのポリシー管理機能の設定を変更します。

    settings サブコマンドがフラグなしで呼び出されると、現在の設定がフェッチされコンソールに出力されます。

    circleci-cli policy settings --owner-id <your-organization-ID>

    出力例:

    {
      "enabled": false
    }

ポリシーの作成とアップロード

以下の手順に従って、CircleCI 設定ファイルの version2.1 以上であることを確認するポリシーを作成します。

  1. 組織の設定ファイルのポリシー管理機能を有効にします。

    circleci-cli policy settings --enabled=true --owner-id <your-organization-ID>

    出力例:

    {
      "enabled": true
    }
  2. 空のディレクトリにポリシーファイルを作成します。 例えば以下のようになります。

    mkdir ./config-policies
  3. 新しいディレクトリ内に、version.rego などの新しいポリシー用の Rego ファイルを作成します。

  4. 以下の内容を version.rego に追加します。

    # All policies start with the org package definition
    package org
    
    policy_name["example"]
    
    # signal to circleci that check_version is enabled and must be included when making a decision
    enable_rule["check_version"]
    
    # signal to circleci that check_version is a hard_failure condition and that builds should be
    # stopped if this rule is not satisfied.
    hard_fail["check_version"]
    
    # define check version
    check_version = reason {
        not input.version # check the case where version is not in the input
        reason := "version must be defined"
    } {
        not is_number(input.version) # check that version is number
        reason := "version must be a number"
    } {
        not input.version >= 2.1 # check that version is at least 2.1
        reason := sprintf("version must be at least 2.1 but got %s", [input.version])
    }
  5. 組織にポリシーをアップロードします。

    circleci-cli policy push ./config-policies --owner-id <your-organization-ID>

    これで、組織内でパイプラインがトリガーされる際、このポリシーに対してプロジェクトの .circleci/config.yml が検証されるようになりました。

ポリシーの更新

既存のポリシーに変更を加える方法を説明するために、上記のポリシーの作成中に間違ってしまったとします。 組織では CircieCI のバージョン 2.0 を使用していることに気づいたため、ポリシーにこれを反映します。

  1. version.rego ファイルでルールの定義を変更します。

    {
        not input.version >= 2.0 # check that version is at least 2.0
        reason := sprintf("version must be at least 2.0 but got %s", [input.version])
    }
  2. この更新されたポリシーファイルを含むポリシーディレクトリを CLI を使ってプッシュします (差分を検証し、プロンプトが表示されたら yes を選択します)。

    circleci-cli policy push ./config-policies --owner-id <your-organization-ID>

組織のポリシー評価を有効・無効にする

組織のパイプライン設定にポリシーの評価を適用するかどうかは、 --enabled フラグを使って制御できます。

  • --enabledtrue に設定されていると、パイプラインがトリガーされる際、組織のポリシーに対してプロジェクトの設定ファイルが評価されます。

  • --enabledfalse に設定されていると、パイプラインがトリガーされる際、組織のポリシーに対するプロジェクトの設定ファイルの評価は行われません

circleci-cli policy settings --enabled=true --owner-id <your-organization-ID>

出力例:

{
  "enabled": true
}

VCS を使ったポリシーの管理

CircleCI のポリシーは、ポリシーのディレクトリを CLI を介して CircleCI にプッシュして管理します。 推奨されるポリシーディレクトリの管理方法は、組織の VCS のレポジトリにポリシーディレクトリを保存することです。 これは、CircleCI の内部でポリシーを管理する方法です。 ポリシーバンドルのプッシュは CircleCI パイプラインをトリガーすることで実行されます。

ポリシーのプッシュにボットアカウントを作成し、関連付けられている CircleCI パーソナル API トークンを使って認証することを推奨します。 最大限のセキュリティを確保するには、トークンを環境変数としてコンテキスト内に保存し、そのコンテキストをポリシーの管理を担当するグループに制限する必要があります 詳細については、 コンテキストの使用 のページを参照してください。

設定ファイルのポリシー管理用 CI パイプラインのセットアップ

  1. VCS にポリシーを管理するためのレポジトリをセットアップします。

  2. Rego ポリシーファイル用のディレクトリを、以下のように作成します。

    mkdir ./config-policies
  3. ポリシーのリポジトリ用の .circleci/config.yml ファイルを作成し、以下の設定サンプルをコピー & ペーストします。 このサンプルでは、main ブランチのコミット時に CircleCI にポリシーをプッシュし、他のすべてのブランチへのコミット時のポリシーバンドルにおける差分を表示します。

    version: 2.1
    
    orbs:
      circleci-cli: circleci/circleci-cli@0.1.9 # Use orb to make the `circleci-cli/default` executor available for running jobs
    
    workflows:
      main-workflow:
        jobs:
          - diff-policy-bundle:
              context: <my-context>
              filters:
                branches:
                  ignore: main # on all branches other than main
          - push-policy-bundle:
              context: <my-context>
              filters:
                branches:
                  only: main # only on the main branch
    
    jobs:
      diff-policy-bundle:
        executor: circleci-cli/default
        resource_class: small
        steps:
          - checkout
          - run:
              name: Diff policy bundle
              command: circleci policy diff ./config --owner-id $ORG_ID # show a diff of the policy bundle
    
      push-policy-bundle:
        executor: circleci-cli/default
        resource_class: small
        steps:
          - checkout
          - run:
              name: Push policy bundle
              command: circleci policy push ./config --no-prompt --owner-id $ORG_ID # push the policy bundle to CircleCI

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。