DOCSEARCHbyAlgolia
Submit Docs

Chainsaw

repository·main·Indexed 20 days ago

https://github.com/kyverno/chainsaw

A declarative testing tool for Kubernetes operators and controllers that allows users to define and execute end-to-end tests for any Kubernetes objects. It includes a CLI for asserting cluster state, linting test documents, exporting JSON schemas, and migrating resources from KUTTL. The tool provides a Go Client interface for standard CRUD operations on Kubernetes objects with strict field validation.

Tokens
98.9K
Snippets
413
Records
501
Agent score
68%

What's inside chainsaw

  1. Overview of Chainsaw

    main
    Chainsaw is an open-source tool that provides a declarative approach to testing Kubernetes operators and controllers. While its primary design goal is testing operators and controllers, it can be used to declaratively test any Kubernetes objects. It was originally developed to define and run end-to-end tests for Kyverno.

  2. What is Chainsaw and when to use it

    main

    Chainsaw is a tool designed for running end-to-end (E2E) tests within Kubernetes clusters. It is specifically optimized for testing Kubernetes operators by executing a sequence of steps and asserting that specific conditions are met.

    A typical workflow involves:

    1. Creating a resource (e.g., a policy or a configuration).
    2. Creating a target resource to trigger the operator.
    3. Asserting that the operator acted as expected (e.g., checking for mutations, validations, or generated resources).
    4. Cleaning up the environment for the next test cycle.

  3. Supported Chainsaw operations

    main

    Chainsaw provides a variety of operations to define test steps. These operations allow you to manipulate Kubernetes resources, execute commands, or manage test flow. The available operations are:

    • Apply: Apply a resource to the cluster.
    • Assert: Assert that a resource exists or matches specific criteria.
    • Command: Execute a command.
    • Create: Create a resource.
    • Delete: Delete a resource.
    • Error: Expect an error to occur.
    • Patch: Patch a resource.
    • Script: Run a script.
    • Sleep: Pause execution for a specified duration.
    • Update: Update a resource.

  4. What is a StepTemplate and when to use it

    main
    A StepTemplate is a reusable resource in Chainsaw that allows you to factor out common step patterns into a shared definition. Unlike a standard test step which is defined directly within a Test, a StepTemplate lives in its own resource and can be invoked by multiple tests. This helps keep test suites DRY (Don't Repeat Yourself) by allowing you to define a pattern once and pass different arguments to it during each invocation.

  5. How `try` statements work in Chainsaw

    main

    A try statement is a sequential execution block used to define a series of test steps. Operations within a try block are executed in the exact order they are declared.

    Failure Behavior: If any single operation within the sequence fails, the entire try statement is marked as failed, and subsequent operations in that sequence are not executed.

  6. How Chainsaw prioritizes configuration files

    main

    Chainsaw follows a specific hierarchy when determining which configuration to use. It will use the first one it finds in this order:

    1. User-specified configuration: A file explicitly provided via the --config command-line flag.
    2. Default configuration file: A file named .chainsaw.yaml located in the current working directory.
    3. Internal default configuration: An embedded default configuration within the Chainsaw binary used if no other file is found.

  7. Understand KUBECONFIG behavior for scripts

    main
    Unless the --no-cluster flag is specified during execution, Chainsaw always executes script commands within the context of a temporary KUBECONFIG. This temporary configuration is built from the configured target cluster and contains a single cluster, auth info, and context, all named chainsaw.

  8. Use the create operation to define resources

    main

    The create operation is used within a Chainsaw Test step to define Kubernetes resources that should be created in a cluster.

    Important Behavior: If the resource you are attempting to create already exists in the cluster, the step will fail.

    Supported features for the create operation include:

    • Bindings
    • Outputs
    • Templating
    • Operation checks

  10. How catch statements work in Chainsaw

    main

    A catch statement is a sequence of operations that executes only if the operations in a step's try statement fail.

    Key Behavior:

    • The catch block is triggered by a failure in the preceding try block.
    • All operations within a catch statement will be executed in sequence, regardless of whether individual operations within the catch block itself succeed or fail.

  11. Use operation outputs to reuse results across steps

    main

    Chainsaw allows you to capture the results of an operation (like the standard output of a script) and register them as a new binding using the outputs field. Once registered, these outputs are available to subsequent operations in the test execution flow.

    Key behaviors:

    • Registration: Use the outputs field within an operation to create a new binding.
    • Standard Output: By default, an output can capture the content of the standard output using the ($stdout) expression.
    • Scope: Outputs evaluated after an operation finishes are registered in the bindings and made available for following operations.
    apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - script:
        outputs:
        - name: OUTPUT
          value: ($stdout)
        content: echo "hello"
    - script:
        # The $OUTPUT binding from the previous step is now available
        env:
        - name: INPUT
          value: ($OUTPUT)
        content: echo $INPUT

  12. Understand resource cardinality in file references

    main

    When you reference a file (or a glob pattern) that contains multiple Kubernetes resources, Chainsaw treats each resource as a separate instance of the operation.

    Important: Because the operation is duplicated for every resource found in the file, any associated bindings or outputs will also be evaluated for every single resource instance. Plan your test logic accordingly to ensure bindings and outputs correctly account for multiple resources.