DOCSEARCHbyAlgolia
Submit Docs

jsPolicy

website·Indexed 33 days ago

https://www.jspolicy.com/docs/

A policy engine for Kubernetes that allows developers to write validating and mutating policies using JavaScript or TypeScript. It provides a set of built-in functions for cluster interaction, such as create(), update(), remove(), and mutate(), and can be installed via Helm v3.

Tokens
13.4K
Snippets
54
Records
94
Agent score
67%

What's inside jsPolicy

  1. Overview of jsPolicy for Kubernetes

    jsPolicy is a policy engine for Kubernetes that enables developers to write policies using JavaScript or TypeScript. It leverages Google's V8 engine with pre-heated sandbox environments for high-performance execution, typically completing most policies in under one millisecond. It supports the use of any CommonJS JavaScript or TypeScript libraries from npm or private registries.

  2. Overview of jsPolicy Architecture

    jsPolicy is a Kubernetes policy engine that allows users to write policies in JavaScript or TypeScript. It operates as a single container consisting of three logical components: the Webhook Manager, the V8 JavaScript Sandbox Pool, and the Policy Compiler.

  3. Overview of jsPolicy logic implementation workflows

    jsPolicy provides three primary workflows for implementing policy logic. The choice depends on the required level of type safety, IDE support, and testing capabilities.
    FeatureEmbedded spec.javascriptSeparate JavaScriptTypeScript
    LanguageJavaScriptJavaScriptTypeScript (modern)
    Type SafetyNoNoYes
    IDE SupportBad (JS in YAML)GoodGreat
    TestingEnd-to-end onlyUnit, Functional, E2EUnit, Functional, E2E
    PublishingVia JsPolicy YAMLVia npm packagesVia npm packages
    Bundle GenAutomaticManual/SDKManual/SDK
    SDKN/AjsPolicy SDKjsPolicy SDK

  4. jsPolicy Features and Capabilities

    jsPolicy is a Kubernetes policy engine with the following capabilities:

    • Language Support: Policies are written in JavaScript or TypeScript (or any language that compiles to JS).
    • Validating Policies: Supports standard validating admission control policies.
    • Mutating Policies: Provides a streamlined way to write mutating admission control policies.
    • Controller Policies: Supports policies executed after Events in the cluster (a unique feature not found in OPA or Kyverno).
    • Tooling: Integrates with the standard JavaScript ecosystem for development, testing, and maintenance.
    • Package Management: Policies and policy functions can be published and shared via npm (npmjs.com) or private npm registries.

  5. Understand the JsPolicyViolations CRD structure

    The JsPolicyViolations Custom Resource Definition (CRD) in the policy.jspolicy.com/v1beta1 API group is used to report policy violations. It captures details about the denied action, the specific reason for the violation, the request information (including the target resource and operation), and the user identity associated with the request.
    apiVersion: policy.jspolicy.com/v1beta1
kind: JsPolicyViolations
metadata:
  name: "policy-name.company.tld"
status:
  violations:
    - action: "deny"
      code: 500
      message: "Namespace 'default' not allowed!"
      reason: "namespace_disallowed"
      requestInfo:
        operation: ""
        apiVersion: "v1"
        kind: "Pod"
        name: "nginx"
        namespace: "default"
      userInfo:
        uid: "uid"
        username: "admin"
      timestamp: "2021-05-05T00:32:02Z"

  6. Access requesting user information

    The userInfo object contains details about the user making the request:

    • username: The unique identifier for the user among all active users.
    • uid: A unique value identifying the user across time (persists even if a user is deleted and recreated with the same name).
    • groups: A list of groups the user belongs to.
    • extra: Additional information provided by the authenticator.

  7. Understand jsPolicy policy types

    jsPolicy provides three types of policies to govern Kubernetes clusters:

    1. Mutating Policies: Triggered by requests to the k8s API server. They run sequentially and are expected to call mutate() on the request object.
    2. Validating Policies: Triggered by requests to the k8s API server. They run in parallel after mutating policies. If any validating policy calls deny(), the request is aborted and not persisted in etcd.
    3. Controller Policies: Triggered asynchronously by Kubernetes Events (CRUD operations). They are queued and can perform any action, including executing other CRUD operations in the cluster.

    Additionally, Mutating and Validating policies can use warn() to send warnings to the client (e.g., visible in kubectl output) without blocking the request.

  8. Compare jsPolicy policy types

    jsPolicy provides three distinct policy types based on when they are triggered and their intended outcome:

    TypeTriggerExecution OrderExpected Result
    MutatingRequests to k8s API serverSequentialModified request object via mutate()
    ValidatingRequests to k8s API serverParallelallow() or deny() the request
    ControllerChanges to k8s objects (Events)QueuedAny action/side-effect

    Mutating and Validating policies run during the HTTP request to the Kubernetes API server after authentication and RBAC. Mutating policies run first (sequentially), followed by Validating policies (in parallel). If any Validating policy calls deny(), the request is aborted and not persisted in etcd.

  9. Use Mutating policies to modify Kubernetes objects

    Mutating policies are used to change the payload of a Kubernetes object during a request (e.g., via kubectl). They are executed sequentially after RBAC to prevent interference between multiple mutations.

    Common use cases include:

    • Adding mandatory labels or annotations to metadata.
    • Auto-completing fields (e.g., adding a nodeSelector to a Pod).
    • Replacing placeholders in resource definitions (e.g., replacing #BASE_HOSTNAME# with a real domain in an Ingress).

    Reinvocation Policy: You can configure reinvocationPolicy to determine if the policy should be called again if other admission plugins modify the object:

    • Never (Default): The webhook is called only once per admission evaluation.
    • IfNeeded: The webhook may be called again if the object is modified by other plugins after the initial call.

  10. Import npm dependencies into a JsPolicy

    Use the import statement within the javascript block of a JsPolicy to use external libraries. Dependencies must be declared in the spec.dependencies section of the policy manifest using the same syntax as a package.json file. JsPolicy automatically runs npm install and uses webpack to bundle and minify the dependencies and the policy payload into a single JsPolicyBundle in the cluster.

    To import packages from private npm registries, you must overwrite the ~/.npmrc file within the jspolicy container.

    apiVersion: policy.jspolicy.com/v1beta1
kind: JsPolicy
metadata:
  name: "dependency-policy.example.com"
spec:
  operations: ["CREATE"]
  resources: ["pods"]
  # Declare dependencies like in package.json
  dependencies:
    lodash: "^4.17.21"
  javascript: |
    import _ from 'lodash';

    // Use the imported library in the policy logic
    if (_.isEqual(request.object.metadata?.labels, {"my-forbidden-label": "my-forbbiden-value"})) {
      deny("forbidden label set encountered");
    }

  11. Delete jsPolicy Custom Resource Definitions (CRDs)

    To remove all jsPolicy CRDs and their associated resources (such as JsPolicy, JsPolicyBundle, and JsPolicyViolations objects), use the following command. Warning: This action results in the permanent loss of all jsPolicy objects in the cluster.
    kubectl api-resources --api-group='policy.jspolicy.com' -o name | xargs kubectl delete crd

  12. Share jsPolicy policies via Kubernetes YAML

    Policy authors can share policies for others to use in Kubernetes by providing YAML files. There are two primary distribution methods:

    1. Share a standalone JsPolicy YAML file for direct application.
    2. Share a combination of a JsPolicy and a JsPolicyBundle YAML file to provide both the policy definition and its associated bundle.
    # Apply a single policy
kubectl apply -f policy.yaml

# Apply a policy and its bundle
kubectl apply -f policy.bundle.yaml -f policy.yaml