Settings For JsPolicy Resources

Writing policies for jsPolicy generally means that you need to define two things:

Policy Settings: JsPolicy specifies the type of policy and defines when this policy should apply
Policy Logic: Put the logic into the spec.javascript of a JsPolicy or use a separate JsPolicyBundle that contains the policy logic in the form of base64 encoded, compressed JavaScript code

Configuration#

All relevant settings for policies are stored inside the JsPolicy custom resource and there are three types of options:

Policy Type: Validating, Mutating, or Controller
Policy Trigger: defines for which kind of operations and objects the policy should be exectued
Runtime Settings: define additional parameters that matter during the execution of the policy logic.

Policy Type#

The type of the policy tells jsPolicy what the policy is supposed to do:

mutate the object/payload of a request to the Kubernetes API server (mutating admission control webhook)
validate requests to the Kubernetes API server (validating admission control webhook)
react to Kubernetes Events after an object in your cluster has changed (reconciliation function of a Kubernetes controller)

Learn more about the different Policy Types

The policy type is defined via spec.type and Validating is the default value and may be omitted.

apiVersion: policy.jspolicy.com/v1beta1
kind: JsPolicy
metadata:
  name: "policy-name.company.tld"
spec:
  type: Validating  # other options: Mutating | Controller

Policy Trigger#

Since you do not want all your policies to be executed every time for all interactions with all the objects in your Kubernetes cluster, you can limit for which objects a particular policy should trigger.

The following options may be configured to specify when a particular policy should be triggered:

operations: An array of strings containing Kubernetes CRUD operations, i.e. any combination of CREATE, UPDATE, DELETE
resources: An array of strings stating Kubernetes resources, e.g. pods, deployments, services etc.
scope: A string stating if the operation is Namespaced or Cluster-wide (default value: * (means Namespaced || Cluster))
namespaceSelector: A Kubernetes namespace selector which defines that a policy should only trigger for operations in namespaces with specific attributes (e.g. only namespaces with certain labels)
objectSelector: A Kubernetes object selector which defines that a policy should only trigger for objects with specific attributes (e.g. only objects with certain labels)
matchPolicy: A string stating the Kubernetes match policy which tells Kubernetes how fuzzy the objectSelector shall be applied (either Exact or Equivalent(default))
apiGroups: An array of strings stating Kubernetes API groups (default: * matching any API group)
apiVersions: An array of strings stating Kubernetes API versions (default: * matching any API version)

apiVersion: policy.jspolicy.com/v1beta1
kind: JsPolicy
metadata:
  name: "mutate-images.company.tld"
spec:
  type: Mutating
  operations: ["CREATE", "UPDATE"]
  resources: ["pods", "deployments"]
  scope: Namespaced
  namespaceSelector:
    matchExpressions:               # only trigger for namespaces with label "environment: prod" and/or label "environment: staging"
    - key: environment
      operator: In
      values: ["prod","staging"]
  objectSelector:                   # all trigger for objects with label "live: true"
    matchLabels:
      live: "true"
  matchPolicy: "Equivalent"
  apiGroups: ["*"]
  apiVersions: ["*"]
  # Optional javascript here
  # javascript: if ...

Runtime Settings#

Within the spec of a JsPolicy object, you can also define certain settings that are relevant during the execution of a policy:

violationPolicy: deny (default) or warn (for testing) when the policy logic calls the deny() function
failurePolicy: Fail (default) or Ignore when jsPolicy fails to execute the policy or it aborts with a runtime error
reinvocationPolicy: Reinvocation Policy defines whether JSPolicy is called again as part of the admission evaluation if the object being admitted is modified by other admission plugins after the initial webhook call (IfNeeded) or not (Never, default)
auditPolicy: Log (default) or Skip logging any policy violations (requests that lead to deny()) in the status of this policy
auditLogSize: Maximum number of violations that should be stored in the status of this policy (default: 10 violations)
timeoutSeconds: Maximum number of seconds that the execution of the policy logic may take before jsPolicy aborts the policy execution (default: 10 seconds, maximum is 30)

apiVersion: policy.jspolicy.com/v1beta1
kind: JsPolicy
metadata:
  name: "validate-images.company.tld"
spec:
  operations: ["CREATE", "UPDATE"]
  resources: ["pods", "deployments"]
  violationPolicy: warn
  failurePolicy: Ignore
  reinvocationPolicy: IfNeeded
  auditPolicy: Skip
  timeoutSeconds: 30