2.7. テンプレート処理

fromSecret 関数は、シークレット内にある指定のデータキーの値を返します。関数については、以下の構文を確認してください。

func fromSecret (ns string, secretName string, datakey string) (dataValue string, err error)

この関数を使用するには、Kubernetes Secret リソースの namespace、名前、およびデータキーを入力します。ハブクラスターテンプレートの関数を使用する場合は、ポリシーに使用されるのと同じ namespace を使用する必要があります。詳細は、Template processing を参照してください。

注意: この関数をハブクラスターテンプレートで使用すると、保護関数 を使用して出力が自動的に暗号化されます。

Kubernetes Secret がターゲットクラスターに存在しない場合は、ポリシー違反が表示されます。データキーがターゲットクラスターに存在しない場合は、値が空の文字列になります。以下で、ターゲットクラスターで Secret リソースを有効にする設定ポリシーを確認します。PASSWORD データキーの値は、ターゲットクラスターのシークレットを参照するテンプレートを指します。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
      apiVersion: v1
      data:
        USER_NAME: YWRtaW4=
        PASSWORD: '{{ fromSecret "default" "localsecret" "PASSWORD" }}'
      kind: Secret
      metadata:
        name: demosecret
        namespace: test
      type: Opaque
  remediationAction: enforce
  severity: low

fromConfigMap 関数は、ConfigMap 内にある指定のデータキーの値を返します。関数については、以下の構文を確認してください。

func fromConfigMap (ns string, configmapName string, datakey string) (dataValue string, err Error)

この関数を使用するには、Kubernetes ConfigMap リソースの namespace、名前、およびデータキーを入力します。ハブクラスターテンプレートの関数を使用するポリシーに使用されるのと同じ namespace を使用する必要があります。詳細は、Template processing を参照してください。Kubernetes ConfigMap リソースまたはデータキーがターゲットクラスターに存在しない場合は、ポリシー違反が表示されます。データキーがターゲットクラスターに存在しない場合は、値が空の文字列になります。以下で、ターゲットのマネージドクラスターで Kubernetes リソースを有効にする設定ポリシーを表示します。log-file データキーの値は、ConfigMap から log-file、default namespace から log-config の値を取得するテンプレートであり、log-level はデータキーの log-level に設定されます。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromcm-lookup
  namespace: test-templates
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: demo-app-config
        namespace: test
      data:
        app-name: sampleApp
        app-description: "this is a sample app"
        log-file: '{{ fromConfigMap "default" "logs-config" "log-file" }}'
        log-level: '{{ fromConfigMap "default" "logs-config" "log-level" }}'
  remediationAction: enforce
  severity: low

fromClusterClaim 関数は、ClusterClaim リソースの Spec.Value の値を返します。関数については、以下の構文を確認してください。

func fromClusterClaim (clusterclaimName string) (dataValue string, err Error)

この関数を使用する場合は、Kubernetes ClusterClaim リソースの名前を入力します。ClusterClaim リソースが存在しない場合は、ポリシー違反が表示されます。以下で、ターゲットのマネージドクラスターで Kubernetes リソースを有効にする設定ポリシーの例を確認してください。platform データキーの値は、platform.open-cluster-management.io クラスター要求の値を取得するテンプレートです。同様に、product と version の値は ClusterClaim から取得します。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-clusterclaims
  namespace: default
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: sample-app-config
        namespace: default
      data:
        # Configuration values can be set as key-value properties
        platform: '{{ fromClusterClaim "platform.open-cluster-management.io" }}'
        product: '{{ fromClusterClaim "product.open-cluster-management.io" }}'
        version: '{{ fromClusterClaim "version.openshift.io" }}'
  remediationAction: enforce
  severity: low

lookup 関数は、JSON と互換性のあるマップとして Kubernetes リソースを返します。要求されたリソースが存在しない場合は、空のマップが返されます。リソースが存在せず、値が別のテンプレート関数に提供されている場合は、エラー invalid value; expected string が発生する可能性があります。

注記: default テンプレート関数を使用して、後のテンプレート関数に正しい型が提供されるようにします。サポートされている Sprig オープンソース関数 セクションを参照してください。

関数については、以下の構文を確認してください。

func lookup (apiversion string, kind string, namespace string, name string, labelselector ...string) (value string, err Error)

この関数を使用する場合は、Kubernetes リソースの API バージョン、種類、namespace、名前、およびオプションのラベルセレクターを入力します。ハブクラスターテンプレート内のポリシーに使用されるものと同じ namespace を使用する必要があります。詳細は、Template processing を参照してください。ラベルセレクターの例は、Additional resources セクションにある Kubernetes labels and selectors ドキュメントへのリファレンスを参照してください。以下で、ターゲットのマネージドクラスターで Kubernetes リソースを有効にする設定ポリシーの例を確認してください。metrics-url データキーの値は、default namespace から v1/Service Kubernetes リソースの metrics を取得するテンプレートであり、クエリーされたリソースにある Spec.ClusterIP の値に設定されます。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-lookup
  namespace: test-templates
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: demo-app-config
        namespace: test
      data:
        # Configuration values can be set as key-value properties
        app-name: sampleApp
        app-description: "this is a sample app"
        metrics-url: |
          http://{{ (lookup "v1" "Service" "default" "metrics").spec.clusterIP }}:8080
  remediationAction: enforce
  severity: low

base64enc 関数は、入力 data string を base64 でエンコードされた値で返します。関数については、以下の構文を確認してください。

func base64enc (data string) (enc-data string)

この関数を使用する場合は、文字列値を入力します。以下は、base64enc 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    data:
      USER_NAME: '{{ fromConfigMap "default" "myconfigmap" "admin-user" | base64enc }}'

base64dec 関数は、入力 enc-data 文字列 を base64 デコードされた値で返します。関数については、以下の構文を確認してください。

func base64dec (enc-data string) (data string)

この関数を使用する場合は、文字列値を入力します。以下は、base64dec 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    data:
      app-name: |
         "{{ ( lookup "v1"  "Secret" "testns" "mytestsecret") .data.appname ) | base64dec }}"

indent 関数により、パディングされた データ文字列 が返されます。関数については、以下の構文を確認してください。

func indent (spaces  int,  data string) (padded-data string)

この関数を使用する場合は、特定のスペース数でデータ文字列を入力します。以下は、indent 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    data:
      Ca-cert:  |
        {{ ( index ( lookup "v1" "Secret" "default" "mycert-tls"  ).data  "ca.pem"  ) |  base64dec | indent 4  }}

autoindent 関数は、indent 関数のように機能し、テンプレートの前のスペース数に基づいて自動的に先頭のスペース数を決定します。以下は、autoindent 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    data:
      Ca-cert:  |
        {{ ( index ( lookup "v1" "Secret" "default" "mycert-tls"  ).data  "ca.pem"  ) |  base64dec | autoindent }}

toInt 関数は入力値の整数値をキャストして返します。また、テンプレートの最後の関数である場合は、ソースコンテンツがさらに処理されます。これは、YAML で値が整数として解釈されるようにするためです。関数については、以下の構文を確認してください。

func toInt (input interface{}) (output int)

この関数を使用する場合は、整数としてキャストする必要があるデータを入力します。以下は、toInt 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    spec:
      vlanid:  |
        {{ (fromConfigMap "site-config" "site1" "vlan")  | toInt }}

toBool 関数は、入力文字列をブール値に変換し、ブール値を返します。また、テンプレートの最後の関数である場合は、ソースコンテンツがさらに処理されます。これは、YAML で値がブール値として解釈されるようにするためです。関数については、以下の構文を確認してください。

func toBool (input string) (output bool)

この関数を使用する場合は、ブール値に変換する必要のある文字列データを入力します。以下は、toBool 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    spec:
      enabled:  |
        {{ (fromConfigMap "site-config" "site1" "enabled")  | toBool }}

protect 機能により、ハブクラスターポリシーテンプレートで文字列を暗号化できます。これは、ポリシーの評価時にマネージドクラスターで自動的に復号化されます。以下は、protect 関数を使用する設定ポリシーの例になります。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
  namespace: test
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
    ...
    spec:
      enabled:  |
        {{hub (lookup "v1" "Secret" "default" "my-hub-secret").data.message | protect hub}}

前述の YAML の例では、lookup 関数を使用するために定義した既存のハブクラスターポリシーテンプレートがあります。マネージドクラスターの namespace に複製されたポリシーでは、値は $ocm_encrypted:okrrBqt72oI+3WT/0vxeI3vGa+wpLD7Z0ZxFMLvL204= のようになります。

それぞれの暗号化アルゴリズムは、256 ビットキーを使用した AES-CBC です。各暗号化キーはマネージドクラスターごとに一意で、30 日ごとに自動的にローテーションされます。

これにより、復号化された値がマネージドクラスターのポリシーに保存されることはありません。

即時のローテーションを強制するには、ハブクラスターのマネージドクラスター namespace の policy-encryption-key Secret で policy.open-cluster-management.io/last-rotated アノテーションを削除します。その後、ポリシーが再処理され、新しい暗号化キーが使用されます。

toLiteral 関数は、処理後にテンプレート文字列を囲む引用符をすべて削除します。この関数を使用して、JSON 文字列を ConfigMap フィールドからマニフェストの JSON 値に変換できます。次の関数を実行して、key パラメーター値から引用符を削除します。

key: '{{ "[\"10.10.10.10\", \"1.1.1.1\"]" | toLiteral }}'

toLiteral 関数を使用すると、次の更新が表示されます。

key: ["10.10.10.10", "1.1.1.1"]

copySecretData 関数は、指定されたシークレットのすべての data コンテンツをコピーします。次の関数のサンプルをご覧ください。

complianceType: musthave
      objectDefinition:
        apiVersion: v1
        kind: Secret
        metadata:
          name: my-secret-copy
        data: '{{ copySecretData "default" "my-secret" }}'

注意: この関数をハブクラスターテンプレートで使用すると、保護関数 を使用して出力が自動的に暗号化されます。

copyConfigMapData 関数は、指定された ConfigMap のすべての data コンテンツをコピーします。次の関数のサンプルをご覧ください。

complianceType: musthave
      objectDefinition:
        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: my-secret-copy
        data: '{{ copyConfigMapData "default" "my-configmap" }}'

さらに、Red Hat Advanced Cluster Management は、sprig オープンソースプロジェクトに含まれる以下のテンプレート関数をサポートします。

ハブクラスターテンプレートは、ポリシーの作成中、または参照されたリソースが更新されたときに、参照されたリソースのデータに解決されます。

更新を手動で開始する必要がある場合は、特別なアノテーション policy.open-cluster-management.io/trigger-update を使用して、テンプレートによって参照されるデータの変更を示します。特別なアノテーション値を変更すると、テンプレート処理が自動的に開始されます。さらに、参照されたリソースの最新のコンテンツが読み取られ、ポリシー定義で更新されます。ポリシー定義は、マネージドクラスターでの処理のために伝達されます。このアノテーションを使用する方法の 1 つは、値を毎回 1 ずつインクリメントすることです。

YAML 文字列表現を使用してオブジェクトテンプレートを設定します。object-template-raw パラメーターは、if-else や range 関数などの高度なテンプレートのユースケースをサポートするオプションのパラメーターです。次の例は、Sea Otter と等しい name キーを持つ defaultの namespace 内の任意の ConfigMap に species-category: mammal ラベルを追加するように定義されています。

object-templates-raw: |
  {{- range (lookup "v1" "ConfigMap" "default" "").items }}
  {{- if eq .data.name "Sea Otter" }}
  - complianceType: musthave
    objectDefinition:
      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: {{ .metadata.name }}
        namespace: {{ .metadata.namespace }}
        labels:
          species-category: mammal
  {{- end }}
  {{- end }}

注記: spec.object-templates と spec.object-templates-raw はオプションですが、2 つのパラメーターフィールドのいずれかを設定する必要があります。

高度なテンプレートを使用して、マネージドクラスターのインフラストラクチャー MachineSet オブジェクトを作成および設定する次のポリシーの例を参照してください。

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: create-infra-machineset
spec:
  remediationAction: enforce
  severity: low
  object-templates-raw: |
    {{- /* Specify the parameters needed to create the MachineSet  */ -}}
    {{- $machineset_role := "infra" }}
    {{- $region := "ap-southeast-1" }}
    {{- $zones := list "ap-southeast-1a" "ap-southeast-1b" "ap-southeast-1c" }}
    {{- $infrastructure_id := (lookup "config.openshift.io/v1" "Infrastructure" "" "cluster").status.infrastructureName }}
    {{- $worker_ms := (index (lookup "machine.openshift.io/v1beta1" "MachineSet" "openshift-machine-api" "").items 0) }}
    {{- /* Generate the MachineSet for each zone as specified  */ -}}
    {{- range $zone := $zones }}
    - complianceType: musthave
      objectDefinition:
        apiVersion: machine.openshift.io/v1beta1
        kind: MachineSet
        metadata:
          labels:
            machine.openshift.io/cluster-api-cluster: {{ $infrastructure_id }}
          name: {{ $infrastructure_id }}-{{ $machineset_role }}-{{ $zone }}
          namespace: openshift-machine-api
        spec:
          replicas: 1
          selector:
            matchLabels:
              machine.openshift.io/cluster-api-cluster: {{ $infrastructure_id }}
              machine.openshift.io/cluster-api-machineset: {{ $infrastructure_id }}-{{ $machineset_role }}-{{ $zone }}
          template:
            metadata:
              labels:
                machine.openshift.io/cluster-api-cluster: {{ $infrastructure_id }}
                machine.openshift.io/cluster-api-machine-role: {{ $machineset_role }}
                machine.openshift.io/cluster-api-machine-type: {{ $machineset_role }}
                machine.openshift.io/cluster-api-machineset: {{ $infrastructure_id }}-{{ $machineset_role }}-{{ $zone }}
            spec:
              metadata:
                labels:
                  node-role.kubernetes.io/{{ $machineset_role }}: ""
              taints:
                - key: node-role.kubernetes.io/{{ $machineset_role }}
                  effect: NoSchedule
              providerSpec:
                value:
                  ami:
                    id: {{ $worker_ms.spec.template.spec.providerSpec.value.ami.id }}
                  apiVersion: awsproviderconfig.openshift.io/v1beta1
                  blockDevices:
                    - ebs:
                        encrypted: true
                        iops: 2000
                        kmsKey:
                          arn: ''
                        volumeSize: 500
                        volumeType: io1
                  credentialsSecret:
                    name: aws-cloud-credentials
                  deviceIndex: 0
                  instanceType: {{ $worker_ms.spec.template.spec.providerSpec.value.instanceType }}
                  iamInstanceProfile:
                    id: {{ $infrastructure_id }}-worker-profile
                  kind: AWSMachineProviderConfig
                  placement:
                    availabilityZone: {{ $zone }}
                    region: {{ $region }}
                  securityGroups:
                    - filters:
                        - name: tag:Name
                          values:
                            - {{ $infrastructure_id }}-worker-sg
                  subnet:
                    filters:
                      - name: tag:Name
                        values:
                          - {{ $infrastructure_id }}-private-{{ $zone }}
                  tags:
                    - name: kubernetes.io/cluster/{{ $infrastructure_id }}
                      value: owned
                  userDataSecret:
                    name: worker-user-data
    {{- end }}

Red Hat Advanced Cluster Management による処理を目的としていないテンプレートを含めて、ポリシーを作成する場合があります。デフォルトでは、Red Hat Advanced Cluster Management は全テンプレートを処理します。

ハブクラスターのテンプレート処理を省略するには、{{ template content }} を {{ `{{ template content }}` }} に変更する必要があります。

または、Policy の ConfigurationPolicy セクションに policy.open-cluster-management.io/disable-templates: "true" のアノテーションを追加します。このアノテーションを追加する場合に、1 つ前の回避策は必要ありません。ConfigurationPolicy のテンプレート処理はバイパスされます。