From d778cbb257d4f2d830abb2f545390589b7de515c Mon Sep 17 00:00:00 2001 From: Erki Koop Date: Fri, 6 Oct 2023 17:03:12 +0300 Subject: [PATCH 1/2] Add mutation policy documentation Signed-off-by: Erki Koop --- docs/resources/mutation_policy.md | 872 ++++++++++++++++++++ templates/resources/mutation_policy.md.tmpl | 109 +++ 2 files changed, 981 insertions(+) create mode 100644 docs/resources/mutation_policy.md create mode 100644 templates/resources/mutation_policy.md.tmpl diff --git a/docs/resources/mutation_policy.md b/docs/resources/mutation_policy.md new file mode 100644 index 000000000..35e421f6e --- /dev/null +++ b/docs/resources/mutation_policy.md @@ -0,0 +1,872 @@ +--- +Title: "Mutation Policy Resource" +Description: |- + Creating the Tanzu Kubernetes mutation policy resource. +--- + +# Mutation Policy + +The `tanzu-mission-control_mutation_policy` resource enables you to attach a mutation policy with an input recipe to a organisation, cluster group, or a cluster for management through Tanzu Mission Control. + +## Input Recipe + +In the Tanzu Mission Control mutation policy resource, there are three system defined types of mutation templates that you can use: +- **annotation** +- **label** +- **pod-security** + +## Policy Scope and Inheritance + +In the Tanzu Mission Control resource hierarchy, there are three levels at which you can specify mutation policy resources: +- **organization** - `organization` block under `scope` sub-resource +- **object groups** - `cluster_group` block under `scope` sub-resource +- **Kubernetes objects** - `cluster` block under `scope` sub-resource + +**Note:** +The scope parameter is mandatory in the schema and the user needs to add one of the defined scopes to the script for the provider to function. +Only one scope per resource is allowed. + +## Target Kubernetes Resources + +Label and annotation mutation policy recipes contain a Kubernetes Resource spec that contains `api_groups` and `kind` as sub fields. +These attributes are of the kind `[]string` which the policy API supports. In terraform, while declaring multiple +`api_groups` and `kinds` under one block of `target_kubernetes_resources` is validated by the API but not reflected on the UI. +For UI comparison with Terraform, one must add multiple blocks of `target_kubernetes_resources`, each containing a API Group and a Kind. + +Example: + +``` +target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] +} +target_kubernetes_resources { + api_groups = [ + "batch", + ] + kinds = [ + "Pod", + ] +} +``` + +## Cluster scoped annotation Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "cluster_annotation_mutation_policy" { + name = "tf-mutation-test" + + scope { + cluster { + management_cluster_name = "attached" + provisioner_name = "attached" + name = "test" + } + } + spec { + input { + annotation { + target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] + } + scope = "*" + annotation { + key = "test" + value = "optional" + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Cluster scoped label Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "cluster_label_mutation_policy" { + name = "tf-mutation-test" + + scope { + cluster { + management_cluster_name = "attached" + provisioner_name = "attached" + name = "test" + } + } + + spec { + input { + label { + target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] + } + scope = "*" + label { + key = "test" + value = "optional" + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Cluster scoped pod-security Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "cluster_pod_security_mutation_policy" { + name = "tf-mutation-test" + + scope { + cluster { + management_cluster_name = "attached" + provisioner_name = "attached" + name = "test" + } + } + + spec { + input { + pod_security { + allow_privilege_escalation { + condition = "Always" + value = true + } + capabilities_add { + operation = "merge" + values = ["AUDIT_CONTROL", "AUDIT_WRITE"] + } + capabilities_drop { + operation = "merge" + values = ["AUDIT_WRITE"] + } + fs_group { + condition = "Always" + value = 0 + } + privileged { + condition = "Always" + value = true + } + read_only_root_filesystem { + condition = "Always" + value = true + } + run_as_group { + condition = "Always" + value = 0 + } + run_as_non_root { + condition = "Always" + value = true + } + run_as_user { + condition = "Always" + value = 0 + } + se_linux_options { + condition = "Always" + level = "test" + user = "test" + role = "test" + type = "test" + } + supplemental_groups { + condition = "Always" + values = [0, 1, 2, 3] + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Cluster group scoped annotation Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "cluster_group_annotation_mutation_policy" { + name = "tf-mutation-test" + + scope { + cluster_group { + cluster_group = "tf-create-test" + } + } + + spec { + input { + annotation { + target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] + } + scope = "*" + annotation { + key = "test" + value = "optional" + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Cluster group scoped label Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "cluster_group_label_mutation_policy" { + name = "tf-mutation-test" + + scope { + cluster_group { + cluster_group = "tf-create-test" + } + } + + spec { + input { + label { + target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] + } + scope = "*" + label { + key = "test" + value = "optional" + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Cluster group scoped pod-security Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "cluster_group_pod_security_mutation_policy" { + name = "tf-mutation-test" + + scope { + cluster_group { + cluster_group = "tf-create-test" + } + } + + spec { + input { + pod_security { + allow_privilege_escalation { + condition = "Always" + value = true + } + capabilities_add { + operation = "merge" + values = ["AUDIT_CONTROL", "AUDIT_WRITE"] + } + capabilities_drop { + operation = "merge" + values = ["AUDIT_WRITE"] + } + fs_group { + condition = "Always" + value = 0 + } + privileged { + condition = "Always" + value = true + } + read_only_root_filesystem { + condition = "Always" + value = true + } + run_as_group { + condition = "Always" + value = 0 + } + run_as_non_root { + condition = "Always" + value = true + } + run_as_user { + condition = "Always" + value = 0 + } + se_linux_options { + condition = "Always" + level = "test" + user = "test" + role = "test" + type = "test" + } + supplemental_groups { + condition = "Always" + values = [0, 1, 2, 3] + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Organization scoped annotation Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "org_annotation_mutation_policy" { + name = "tf-mutation-test" + + scope { + organization { + organization = "dummy-id" + } + } + + spec { + input { + annotation { + target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] + } + scope = "*" + annotation { + key = "test" + value = "optional" + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Organization scoped label Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "org_label_mutation_policy" { + name = "tf-mutation-test" + + scope { + organization { + organization = "dummy-id" + } + } + + spec { + input { + label { + target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] + } + scope = "Cluster" + label { + key = "test" + value = "optional" + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + +## Organization scoped pod-security Mutation Policy + +### Example Usage + +```terraform +resource "tanzu-mission-control_mutation_policy" "org_pod_security_mutation_policy" { + name = "tf-mutation-test" + + scope { + organization { + organization = "dummy-id" + } + } + + spec { + input { + pod_security { + allow_privilege_escalation { + condition = "Always" + value = true + } + capabilities_add { + operation = "merge" + values = ["AUDIT_CONTROL", "AUDIT_WRITE"] + } + capabilities_drop { + operation = "merge" + values = ["AUDIT_WRITE"] + } + fs_group { + condition = "Always" + value = 0 + } + privileged { + condition = "Always" + value = true + } + read_only_root_filesystem { + condition = "Always" + value = true + } + run_as_group { + condition = "Always" + value = 0 + } + run_as_non_root { + condition = "Always" + value = true + } + run_as_user { + condition = "Always" + value = 0 + } + se_linux_options { + condition = "Always" + level = "level_test" + user = "user_test" + role = "role_test" + type = "type_test" + } + supplemental_groups { + condition = "Always" + values = [0, 1, 2, 3] + } + } + } + namespace_selector { + match_expressions = [ + { + key = "component" + operator = "NotIn" + values = [ + "api-server", + "agent-gateway" + ] + }, + ] + } + } +} +``` + + +## Schema + +### Required + +- `name` (String) Name of the mutation policy +- `scope` (Block List, Min: 1, Max: 1) Scope for the mutation, custom, security, image, network and namespace quota policy, having one of the valid scopes for mutation, custom, security and namespace quota policy: cluster, cluster_group or organization and valid scopes for image and network policy: workspace or organization. (see [below for nested schema](#nestedblock--scope)) +- `spec` (Block List, Min: 1, Max: 1) Spec for the mutation policy (see [below for nested schema](#nestedblock--spec)) + +### Optional + +- `meta` (Block List, Max: 1) Metadata for the resource (see [below for nested schema](#nestedblock--meta)) + +### Read-Only + +- `id` (String) The ID of this resource. + + +### Nested Schema for `scope` + +Optional: + +- `cluster` (Block List, Max: 1) The schema for cluster policy full name (see [below for nested schema](#nestedblock--scope--cluster)) +- `cluster_group` (Block List, Max: 1) The schema for cluster group policy full name (see [below for nested schema](#nestedblock--scope--cluster_group)) +- `organization` (Block List, Max: 1) The schema for organization policy full name (see [below for nested schema](#nestedblock--scope--organization)) + + +### Nested Schema for `scope.cluster` + +Required: + +- `name` (String) Name of this cluster + +Optional: + +- `management_cluster_name` (String) Name of the management cluster +- `provisioner_name` (String) Provisioner of the cluster + + + +### Nested Schema for `scope.cluster_group` + +Required: + +- `cluster_group` (String) Name of this cluster group + + + +### Nested Schema for `scope.organization` + +Required: + +- `organization` (String) ID of this organization + + + + +### Nested Schema for `spec` + +Required: + +- `input` (Block List, Min: 1, Max: 1) Input for the mutation policy, having one of the valid recipes: annotation, label or pod-security. (see [below for nested schema](#nestedblock--spec--input)) + +Optional: + +- `namespace_selector` (Block List, Max: 1) Label based Namespace Selector for the policy (see [below for nested schema](#nestedblock--spec--namespace_selector)) + + +### Nested Schema for `spec.input` + +Optional: + +- `annotation` (Block List, Max: 1) The input schema for mutation policy annotation recipe version v1 (see [below for nested schema](#nestedblock--spec--input--annotation)) +- `label` (Block List, Max: 1) The input schema for mutation policy label recipe version v1 (see [below for nested schema](#nestedblock--spec--input--label)) +- `pod_security` (Block List, Max: 1) The input schema for mutation policy pod_security recipe version v1 (see [below for nested schema](#nestedblock--spec--input--pod_security)) + + +### Nested Schema for `spec.input.annotation` + +Required: + +- `target_kubernetes_resources` (Block List, Min: 1) A list of kubernetes api resources on which the policy will be enforced, identified using apiGroups and kinds. (see [below for nested schema](#nestedblock--spec--input--annotation--target_kubernetes_resources)) +- `annotation` (Block List, Min: 1) Annotation key and value pair. (see [below for nested schema](#nestedblock--spec--input--annotation--annotation)) + +Optional: + +- `scope` (String) Scope of the resource. (`*`, `Cluster`, `Namespaced`) + + +### Nested Schema for `spec.input.annotation.target_kubernetes_resources` + +Required: + +- `api_groups` (List of String) APIGroup is a group containing the resource type. +- `kinds` (List of String) Kind is the name of the object schema (resource type). + + +### Nested Schema for `spec.input.annotation.annotation` + +Required: + +- `key` Key segment of the annotation. +- `value` Value segment of the annotation. + + +### Nested Schema for `spec.input.label` + +Required: + +- `target_kubernetes_resources` (Block List, Min: 1) A list of kubernetes api resources on which the policy will be enforced, identified using apiGroups and kinds. (see [below for nested schema](#nestedblock--spec--input--label--target_kubernetes_resources)) +- `label` (Block List, Min: 1) Annotation key and value pair. (see [below for nested schema](#nestedblock--spec--input--label--label)) + +Optional: + +- `scope` (String) Scope of the resource. (`*`, `Cluster`, `Namespaced`) + + +### Nested Schema for `spec.input.label.target_kubernetes_resources` + +Required: + +- `api_groups` (List of String) APIGroup is a group containing the resource type. +- `kinds` (List of String) Kind is the name of the object schema (resource type). + + +### Nested Schema for `spec.input.label.label` + +Required: + +- `key` Key segment of the label. +- `value` Value segment of the label. + + +### Nested Schema for `spec.input.pod_security` + +Optional: + +- `allow_privilege_escalation` (Block List, Max: 1) Allow privilege escalation (see [below for nested schema](#nestedblock--spec--input--pod_security--allow_privilege_escalation)) +- `capabilities_add` (Block List, Max: 1) Capabilities add (see [below for nested schema](#nestedblock--spec--input--pod_security--capabilities_add)) +- `capabilities_drop` (Block List, Max: 1) Capabilities drop (see [below for nested schema](#nestedblock--spec--input--pod_security--capabilities_drop)) +- `fs_group` (Block List, Max: 1) fsGroup (see [below for nested schema](#nestedblock--spec--input--pod_security--fs_group)) +- `privileged` (Block List, Max: 1) Privileged (see [below for nested schema](#nestedblock--spec--input--pod_security--privileged)) +- `read_only_root_filesystem` (Block List, Max: 1) Read only root filesystem (see [below for nested schema](#nestedblock--spec--input--pod_security--read_only_root_filesystem)) +- `run_as_group` (Block List, Max: 1) Run as group (see [below for nested schema](#nestedblock--spec--input--pod_security--run_as_group)) +- `run_as_non_root` (Block List, Max: 1) Run as non-root (see [below for nested schema](#nestedblock--spec--input--pod_security--run_as_non_root)) +- `run_as_user` (Block List, Max: 1) Run as user (see [below for nested schema](#nestedblock--spec--input--pod_security--run_as_user)) +- `se_linux_options` (Block List, Max: 1) SE Linux options (see [below for nested schema](#nestedblock--spec--input--pod_security--se_linux_options)) +- `supplemental_groups` (Block List, Max: 1) Supplemental groups (see [below for nested schema](#nestedblock--spec--input--pod_security--supplemental_groups)) + + +### Nested Schema for `spec.input.pod_security.allow_privilege_escalation` + +Required: + +- `condition` (String) Defined condition, Always, IfFieldExists or IfFieldDoesNotExist. +- `value` (Boolean) Value of defined condition. + + +### Nested Schema for `spec.input.pod_security.capabilities_add` + +Required: + +- `operation` (String) Option to either override the list or merge values into the list or prune values from the list. +- `values` (Map of String) List of values to override/merge/prune in capabilities.add field in container security context. + + +### Nested Schema for `spec.input.pod_security.capabilities_drop` + +Required: + +- `operation` (String) Option to either override the list or merge values into the list or prune values from the list. +- `values` (Map of String) List of values to override/merge/prune in capabilities.drop field in container security context + + +### Nested Schema for `spec.input.pod_security.fs_group` + +Required: + +- `condition` (String) Value to set for fsGroup field in pod security context. +- `value` (Number) Condition specifies whether to always mutate/set this value or only if pod security context contains or does not contain this field + + +### Nested Schema for `spec.input.pod_security.privileged` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field. +- `value` (Boolean) Value to set for privileged field in container security context. + + +### Nested Schema for `spec.input.pod_security.read_only_root_filesystem` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field. +- `value` (Boolean) Value to set for privileged field + + +### Nested Schema for `spec.input.pod_security.run_as_group` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field. +- `value` (Number) Value to set for runAsGroup field in container security context. + + +### Nested Schema for `spec.input.pod_security.run_as_non_root` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field. +- `value` (Boolean) Value to set for run_as_non_root field in container security context + + +### Nested Schema for `spec.input.pod_security.run_as_user` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field +- `value` (Number) Value to set for run_as_user field in container security context + + +### Nested Schema for `spec.input.pod_security.se_linux_options` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field. + +Optional: + +- `level` (String) SELinux level +- `role` (String) SELinux role +- `type` (String) SELinux type +- `user` (String) SELinux user + + +### Nested Schema for `spec.input.pod_security.supplemental_groups` + +Required: + +- `condition` (String) Condition specifies whether to always mutate/set this value or only if container security context contains or does not contain this field +- `values` (Map of Number) List of values to set for supplemental_groups field in pod security context. + + + +### Nested Schema for `spec.namespace_selector` + +Required: + +- `match_expressions` (Block List, Min: 1) Match expressions is a list of label selector requirements, the requirements are ANDed (see [below for nested schema](#nestedblock--spec--namespace_selector--match_expressions)) + + +### Nested Schema for `spec.namespace_selector.match_expressions` + +Required: + +- `values` (List of String) Values is an array of string values + +Optional: + +- `key` (String) Key is the label key that the selector applies to +- `operator` (String) Operator represents a key's relationship to a set of values + + + +### Nested Schema for `meta` + +Optional: + +- `annotations` (Map of String) Annotations for the resource +- `description` (String) Description of the resource +- `labels` (Map of String) Labels for the resource + +Read-Only: + +- `resource_version` (String) Resource version of the resource +- `uid` (String) UID of the resource diff --git a/templates/resources/mutation_policy.md.tmpl b/templates/resources/mutation_policy.md.tmpl new file mode 100644 index 000000000..ae8f750f8 --- /dev/null +++ b/templates/resources/mutation_policy.md.tmpl @@ -0,0 +1,109 @@ +--- +Title: "Mutation Policy Resource" +Description: |- + Creating the Tanzu Kubernetes mutation policy resource. +--- + +# Mutation Policy + +The `tanzu-mission-control_mutation_policy` resource enables you to attach a mutation policy with an input recipe to a organisation, cluster group, or a cluster for management through Tanzu Mission Control. + +## Input Recipe + +In the Tanzu Mission Control mutation policy resource, there are three system defined types of mutation templates that you can use: +- **annotation** +- **label** +- **pod-security** + +## Policy Scope and Inheritance + +In the Tanzu Mission Control resource hierarchy, there are three levels at which you can specify mutation policy resources: +- **organization** - `organization` block under `scope` sub-resource +- **object groups** - `cluster_group` block under `scope` sub-resource +- **Kubernetes objects** - `cluster` block under `scope` sub-resource + +**Note:** +The scope parameter is mandatory in the schema and the user needs to add one of the defined scopes to the script for the provider to function. +Only one scope per resource is allowed. + +## Target Kubernetes Resources + +Label and annotation mutation policy recipes contain a Kubernetes Resource spec that contains `api_groups` and `kind` as sub fields. +These attributes are of the kind `[]string` which the policy API supports. In terraform, while declaring multiple +`api_groups` and `kinds` under one block of `target_kubernetes_resources` is validated by the API but not reflected on the UI. +For UI comparison with Terraform, one must add multiple blocks of `target_kubernetes_resources`, each containing a API Group and a Kind. + +Example: + +``` +target_kubernetes_resources { + api_groups = [ + "apps", + ] + kinds = [ + "Event", + ] +} +target_kubernetes_resources { + api_groups = [ + "batch", + ] + kinds = [ + "Pod", + ] +} +``` + +## Cluster scoped annotation Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_cluster_scoped_annotation_mutation_policy.tf" }} + +## Cluster scoped label Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_cluster_scoped_label_mutation_policy.tf" }} + +## Cluster scoped pod-security Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_cluster_scoped_pod_security_mutation_policy.tf" }} + +## Cluster group scoped annotation Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_cluster_group_scoped_annotation_mutation_policy.tf" }} + +## Cluster group scoped label Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_cluster_group_scoped_label_mutation_policy.tf" }} + +## Cluster group scoped pod-security Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_cluster_group_scoped_pod_security_mutation_policy.tf" }} + +## Organization scoped annotation Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_organization_scoped_annotation_mutation_policy.tf" }} + +## Organization scoped label Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_organization_scoped_label_mutation_policy.tf" }} + +## Organization scoped pod-security Mutation Policy + +### Example Usage + +{{ tffile "examples/resources/mutation_policy/resource_organization_scoped_pod_security_mutation_policy.tf" }} From 8e14d1caf847ffaf2f08067bd953ef99dff2b13f Mon Sep 17 00:00:00 2001 From: Erki Koop Date: Sun, 15 Oct 2023 16:38:05 +0300 Subject: [PATCH 2/2] Add review changes Signed-off-by: Erki Koop --- templates/resources/mutation_policy.md.tmpl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/templates/resources/mutation_policy.md.tmpl b/templates/resources/mutation_policy.md.tmpl index ae8f750f8..d07a4cb8c 100644 --- a/templates/resources/mutation_policy.md.tmpl +++ b/templates/resources/mutation_policy.md.tmpl @@ -107,3 +107,5 @@ target_kubernetes_resources { ### Example Usage {{ tffile "examples/resources/mutation_policy/resource_organization_scoped_pod_security_mutation_policy.tf" }} + +{{ .SchemaMarkdown | trimspace }}