From 9636e992689e0760b502f5f627d695c3546ca319 Mon Sep 17 00:00:00 2001 From: Prachi Damle Date: Tue, 14 Apr 2020 01:16:22 -0700 Subject: [PATCH 1/3] Docs on how to create OPA Gatekeeper constraints using default templates --- .../tools/opa-gatekeper/_index.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) diff --git a/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md index 12c951c6279..043e4bc2a4e 100644 --- a/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md @@ -45,6 +45,8 @@ When OPA Gatekeeper is enabled, Rancher installs some templates by default. To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on **Templates.** +For detailed steps on how to create constraints using these default templates, please refer [this section below](#Using-the-Default-Constraint-Templates) + Rancher also provides the ability to create your own constraint templates by importing YAML definitions. # Creating and Configuring Constraints @@ -95,3 +97,117 @@ The detail view of each constraint lists information about the resource that vio **Result:** Upon disabling OPA Gatekeeper, all constraint templates and constraints will also be deleted. +# Using the Default Constraint Templates + +When OPA Gatekeeper is enabled, Rancher installs some templates by default. Currently there are following templates installed: + +1. **k8sallowedrepos** - Template that can be used to whitelist registries. +1. **k8srequiredlabels** - Template that can be used to enforce desired Labels on specific Kubernetes objects. + +This section describes how to use these templates to create constraints for enforcing certain policies on the cluster via the **Dashboard** view. + +Currently it is not possible to create a constraint via "Edit as Form" by passing non-scalar parameters, but one can create it by using the **Edit As YAML** option. + +The constraint created can be edited using the form. + +## Constraint to whitelist registries + +Suppose you want to apply a policy that restricts creation of any Pods in your cluster to use images from a particular repository only, + +then you can create a constraint from the **k8sallowedrepos** template. + +For example, suppose we want all "Pods" launched in the namespace "test" to use images only from "quay.io" registry. + +Steps to do that via Rancher's dashboard view are as follows: +1. Enable OPA Gatekeeper using the cluster's **Dashboard** view +1. Navigate to OPA Gatekeeper -> Constraints -> Create +1. Use the **Edit As YAML** option on the right hand corner of the Create Form; paste the following yaml and click **Create** to add the constraint +1. The yaml specifies the parameter "repos" as defined by the "k8sallowedrepos" template schema. +1. This constraint specifies that the image repository "quay.io" should be used by all "Pod" objects in "test" namespace. +1. Notice that all the system namespaces are by default added to list of "excludedNamespaces" + + ```yml + type: constraints.gatekeeper.sh.k8sallowedrepos + spec: + match: + excludedNamespaces: + - cattle-system + - gatekeeper-system + - ingress-nginx + - kube-node-lease + - kube-public + - kube-system + - security-scan + kinds: + - apiGroups: [""] + kinds: ["Pod"] + namespaces: + - "test" + labelSelector: + matchExpressions: [] + namespaceSelector: + matchExpressions: [] + parameters: + repos: + - "quay.io" + enforcementAction: deny + metadata: + name: test-repo-is-quay-io + annotations: + cattle.io/description: whitelist repo quay.io + ``` + +1. After the above constraint is created, it will be listed under "K8sAllowedRepos" on the "Constraints" page. +1. You can edit the constraint via form to change the namespaces and other information. +1. Now if you navigate **Back to Rancher** and create a workload under "test" namespace with any image other than the "quay.io" registry, +you will get an error from OPA Gatekeeper. + + +## Constraint to enforce Labels + +Suppose you want to apply a policy that requires certain set of Labels present on Kubernetes resources of specific Kind, then you can create a constraint from the **k8srequiredlabels** template. + +For example, suppose we want all "Namespaces" in the cluster to have labels "test". + +Steps to do that via Rancher's dashboard view are as follows: +1. Enable OPA Gatekeeper using the cluster's **Dashboard** view. +1. Navigate to OPA Gatekeeper -> Constraints -> Create. +1. Use the **Edit As YAML** option on the right hand corner of the Create Form; paste the following yaml and click **Create** to add the constraint. +1. The yaml specifies the parameters "message" and "labels" as defined by the "k8srequiredlabels" template schema. +1. This constraint defines that all "namespaces" must have a label "team" whose value should match the given "allowedRegex". +1. Notice that all the system namespaces are by default added to list of "excludedNamespaces". + + ```yml + type: constraints.gatekeeper.sh.k8srequiredlabels + spec: + match: + excludedNamespaces: + - cattle-system + - gatekeeper-system + - ingress-nginx + - kube-node-lease + - kube-public + - kube-system + - security-scan + kinds: + - apiGroups: [""] + kinds: ["Namespace"] + labelSelector: + matchExpressions: [] + namespaceSelector: + matchExpressions: [] + parameters: + message: "All namespaces must have an `team` label that points to your team name" + labels: + - key: team + allowedRegex: "^[a-zA-Z]+$" + enforcementAction: deny + metadata: + name: ns-must-have-label + annotations: + cattle.io/description: constraint for ns label + ``` + +1. After the above constraint is created, it will be listed under "K8sRequiredLabels" on the "Constraints" page. +1. You can edit the constraint via form to change the namespaces and other information. +1. Now if you navigate **Back to Rancher** and create a new namespace in the cluster without having the label "team", the create request should be denied. From cddcdfda78974d61cf7abeccd93c69dc0593fe1b Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 14 Apr 2020 12:42:51 -0700 Subject: [PATCH 2/3] Edit docs about default constraint templates --- .../tools/opa-gatekeper/_index.md | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md index 043e4bc2a4e..01b319bf31d 100644 --- a/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md @@ -45,7 +45,7 @@ When OPA Gatekeeper is enabled, Rancher installs some templates by default. To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on **Templates.** -For detailed steps on how to create constraints using these default templates, please refer [this section below](#Using-the-Default-Constraint-Templates) +For detailed steps on how to create constraints using these default templates, please refer [this section below](#using-the-default-constraint-templates) Rancher also provides the ability to create your own constraint templates by importing YAML definitions. @@ -99,34 +99,31 @@ The detail view of each constraint lists information about the resource that vio # Using the Default Constraint Templates -When OPA Gatekeeper is enabled, Rancher installs some templates by default. Currently there are following templates installed: +When OPA Gatekeeper is enabled, Rancher installs some templates by default. Currently the following constraint templates are installed: 1. **k8sallowedrepos** - Template that can be used to whitelist registries. -1. **k8srequiredlabels** - Template that can be used to enforce desired Labels on specific Kubernetes objects. +1. **k8srequiredlabels** - Template that can be used to enforce desired labels on specific Kubernetes objects. This section describes how to use these templates to create constraints for enforcing certain policies on the cluster via the **Dashboard** view. -Currently it is not possible to create a constraint via "Edit as Form" by passing non-scalar parameters, but one can create it by using the **Edit As YAML** option. +Currently it is not possible to create a constraint via "Edit as Form" by passing non-scalar parameters, but one can create them by using the **Edit As YAML** option. The constraint created can be edited using the form. -## Constraint to whitelist registries +### Constraint to Whitelist Registries -Suppose you want to apply a policy that restricts creation of any Pods in your cluster to use images from a particular repository only, +Suppose you want to apply a policy that restricts creation of any pods in your cluster to use images only from a whitelisted repository. In this case, you would create a constraint from the **k8sallowedrepos** template. -then you can create a constraint from the **k8sallowedrepos** template. - -For example, suppose we want all "Pods" launched in the namespace "test" to use images only from "quay.io" registry. +For example, suppose we want all pods launched in the namespace `test` to use images only from the quay.io registry. Steps to do that via Rancher's dashboard view are as follows: -1. Enable OPA Gatekeeper using the cluster's **Dashboard** view -1. Navigate to OPA Gatekeeper -> Constraints -> Create -1. Use the **Edit As YAML** option on the right hand corner of the Create Form; paste the following yaml and click **Create** to add the constraint -1. The yaml specifies the parameter "repos" as defined by the "k8sallowedrepos" template schema. -1. This constraint specifies that the image repository "quay.io" should be used by all "Pod" objects in "test" namespace. -1. Notice that all the system namespaces are by default added to list of "excludedNamespaces" - ```yml +> **Prerequisite:** OPA Gatekeeper must be enabled using the cluster's **Dashboard** view. + +1. Navigate to **OPA Gatekeeper > Constraints > Create.** +1. Use the **Edit As YAML** option on the right hand corner of the Create form. Paste the following YAML and click **Create** to add the constraint: + + ```yaml type: constraints.gatekeeper.sh.k8sallowedrepos spec: match: @@ -156,28 +153,27 @@ Steps to do that via Rancher's dashboard view are as follows: annotations: cattle.io/description: whitelist repo quay.io ``` + + The YAML specifies the directive `repos` as defined by the `k8sallowedrepos` template schema. -1. After the above constraint is created, it will be listed under "K8sAllowedRepos" on the "Constraints" page. -1. You can edit the constraint via form to change the namespaces and other information. -1. Now if you navigate **Back to Rancher** and create a workload under "test" namespace with any image other than the "quay.io" registry, -you will get an error from OPA Gatekeeper. + This constraint specifies that the image repository "quay.io" should be used by all pod objects in the `test` namespace. Notice that all the system namespaces are by default added to the list of `excludedNamespaces`. After the above constraint is created, it will be listed under "K8sAllowedRepos" on the "Constraints" page. You can edit the constraint via the form to change the namespaces and other information. +**Result:** Now if you navigate **Back to Rancher** and create a workload under the `test` namespace with any image other than the "quay.io" registry, you will get an error from OPA Gatekeeper. -## Constraint to enforce Labels +### Constraint to Enforce Labels -Suppose you want to apply a policy that requires certain set of Labels present on Kubernetes resources of specific Kind, then you can create a constraint from the **k8srequiredlabels** template. +Suppose you want to apply a policy that requires certain set of labels present on Kubernetes resources of a specific kind, then you can create a constraint from the **k8srequiredlabels** template. -For example, suppose we want all "Namespaces" in the cluster to have labels "test". +For example, suppose we want all namespaces in the cluster to be labeled with the name of a team. Steps to do that via Rancher's dashboard view are as follows: -1. Enable OPA Gatekeeper using the cluster's **Dashboard** view. -1. Navigate to OPA Gatekeeper -> Constraints -> Create. -1. Use the **Edit As YAML** option on the right hand corner of the Create Form; paste the following yaml and click **Create** to add the constraint. -1. The yaml specifies the parameters "message" and "labels" as defined by the "k8srequiredlabels" template schema. -1. This constraint defines that all "namespaces" must have a label "team" whose value should match the given "allowedRegex". -1. Notice that all the system namespaces are by default added to list of "excludedNamespaces". - ```yml +> **Prerequisite:** OPA Gatekeeper must be enabled using the cluster's **Dashboard** view. + +1. Navigate to OPA Gatekeeper > Constraints > Create. +1. Use the **Edit As YAML** option on the right hand corner of the Create form. Paste the following yaml and click **Create** to add the constraint: + + ```yaml type: constraints.gatekeeper.sh.k8srequiredlabels spec: match: @@ -197,7 +193,7 @@ Steps to do that via Rancher's dashboard view are as follows: namespaceSelector: matchExpressions: [] parameters: - message: "All namespaces must have an `team` label that points to your team name" + message: "All namespaces must have a `team` label that points to your team name" labels: - key: team allowedRegex: "^[a-zA-Z]+$" @@ -207,7 +203,11 @@ Steps to do that via Rancher's dashboard view are as follows: annotations: cattle.io/description: constraint for ns label ``` + + The YAML specifies the directives `message` and `labels` as defined by the **k8srequiredlabels** template schema. This constraint defines that all"namespaces must have a label `team` whose value should match the given "allowedRegex". Notice that all the system namespaces are by default added to list of `excludedNamespaces`. -1. After the above constraint is created, it will be listed under "K8sRequiredLabels" on the "Constraints" page. -1. You can edit the constraint via form to change the namespaces and other information. -1. Now if you navigate **Back to Rancher** and create a new namespace in the cluster without having the label "team", the create request should be denied. + After the above constraint is created, it will be listed under "K8sRequiredLabels" on the "Constraints" page. + + You can edit the constraint via the form to change the namespaces and other information. + +**Result:** Now if you navigate **Back to Rancher** and create a new namespace in the cluster without having the label `team`, the create request should be denied. From 2c3f255f67cd545818c93a1b800ca9fc38de846c Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 14 Apr 2020 12:48:41 -0700 Subject: [PATCH 3/3] Minor fixes --- .../tools/opa-gatekeper/_index.md | 24 +++++++++---------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md index 01b319bf31d..8955be1bf2e 100644 --- a/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/opa-gatekeper/_index.md @@ -45,7 +45,7 @@ When OPA Gatekeeper is enabled, Rancher installs some templates by default. To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on **Templates.** -For detailed steps on how to create constraints using these default templates, please refer [this section below](#using-the-default-constraint-templates) +For detailed steps on how to create constraints using these default templates, please refer to [this section.](#using-the-default-constraint-templates) Rancher also provides the ability to create your own constraint templates by importing YAML definitions. @@ -101,8 +101,8 @@ The detail view of each constraint lists information about the resource that vio When OPA Gatekeeper is enabled, Rancher installs some templates by default. Currently the following constraint templates are installed: -1. **k8sallowedrepos** - Template that can be used to whitelist registries. -1. **k8srequiredlabels** - Template that can be used to enforce desired labels on specific Kubernetes objects. +1. `k8sallowedrepos` - Template that can be used to whitelist registries. +1. `k8srequiredlabels` - Template that can be used to enforce desired labels on specific Kubernetes objects. This section describes how to use these templates to create constraints for enforcing certain policies on the cluster via the **Dashboard** view. @@ -112,13 +112,13 @@ The constraint created can be edited using the form. ### Constraint to Whitelist Registries -Suppose you want to apply a policy that restricts creation of any pods in your cluster to use images only from a whitelisted repository. In this case, you would create a constraint from the **k8sallowedrepos** template. +Suppose you want to apply a policy that restricts creation of any pods in your cluster to use images only from a whitelisted repository. In this case, you would create a constraint from the `k8sallowedrepos` template. For example, suppose we want all pods launched in the namespace `test` to use images only from the quay.io registry. Steps to do that via Rancher's dashboard view are as follows: -> **Prerequisite:** OPA Gatekeeper must be enabled using the cluster's **Dashboard** view. +> **Prerequisite:** OPA Gatekeeper must be enabled using the cluster's Dashboard view. 1. Navigate to **OPA Gatekeeper > Constraints > Create.** 1. Use the **Edit As YAML** option on the right hand corner of the Create form. Paste the following YAML and click **Create** to add the constraint: @@ -156,19 +156,19 @@ Steps to do that via Rancher's dashboard view are as follows: The YAML specifies the directive `repos` as defined by the `k8sallowedrepos` template schema. - This constraint specifies that the image repository "quay.io" should be used by all pod objects in the `test` namespace. Notice that all the system namespaces are by default added to the list of `excludedNamespaces`. After the above constraint is created, it will be listed under "K8sAllowedRepos" on the "Constraints" page. You can edit the constraint via the form to change the namespaces and other information. + This constraint specifies that the image repository "quay.io" should be used by all pod objects in the `test` namespace. Notice that all the system namespaces are by default added to the list of `excludedNamespaces`. You can edit the constraint via the form to change the namespaces and other information. -**Result:** Now if you navigate **Back to Rancher** and create a workload under the `test` namespace with any image other than the "quay.io" registry, you will get an error from OPA Gatekeeper. +**Result:** After the above constraint is created, it will be listed under `K8sAllowedRepos` on the **Constraints** page. Now if you navigate **Back to Rancher** and create a workload under the `test` namespace with any image other than the "quay.io" registry, you will get an error from OPA Gatekeeper. ### Constraint to Enforce Labels -Suppose you want to apply a policy that requires certain set of labels present on Kubernetes resources of a specific kind, then you can create a constraint from the **k8srequiredlabels** template. +Suppose you want to apply a policy that requires certain set of labels present on Kubernetes resources of a specific kind, then you can create a constraint from the `k8srequiredlabels` template. For example, suppose we want all namespaces in the cluster to be labeled with the name of a team. Steps to do that via Rancher's dashboard view are as follows: -> **Prerequisite:** OPA Gatekeeper must be enabled using the cluster's **Dashboard** view. +> **Prerequisite:** OPA Gatekeeper must be enabled using the cluster's Dashboard view. 1. Navigate to OPA Gatekeeper > Constraints > Create. 1. Use the **Edit As YAML** option on the right hand corner of the Create form. Paste the following yaml and click **Create** to add the constraint: @@ -204,10 +204,8 @@ Steps to do that via Rancher's dashboard view are as follows: cattle.io/description: constraint for ns label ``` - The YAML specifies the directives `message` and `labels` as defined by the **k8srequiredlabels** template schema. This constraint defines that all"namespaces must have a label `team` whose value should match the given "allowedRegex". Notice that all the system namespaces are by default added to list of `excludedNamespaces`. - - After the above constraint is created, it will be listed under "K8sRequiredLabels" on the "Constraints" page. + The YAML specifies the directives `message` and `labels` as defined by the `k8srequiredlabels` template schema. This constraint defines that all"namespaces must have a label `team` whose value should match the given "allowedRegex". Notice that all the system namespaces are by default added to list of `excludedNamespaces`. You can edit the constraint via the form to change the namespaces and other information. -**Result:** Now if you navigate **Back to Rancher** and create a new namespace in the cluster without having the label `team`, the create request should be denied. +**Result:** After the above constraint is created, it will be listed under `K8sRequiredLabels` on the **Constraints** page. Now if you navigate **Back to Rancher** and create a new namespace in the cluster without having the label `team`, the create request should be denied.