huawei-cloud-ucs-policy-governor

Huawei Cloud UCS ポリシーガバナー

概要

このスキルは、hcloud CLI を使用して Huawei Cloud UCS（Ubiquitous Cloud Native Service）のポリシーガバナンスとコンプライアンス管理機能を提供します。ポリシーインスタンスのライフサイクル、ポリシー定義、ポリシーの適用、コンプライアンス監査に対応しています。

アーキテクチャ：hcloud CLI → UCS Service API → PolicyInstance／PolicyDefinition／PolicyJob リソース

関連スキル：

• huawei-cloud-ucs-cluster-onboarding-manager - クラスターの登録、ライフサイクル、フリートのグループ化、アクセス管理

機能：

• クラスターまたはフリートグループのポリシーインスタンスを作成
• ポリシーインスタンスを更新、照会、削除
• ポリシー定義（テンプレート）の一覧表示と照会
• クラスターまたはフリートグループでポリシーを有効化、無効化
• ListPolicyJobs／ShowPolicyJob によるポリシー適用ジョブのステータス確認
• フリートのコンプライアンス監査とポリシー適用結果の確認

一般的なユースケース：

• 「本番クラスター用のセキュリティポリシーインスタンスを作成」
• 「フリートグループ用のコンプライアンスポリシーを作成」
• 「利用可能なポリシー定義をすべて一覧表示」
• 「クラスター『prod-backend』でポリシーを有効化」
• 「フリートグループ『production-fleet』でポリシーを有効化」
• 「メンテナンスのためにポリシーを一時的に無効化」
• 「ポリシー適用ジョブのステータスを確認」
• 「すべてのクラスターにわたるポリシー適用を監査」
• 「ポリシーインスタンスの設定を更新」
• 「不要になったポリシーインスタンスを削除」
• 「適用前にポリシー定義の詳細を照会」

ワークフロー

このスキルのワークフローは次のとおりです。

1. 環境の確認 — hcloud CLI がインストールされ、AK／SK 認証情報が設定されていることを確認します（CLI インストールガイドを参照）。
2. ポリシー定義の照会 — ListPolicyDefinitions を呼び出し、利用可能なガバナンスポリシーテンプレートを確認します。
3. ポリシーインスタンスの管理 — ユーザーのリクエストに応じて管理操作を選択します。
   • 作成：CreateClusterPolicyInstance または CreateClusterGroupPolicyInstance（ポリシーセンターが有効なクラスター／フリートが必要です）
   • 更新：UpdatePolicyInstance（ユーザーの確認が必要です — パラメーターの確認を参照）
   • 照会：ListPolicyInstances ／ ShowPolicyInstance
   • 削除：DeletePolicyInstance（⚠️ 元に戻せません。ユーザーの確認が必要です）
4. ポリシーセンターの管理（任意）：
   • 有効化：EnableClusterPolicy ／ EnableClusterGroupPolicy（Available ステータスのクラスター／フリートが必要です）
   • 無効化：DisableClusterPolicy ／ DisableClusterGroupPolicy（ユーザーの確認が必要です — 適用を一時停止します）
5. コンプライアンス監査 — ListPolicyJobs ／ ShowPolicyJob を呼び出し、ポリシー適用履歴とコンプライアンスステータスを確認します。
6. 検証 — ポリシーインスタンスのステータスと適用動作を確認します（検証を参照）。

KooCLI コマンド形式の標準

すべての操作で hcloud UCS <Operation> --<param>=<value> --cli-region=<region> 形式を使用します。パラメーターには --key=value 形式を使用し、JSON 本文は使用しません。各パラメーターの詳細については、パラメーターリファレンスを参照してください。

サポート対象リージョン（検証済み）：

リージョン	ステータス	備考
cn-north-4	✅ 利用可能	プライマリーリージョン。すべてのコマンドを検証済み
ap-southeast-3	✅ 利用可能	2 回目のテストで検証済み
cn-south-4	❌ 利用不可	DNS 名前解決に失敗します。使用しないでください

ほかのリージョンもサポートされている可能性がありますが、検証されていません。まず hcloud UCS ListPolicyDefinitions --cli-region=<region> で必ずテストしてください。

前提条件

1. hcloud CLI の要件（必須）

• hcloud CLI がインストールされていること（バージョン >= 7.2.2）
• hcloud version を実行してインストールを確認します
• 初回利用時：printf "y\n" | hcloud version を実行してプライバシーに関する声明に同意します

2. 認証情報の設定

hcloud CLI は、環境変数を使用した 2 種類の認証情報モードをサポートしており、実行時に自動的に判別します。

モード A — 長期 AK/SK（永続的なアクセス）：

export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

モード B — 一時的な AK/SK + SecurityToken（一時的なアクセスや委任されたアクセスに推奨）：

export HUAWEI_CLOUD_AK=<your-temp-ak>
export HUAWEI_CLOUD_SK=<your-temp-sk>
export HUAWEI_CLOUD_SECURITY_TOKEN=<your-security-token>
export HUAWEI_CLOUD_REGION=cn-north-4

HUAWEI_CLOUD_SECURITY_TOKEN が設定されている場合、hcloud CLI は一時的な認証情報による認証を自動的に使用します。AK/SK のみが設定されている場合は、長期認証情報による認証を使用します。

• セキュリティルール：
  • 🚫 AK/SK/SecurityToken の値をコード、会話、コマンドに決して露出させないでください
  • 🚫 認証情報の確認に echo $HUAWEI_CLOUD_AK や echo $HUAWEI_CLOUD_SK を決して使用しないでください
  • ✅ 環境変数 HUAWEI_CLOUD_AK、HUAWEI_CLOUD_SK、HUAWEI_CLOUD_REGION、HUAWEI_CLOUD_SECURITY_TOKEN を使用してください
  • ✅ クラウド操作にはルートアカウントより IAM ユーザーを優先してください
  • ✅ 機密性の高い操作には MFA を有効にしてください

⚠️ 重要なセキュリティ上の注意事項：

• 認証情報をバージョン管理に決してコミットしないでください
• 必要最小限の権限を持つ IAM ユーザーを使用してください
• 機密性の高い操作には MFA を有効にしてください
• AK/SK を定期的にローテーションしてください

3. IAM 権限の要件

API アクション	権限	用途
ucs:clusterPolicyInstance:create	ポリシーの作成	クラスターレベルのポリシーインスタンスを作成する
ucs:clusterGroupPolicyInstance:create	ポリシーの作成	フリートグループレベルのポリシーインスタンスを作成する
ucs:policyInstance:update	ポリシーの更新	ポリシーインスタンスを変更する
ucs:policyInstance:get	ポリシーの取得	ポリシーインスタンスの詳細を表示する
ucs:policyInstance:delete	ポリシーの削除	ポリシーインスタンスを削除する
ucs:policyInstance:list	ポリシーの一覧表示	すべてのポリシーインスタンスを一覧表示する
ucs:policyDefinition:list	定義の一覧表示	使用可能なポリシー定義を一覧表示する
ucs:policyDefinition:get	定義の取得	ポリシー定義の詳細を表示する
ucs:clusterPolicy:enable	ポリシーの有効化	クラスターレベルのポリシー適用を有効にする
ucs:clusterPolicy:disable	ポリシーの無効化	クラスターレベルのポリシー適用を無効にする
ucs:clusterGroupPolicy:enable	ポリシーの有効化	フリートグループレベルのポリシー適用を有効にする
ucs:clusterGroupPolicy:disable	ポリシーの無効化	フリートグループレベルのポリシー適用を無効にする
ucs:policyJob:list	ジョブの一覧表示	ポリシー適用ジョブを一覧表示する
ucs:policyJob:get	ジョブの取得	ポリシー適用ジョブの詳細を表示する

ポリシー JSON の全体については、IAM 権限ポリシーを参照してください。

権限エラーへの対応：

1. 権限エラーによりコマンドが失敗した場合は、references/iam-policies.md を読みます
2. 必要な権限の一覧とポリシー JSON をユーザーに表示します
3. IAM コンソールでカスタムポリシーを作成し、承認を付与するようユーザーに案内します
4. 実行を一時停止し、権限が付与されたというユーザーの確認を待ちます

主要なコマンド

1. ポリシーインスタンスの管理

詳細なワークフローについては、タスク：ポリシー管理を参照してください。

# Create a cluster-level policy instance
hcloud UCS CreateClusterPolicyInstance --clusterid=<ucs-cluster-id> --constraintTemplateID=<template-id> --enforcementAction=deny --namespaces.1=default --namespaces.2=production --parameters='{"maxReplicas":"3"}' --cli-region=cn-north-4

# Create a fleet group-level policy instance
hcloud UCS CreateClusterGroupPolicyInstance --clustergroupid=<fleet-group-id> --constraintTemplateID=<template-id> --enforcementAction=warn --parameters='{"cpuLimit":"2"}' --cli-region=cn-north-4

# Update a policy instance
hcloud UCS UpdatePolicyInstance --policyinstanceid=<instance-id> --constraintTemplateID=<new-template-id> --enforcementAction=warn --parameters='{"cpuLimit":"4"}' --cli-region=cn-north-4

# Show policy instance details
hcloud UCS ShowPolicyInstance --policyinstanceid=<instance-id> --cli-region=cn-north-4

# Delete a policy instance
hcloud UCS DeletePolicyInstance --policyinstanceid=<instance-id> --cli-region=cn-north-4

# List all policy instances (no filter parameters available)
hcloud UCS ListPolicyInstances --cli-region=cn-north-4

2. ポリシー定義の管理

# List all available policy definitions (no filter parameters available)
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4

# Show policy definition details
# NOTE: --policydefinitionid requires the metadata.uid (UUID format) from ListPolicyDefinitions,
# NOT the policy definition name. Using a name will return UCS.000000 error.
# Step 1: List policy definitions to get the UID
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4
# Step 2: Use the metadata.uid value from the list result
hcloud UCS ShowPolicyDefinition --policydefinitionid=<metadata.uid> --cli-region=cn-north-4

3. ポリシーの適用（有効化／無効化）

# Enable a policy on a cluster
hcloud UCS EnableClusterPolicy --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Enable a policy on a fleet group
hcloud UCS EnableClusterGroupPolicy --clustergroupid=<fleet-group-id> --cli-region=cn-north-4

# Enable a policy on a cluster with retry
hcloud UCS EnableClusterPolicy --clusterid=<ucs-cluster-id> --retry=true --cli-region=cn-north-4

# Disable a policy on a cluster
hcloud UCS DisableClusterPolicy --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Disable a policy on a fleet group
hcloud UCS DisableClusterGroupPolicy --clustergroupid=<fleet-group-id> --cli-region=cn-north-4

4. ポリシー適用ジョブのステータス

詳細なワークフローについては、タスク：コンプライアンス監査を参照してください。

# List policy enforcement jobs
hcloud UCS ListPolicyJobs --cli-region=cn-north-4

# List policy enforcement jobs filtered by kind
hcloud UCS ListPolicyJobs --kind=EnablePolicy --cli-region=cn-north-4

# Show a specific policy enforcement job
hcloud UCS ShowPolicyJob --jobid=<job-id> --cli-region=cn-north-4

パラメーター確認

操作	CLI コマンド	リスクレベル	確認が必要な事項
DeletePolicyInstance	hcloud UCS DeletePolicyInstance --policyinstanceid=<id>	High	ポリシーインスタンスを削除すると、適用が完全に解除されます。クラスター／フリートはこのポリシーの適用対象ではなくなり、コンプライアンスリスクが高まります。まず無効化することを検討してください。
UpdatePolicyInstance	hcloud UCS UpdatePolicyInstance --policyinstanceid=<id> --enforcementAction=<action>	Medium	ポリシーパラメーターを変更すると、適用動作に影響します。enforcementAction を warn から deny に変更すると、準拠していないデプロイメントがブロックされます。新しいパラメーターを確認してください。
DisableClusterPolicy	hcloud UCS DisableClusterPolicy --clusterid=<id>	Medium	クラスターのポリシーを無効にすると、適用が一時停止します。既存の違反記録は保持されますが、新たなチェックは実行されません。続行する前に確認してください。
DisableClusterGroupPolicy	hcloud UCS DisableClusterGroupPolicy --clustergroupid=<id>	Medium	フリートレベルのポリシーを無効にすると、フリートグループ内のすべてのクラスターにわたるコンプライアンスガバナンスに影響します。既存の違反は保持されますが、新たなチェックは実行されません。続行する前に確認してください。

パラメーターリファレンス

共通パラメーター

パラメーター	必須／任意	説明	デフォルト
--cli-region	必須	Huawei Cloud リージョン ID	設定値または HUAWEI_CLOUD_REGION

ポリシーインスタンスのパラメーター

パラメーター	必須	説明	制約
--clusterid	はい*	対象の UCS クラスター ID	CreateClusterPolicyInstance に必須
--clustergroupid	はい*	対象のフリートグループ ID	CreateClusterGroupPolicyInstance に必須
--constraintTemplateID	いいえ	制約テンプレート ID	既存の制約テンプレートを参照します
--enforcementAction	いいえ	適用アクション	warn または deny
--namespaces.[N]	いいえ	対象の名前空間配列	配列のインデックスは 1 から始まります
--parameters	いいえ	ポリシーパラメーターオブジェクト	JSON オブジェクト文字列
--policyinstanceid	はい	インスタンス ID（取得／更新／削除用）	Show／Update／Delete 操作で使用します
--retry	いいえ	有効化時の再試行フラグ	EnableClusterPolicy／EnableClusterGroupPolicy のクエリパラメーター

*注：クラスター単位の操作（CreateClusterPolicyInstance、EnableClusterPolicy、DisableClusterPolicy）では --clusterid が必要です。フリートグループ単位の操作（CreateClusterGroupPolicyInstance、EnableClusterGroupPolicy、DisableClusterGroupPolicy）では --clustergroupid が必要です。

ポリシー定義のパラメーター

パラメーター	必須	説明	制約
--policydefinitionid	はい	定義 UID（metadata.uid）	ListPolicyDefinitions の応答に含まれる UUID 形式の値です。UID の代わりにポリシー名を使用すると、UCS.000000 エラーが返されます

ポリシージョブのパラメーター

パラメーター	必須	説明	制約
--jobid	はい	ポリシージョブ ID	ShowPolicyJob で使用します
--kind	いいえ	ジョブタイプフィルター	デフォルトは EnablePolicy です。ListPolicyJobs で使用します

出力形式

CreateClusterPolicyInstance / CreateClusterGroupPolicyInstance

[要検証 — 検証済みの ShowClusterList/ListPolicyDefinitions のパターンに基づくと、UCS のレスポンスは k8s 形式に従います]

UCS API はフラットな JSON ではなく、Kubernetes 形式のオブジェクトを返します。検証済みの ShowClusterList および ListPolicyDefinitions のレスポンスに基づくと、ポリシーインスタンスのレスポンスは、id、constraintTemplateID、enforcementAction のようなフラットなフィールドではなく、kind、apiVersion、metadata、spec、status フィールドを含む k8s 形式のオブジェクト構造を使用する可能性があります。

主なフィールド（想定される形式。要検証）：

• インスタンス UUID：フラットな id ではなく、metadata.uid に格納される可能性があります
• 制約テンプレートの参照：spec.constraintTemplateID に格納される可能性があります
• 適用アクション：spec.enforcementAction（warn または deny）に格納される可能性があります
• ステータス：status.phase（Enabled、Disabled、Pending）に格納される可能性があります

ListPolicyDefinitions

レスポンス例（検証済み）：

{
  "items": [
    {
      "kind": "ConstraintTemplate",
      "apiVersion": "templates.gatekeeper.sh/v1beta1",
      "metadata": {
        "name": "k8srequiredresources",
        "uid": "3b900254-0086-11ee-924e-0255ac1000d3",
        "creationTimestamp": "2023-06-01T14:11:41Z",
        "annotations": {
          "name-chinese": "K8sRequiredResources",
          "tag-chinese": "集群安全策略",
          "description-chinese": "..."
        }
      },
      "spec": {
        "type": "general",
        "officialTag": "ClusterSecurityPolicies",
        "level": "1",
        "targetKind": "Pod",
        "official": true,
        "description": "Requires containers to have defined resources set...",
        "constraintTemplate": {
          "kind": "ConstraintTemplate",
          "apiVersion": "templates.gatekeeper.sh/v1",
          "metadata": { "name": "k8srequiredresources" },
          "spec": {
            "crd": {
              "spec": {
                "names": { "kind": "K8sRequiredResources" },
                "validation": { "openAPIV3Schema": { "properties": {} } }
              }
            },
            "targets": [
              {
                "target": "admission.k8s.gatekeeper.sh",
                "rego": "...",
                "libs": []
              }
            ]
          }
        }
      }
    }
  ]
}

主なフィールド：

• metadata.name：制約テンプレート名（CreateClusterPolicyInstance ではフラットな id ではなく、constraintTemplateID として使用）
• metadata.uid：定義 UUID
• spec.officialTag：ポリシーカテゴリー／タグ（フラットな category ではありません）
• spec.level：重大度レベル（フラットな severity ではありません）
• spec.targetKind：対象リソースの種類（例：Pod）
• spec.description：ポリシーの説明
• spec.constraintTemplate.spec.crd.spec.validation.openAPIV3Schema.properties：パラメーター定義（フラットな parameters 配列ではありません）
• spec.type：ポリシーの種類（例：general）
• spec.official：公式（組み込み）ポリシーかどうか

ListPolicyJobs

レスポンス例（空の結果で検証済み）：

ジョブが存在しない場合は、{ "items": [] }（空の配列）が返されます。ジョブが存在する場合は、検証済みの UCS パターンに基づく k8s 形式のオブジェクトが返されます。

{
  "items": []
}

[ジョブが存在する場合のレスポンスは要検証 — kind、apiVersion、metadata、spec、status フィールドを含む k8s 形式のオブジェクトの可能性があります]

主なフィールド（想定される形式。要検証）：

• ジョブ UUID：フラットな jobid ではなく、metadata.uid に格納される可能性があります
• ジョブの種類：spec.kind（EnablePolicy など）に格納される可能性があります
• ジョブのステータス：status.phase（Success、Failed、InProgress）に格納される可能性があります

検証

手順ごとの検証については、検証方法を参照してください。

一般的なリージョン ID

リージョン名	リージョン ID
中国北部 - 北京 4	cn-north-4
中国北部 - 北京 1	cn-north-1
中国東部 - 上海 1	cn-east-3
中国東部 - 上海 2	cn-east-2
中国南部 - 広州	cn-south-1
中国南部 - 深圳	cn-south-4
中国南西部 - 貴陽 1	cn-southwest-2
アジア太平洋 - バンコク	ap-southeast-2
アジア太平洋 - シンガポール	ap-southeast-1
アジア太平洋 - 香港	ap-southeast-3
ヨーロッパ - パリ	eu-west-0

ベストプラクティス

1. ポリシーパラメーター：制約テンプレートの参照には --policy_definition_id ではなく --constraintTemplateID を使用します
2. フリートレベルのポリシー：一貫した適用のため、CreateClusterGroupPolicyInstance を使用してフリートグループにポリシーを適用します
3. 段階的なロールアウト：まず EnableClusterPolicy を使用してステージングクラスターでポリシーを有効にし、その後 EnableClusterGroupPolicy を使用して本番環境のフリートグループに展開します
4. コンプライアンスの監視：ListPolicyJobs と ShowPolicyJob を使用して、適用タスクのステータスを監視します
5. 適用アクション：初期ロールアウトでは warn（違反を報告しますが、ブロックはしません）を選択し、その後、厳格に適用するには deny に切り替えます
6. 削除前に無効化：突然ポリシーが適用されなくなる事態を防ぐため、削除前に DisableClusterPolicy／DisableClusterGroupPolicy を使用してポリシーを無効にします
7. 名前空間のスコープ設定：ポリシーの適用範囲を特定の名前空間に限定するには、--namespaces.[N] を使用します

参考ドキュメント

ドキュメント	説明
UCS ポリシー API ガイド	hcloud UCS ポリシー API リファレンス
IAM 権限ポリシー	必要な権限とポリシー JSON
検証方法	手順ごとの検証
よくある落とし穴	トラブルシューティングガイド
タスク：ポリシー管理	ポリシーインスタンスの CRUD ワークフロー
タスク：コンプライアンス監査	コンプライアンスと監査のワークフロー
CLI インストールガイド	KooCLI のインストールと認証の設定
受け入れ基準	テストチェックリストと基準

注意事項

• ポリシーの削除は取り消せません — 適用設定は完全に削除されます
• ポリシーを無効にすると適用が一時停止します — ポリシーが無効な間、違反はチェックされません
• フリートグループのポリシーはすべてのメンバークラスターに適用されます — 適用前にグループのメンバーシップが正しいことを確認してください
• AK/SK をハードコードしてはいけません — 認証情報は環境変数を通じてのみ取得してください
• サポートされている方法は hcloud CLI のみです — すべての操作で hcloud UCS <Operation> 形式を使用します
• CreatePolicyInstance は 2 つの別々の操作です — クラスターレベルのポリシーには CreateClusterPolicyInstance を、フリートグループレベルのポリシーには CreateClusterGroupPolicyInstance を使用します
• 有効化／無効化の操作はスコープごとに異なります — クラスターには EnableClusterPolicy／DisableClusterPolicy を、フリートグループには EnableClusterGroupPolicy／DisableClusterGroupPolicy を使用します
• GetPolicyAssignment は存在しません — 適用タスクのステータスを確認するには、ListPolicyJobs と ShowPolicyJob を使用します
• ListPolicyInstances と ListPolicyDefinitions にはフィルターパラメーターがありません — 使用できるのは --cli-region のみです
• ShowPolicyDefinition には名前ではなく UID が必要です — --policydefinitionid パラメーターには、ListPolicyDefinitions の応答に含まれる metadata.uid（UUID 形式）を指定する必要があります。ポリシー定義名を使用すると、UCS.000000 エラーが返されます。UID を取得するため、必ず最初に ListPolicyDefinitions を呼び出してください
• hcloud の JSON 出力の解析 — hcloud のデフォルト出力には JSON と診断テーブルが混在するため、json.loads() は失敗します。プログラムで解析する場合は、純粋な JSON 出力を得るために --cli-output=json を使用してください：

# Default output (mixed format, json.loads() will fail)
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4

# Pure JSON output (safe for json.loads())
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4 --cli-output=json

よくある落とし穴

詳しいトラブルシューティングガイドについては、よくある落とし穴と解決策を参照してください。

クイックリファレンス：

落とし穴	症状	簡単な解決策
作成操作が誤っている	誤ったスコープで作成に失敗する	クラスターには CreateClusterPolicyInstance を、フリートグループには CreateClusterGroupPolicyInstance を使用します
制約テンプレートが見つからない	作成に失敗する	ListPolicyDefinitions を使用して有効なテンプレート ID を確認します
クラスターが登録されていない	EnableClusterPolicy が失敗する	huawei-cloud-ucs-cluster-onboarding-manager でクラスターを登録します
フリートグループが空	どこにもポリシーが適用されない	まずクラスターをフリートグループに追加します
パラメーター名が誤っている	コマンドが失敗する（アンダースコアと camelCase の違い）	--instance_id ではなく --policyinstanceid を、--cluster_id ではなく --clusterid を使用します
GetPolicyAssignment を使用している	操作が見つからない	代わりに ListPolicyJobs／ShowPolicyJob を使用します
リストのフィルターパラメーターを使用している	予期しない動作	ListPolicyInstances／ListPolicyDefinitions にはフィルターパラメーターがなく、--cli-region のみ使用できます