設定ファイルのポリシーの作成と管理

クラウド

このページの内容

ポリシーを作成する

設定ファイルのポリシー管理機能が Scale プランでご利用いただけるようになりました。この機能は現在オープンプレビュー段階であり、すべての側面において、今後変更される可能性があります。

設定ファイルのポリシー管理機能がオープンプレビュー段階の間は、コンプライアンスの用途には使用しないでください。 オープンプレビューの間は本機能を使用できない期間が発生する可能性があります。その間、構築した設定ファイルのポリシーに対する評価が行われない場合があります。

このページでは、設定ファイルのポリシー管理プロセスを実行する方法をガイド形式で説明します。

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

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

ポリシーの評価を有効化するには、以下のコマンドを実行します。これにより、--enabled が true になります。パイプラインのトリガー時に、組織のポリシーに対してプロジェクトの設定ファイルが評価されます。
```
circleci policy push ./policy_bundle_dir_path --owner-id <your-organization-ID>
```
settings : 必要に応じて設定ファイルのポリシー管理機能の設定を変更します。

settings サブコマンドがフラグなしで呼び出されると、現在の設定がフェッチされコンソールに出力されます。
```
{
  "enabled": true
}
```
ポリシーの評価を無効化するには、以下のコマンドを実行します。これにより、--enabled が false になります。パイプラインのトリガー時には、組織のポリシーに対するプロジェクトの設定ファイルの評価は行われません。
```
circleci policy settings --enabled=false --owner-id <your-organization-ID>
```
出力例:
```
{
  "enabled": false
}
```

組織 ID が要求されます。組織 ID には --owner-id フラグがついています。組織/ユーザー ID を見つけるには、CircleCI Web アプリのサイドバーで Organization Settings を選択します。

screenshot showing where to find your organization ID

ポリシーを作成する

設定ファイルのポリシー管理で CLI を使用する前に、ご使用の CLI がトークンで認証されており、更新されていることをご確認ください。詳細については、ローカルの CLI のインストールのページをご覧ください。

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

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

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

出力例:

{
  "enabled": true
}

ポリシーの保存用に空のディレクトリを作成します。たとえば以下のようになります。
```
mkdir ./config-policies
```
新しいディレクトリ内に、新しいポリシー用の Rego ファイルを作成します。今回は version.rego という名前にします。

以下の内容を 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])
}

組織にポリシーをアップロードします。
```
circleci-cli policy push ./config-policies --owner-id <your-organization-ID>
```
これで、組織内でパイプラインがトリガーされる際、このポリシーに対してプロジェクトの .circleci/config.yml が検証されるようになりました。

ポリシーの更新

既存のポリシーに変更を加える方法を説明するために、上記のポリシーの作成中に間違ってしまったとします。たとえば、組織の一部のプロジェクト設定ファイルで CircieCI のバージョン 2.0 が使用されていたので、これをポリシーに反映してみましょう。

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])
}

この更新されたポリシーファイルを含むポリシーディレクトリを CLI を使ってプッシュします (差分を検証し、プロンプトが表示されたら yes を選択します)。
```
circleci-cli policy push ./config-policies --owner-id <your-organization-ID>
```

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

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

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

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

出力例:

{
  "enabled": true
}

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

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

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

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

VCS にポリシーを管理するためのレポジトリをセットアップします。
新しいリポジトリに Rego ポリシーファイル用のディレクトリを作成します。
```
mkdir ./config-policies
```

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

この例では、各ジョブのコンテキストを <my-context> と表記しています。このコンテキスト名は任意ですが、該当するコンテキストがアクティブであり、以下の環境変数を宣言している必要があります。

CIRCLECI_CLI_TOKEN: CLI 認証用のパーソナル API トークンの値を設定
ORG_ID: 組織 ID の値を設定

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

$ORG_ID は組織 ID を保存するための環境変数です。

各ジョブのコンテキストは <my-context> です。このコンテキスト名は任意ですが、CLI を認証するには、環境変数 CIRCLECI_CLI_TOKEN を宣言する必要があります。

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

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

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか

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

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

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.