Skip to main content

3. Create & Test Policies

To write a policy with JsPolicy, we need to do two things:

  1. Configure the Policy Settings via the JsPolicy resource
  2. Add Policy Logic either via embedding vanilla JavaScript code to spec.javascript inside the JsPolicy resource or by creating a separate JsPolicyBundle from compiled JavaScript or TypeScript code

Configure Policy Settings#

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

An example of a JsPolicy object with these settings could look like this:

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"
# Optional javascript here if we choose to use inline vanilla JavaScript code
# javascript: if ...

Policy Type#

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

Learn more about the different Policy Types

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)

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
  • 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)

Write Policy Logic#

There are different ways to write policy logic for JsPolicy. The following table compares three common workflows:

Embedded spec.javascriptSeparate JavaScriptTypeScript
LanguageJavaScriptJavaScriptTypeScript (modern)
Type Safetynonoyes
IDE Supportbad (JavaScript in YAML)goodgreat (auto-completion, warnings, types)
Testingonly end-to-end via test kubectl requestsunit, functional and end-to-end testsunit, functional and end-to-end tests
Publishingonly via JsPolicy YAML filesvia npm packagesvia npm packages
JsBundle Generationautomatic by jsPolicymanual or via dev tools (SDK)manual or via dev tools (SDK)
SDK-jsPolicy SDKjsPolicy SDK

Inline JavaScript Policies#

Use the spec.javascript option of the JsPolicy CRD to write policy code inline as embedded JavaScript ES5 (vanilla JS):

apiVersion: policy.jspolicy.com/v1beta1
kind: JsPolicy
metadata:
name: "deny-default-namespace.company.tld"
spec:
operations: ["CREATE"]
resources: ["*"]
scope: Namespaced
javascript: |
if (request.namespace === "default") {
deny("Creation of resources within the default namespace is not allowed!");
}

Dependencies For Embedded JavaScript Policies#

Use the spec.dependencies option to define dependencies that you want to load for this policy. You can specify any CommonJS package from the npm registry here or import your own packages.

Separate JavaScript or TypeScript#

You can use a separate JavaScript project to build, test and deploy your policies. Any language that can get cross-compiled to Javascript is supported. Please take a look at our Policy SDK or TypeScript example on how to write policies and compile them to JsPolicy and JsPolicyBundle objects.

Test Policies#

Of course, you can simply apply your policies via kubectl apply to any cluster and then run kubectl command to end-to-end test your policies. However, since your policy logic will be entirely written in JavaScript (or TypeScript which compiles to JavaScript), you can use any JavaScript testing framework to create and run test suits, including unit tests, functional tests, integration tests and end-to-end tests.

See the example tests in the jsPolicy SDK project on GitHub for a reference implementation using the test framework Jest developed by Facebook.