diff --git a/main/configuration/options/deletion/index.html b/main/configuration/options/deletion/index.html index 765cac161..e53450947 100644 --- a/main/configuration/options/deletion/index.html +++ b/main/configuration/options/deletion/index.html @@ -5,4 +5,5 @@ spec: deletion: propagation: Foreground -

With flags

Note

Deletion options can't be configured with flags.

\ No newline at end of file +

With flags

chainsaw test --deletion-propagation-policy Foreground
+
\ No newline at end of file diff --git a/main/reference/commands/chainsaw_test/index.html b/main/reference/commands/chainsaw_test/index.html index c6e3cc4d9..9907a7bf9 100644 --- a/main/reference/commands/chainsaw_test/index.html +++ b/main/reference/commands/chainsaw_test/index.html @@ -6,7 +6,7 @@ --cluster strings Register cluster (format <cluster name>=<kubeconfig path>:[context name]) --config string Chainsaw configuration file --delete-timeout duration The delete timeout to use as default for configuration (default 15s) - --deletion-propagation-policy string The deletion propagation policy (Foreground|Background|Orphan) (default "Foreground") + --deletion-propagation-policy string The deletion propagation policy (Foreground|Background|Orphan) (default "Background") --error-timeout duration The error timeout to use as default for configuration (default 30s) --exclude-test-regex string Regular expression to exclude tests --exec-timeout duration The exec timeout to use as default for configuration (default 5s) diff --git a/main/search/search_index.json b/main/search/search_index.json index 03b64f069..9ef5a4bbe 100644 --- a/main/search/search_index.json +++ b/main/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"cicd/gh-action/","title":"GitHub action","text":"

A GitHub action is available to easily install Chainsaw in your workflows.

The GitHub action is available at kyverno/action-install-chainsaw or in the marketplace.

"},{"location":"cicd/gh-action/#usage","title":"Usage","text":"

This action currently supports GitHub-provided Linux, macOS and Windows runners (self-hosted runners may not work).

Add the following entry to your Github workflow YAML file:

uses: kyverno/action-install-chainsaw@v0.1.0\nwith:\n  release: v0.1.0 # optional\n

Example using a pinned version:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw\n    steps:\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n        with:\n          release: v0.0.9\n      - name: Check install\n        run: chainsaw version\n

Example using the default version:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw\n    steps:\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n      - name: Check install\n        run: chainsaw version\n

Example using cosign verification:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw\n    steps:\n      - name: Install Cosign\n        uses: sigstore/cosign-installer@v3.1.1\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n        with:\n          verify: true\n      - name: Check install\n        run: chainsaw version\n

If you want to install Chainsaw from its main version by using go install under the hood, you can set release as main. Once you did that, Chainsaw will be installed via go install which means that please ensure that go is installed.

Example of installing Chainsaw via go install:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw via go install\n    steps:\n      - name: Install go\n        uses: actions/setup-go@v4\n        with:\n          go-version: '1.21'\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n        with:\n          release: main\n      - name: Check install\n        run: chainsaw version\n
"},{"location":"cicd/gh-action/#optional-inputs","title":"Optional Inputs","text":"

The following optional inputs:

Input Description release chainsaw version to use instead of the default. install-dir directory to place the chainsaw binary into instead of the default ($HOME/.chainsaw). use-sudo set to true if install-dir location requires sudo privs. Defaults to false. verify set to true to enable cosign verification of the downloaded archive."},{"location":"community/","title":"Community","text":"

Chainsaw has a growing community and we would definitely love to see you join and contribute.

Everyone is welcome to make suggestions, report bugs, open feature requests, contribute code or docs, participate in discussions, write blogs or anything that can benefit the project.

Chainsaw is built and maintained under the Kyverno umbrella but decisions are Community driven Everyone's voice matters

"},{"location":"community/#slack-channel","title":"Slack channel","text":"

Join our slack channel #kyverno-chainsaw to meet with users, contributors and maintainers.

"},{"location":"community/#community-meetings","title":"Community Meetings","text":"

To attend our community meetings, join the Chainsaw group. You will then be sent a meeting invite and will have access to the agenda and meeting notes. Any member may suggest topics for discussion.

This is a public, weekly for Kyverno-Chainsaw maintainers to make announcements and provide project updates, and request input and feedback. This forum allows community members to raise agenda items of any sort, including but not limited to any PRs or issues on which they are working.

Weekly every Thursday at 2:00 PM UTC

"},{"location":"community/#roadmap","title":"RoadMap","text":"

For detailed information on our planned features and upcoming updates, please view our Roadmap.

"},{"location":"community/#contributing","title":"Contributing","text":"

Please read the contributing guide for details around:

  1. Code of Conduct
  2. Code Culture
  3. Details on how to contribute
"},{"location":"community/#adopters","title":"Adopters","text":"

If you are using Chainsaw and want to share it publicly we always appreciate a bit of support. Pull requests to the ADOPTERS LIST will put a smile on our faces

"},{"location":"configuration/","title":"Configuring Chainsaw","text":"

This documentation focuses on providing a breakdown of the Chainsaw configuration structure and how to use it.

Chainsaw can be configured in two different and complementary ways:

"},{"location":"configuration/#specific-configuration-options","title":"Specific configuration options","text":"

Please pay attention to the configuration options below, they may or may not be relevant in your case but can be useful in certain cases:

"},{"location":"configuration/file/","title":"Configuration file","text":"

Chainsaw prioritizes its configuration in the following order:

  1. User-specified configuration

    If you explicitly provide a configuration file using a command-line flag

  2. Default configuration file

    If no configuration is specified, Chainsaw will look for a default file named .chainsaw.yaml in the current working directory

  3. Internal default configuration

    In the absence of both of the above, Chainsaw will use a default configuration file embedded in the Chainsaw binary

"},{"location":"configuration/file/#example","title":"Example","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  timeouts:\n    apply: 45s\n    assert: 20s\n    cleanup: 45s\n    delete: 25s\n    error: 10s\n    exec: 45s\n  cleanup:\n    skipDelete: false\n  execution:\n    failFast: true\n    parallel: 4\n  # ...\n
"},{"location":"configuration/file/#how-to-specify-a-configuration","title":"How to specify a configuration","text":"

To use a custom configuration file:

chainsaw test --config path/to/your/config.yaml\n
"},{"location":"configuration/file/#default-configuration","title":"Default configuration","text":"

The default configuration below is used by Chainsaw when no configuration file was provided and the default file .chainsaw.yaml does not exist.

apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: default\nspec: {}\n
"},{"location":"configuration/file/#reference-documentation","title":"Reference documentation","text":"

See Configuration API reference for more details.

"},{"location":"configuration/flags/","title":"Command line flags","text":"

After a configuration file is loaded, you can override specific settings using command-line flags.

Precedence

Command-line flags always take precedence over the configuration coming from a configuration file.

"},{"location":"configuration/flags/#example","title":"Example","text":"
chainsaw test                         \\\n  path/to/test/dir                    \\\n  --config path/to/your/config.yaml   \\\n  --assert-timeout 45s                \\\n  --skip-delete false                 \\\n  --fail-fast true                    \\\n  --parallel 4                        \\\n  ...\n

In this example, Chainsaw will load a configuration file but the timeout configuration and other settings will be overridden by the values set in the flags, regardless of the value in the loaded configuration file.

"},{"location":"configuration/flags/#reference-documentation","title":"Reference documentation","text":"

See chainsaw test command reference for the list of all available flags.

"},{"location":"configuration/options/cleanup/","title":"Cleanup options","text":"

Cleanup options contain the configuration used by Chainsaw for cleaning up resources.

"},{"location":"configuration/options/cleanup/#supported-elements","title":"Supported elements","text":"Element Default Description skipDelete false If set, do not delete the resources after running a test. delayBeforeCleanup DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts."},{"location":"configuration/options/cleanup/#delay-before-cleanup","title":"Delay before cleanup","text":"

At the end of each test, Chainsaw will delete the resources it created during the test.

When testing operators, it can be useful to wait a little bit before starting the cleanup process to make sure the operator/controller has the necessary time to update its internal state.

"},{"location":"configuration/options/cleanup/#configuration","title":"Configuration","text":""},{"location":"configuration/options/cleanup/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  cleanup:\n    skipDelete: true\n    delayBeforeCleanup: 5s\n
"},{"location":"configuration/options/cleanup/#with-flags","title":"With flags","text":"
chainsaw test                   \\\n  --skip-delete                 \\\n  --delay-before-cleanup 5s\n
"},{"location":"configuration/options/clusters/","title":"Multi-cluster options","text":"

Multi-cluster options contain the configuration of additional clusters.

"},{"location":"configuration/options/clusters/#supported-elements","title":"Supported elements","text":"

Every cluster is registered by name and supports the following elements:

Element Default Description kubeconfig string Kubeconfig is the path to the referenced file. context string Context is the name of the context to use."},{"location":"configuration/options/clusters/#configuration","title":"Configuration","text":""},{"location":"configuration/options/clusters/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: custom-config\nspec:\n  clusters:\n    # this cluster will use the default (current) context\n    # configured in the kubeconfig file\n    cluster-1:\n      kubeconfig: /path/to/kubeconfig-1\n    # this cluster will use the context named `context-2`\n    # in the kubeconfig file\n    cluster-2:\n      kubeconfig: /path/to/kubeconfig-2\n      context: context-2\n
"},{"location":"configuration/options/clusters/#with-flags","title":"With flags","text":"

Note

The --cluster flag can appear multiple times and is expected to come in the following format:

--cluster cluster-name=/path/to/kubeconfig[:context-name].

chainsaw test                                               \\\n    --cluster cluster-1=/path/to/kubeconfig-1               \\\n    --cluster cluster-2=/path/to/kubeconfig-2:context-2\n
"},{"location":"configuration/options/deletion/","title":"Deletion options","text":"

Deletion options determine the configuration used by Chainsaw for deleting resources.

"},{"location":"configuration/options/deletion/#supported-elements","title":"Supported elements","text":"Element Default Description propagation Background Propagation decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation."},{"location":"configuration/options/deletion/#propagation","title":"Propagation","text":"

This element will affect Kubernetes cascading deletion. Supported values are Orphan, Background and Foreground.

Tip

Setting Orphan is probably never a good idea because it would leak resources in the test cluster. Chainsaw uses Background as its default value which is a reasonable choice.

Note that Foreground can be useful to fail when the dependent resources fail to delete.

"},{"location":"configuration/options/deletion/#configuration","title":"Configuration","text":""},{"location":"configuration/options/deletion/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  deletion:\n    propagation: Foreground\n
"},{"location":"configuration/options/deletion/#with-flags","title":"With flags","text":"

Note

Deletion options can't be configured with flags.

"},{"location":"configuration/options/discovery/","title":"Discovery options","text":"

Discovery options contain the discovery configuration used by Chainsaw when discovering tests in specified folders.

"},{"location":"configuration/options/discovery/#supported-elements","title":"Supported elements","text":"Element Default Description testFile chainsaw-test TestFile is the name of the file containing the test to run. If no extension is provided, chainsaw will try with .yaml first and .yml if needed. fullName false FullName makes use of the full test case folder path instead of the folder name. includeTestRegex IncludeTestRegex is used to include tests based on a regular expression. excludeTestRegex ExcludeTestRegex is used to exclude tests based on a regular expression."},{"location":"configuration/options/discovery/#configuration","title":"Configuration","text":""},{"location":"configuration/options/discovery/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  discovery:\n    testFile: chainsaw-test\n    fullName: true\n    includeTestRegex: chainsaw/.*\n    excludeTestRegex: chainsaw/exclude-.*\n
"},{"location":"configuration/options/discovery/#with-flags","title":"With flags","text":"
chainsaw test                                   \\\n  --test-file chainsaw-test                     \\\n  --full-name                                   \\\n  --include-test-regex 'chainsaw/.*'            \\\n  --exclude-test-regex 'chainsaw/exclude-.*'\n
"},{"location":"configuration/options/error/","title":"Error options","text":"

Error options contain the global error configuration used by Chainsaw.

"},{"location":"configuration/options/error/#supported-elements","title":"Supported elements","text":"Field Default Description catch Catch defines what the tests steps will execute when an error happens. This will be combined with catch handlers defined at the test and step levels."},{"location":"configuration/options/error/#configuration","title":"Configuration","text":""},{"location":"configuration/options/error/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  error:\n    catch:\n    - events: {}\n    - describe:\n        resource: crds\n
"},{"location":"configuration/options/error/#with-flags","title":"With flags","text":"

Note

Error options can't be configured with flags.

"},{"location":"configuration/options/execution/","title":"Execution options","text":"

Execution options determine how tests are run by Chainsaw.

"},{"location":"configuration/options/execution/#supported-elements","title":"Supported elements","text":"Element Default Description failFast false FailFast determines whether the test should stop upon encountering the first failure. parallel auto The maximum number of tests to run at once. repeatCount 1 RepeatCount indicates how many times the tests should be executed. forceTerminationGracePeriod ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments."},{"location":"configuration/options/execution/#termination-grace-period","title":"Termination grace period","text":"

Some Kubernetes resources can take time before being terminated. For example, deleting a pod can take time if the underlying container doesn't quit quickly enough.

Chainsaw can override the grace period for the following resource kinds:

"},{"location":"configuration/options/execution/#configuration","title":"Configuration","text":""},{"location":"configuration/options/execution/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  execution:\n    failFast: true\n    parallel: 8\n    repeatCount: 2\n    forceTerminationGracePeriod: 5s\n
"},{"location":"configuration/options/execution/#with-flags","title":"With flags","text":"
chainsaw test                                   \\\n  --fail-fast                                   \\\n  --parallel 8                                  \\\n  --repeat-count 2                              \\\n  --force-termination-grace-period 5s\n
"},{"location":"configuration/options/label-selectors/","title":"Label selectors","text":"

Chainsaw can filter the tests to run using label selectors.

"},{"location":"configuration/options/label-selectors/#configuration","title":"Configuration","text":""},{"location":"configuration/options/label-selectors/#with-file","title":"With file","text":"

Note

Label selectors can't be configured with a configuration file.

"},{"location":"configuration/options/label-selectors/#with-flags","title":"With flags","text":"
chainsaw test --selector foo=bar\n
"},{"location":"configuration/options/namespace/","title":"Namespace options","text":"

Namespace options contain the configuration used by Chainsaw to allocate a namespace for each test.

"},{"location":"configuration/options/namespace/#supported-elements","title":"Supported elements","text":"Element Default Description name Name defines the namespace to use for tests. If not specified, every test will execute in a random ephemeral namespace unless the namespace is overridden in a the test spec. template Template defines a template to create the test namespace."},{"location":"configuration/options/namespace/#configuration","title":"Configuration","text":""},{"location":"configuration/options/namespace/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  namespace:\n    name: foo\n    template:\n      metadata:\n        annotations:\n          from-config-file: hello\n
"},{"location":"configuration/options/namespace/#with-flags","title":"With flags","text":"

Note

The template element can't be configured with flags.

chainsaw test --namespace foo\n
"},{"location":"configuration/options/no-cluster/","title":"No cluster options","text":"

Chainsaw can be run without any connection to a Kubernetes cluster.

In this case, Chainsaw will not try to create an ephemeral namespace and all operations requiring a Kubernetes cluster will fail.

"},{"location":"configuration/options/no-cluster/#configuration","title":"Configuration","text":""},{"location":"configuration/options/no-cluster/#with-file","title":"With file","text":"

Note

No cluster options can't be configured with a configuration file.

"},{"location":"configuration/options/no-cluster/#with-flags","title":"With flags","text":"
chainsaw test --no-cluster\n
"},{"location":"configuration/options/pause/","title":"Pause options","text":"

Chainsaw can be configured to pause and wait for user input when a failure happens. This is useful when Chainsaw is run locally to allow debugging and troubleshooting failures.

"},{"location":"configuration/options/pause/#configuration","title":"Configuration","text":""},{"location":"configuration/options/pause/#with-file","title":"With file","text":"

Note

Pause options can't be configured with a configuration file.

"},{"location":"configuration/options/pause/#with-flags","title":"With flags","text":"
chainsaw test --pause-on-failure\n
"},{"location":"configuration/options/report/","title":"Reporting options","text":"

Reporting options contain the configuration used by Chainsaw for reporting.

"},{"location":"configuration/options/report/#supported-elements","title":"Supported elements","text":"Element Default Description format JSON ReportFormat determines test report format (JSON path ReportPath defines the path. name chainsaw-report ReportName defines the name of report to create. It defaults to \"chainsaw-report\"."},{"location":"configuration/options/report/#configuration","title":"Configuration","text":""},{"location":"configuration/options/report/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  report:\n    format: JSON\n    name: chainsaw-report\n    path: /home/chainsaw\n
"},{"location":"configuration/options/report/#with-flags","title":"With flags","text":"

Note

The report path can be specified as either a relative or an absolute path.

chainsaw test                             \\\n  --report-format JSON                    \\\n  --report-name chainsaw-report           \\\n  --report-path /path/to/save/report\n
"},{"location":"configuration/options/templating/","title":"Templating options","text":"

Templating options contain the templating configuration.

"},{"location":"configuration/options/templating/#supported-elements","title":"Supported elements","text":"Element Default Description enabled true Enabled determines whether resources should be considered for templating.

Tip

Templating was disabled by default in v0.1.* but is now enabled by default since v0.2.1.

"},{"location":"configuration/options/templating/#configuration","title":"Configuration","text":""},{"location":"configuration/options/templating/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  templating:\n    enabled: false\n
"},{"location":"configuration/options/templating/#with-flags","title":"With flags","text":"
chainsaw test --template=false\n
"},{"location":"configuration/options/timeouts/","title":"Timeouts","text":"

Timeouts in Chainsaw are specified per type of operation. This is required because the timeout varies greatly depending on the nature of an operation.

For example, applying a manifest in a cluster is expected to execute reasonably fast, while validating a resource can be a much longer operation.

"},{"location":"configuration/options/timeouts/#supported-timeouts","title":"Supported timeouts","text":"Element Default Description apply 5s Used when Chainsaw applies manifests in a cluster assert 30s Used when Chainsaw validates resources in a cluster cleanup 30s Used when Chainsaw removes resources created for a test delete 15s Used when Chainsaw deletes resources from a cluster error 30s Used when Chainsaw validates resources in a cluster exec 5s Used when Chainsaw executes arbitrary commands or scripts"},{"location":"configuration/options/timeouts/#configuration","title":"Configuration","text":""},{"location":"configuration/options/timeouts/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  timeouts:\n    apply: 45s\n    assert: 20s\n    cleanup: 45s\n    delete: 25s\n    error: 10s\n    exec: 45s\n
"},{"location":"configuration/options/timeouts/#with-flags","title":"With flags","text":"
chainsaw test               \\\n  --apply-timeout 45s       \\\n  --assert-timeout 45s      \\\n  --cleanup-timeout 45s     \\\n  --delete-timeout 45s      \\\n  --error-timeout 45s       \\\n  --exec-timeout 45s\n
"},{"location":"configuration/options/values/","title":"External values","text":"

Chainsaw can pass arbitrary values when running tests using the --values flag. Values will be available to tests under the $values binding.

"},{"location":"configuration/options/values/#configuration","title":"Configuration","text":""},{"location":"configuration/options/values/#with-file","title":"With file","text":"

Note

Values can't be configured with a configuration file.

"},{"location":"configuration/options/values/#with-flags","title":"With flags","text":"
chainsaw test --values ./values.yaml\n
"},{"location":"examples/","title":"Examples","text":"

Info

Select an item in the navigation menu to browse a specific page.

"},{"location":"examples/concurrency/","title":"Concurrency control","text":"

By default, Chainsaw will run tests in parallel.

The number of concurrent tests can be configured globally using a configuration file or with the --parallel flag.

Alternatively, the concurrent nature of a test can specified at the test level:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # concurrency can be specified per test (`true` or `false`)\n  # default value is `true`\n  concurrent: false\n  # ...\n

All non-concurrent tests are executed first, followed by the concurrent tests running in parallel.

"},{"location":"examples/crds/","title":"Work with CRDs","text":"

New CRDs are not immediately available for use in the Kubernetes API until the Kubernetes API has acknowledged them.

If a CRD is being defined inside of a test step, be sure to wait for it to appear.

The test below applies a CRD and waits for it to become available:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: apiextensions.k8s.io/v1\n          kind: CustomResourceDefinition\n          metadata:\n            name: issues.example.com\n          spec:\n            group: example.com\n            names:\n              kind: Issue\n              listKind: IssueList\n              plural: issues\n              singular: issue\n            scope: Namespaced\n            versions: ...\n    - assert:\n        resource:\n          apiVersion: apiextensions.k8s.io/v1\n          kind: CustomResourceDefinition\n          metadata:\n            name: issues.example.com\n          status:\n            acceptedNames:\n              kind: Issue\n              listKind: IssueList\n              plural: issues\n              singular: issue\n            storedVersions:\n            - v1alpha1\n

The CRD can be used in subsequent steps.

"},{"location":"examples/events/","title":"Work with events","text":"

Kubernetes events are regular Kubernetes objects and can be asserted on just like any other object:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: Event\n          reason: Started\n          source:\n            component: kubelet\n          involvedObject:\n            apiVersion: v1\n            kind: Pod\n            name: my-pod\n
"},{"location":"examples/inline/","title":"Inline resources","text":"

When an operation needs to reference a resource, it can do so using a file path or directly specify the resource inline using the resource field.

The test below is equivalent to our first test:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n
"},{"location":"examples/kube-version/","title":"Check Kubernetes version","text":"

The test below fetches the Kubernetes cluster version using the x_k8s_server_version function. It then uses the minor version retrieved to adapt an assertion based on the value in the $minorversion binding.

Tip

You can implement a ternary operator in JMESPath using an expression like this:

<condition> && <value-if-true> || <value-if-false>

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  bindings:\n  - name: version\n    value: (x_k8s_server_version($config))\n  - name: minorversion\n    value: (to_number($version.minor))\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: v1\n          kind: Pod\n          metadata:\n            name: pod01\n          spec:\n            containers:\n            - name: busybox\n              image: busybox:1.35\n    # ...\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: Pod\n          metadata:\n            annotations:\n              # If the minor version of the Kubernetes cluster against\n              # which this is tested is less than 29, the annotation is\n              # expected to have the group 'system:masters' in it.\n              # Otherwise, due to a change in kubeadm, the group should\n              # be 'kubeadm:cluster-admins'.\n              kyverno.io/created-by: (($minorversion < `29` && '{\"groups\":[\"system:masters\",\"system:authenticated\"],\"username\":\"kubernetes-admin\"}') || '{\"groups\":[\"kubeadm:cluster-admins\",\"system:authenticated\"],\"username\":\"kubernetes-admin\"}')\n            name: pod01\n
"},{"location":"examples/label-selectors/","title":"Work with label selectors","text":"

Chainsaw can filter the tests to run using label selectors.

You can pass label selectors using the --selector flag when invoking the chainsaw test command.

Given the test below:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: basic\n  labels:\n    foo: bar\nspec:\n  # ...\n

Invoking Chainsaw with the command below will take the test above into account:

chainsaw test --selector foo=bar\n
"},{"location":"examples/multi-cluster/","title":"Multi-cluster setup","text":"

Chainsaw supports registering and using multiple clusters in tests.

We can also register clusters dynamically and combine this with cluster selection to achieve scenarios where clusters are dynamically allocated in a test step, used in the following steps, and cleaned up at the end.

The following test demonstrates such a scenario by creating a local kind cluster in the first, using it in the second step, and configuring a cleanup script to delete the cluster when the test terminates:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    # create a local cluster\n    - script:\n        timeout: 1m\n        content: |\n          kind create cluster --name dynamic --kubeconfig ./dynamic\n    # register `cleanup` operations to delete the cluster\n    # at the end of the test\n    cleanup:\n    - script:\n        content: |\n          kind delete cluster --name dynamic\n    - script:\n        content: |\n          rm -f ./dynamic\n    # register the `dynamic` cluster in this step\n  - clusters:\n      dynamic:\n        kubeconfig: ./dynamic\n    # and use the `dynamic` cluster for all operations in the step\n    cluster: dynamic\n    try:\n    - apply:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n            namespace: default\n          data:\n            foo: bar\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n            namespace: default\n          data:\n            foo: bar\n

Running the test above will produce the following output:

    | 10:44:53 | example | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-useful-seahorse\n    | 10:44:53 | example | step-1   | TRY       | RUN   |\n    | 10:44:53 | example | step-1   | SCRIPT    | RUN   |\n        === COMMAND\n        /bin/sh -c kind create cluster --name dynamic --kubeconfig ./dynamic\n    | 10:45:10 | example | step-1   | SCRIPT    | LOG   |\n        === STDERR\n        Creating cluster \"dynamic\" ...\n         \u2022 Ensuring node image (kindest/node:v1.27.3) \ud83d\uddbc  ...\n         \u2713 Ensuring node image (kindest/node:v1.27.3) \ud83d\uddbc\n         \u2022 Preparing nodes \ud83d\udce6   ...\n         \u2713 Preparing nodes \ud83d\udce6 \n         \u2022 Writing configuration \ud83d\udcdc  ...\n         \u2713 Writing configuration \ud83d\udcdc\n         \u2022 Starting control-plane \ud83d\udd79\ufe0f  ...\n         \u2713 Starting control-plane \ud83d\udd79\ufe0f\n         \u2022 Installing CNI \ud83d\udd0c  ...\n         \u2713 Installing CNI \ud83d\udd0c\n         \u2022 Installing StorageClass \ud83d\udcbe  ...\n         \u2713 Installing StorageClass \ud83d\udcbe\n        Set kubectl context to \"kind-dynamic\"\n        You can now use your cluster with:\n\n        kubectl cluster-info --context kind-dynamic --kubeconfig ./dynamic\n\n        Thanks for using kind! \ud83d\ude0a\n    | 10:45:10 | example | step-1   | SCRIPT    | DONE  |\n    | 10:45:10 | example | step-1   | TRY       | DONE  |\n    | 10:45:10 | example | step-2   | TRY       | RUN   |\n    | 10:45:10 | example | step-2   | APPLY     | RUN   | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | CREATE    | OK    | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | APPLY     | DONE  | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | ASSERT    | RUN   | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | ASSERT    | DONE  | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | TRY       | DONE  |\n    | 10:45:10 | example | step-2   | CLEANUP   | RUN   |\n    | 10:45:10 | example | step-2   | DELETE    | RUN   | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | DELETE    | OK    | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | DELETE    | DONE  | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | CLEANUP   | DONE  |\n    | 10:45:10 | example | step-1   | CLEANUP   | RUN   |\n    | 10:45:10 | example | step-1   | SCRIPT    | RUN   |\n        === COMMAND\n        /bin/sh -c kind delete cluster --name dynamic\n    | 10:45:10 | example | step-1   | SCRIPT    | LOG   |\n        === STDERR\n        Deleting cluster \"dynamic\" ...\n        Deleted nodes: [\"dynamic-control-plane\"]\n    | 10:45:10 | example | step-1   | SCRIPT    | DONE  |\n    | 10:45:10 | example | step-1   | SCRIPT    | RUN   |\n        === COMMAND\n        /bin/sh -c rm -f ./dynamic\n    | 10:45:10 | example | step-1   | SCRIPT    | DONE  |\n    | 10:45:10 | example | step-1   | CLEANUP   | DONE  |\n    | 10:45:10 | example | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-useful-seahorse\n    | 10:45:11 | example | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-useful-seahorse\n    | 10:45:16 | example | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-useful-seahorse\n
"},{"location":"examples/negative-testing/","title":"Negative testing","text":"

Negative testing is the process of testing cases that are supposed to fail. That is, a test expects errors to happen and if the expected errors don't occur the test must fail.

Chainsaw supports negative testing by letting you decide what should be considered an error or not.

Tip

By default, Chainsaw will consider an operation failed if there was an error executing it (non-zero exit code in scripts and commands, error returned by the API server when calling into Kubernetes, etc...).

"},{"location":"examples/negative-testing/#script-case","title":"Script case","text":"

The test below expects an error and validates the returned error message:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: kubectl get foo\n        check:\n          ($error != null): true\n          ($stderr): |-\n            error: the server doesn't have a resource type \"foo\"\n

If for whatever reason, the kubectl get foo doesn't return an error, or the message received in standard error output is not error: the server doesn't have a resource type \"foo\", Chainsaw will consider the operation failed.

If it returns an error and the expected error message, Chainsaw will consider the operation successful.

"},{"location":"examples/negative-testing/#working-with-resources","title":"Working with resources","text":"

The test below tries to apply resources in a cluster but expects the operation to fail:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: resources.yaml\n        expect:\n          # check that applying the resource failed\n        - check:\n            ($error != null): true\n

If applying the resource succeeded, Chainsaw will consider the operation failed.

On the other hand, if applying the resource fails, Chainsaw will consider the operation to be successful.

"},{"location":"examples/negative-testing/#resource-matching","title":"Resource matching","text":"

In the previous example, if the resources.yaml contains multiple resources, but only some of them may be expected to fail.

Chainsaw allows matching resources when evaluating checks:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: resources.yaml\n        expect:\n          # the check below only applies if the resource being checked\n          # matches the condition defined in the `match` field\n        - match:\n            apiVersion: v1\n            kind: ConfigMap\n            metadata:\n              name: quick-start\n          check:\n            ($error != null): true\n

Using the match field, we can easily target failures related to specific resources.

"},{"location":"examples/non-resource-assertions/","title":"Non-resource assertions","text":"

Under certain circumstances, it makes sense to evaluate assertions that do not depend on resources. For example, when asserting the number of nodes in a cluster is equal to a known value.

The test below uses the x_k8s_list function to query the list of nodes in the cluster. It uses the results to compare the number of nodes found with a known number (1 in this case).

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          (x_k8s_list($client, 'v1', 'Node')):\n            (length(items)): 1\n
"},{"location":"examples/test-output/","title":"Test command output","text":"

Chainsaw can be used to easily check terminal output from CLIs and other commands. This is useful in that convoluted bash scripts involving chaining together tools like grep can be avoided or at least minimized to only complex use cases. Output to both stdout and stderr can be checked for a given string or precise contents.

"},{"location":"examples/test-output/#checking-output-contains","title":"Checking Output Contains","text":"

One basic use case for content checking is that the output simply contains a given string or piece of content. For example, you might want to run automated tests on a CLI binary you build to ensure that a given command produces output that contains some content you specify somewhere in the output. Let's use the following output from the kubectl version command to show these examples.

kubectl version\n\nClient Version: v1.28.2\nKustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3\nServer Version: v1.27.4+k3s1\n

Below is an example that ensures the string '1.28' is found somewhere in that output. So long as the content is present anywhere, the test will succeed. To perform this check, the contains() JMESPath filter is used.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check kubectl\n    try:\n    - script:\n        content: kubectl version\n        check:\n          # This check ensures that the string '1.28' is found\n          # in stdout or else fails\n          (contains($stdout, '1.28')): true\n

Checks for content containing a given value can be negated as well. For example, checking to ensure the output does NOT contain the string '1.25'.

- script:\n    content: kubectl version\n    check:\n      # This check ensures that the string '1.25' is NOT found\n      # in stdout or else fails\n      (contains($stdout, '1.25')): false\n
"},{"location":"examples/test-output/#checking-output-is-exactly","title":"Checking Output Is Exactly","text":"

In addition to checking that CLI/command output contains some contents, you may need to ensure that the contents are exactly as intended. The Chainsaw test below accomplishes this by comparing the entire contents of stdout with those specified in the block scalar. If so much as one character, space, or line break is off, the test will fail. This is useful in that not only can content be checked but the formatting of that content can be ensured it matches a given declaration.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check kubectl\n    try:\n    - script:\n        content: kubectl version\n        check:\n          # This check ensures the contents of stdout are exactly as shown.\n          # Any deviations will cause a failure.\n          ($stdout): |-\n            Client Version: v1.28.2\n            Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3\n            Server Version: v1.27.4+k3s1\n
"},{"location":"examples/test-output/#checking-output-in-errors","title":"Checking Output In Errors","text":"

In addition to testing that commands succeed and with output in a given shape, it's equally valuable and necessary to perform negative tests; that tests fail and with contents that are as expected. Similarly, those checks can be for output which has some contents as well as output which appears exactly as desired. For example, you may wish to check that running the kubectl foo command not only fails as expected but that the output shown to users contains a certain word or sentence.

kubectl foo\n\nerror: unknown command \"foo\" for \"kubectl\"\n\nDid you mean this?\n        top\n

Below you can see an example where the command kubectl foo is expected to fail but that the error message returned contains some output, in this case the string 'top'.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check bad kubectl command\n    try:\n    - script:\n        content: kubectl foo\n        check:\n          # This checks that the result of the content was an error.\n          ($error != null): true\n          # This check below ensures that the string 'top' is found in stderr or else fails\n          (contains($stderr, 'top')): true\n

Likewise, this failure output can be checked that it is precise. Note that in the example below, due to the use of a tab character in the output of kubectl foo, the value of the ($stderr) field is given as a string to preserve these non-printing characters.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check kubectl\n    try:\n    - script:\n        content: kubectl foo\n        check:\n          # This checks that the result of the content was an error.\n          ($error != null): true\n          # This checks that the output is exactly as intended.\n          ($stderr): \"error: unknown command \\\"foo\\\" for \\\"kubectl\\\"\\n\\nDid you mean this?\\n\\ttop\"\n
"},{"location":"examples/values/","title":"Pass data to tests","text":"

Chainsaw can pass arbitrary values when running tests using the --values flag. Values will be available to tests under the $values binding.

This is useful when a test needs to be configured externally.

"},{"location":"examples/values/#reference-external-data","title":"Reference external data","text":"

The test below expects the $value.foo to be provided when chainsaw is invoked.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          ($values.foo): bar\n
"},{"location":"examples/values/#invoking-chainsaw","title":"Invoking Chainsaw","text":""},{"location":"examples/values/#read-values-from-a-file","title":"Read values from a file","text":"
chainsaw test --values ./values.yaml\n
"},{"location":"examples/values/#read-from-stdin","title":"Read from stdin","text":"
echo \"foo: bar\" | chainsaw test --values -\n
"},{"location":"examples/values/#use-heredoc","title":"Use heredoc","text":"
chainsaw test --values - <<EOF\nfoo: bar\nEOF\n
"},{"location":"general/bindings/","title":"Bindings","text":"

You can think of bindings as a side context where you can store and retrieve data by name.

This is particularly useful when some data is only known at runtime. For example, to pass data from one operation to another, to implement resource templating, to fetch data from an external system, or anything that needs to be computed at runtime.

"},{"location":"general/bindings/#syntax","title":"Syntax","text":"

The test below illustrates bindings declaration at different levels:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # bindings can be declared at the test level\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n    # bindings can also be declared at the step level\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        # bindings can also be declared at the operation level\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n          # combined bindings together using the `join` functions and\n          # assign the result to the GREETINGS environment variable\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        content: echo $GREETINGS\n
"},{"location":"general/bindings/#reference","title":"Reference","text":"

Browse the reference documentation to see the syntax details and where bindings can be declared.

"},{"location":"general/bindings/#inheritance","title":"Inheritance","text":"

Bindings can be configured at the test, step or operation level.

All bindings configured at a given level are automatically inherited at lower levels.

"},{"location":"general/bindings/#immutability","title":"Immutability","text":"

Bindings are immutable. This means two bindings can have the same name without overwriting each other.

When a binding is registered it potentially hides other bindings with the same name.

When this binding goes out of scope, previously registered bindings with the same name become visible again.

"},{"location":"general/bindings/#templating","title":"Templating","text":"

Both name and value of a binding can use templating.

"},{"location":"general/bindings/#built-in-bindings","title":"Built-in bindings","text":"

Chainsaw offers some built-in bindings you can directly use in your tests, steps and operations.

Browse the built-in bindings list to find available bindings.

"},{"location":"general/checks/","title":"Operation checks","text":"

Considering an operation's success or failure is not always as simple as checking an error code.

To support those kinds of use cases, some operations support additional checks to evaluate the operation result against an assertion tree.

"},{"location":"general/checks/#input-model","title":"Input model","text":"

Different operations have a different model passed through the assertion tree.

Please consult the Built-in bindings reference documentation to learn what is available depending on the operation.

"},{"location":"general/checks/#expect-vs-check","title":"Expect vs Check","text":"

While a simple check is enough to determine the result of a single operation, we needed a more advanced construct to cover apply, create, delete, patch and update operations. Those operations can operate on files containing multiple resources and every resource can lead to a different result and expectation.

"},{"location":"general/checks/#check","title":"Check","text":"

The example below uses a simple check. The operation is expected to fail (($error != null): true):

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: |\n          exit 1\n        check:\n          # an error is expected, this will:\n          # - succeed if the operation failed\n          # - fail if the operation succeeded\n          ($error != null): true\n
"},{"location":"general/checks/#expect","title":"Expect","text":"

To support more granular checks we use the expect field that contains an array of Expectations.

Every expectation is made of an optional match combined with a check statement.

This way it is possible to control the scope of a check:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        file: resources.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n

In the test above, only config maps are expected to fail. If the resources.yaml file contains other type of resources they are supposed to be created without error (if an error happens for a non config map resource, the operation will be considered a failure).

"},{"location":"general/inheritance/","title":"Inheritance","text":"

Chainsaw has a concept of levels and most of the configuration elements and dynamic elements are inherited from one layer to the next in one way or another.

"},{"location":"general/inheritance/#levels","title":"Levels","text":"
flowchart TD\n    Configuration -. Configuration elements are inherited in tests .-> Test\n    Test -. Test elements are inherited in test steps .-> Step\n    Step -. Step elements are inherited in step operations .-> Operation
"},{"location":"general/inheritance/#configuration","title":"Configuration","text":"

The first layer comes from the Chainsaw configuration. You can think about this layer as the global scope and a way to configure how Chainsaw will behave globally.

Under certain circumstances, lower layers will be allowed to consume and/or override elements from upper layers.

"},{"location":"general/inheritance/#test","title":"Test","text":"

At the test level, you can override or create new elements. They will only be visible to the test, steps and operations that are part of it.

In any case, tests are strongly isolated and have no way to communicate with or depend on other tests.

"},{"location":"general/inheritance/#step","title":"Step","text":"

Again, at the step level, you can override or create new elements and they will only be visible to the step and operations that are part of it.

"},{"location":"general/inheritance/#operation","title":"Operation","text":"

At the operation level, you can override or create new elements and use them in the operation itself.

"},{"location":"general/inheritance/#immutability","title":"Immutability","text":"

Even if elements are inherited, they are immutable.

Some elements can be overridden but never overwritten.

"},{"location":"general/inheritance/#outputs","title":"Outputs","text":"

Inheritance always flows from one level to the next and never propagates back to the upper levels.

There's no exception to this rule, but the only case where one operation can communicate with other ones is when using outputs.

"},{"location":"general/namespace/","title":"Test namespace","text":"

By default, Chainsaw will create an ephemeral namespace with a random name for each test, unless a specific namespace name is provided at the global or test level.

"},{"location":"general/namespace/#selection","title":"Selection","text":""},{"location":"general/namespace/#global","title":"Global","text":"

One way to control the namespace used to run tests is to specify the name in the Chainsaw configuration Namespace options.

If a namespace name is specified at the configuration level Chainsaw will use it to run the tests (unless an individual test overrides the namespace name).

"},{"location":"general/namespace/#per-test","title":"Per test","text":"

If the test name is specified in a test spec, Chainsaw will use it to run the test regardless of whether a namespace name was configured at the global level.

"},{"location":"general/namespace/#random","title":"Random","text":"

If no namespace name was specified at the global or test level, Chainsaw will create a random one for the lifetime of the test.

"},{"location":"general/namespace/#cleanup","title":"Cleanup","text":"

As with any other resource, Chainsaw will clean up the namespace only if the namespace was created by Chainsaw.

If the namespace already exists when the test starts, Chainsaw will use it to run the test but won't delete it after the test terminates.

"},{"location":"general/namespace/#template","title":"Template","text":"

A namespace template can be provided at the global or test level.

This is useful if you want to make something specific with the namespace Chainsaw creates (add labels, add annotations, etc...).

Tip

A namespace template specified at the test level takes precedence over the namespace template specified at the global level.

"},{"location":"general/namespace/#namespace-injection","title":"Namespace injection","text":"

Because the name of the namespace is only known at runtime, depending on the resource being manipulated, Chainsaw will eventually inject the namespace name, except if:

"},{"location":"general/namespace/#example","title":"Example","text":"

The resource below is a namespaced one and has no namespace specified. Chainsaw will automatically inject the namespace name in it:

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\n  # there is no namespace configured and the resource\n  # is a namespaced one.\n  # Chainsaw will automatically inject the test namespace\ndata:\n  foo: bar\n
"},{"location":"general/outputs/","title":"Outputs","text":"

Operation outputs can be useful for communicating and reusing computation results across operations.

Chainsaw evaluates outputs after an operation has finished executing. The results of output evaluations are registered in the bindings and are made available for the following operations.

"},{"location":"general/outputs/#syntax","title":"Syntax","text":""},{"location":"general/outputs/#basic","title":"Basic","text":"

The test below illustrates output usage:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        # output is used to register a new `$OUTPUT` binding\n        outputs:\n        - name: OUTPUT\n          value: ($stdout)\n        content: echo $GREETINGS\n    - script:\n        # output from the previous operation is used\n        # to configure an evironment variable\n        env:\n        - name: INPUT\n          value: ($OUTPUT)\n        content: echo $INPUT\n
"},{"location":"general/outputs/#matching","title":"Matching","text":"

An output supports an optional match field. The match statement is used to conditionally assign the output binding.

The test below illustrates output with matching:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        # output is used to register a new `$OUTPUT` binding\n        outputs:\n          # by default, the `$OUTPUT` binding is assigned\n          # the content of the standard output\n        - name: OUTPUT\n          value: ($stdout)\n          # if the match statement evaluates to true,\n          # the `$OUTPUT` binding will be set to\n          # 'YES! chainsaw is awesome'\n        - match:\n            ($OUTPUT): hello chainsaw is awesome\n          name: OUTPUT\n          value: YES! chainsaw is awesome\n        content: echo $GREETINGS\n    - script:\n        # output from the previous operation is used\n        # to configure an evironment variable\n        env:\n        - name: INPUT\n          value: ($OUTPUT)\n        content: echo $INPUT\n
"},{"location":"general/outputs/#reference","title":"Reference","text":"

Browse the reference documentation to see the syntax details and where outputs can be declared.

"},{"location":"general/outputs/#templating","title":"Templating","text":"

Both name and value of an output can use templating.

"},{"location":"general/references/","title":"References","text":"

Chainsaw tests often need to reference resources. Including references in tests can be done in multiple ways.

"},{"location":"general/references/#inline","title":"Inline","text":"

One way to declare a resource is to do it directly inside the test definition:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n

This doesn't encourage file reuse but can be handy, especially when the resource definition is short or when the execution environment doesn't support file system access.

"},{"location":"general/references/#file-reference","title":"File reference","text":"

Another option is to use the file field. The file can be a specific file, or multiple files declared using a glob pattern:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n
"},{"location":"general/references/#url-reference","title":"URL reference","text":"

A third option is to use a URL. Chainsaw uses https://github.com/hashicorp/go-getter, it will download the content from the remote service and load it in the operation resources:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/step/configmap.yaml\n
"},{"location":"general/references/#cardinality","title":"Cardinality","text":"

When using file-based references, it is important to note that the referenced file(s) can declare multiple resources. Internally, Chainsaw will duplicate the operation once per resource.

This is important to keep this in mind, especially when working with bindings and outputs. Bindings and outputs will be evaluated for every operation instance.

"},{"location":"general/templating/","title":"Templating","text":"

Chainsaw simplifies dynamic configuration with native templating support.

In the past, users have created all sorts of hacks using tools like envsubst for dynamic substitution of env-variables. Those workarounds usually lack flexibility and introduce new problems like hiding the real resources from Chainsaw, preventing it from cleaning resources properly.

Templating in Chainsaw solves exactly this kind of problem.

"},{"location":"general/templating/#syntax","title":"Syntax","text":"

Tip

Resource templating is heavily based on bindings and uses JMESPath language.

"},{"location":"general/templating/#bindings","title":"Bindings","text":"

In the template below, we are using the $namespace binding at two different places, effectively injecting the ephemeral namespace name in the name and the data.foo fields:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - assert:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: ($namespace)\n        data:\n          foo: ($namespace)\n
"},{"location":"general/templating/#jmespath","title":"JMESPath","text":"

In the template below, we are using the JMESPath join function to create a unique resource name:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - apply:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: (join('-', [$namespace, 'cm']))\n        data:\n          foo: bar\n
"},{"location":"guides/kuttl-migration/","title":"Migration from KUTTL","text":""},{"location":"guides/kuttl-migration/#overview","title":"Overview","text":"

The chainsaw migrate kuttl tests and chainsaw migrate kuttl config commands are designed for the migration of KUTTL tests to Chainsaw.

Reference documentation

You can view the full command documentation here.

"},{"location":"guides/kuttl-migration/#examples","title":"Examples","text":""},{"location":"guides/kuttl-migration/#migrate-tests","title":"Migrate tests","text":"

The command below will migrate KUTTL tests to Chainsaw and overwrite original files with converted ones.

chainsaw migrate kuttl tests path/to/kuttl/tests --save --cleanup\n

This will generate a chainsaw-test.yaml for every KUTTL test discovered.

"},{"location":"guides/kuttl-migration/#migrate-configuration","title":"Migrate configuration","text":"

The command below will migrate a KUTTL test suite file to the corresponding Chainsaw Configuration.

chainsaw migrate kuttl config path/to/kuttl/testsuite --save --cleanup\n

This will generate a .chainsaw.yaml configuration file.

"},{"location":"guides/lint/","title":"Lint tests","text":""},{"location":"guides/lint/#overview","title":"Overview","text":"

Chainsaw comes with a lint command to detect ill-formated tests.

Reference documentation

You can view the full command documentation here.

"},{"location":"guides/lint/#usage","title":"Usage","text":"

To build the docs of a test, Chainsaw provides the chainsaw lint test -f path/to/chainsaw-test.yaml command.

chainsaw lint test -f - <<EOF\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: assertion-tree\nspec:\n  steps:\n  - try:\n    - assert:\n        file: assert.yaml\nEOF\n
Processing input...\nThe document is valid\n
"},{"location":"guides/test-docs/","title":"Building test docs","text":""},{"location":"guides/test-docs/#overview","title":"Overview","text":"

Chainsaw makes it simple to build the documentation of your tests.

As test suites grow, it becomes important to document what a test does and how it is supposed to work.

Going through the implementation of a test to understand its purpose is not an efficient strategy.

Reference documentation

You can view the full command documentation here.

"},{"location":"guides/test-docs/#usage","title":"Usage","text":"

To build the docs of a test, Chainsaw provides the chainsaw build docs command.

chainsaw build docs --test-dir path/to/chainsaw/tests\n

This will automatically discover tests and document steps and operations in try, catch and finally statements.

"},{"location":"guides/test-docs/#the-description-field","title":"The description field","text":"

Additionally, you can set the description field in:

Chainsaw will output them nicely in the built docs.

"},{"location":"guides/test-docs/#example","title":"Example","text":"

See below for an example test and the corresponding built docs.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: basic\nspec:\n  description: This is a very simple test that creates a configmap and checks the content is as expected.\n  steps:\n  - description: This steps applies the configmap in the cluster and checks the configmap content.\n    try:\n    - description: Create the configmap.\n      apply:\n        file: configmap.yaml\n    - description: Check the configmap content.\n      assert:\n        file: configmap-assert.yaml\n
"},{"location":"guides/test-docs/#test-basic","title":"Test: basic","text":"

This is a very simple test that creates a configmap and checks the content is as expected.

"},{"location":"guides/test-docs/#steps","title":"Steps","text":"# Name Try Catch Finally 1 step-1 2 0 0"},{"location":"guides/test-docs/#step-step-1","title":"Step: step-1","text":"

This step applies the configmap in the cluster and checks the configmap content.

"},{"location":"guides/test-docs/#try","title":"Try","text":"# Operation Description 1 apply Create the configmap. 2 assert Check the configmap content."},{"location":"operations/","title":"Operations","text":"

Chainsaw supports the following operations:

"},{"location":"operations/#helpers","title":"Helpers","text":"

Chainsaw also supports kubectl helpers.

"},{"location":"operations/#properties","title":"Properties","text":""},{"location":"operations/#action-unicity","title":"Action unicity","text":"

Every operation must consist of a single action.

While it is syntactically possible to create an operation with multiple actions, Chainsaw will verify and reject tests if operations containing multiple actions are found.

The reasoning behind this intentional choice is that it becomes harder to understand in which order actions will be executed when an operation consists of multiple actions. For this reason, operations consisting of multiple actions are not allowed.

"},{"location":"operations/#common-fields","title":"Common fields","text":""},{"location":"operations/#continue-on-error","title":"Continue on error","text":"

The continueOnError field determines whether a test step should continue executing or not if the operation fails (in any case the test will be marked as failed).

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n      # in case of error the test will be marked as failed\n      # but the step will not stop execution and will\n      # continue executing the following operations\n    - continueOnError: true\n      apply:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/#description","title":"Description","text":"

All operations support a description field that can be used document your tests.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - description: Waits a couple of seconds\n      sleep:\n        duration: 3s\n
"},{"location":"operations/apply/","title":"Apply","text":"

The apply operation defines resources that should be applied to a Kubernetes cluster. If the resource does not exist yet it will be created, otherwise, it will be configured to match the provided configuration.

"},{"location":"operations/apply/#configuration","title":"Configuration","text":"

The full structure of the Apply is documented here.

"},{"location":"operations/apply/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/apply/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/step/configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/apply/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/assert/","title":"Assert","text":"

The assert operation allows you to specify conditions that should hold true for a successful test.

For example, after applying resources, you might want to ensure that a particular pod is running or a service is accessible.

"},{"location":"operations/assert/#configuration","title":"Configuration","text":"

The full structure of the Assert is documented here.

"},{"location":"operations/assert/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support | Operation checks support"},{"location":"operations/assert/#templating","title":"Templating","text":"

When working with assert and error operations, the content is already an assertion tree and therefore mostly represents a logical operation. An exception to this rule is for fields participating in the resource selection process.

For this reason, only elements used for looking up the resources from the cluster will be considered for templating. That is, apiVersion, kind, name, namespace and labels.

"},{"location":"operations/assert/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # use a specific file\n        file: ../resources/deployment-assert.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # use glob pattern\n        file: \"../assertions/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: Deployment\n          metadata:\n            name: foo\n          spec:\n            (replicas > 3): true\n
"},{"location":"operations/command/","title":"Command","text":"

The command operation provides a mean to execute a specific command during the test step.

Warning

Command arguments are not going through shell expansion.

It's crucial to consider potential differences in behavior, as Chainsaw may interpret them differently compared to regular shell environments.

"},{"location":"operations/command/#configuration","title":"Configuration","text":"

The full structure of the Command is documented here.

"},{"location":"operations/command/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/command/#kubeconfig","title":"KUBECONFIG","text":""},{"location":"operations/command/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - command:\n        entrypoint: echo\n        args:\n        - hello chainsaw\n
"},{"location":"operations/command/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - command:\n        entrypoint: echo\n        args:\n        - hello chainsaw\n        check:\n          # an error is expected, this will:\n          # - succeed if the operation failed\n          # - fail if the operation succeeded\n          ($error != null): true\n
"},{"location":"operations/create/","title":"Create","text":"

The create operation defines resources that should be created in a Kubernetes cluster.

If the resource to be created already exists in the cluster, the step will fail.

"},{"location":"operations/create/#configuration","title":"Configuration","text":"

The full structure of the Create is documented here.

"},{"location":"operations/create/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/create/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/create/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/delete/","title":"Delete","text":"

The delete operation defines resources that should be deleted from a Kubernetes cluster.

Warning

The propagation policy is forced to Background because some types default to Orphan (this is the case for unmanaged jobs for example) and we don't want to let dangling pods run in the cluster after cleanup.

"},{"location":"operations/delete/#configuration","title":"Configuration","text":"

The full structure of the Delete is documented here.

"},{"location":"operations/delete/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/delete/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - delete:\n        ref:\n          apiVersion: v1\n          kind: Pod\n          namespace: default\n          name: my-test-pod\n
"},{"location":"operations/delete/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - delete:\n        ref:\n          apiVersion: v1\n          kind: Pod\n          namespace: default\n          name: my-test-pod\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: Pod\n            metadata:\n              namespace: default\n              name: my-test-pod\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/error/","title":"Error","text":"

The error operation lets you define a set of expected errors for a test step. If any of these errors occur during the test, they are treated as expected outcomes. However, if an error that's not on this list occurs, it will be treated as a test failure.

"},{"location":"operations/error/#configuration","title":"Configuration","text":"

The full structure of the Error is documented here.

"},{"location":"operations/error/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support | Operation checks support"},{"location":"operations/error/#templating","title":"Templating","text":"

When working with assert and error operations, the content is already an assertion tree and therefore mostly represents a logical operation. An exception to this rule is for fields participating in the resource selection process.

For this reason, only elements used for looking up the resources from the cluster will be considered for templating. That is, apiVersion, kind, name, namespace and labels.

"},{"location":"operations/error/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # use a specific file\n        file: ../resources/deployment-error.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # use glob pattern\n        file: \"../errors/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # use an URL\n        file: https://raw.githubusercontent.com/user/repo/branch/path/to/deployment-error.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: Deployment\n          metadata:\n            name: foo\n          spec:\n            (replicas > 3): true\n
"},{"location":"operations/patch/","title":"Patch","text":"

The patch operation defines resources that should be modified in a Kubernetes cluster.

If the resource to be modified does not exist in the cluster, the step will fail.

"},{"location":"operations/patch/#configuration","title":"Configuration","text":"

The full structure of the Patch is documented here.

"},{"location":"operations/patch/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/patch/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/patch/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/script/","title":"Script","text":"

The script operation provides a means to run a script during the test step.

"},{"location":"operations/script/#configuration","title":"Configuration","text":"

The full structure of the Script is documented here.

"},{"location":"operations/script/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/script/#kubeconfig","title":"KUBECONFIG","text":""},{"location":"operations/script/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: |\n          echo \"hello chainsaw\"\n
"},{"location":"operations/script/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: |\n          echo \"hello chainsaw\"\n        check:\n          # an error is expected, this will:\n          # - succeed if the operation failed\n          # - fail if the operation succeeded\n          ($error != null): true\n
"},{"location":"operations/sleep/","title":"Sleep","text":"

The sleep operation provides a means to sleep for a configured duration.

"},{"location":"operations/sleep/#configuration","title":"Configuration","text":"

The full structure of the Sleep is documented here.

"},{"location":"operations/sleep/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/sleep/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - sleep:\n        duration: 30s\n
"},{"location":"operations/update/","title":"Update","text":"

The update operation defines resources that should be updated in a Kubernetes cluster.

If the resource to be updated doesn't exist in the cluster, the step will fail.

"},{"location":"operations/update/#configuration","title":"Configuration","text":"

The full structure of the Update is documented here.

"},{"location":"operations/update/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/update/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example-multi\nspec:\n  steps:\n  - try:\n    - update:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/update/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/helpers/","title":"Kubectl helpers","text":"

Kubectl helpers are declarative versions of kubectl imperative commands.

"},{"location":"operations/helpers/#implementation","title":"Implementation","text":"

Helpers are implemented as syntactic sugars.

They are translated into their corresponding kubectl commands and executed as such.

"},{"location":"operations/helpers/#kubeconfig","title":"KUBECONFIG","text":""},{"location":"operations/helpers/#helpers","title":"Helpers","text":""},{"location":"operations/helpers/describe/","title":"Describe","text":"

Show details of a specific resource or group of resources.

Deprecated syntax

You can specify the resource directly instead of using apiVersion and kind.

This is a deprecated syntax though and will be removed in a future version.

"},{"location":"operations/helpers/describe/#configuration","title":"Configuration","text":"

The full structure of the Describe resource is documented here.

"},{"location":"operations/helpers/describe/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/describe/#clustered-resources","title":"Clustered resources","text":"

When used with a clustered resource, the namespace is ignored and is not added to the corresponding kubectl command.

"},{"location":"operations/helpers/describe/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/describe/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/describe/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        # describe all pods in the test namespace\n        apiVersion: v1\n        kind: Pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        # describe pods that have a name starting with the provided `my-pod`\n        name: my-pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        # describe pods in the namespace `foo`\n        namespace: foo\n
"},{"location":"operations/helpers/describe/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        # describe pods using a label selector query\n        selector: app=my-app\n
"},{"location":"operations/helpers/describe/#show-events","title":"Show events","text":"

Tip

By default, showEventsis true.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        showEvents: false\n
"},{"location":"operations/helpers/events/","title":"Events","text":"

Display one or many events.

"},{"location":"operations/helpers/events/#configuration","title":"Configuration","text":"

The full structure of the Events resource is documented here.

"},{"location":"operations/helpers/events/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/events/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/events/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/events/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get all events in the test namespace\n    - events: {}\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get events in a specific namespace\n    - events:\n        namespace: foo\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get event by name\n    - events:\n        name: my-event\n
"},{"location":"operations/helpers/events/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - events:\n        # get events using a label selector query\n        selector: app=my-app\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - events:\n        # get events using a label selector query\n        selector: app=my-app\n        namespace: foo\n
"},{"location":"operations/helpers/events/#format","title":"Format","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - events:\n        format: json\n
"},{"location":"operations/helpers/get/","title":"Get","text":"

Display one or many resources.

Deprecated syntax

You can specify the resource directly instead of using apiVersion and kind.

This is a deprecated syntax though and will be removed in a future version.

"},{"location":"operations/helpers/get/#configuration","title":"Configuration","text":"

The full structure of the Get resource is documented here.

"},{"location":"operations/helpers/get/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/get/#clustered-resources","title":"Clustered resources","text":"

When used with a clustered resource, the namespace is ignored and is not added to the corresponding kubectl command.

"},{"location":"operations/helpers/get/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/get/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/get/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get all pods in the test namespace\n    - get:\n        apiVersion: v1\n        kind: Pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        # get pods that have a name starting with the provided `my-pod`\n        name: my-pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        # get pods in the namespace `foo`\n        namespace: foo\n
"},{"location":"operations/helpers/get/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        # get pods using a label selector query\n        selector: app=my-app\n
"},{"location":"operations/helpers/get/#format","title":"Format","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        format: json\n
"},{"location":"operations/helpers/logs/","title":"Pods logs","text":"

Print the logs for a container in a pod or specified resource.

"},{"location":"operations/helpers/logs/#configuration","title":"Configuration","text":"

The full structure of the PodLogs resource is documented here.

"},{"location":"operations/helpers/logs/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/logs/#test-namespace","title":"Test namespace","text":"

Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/logs/#all-namespaces","title":"All namespaces","text":"

It is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/logs/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # all pods in the test namespace\n    - podLogs: {}\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        # pods that have a name starting with the provided `my-pod`\n        name: my-pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        # pods in the namespace `foo`\n        namespace: foo\n
"},{"location":"operations/helpers/logs/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        # match pods using a label selector query\n        selector: app=my-app\n
"},{"location":"operations/helpers/logs/#tail","title":"Tail","text":"

Tip

By default, tail will be 10 when a label selector is used, and all if a pod name is specified.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        tail: 30\n
"},{"location":"operations/helpers/logs/#container","title":"Container","text":"

Tip

By default logs from all containers will be fetched.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        container: nginx\n
"},{"location":"operations/helpers/wait/","title":"Wait","text":"

Wait for a specific condition on one or many resources.

Deprecated syntax

You can specify the resource directly instead of using apiVersion and kind.

This is a deprecated syntax though and will be removed in a future version.

"},{"location":"operations/helpers/wait/#configuration","title":"Configuration","text":"

The full structure of the Wait resource is documented here.

"},{"location":"operations/helpers/wait/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/wait/#clustered-resources","title":"Clustered resources","text":"

When used with a clustered resource, the namespace is ignored and is not added to the corresponding kubectl command.

"},{"location":"operations/helpers/wait/#all-resources","title":"All resources","text":"

If you don't specify a name or a selector, the wait operation will consider all resources.

"},{"location":"operations/helpers/wait/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/wait/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/wait/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    # wait all pods are ready in the test namespace\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        # wait a specific pod is ready in the test namespace\n        name: my-pod\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        # wait all pods are ready in the namespace `foo`\n        namespace: foo\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n
"},{"location":"operations/helpers/wait/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        # match pods using a label selector query\n        selector: app=foo\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n
"},{"location":"operations/helpers/wait/#deletion","title":"Deletion","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        timeout: 1m\n        for:\n          # wait for deletion\n          deletion: {}\n
"},{"location":"operations/helpers/wait/#format","title":"Format","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        format: json\n
"},{"location":"quick-start/","title":"Getting started","text":"

Chainsaw is a tool primarily developed to run end-to-end tests in Kubernetes clusters.

It is meant to test Kubernetes operators work as expected by running a sequence of steps and asserting various conditions.

"},{"location":"quick-start/#why-we-made-it","title":"Why we made it?","text":"

While developing Kyverno we need to run end-to-end tests to make sure our admission controller works as expected.

A typical Kyverno end-to-end test

Kyverno can validate, mutate and generate resources based on policies installed in a cluster and a typical test is:

  1. Create a policy
  2. Create a resource
  3. Check that Kyverno acted as expected
  4. Cleanup and move to the next test
"},{"location":"quick-start/#how-to-use-it","title":"How to use it?","text":"

Chainsaw is built with CI tools in mind - you only really need to download and execute it in your build script.

However, installing it on your local machine is entirely possible.

"},{"location":"quick-start/assertion-trees/","title":"Use assertions","text":"

Chainsaw allows declaring complex assertions with a simple and no-code approach, allowing assertions based on comparisons beyond simple equality, working with arrays, and other scenarios that could not be achieved before.

Tip

Under the hood, Chainsaw uses kyverno-json assertion trees. Refer to the assertion trees documentation for more details on the supported syntax.

"},{"location":"quick-start/assertion-trees/#basic-assertion","title":"Basic assertion","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            name: coredns\n            namespace: kube-system\n          spec:\n            replicas: 2\n

When asking Chainsaw to execute the assertion above, it will look for a deployment named coredns in the kube-system namespace and will compare the existing resource with the (partial) resource definition contained in the assertion.

In this specific case, if the field spec.replicas is set to 2 in the existing resource, the assertion will be considered valid. If it is not equal to 2 the assertion will be considered failed.

This is the most basic assertion Chainsaw can evaluate.

"},{"location":"quick-start/assertion-trees/#slightly-less-basic-assertion","title":"Slightly less basic assertion","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            labels:\n              k8s-app: kube-dns\n            namespace: kube-system\n          spec:\n            replicas: 2\n

This time we are not providing a resource name.

Chainsaw will look up all deployments with the k8s-app: kube-dns label in the kube-system namespace. The assertion will be considered valid if at least one deployment matches the (partial) resource definition contained in the assertion. If none match, the assertion will be considered failed.

Apart from the resource lookup process being a little bit more interesting, this kind of assertion is essentially the same as the previous one. Chainsaw is basically making a decision by comparing an actual and expected resource.

"},{"location":"quick-start/assertion-trees/#beyond-simple-equality","title":"Beyond simple equality","text":"

The assertion below will check that the number of replicas for a deployment is greater than 1 AND less than 4.

Chainsaw doesn't need to know the exact expected number of replicas. The (replicas > 1 && replicas < 4) expression will be evaluated until the result is true or the operation timeout expires (making the assertion fail).

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            name: coredns\n            namespace: kube-system\n          spec:\n            (replicas > `1` && replicas < `4`): true\n

Tip

To indicate that a key or value in the YAML document is an expression, simply place the element between parentheses:

"},{"location":"quick-start/assertion-trees/#working-with-arrays","title":"Working with arrays","text":"

Chainsaw query language makes it easy to assert on arrays. You can filter and transform arrays to select what you want to assert.

"},{"location":"quick-start/assertion-trees/#filtering","title":"Filtering","text":"

In the example below we are creating a resource, then we assert that a condition with type == 'Ready' exists and has a field matching status: 'True':

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            ...\n    - assert:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            # filter conditions array to keep elements where `type == 'Ready'`\n            # and assert there's a single element matching the filter\n            # and that this element status is `True`\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/assertion-trees/#iterating","title":"Iterating","text":"

Being able to filter arrays allows selecting the elements to be processed.

On top of that, Chainsaw allows iterating over array elements to validate each item separately.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            labels:\n              k8s-app: kube-dns\n            namespace: kube-system\n          spec:\n            template:\n              spec:\n                # the `~` modifier tells Chainsaw to iterate over the array elements\n                ~.(containers):\n                  securityContext: {}\n

This assertion uses the ~ modifier and Chainsaw will evaluate descendants once per element in the array.

"},{"location":"quick-start/assertion-trees/#comprehensive-reporting","title":"Comprehensive reporting","text":"

Chainsaw offers detailed resource diffs upon assertion failures.

In the example below, the assertion failure message (metadata.annotations.foo: Invalid value: \"null\": Expected value: \"bar\") is augmented with a resource diff.

It provides a clear view of discrepancies between expected and actual resources and gives more context around the specific failure (we can easily identify the owner of the offending pod for example).

| 09:55:50 | deployment | step-1   | ASSERT    | RUN   | v1/Pod @ chainsaw-rare-liger/*\n| 09:56:20 | deployment | step-1   | ASSERT    | ERROR | v1/Pod @ chainsaw-rare-liger/*\n    === ERROR\n    ---------------------------------------------------\n    v1/Pod/chainsaw-rare-liger/example-5477b4ff8c-tnhd9\n    ---------------------------------------------------\n    * metadata.annotations.foo: Invalid value: \"null\": Expected value: \"bar\"\n\n    --- expected\n    +++ actual\n    @@ -1,10 +1,16 @@\n      apiVersion: v1\n      kind: Pod\n      metadata:\n    -  annotations:\n    -    foo: bar\n        labels:\n          app: nginx\n    +  name: example-5477b4ff8c-tnhd9\n        namespace: chainsaw-rare-liger\n    +  ownerReferences:\n    +  - apiVersion: apps/v1\n    +    blockOwnerDeletion: true\n    +    controller: true\n    +    kind: ReplicaSet\n    +    name: example-5477b4ff8c\n    +    uid: 118abe16-ec42-4894-83db-64479c4aac6f\n      spec: {}\n| 09:56:20 | deployment | step-1   | TRY       | DONE  |\n
"},{"location":"quick-start/assertion-trees/#next-step","title":"Next step","text":"

To continue our exploration of the main Chainsaw features, let's look at bindings and resource templating next.

"},{"location":"quick-start/bindings/","title":"Use bindings","text":"

You can think of bindings as a side context where you can store and retrieve data based on keys.

This is particularly useful when some data is only known at runtime. For example, to pass data from one operation to another, to implement resource templating, to fetch data from an external system, etc.

Chainsaw offers some built-in bindings you can directly use in your tests but you can also create your own bindings if needed.

"},{"location":"quick-start/bindings/#inheritance","title":"Inheritance","text":"

Bindings can be configured at the test, step or operation level.

All bindings configured at a given level are automatically inherited in child levels.

JMESPath

Chainsaw uses the JMESPath language, and bindings are implemented using lexical scoping.

"},{"location":"quick-start/bindings/#immutability","title":"Immutability","text":"

Bindings are immutable. This means two bindings can have the same name without overwriting each other.

When a binding is registered it potentially hides other bindings with the same name.

When this binding goes out of scope, previously registered bindings with the same name become visible again.

"},{"location":"quick-start/bindings/#built-in-bindings","title":"Built-in bindings","text":"

The $namespace binding is a good example of a built-in binding provided by Chainsaw. It contains the name of the ephemeral namespace used to execute a test (by default Chainsaw will create an ephemeral namespace for each test).

In the operation below, we are assigning the value of the $namespace binding to an environment variable, and echo it in a script:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        env:\n          # assign the value of the `$namespace` binding\n          # to the environment variable `FOO`\n        - name: FOO\n          value: ($namespace)\n        content: echo $FOO\n
"},{"location":"quick-start/bindings/#custom-bindings","title":"Custom bindings","text":"

On top of built-in bindings, you can also create your own ones, combine bindings together, call JMESPath functions using bindings as arguments, etc.

In the test below we create custom bindings at different levels in the test, combine them by calling the join function, assign the result to an environment variable, and echo it in a script:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # bindings can be declared at the test level\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n    # bindings can also be declared at the step level\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        # bindings can also be declared at the operation level\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n          # combined bindings together using the `join` functions and\n          # assign the result to the GREETINGS environment variable\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        content: echo $GREETINGS\n
"},{"location":"quick-start/bindings/#next-step","title":"Next step","text":"

Let's see how bindings can be useful with resource templating.

"},{"location":"quick-start/cleanup/","title":"Control your cleanup","text":"

Unless configured differently, by default Chainsaw will automatically remove the resources it created after a test finishes.

Cleanup happens in reverse order of creation (created last, cleaned up first). This is important, especially when the controller being tested makes use of finalizers.

Overriding cleanup timeout

Note that Chainsaw performs a blocking deletion, that is, it will wait until the resource is not present anymore in the cluster before proceeding with the next resource cleanup.

"},{"location":"quick-start/cleanup/#timeout","title":"Timeout","text":"

A global cleanup timeout can be defined at the configuration level or using command line flags.

It can also be overridden on a per-test or per-step basis but not at the operation level.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  timeouts:\n    # cleanup timeout at the test level\n    cleanup: 30s\n  steps:\n  - timeouts:\n      # cleanup timeout at the step level\n      cleanup: 2m\n    try: ...\n
"},{"location":"quick-start/cleanup/#automatic-cleanup","title":"Automatic cleanup","text":"

After a test, every resource created by Chainsaw will be automatically deleted. This applies to create and apply operations.

In the logs below we can see Chainsaw deletes the previously created resource:

    | 15:21:29 | quick-start | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-cute-cod\n    | 15:21:29 | quick-start | step-1   | TRY       | RUN   |\n    | 15:21:29 | quick-start | step-1   | APPLY     | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | CREATE    | OK    | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | APPLY     | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | ASSERT    | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | ASSERT    | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | TRY       | DONE  |\n    === step cleanup process start ===\n    | 15:21:29 | quick-start | step-1   | CLEANUP   | RUN   |\n    | 15:21:29 | quick-start | step-1   | DELETE    | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | DELETE    | OK    | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | DELETE    | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | CLEANUP   | DONE  |\n    === step cleanup process end ===\n    === test cleanup process start ===\n    | 15:21:29 | quick-start | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-cute-cod\n    | 15:21:29 | quick-start | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-cute-cod\n    | 15:21:34 | quick-start | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-cute-cod\n    === test cleanup process end ===\n
"},{"location":"quick-start/cleanup/#manual-cleanup","title":"Manual cleanup","text":"

Under certain circumstances, automatic cleanup is not enough and we want to execute custom operations.

Chainsaw allows registering cleanup operations that will be run after automatic cleanup. Custom cleanup operations live at the test step level:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # this step will create a local cluster\n  - try:\n    - script:\n        timeout: 1m\n        content: |\n          kind create cluster --name dynamic --kubeconfig ./dynamic\n    # at cleanup time, we want to delete the local cluster we created\n    # and remove the associated kubeconfig\n    cleanup:\n    - script:\n        content: |\n          kind delete cluster --name dynamic\n    - script:\n        content: |\n          rm -f ./dynamic\n
"},{"location":"quick-start/cleanup/#next-step","title":"Next step","text":"

At this point, we covered the main Chainsaw features.

Look at the next steps section to find out what to do next.

"},{"location":"quick-start/completion/","title":"Shell completion","text":"

Once installed, use chainsaw completion command to generate and register the autocompletion script for the specified shell.

Supported shells are:

"},{"location":"quick-start/first-test/","title":"Create a test","text":"

To create a Chainsaw test all you need to do is to create one (or more) YAML file(s).

The recommended approach is to create one folder per test, with a chainsaw-test.yaml file containing one (or more) test definition(s). The test definition can reference other files in the same folder or anywhere else on the file system as needed.

Tip

While chainsaw supports other syntaxes, we strongly recommend the explicit approach.

"},{"location":"quick-start/first-test/#what-is-a-test","title":"What is a test?","text":"

To put it simply, a test can be represented as an ordered sequence of test steps.

In turn, a test step can be represented as an ordered sequence of operations.

When one of the operations fails the test is considered failed.

If all operations succeed the test is considered successful.

"},{"location":"quick-start/first-test/#lets-write-our-first-test","title":"Let's write our first test","text":"

For this quick start, we will create a (very simple) Test with one step and two operations:

  1. Create a ConfigMap from a manifest
  2. Verify the ConfigMap was created and contains the expected data

Follow the instructions below to create the folder and files defining our first test.

"},{"location":"quick-start/first-test/#create-a-test-folder","title":"Create a test folder","text":"
# create test folder\nmkdir chainsaw-quick-start\n\n# enter test folder\ncd chainsaw-quick-start\n
"},{"location":"quick-start/first-test/#create-a-configmap-manifest","title":"Create a ConfigMap manifest","text":"
# create a ConfigMap\ncat > configmap.yaml << EOF\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  foo: bar\nEOF\n
"},{"location":"quick-start/first-test/#create-a-test-manifest","title":"Create a test manifest","text":"

By default, Chainsaw will look for a file named chainsaw-test.yaml in every folder.

# create test file\ncat > chainsaw-test.yaml << EOF\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: quick-start\nspec:\n  steps:\n  - try:\n    # first operation: create the config map\n    - apply:\n        # file is relative to the test folder\n        file: configmap.yaml\n    # second operation: verify the config map exists and contains the expected data\n    - assert:\n        # file is relative to the test folder\n        file: configmap.yaml\nEOF\n
"},{"location":"quick-start/first-test/#next-step","title":"Next step","text":"

Now we have created our first test, you can continue to the next section to execute it.

"},{"location":"quick-start/install/","title":"Installation","text":"

You can install the pre-compiled binary (in several ways), compile from sources, or run with Docker.

We also provide a GitHub action to easily install Chainsaw in your workflows.

"},{"location":"quick-start/install/#install-the-pre-compiled-binary","title":"Install the pre-compiled binary","text":""},{"location":"quick-start/install/#homebrew-tap","title":"Homebrew tap","text":"

add tap:

brew tap kyverno/chainsaw https://github.com/kyverno/chainsaw\n

install chainsaw:

brew install kyverno/chainsaw/chainsaw\n

Don't forget to specify the tap name

Homebrew core already has a tool named chainsaw.

Be sure that you specify the tap name when installing to install the right tool.

"},{"location":"quick-start/install/#manually","title":"Manually","text":"

Download the pre-compiled binaries for your system from the releases page and copy them to the desired location.

"},{"location":"quick-start/install/#install-using-go-install","title":"Install using go install","text":"

You can install with go install with:

go install github.com/kyverno/chainsaw@latest\n
"},{"location":"quick-start/install/#run-with-docker","title":"Run with Docker","text":"

Chainsaw is also available as a Docker image which you can pull and run:

docker pull ghcr.io/kyverno/chainsaw:<version>\n

Warning

Since Chainsaw relies on files for its operation (like test definitions), you will need to bind mount the necessary directories when running it via Docker.

docker run --rm                             \\\n    -v ./testdata/e2e/:/chainsaw/           \\\n    -v ${HOME}/.kube/:/etc/kubeconfig/      \\\n    -e KUBECONFIG=/etc/kubeconfig/config    \\\n    --network=host                          \\\n    ghcr.io/kyverno/chainsaw:<version>      \\\n    test /chainsaw --config /chainsaw/config.yaml\n
"},{"location":"quick-start/install/#compile-from-sources","title":"Compile from sources","text":"

clone:

git clone https://github.com/kyverno/chainsaw.git\n

build the binaries:

cd chainsaw\ngo mod tidy\nmake build\n

verify it works:

./chainsaw version\n
"},{"location":"quick-start/install/#install-using-nix-package","title":"Install using Nix Package","text":"

To install kyverno-chainsaw, refer to the documentation.

"},{"location":"quick-start/install/#on-nixos","title":"On NixOS","text":"
nix-env -iA nixos.kyverno-chainsaw\n
"},{"location":"quick-start/install/#on-non-nixos","title":"On Non-NixOS","text":"
nix-env -iA nixpkgs.kyverno-chainsaw\n

Warning

Using nix-env permanently modifies a local profile of installed packages. This must be updated and maintained by the user in the same way as with a traditional package manager, foregoing many of the benefits that make Nix uniquely powerful. Using nix-shell or a NixOS configuration is recommended instead.

"},{"location":"quick-start/install/#using-nixos-configuration","title":"Using NixOS Configuration","text":"

Add the following Nix code to your NixOS Configuration, usually located in /etc/nixos/configuration.nix :

environment.systemPackages = [\n  pkgs.kyverno-chainsaw\n];\n
"},{"location":"quick-start/install/#using-nix-shell","title":"Using nix-shell","text":"

A nix-shell will temporarily modify your $PATH environment variable. This can be used to try a piece of software before deciding to permanently install it. Use the following command to install kyverno-chainsaw :

nix-shell -p kyverno-chainsaw\n
"},{"location":"quick-start/install/#github-action","title":"GitHub action","text":"

A GitHub action is available to install Chainsaw in your workflows. See the GitHub action dedicated documentation.

"},{"location":"quick-start/next-steps/","title":"Next steps","text":"

We covered the main features of Chainsaw in this Getting started sections.

While this should help you understand Chainsaw better, there are a lot of other things Chainsaw can do for you.

Tip

If there's anything you would like to be improved, please reach out, we will be happy to discuss and improve as much as we can.

To continue exploring the capabilities of Chainsaw:

"},{"location":"quick-start/operation-outputs/","title":"Use operation outputs","text":"

Operation outputs can be useful for communicating and reusing computation results across operations.

"},{"location":"quick-start/operation-outputs/#lifetime-of-outputs","title":"Lifetime of outputs","text":"

Once an output has been added to the bindings context, this binding will be available to all following operations in the same step.

Currently, outputs do not cross the step boundaries.

"},{"location":"quick-start/operation-outputs/#matching","title":"Matching","text":"

An output supports an optional match field. The match is used to conditionally create a binding.

In the case of applying a file, for example, the file may contain multiple resources. The match can be used to select the resource to use for creating the binding.

"},{"location":"quick-start/operation-outputs/#load-an-existing-resource","title":"Load an existing resource","text":"

The example below invokes a kubectl command to get a configmap from the cluster in json format.

The json output is then parsed and added to the $cm binding and the next operation performs an assertion on it by reading the binding instead of querying the cluster.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: kubectl get cm quick-start -n $NAMESPACE -o json\n        outputs:\n          # parse stdout json output and bind the result to `$cm`\n        - name: cm\n          value: (json_parse($stdout))\n    - assert:\n        resource:\n          ($cm):\n            metadata:\n              (uid != null): true\n
"},{"location":"quick-start/operation-outputs/#match-a-resource","title":"Match a resource","text":"

The example below applies resources from a file.

When the resource being applied is a configmap, we bind the resource to an output to print its UID in the next operation.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: ./resources.yaml\n        outputs:\n          # match the configmap resource and bind it to `$cm`\n        - match:\n            apiVersion: v1\n            kind: ConfigMap\n          name: cm\n          value: (@)\n    - script:\n        env:\n        - name: UID\n          value: ($cm.metadata.uid)\n        content: echo $UID\n
"},{"location":"quick-start/operation-outputs/#next-step","title":"Next step","text":"

In the next section, we will look at the three main elements of a test step, the try, catch and finally blocks.

"},{"location":"quick-start/resource-templating/","title":"Use resource templating","text":"

Chainsaw simplifies dynamic resource configuration with native resource templating support.

Sometimes things we need to create resources or assertions are only known at runtime.

In the past, users have created all sorts of hacks using tools like envsubst for dynamic substitution of env-variables. Those workarounds usually lack flexibility and introduce new problems like hiding the real resources from Chainsaw, preventing it from cleaning resources properly.

Tip

Resource templating is heavily based on bindings and uses JMESPath language.

"},{"location":"quick-start/resource-templating/#leverage-bindings","title":"Leverage bindings","text":"

In the template below, we are using the $namespace binding at two different places, effectively injecting the ephemeral namespace name in the name and the data.foo fields:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - assert:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: ($namespace)\n        data:\n          foo: ($namespace)\n
"},{"location":"quick-start/resource-templating/#leverage-jmespath","title":"Leverage JMESPath","text":"

In the template below, we are using the JMESPath join function to create a unique resource name:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - apply:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: (join('-', [$namespace, 'cm']))\n        data:\n          foo: bar\n
"},{"location":"quick-start/resource-templating/#next-step","title":"Next step","text":"

Combining bindings and templates with operation outputs allows even more flexibility to pass arbitrary data from one operation to another.

"},{"location":"quick-start/resources/","title":"Additional resources","text":"

Resources, blog posts and videos talking about Chainsaw:

"},{"location":"quick-start/resources/#chainsaw-video-review","title":"Chainsaw video review","text":"

If you haven't watched the video below yet, we strongly recommend watching it to discover Chainsaw!

"},{"location":"quick-start/run-tests/","title":"Run tests","text":"

After installing chainsaw and writing tests, the next natural step is to run Chainsaw to execute the tests.

"},{"location":"quick-start/run-tests/#create-a-local-cluster","title":"Create a local cluster","text":"

To use Chainsaw you will need a Kubernetes cluster, Chainsaw won't create one for you.

Not a cluster management tool

We consider this is not the responsibility of Chainsaw to manage clusters. There are plenty of solutions to create and manage local clusters that will do that better than Chainsaw.

The command below will create a local cluster using kind. Use the tool of your choice or directly jump to the next section if you already have a KUBECONFIG configured and pointing to a valid cluster.

# create cluster\nkind create cluster --image \"kindest/node:v1.29.4\"\n
"},{"location":"quick-start/run-tests/#run-chainsaw","title":"Run Chainsaw","text":"

Now you can run the chainsaw test command.

> chainsaw test\n\nVersion: (devel)\nLoading default configuration...\n- Using test file: chainsaw-test.yaml\n- TestDirs [.]\n- SkipDelete false\n- FailFast false\n- ReportFormat ''\n- ReportName ''\n- Namespace ''\n- FullName false\n- IncludeTestRegex ''\n- ExcludeTestRegex ''\n- ApplyTimeout 5s\n- AssertTimeout 30s\n- CleanupTimeout 30s\n- DeleteTimeout 15s\n- ErrorTimeout 30s\n- ExecTimeout 5s\nLoading tests...\n- quick-start (.)\nRunning tests...\n=== RUN   chainsaw\n=== PAUSE chainsaw\n=== CONT  chainsaw\n=== RUN   chainsaw/quick-start\n=== PAUSE chainsaw/quick-start\n=== CONT  chainsaw/quick-start\n    | 10:44:26 | quick-start | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-immense-jay\n    | 10:44:26 | quick-start | step-1   | TRY       | RUN   |\n    | 10:44:26 | quick-start | step-1   | APPLY     | RUN   | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | CREATE    | OK    | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | APPLY     | DONE  | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | ASSERT    | RUN   | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | ASSERT    | DONE  | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | TRY       | DONE  |\n    | 10:44:26 | quick-start | @cleanup | DELETE    | RUN   | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | @cleanup | DELETE    | OK    | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | @cleanup | DELETE    | DONE  | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-immense-jay\n    | 10:44:26 | quick-start | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-immense-jay\n    | 10:44:31 | quick-start | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-immense-jay\n--- PASS: chainsaw (0.00s)\n    --- PASS: chainsaw/quick-start (5.25s)\nPASS\nTests Summary...\n- Passed  tests 1\n- Failed  tests 0\n- Skipped tests 0\nDone.\n

Tip

Chainsaw expects a path to the test folder and will discover tests by analyzing files recursively. When no path is provided Chainsaw will use the current path by default (.).

"},{"location":"quick-start/run-tests/#next-step","title":"Next step","text":"

The test above demonstrates the most basic usage of Chainsaw. In the next sections, we will look at the main features that make Chainsaw a very unique tool.

"},{"location":"quick-start/timeouts/","title":"Control your timeouts","text":"

Timeouts in Chainsaw are specified per type of operation. This is handy because the timeout varies greatly depending on the nature of an operation.

For example, applying a manifest in a cluster is expected to be reasonably fast, while validating a resource can be a long operation.

"},{"location":"quick-start/timeouts/#inheritance","title":"Inheritance","text":"

Timeouts can be configured globally and at the test, step or individual operation level.

All timeouts configured at a given level are automatically inherited in child levels. When looking up a timeout, the most specific one takes precedence over the others.

Info

To learn more about timeouts and how to configure global values, see the timeouts configuration page.

"},{"location":"quick-start/timeouts/#at-the-test-level","title":"At the test level","text":"

When a timeout is configured at the test level it will apply to all operations and steps in the test, unless overridden at a more specific level.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # timeouts configured at the test level will apply to all operations and steps\n  # unless overriden at the step level and/or individual operation level\n  timeouts:\n    apply: 5s\n    assert: 1m\n    # ...\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            # ...\n    - assert:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/timeouts/#at-the-step-level","title":"At the step level","text":"

When a timeout is configured at the step level it will apply to all operations in the step, unless overridden at a more specific level.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # timeouts configured at the step level will apply to all operations\n    # in the step unless overriden at the individual operation level\n  - timeouts:\n      apply: 5s\n      # ...\n    try:\n    - apply:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            # ...\n    # timeouts configured at the step level will apply to all operations\n    # in the step unless overriden at the individual operation level\n  - timeouts:\n      assert: 1m\n      # ...\n    try:\n    - assert:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/timeouts/#at-the-operation-level","title":"At the operation level","text":"

When a timeout is configured at the operation level, it takes precedence over all timeouts configured at upper levels.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # timeout configured at the operation level takes precedence\n        # over timeouts configured at upper levels\n        timeout: 5s\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            # ...\n    - assert:\n        # timeout configured at the operation level takes precedence\n        # over timeouts configured at upper levels\n        timeout: 1m\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/timeouts/#next-step","title":"Next step","text":"

In the next section, we will see how Chainsaw manages cleanup.

"},{"location":"quick-start/try-catch/","title":"Use try, catch and finally","text":"

A test step is made of 3 main blocks used to determine the actions Chainsaw will perform when executing the step, depending on operations outcome.

Operations defined in the try block are executed first, then:

Note

Note that all operations coming from the catch or finally blocks are executed. If one operation fails, Chainsaw will mark the test as failed and continue executing with the next operation.

"},{"location":"quick-start/try-catch/#cleanup","title":"Cleanup","text":"

At the end of a test, Chainsaw automatically cleans up the resources created during the test (cleanup is done in the opposite order of creation).

All operations from the catch and finally blocks are executed before the cleanup process kicks in. This order allows analyzing the resources that potentially caused the step failure before they are deleted.

"},{"location":"quick-start/try-catch/#catch","title":"Catch","text":"

Operations in a catch block are executed only when the step is considered failed.

This is particularly useful to collect additional information to help understand what caused the failure.

In the example below, the test contains a catch block to collect events in the cluster when an operation fails in the step.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # ...\n    - assert:\n        # ...\n    # collect events in the `catch` block\n    # will be executed only if an operation failed\n    catch:\n    - events: {}\n
"},{"location":"quick-start/try-catch/#finally","title":"Finally","text":"

Operations in a finally block will always execute regardless of the success or failure of the test step.

This is particularly useful to perform manual cleanup.

In the example below we create a local cluster in a script operation. The cluster deletion script is added to the finally block, guaranteeing the cluster will be deleted regardless of the test outcome.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # create a local cluster\n  - try:\n    - script:\n        timeout: 1m\n        content: |\n          kind create cluster --name dynamic --kubeconfig ./dynamic\n    - apply:\n        # ...\n    - assert:\n        # ...\n    # add cluster deletion script in the `finally` block\n    # to guarantee the cluster will be deleted after the test\n    finally:\n    - script:\n        content: |\n          kind delete cluster --name dynamic\n    - script:\n        content: |\n          rm -f ./dynamic\n
"},{"location":"quick-start/try-catch/#next-step","title":"Next step","text":"

Every operation in a test must be executed in a timely fashion. In the next section, we will see how you can control your timeouts.

"},{"location":"reference/","title":"Reference documentation","text":"

Info

Select an item in the navigation menu to browse a specific page.

"},{"location":"reference/builtins/","title":"Built-in bindings","text":"

Chainsaw provides built-in bindings listed below.

"},{"location":"reference/builtins/#common","title":"Common","text":"Name Purpose Type $values Values provided when invoking chainsaw with --values flag any $namespace Name of the current test namespace string $client Kubernetes client chainsaw is connected to (if not running with --no-cluster) object $config Kubernetes client config chainsaw is connected to (if not running with --no-cluster) object"},{"location":"reference/builtins/#in-tests","title":"In tests","text":"Name Purpose Type $test.id Current test id int

Note

"},{"location":"reference/builtins/#in-steps","title":"In steps","text":"Name Purpose Type $step.id Current step id int

Note

"},{"location":"reference/builtins/#in-operations","title":"In operations","text":"Name Purpose Type $operation.id Current operation id int $operation.resourceId Current resource id int

Note

"},{"location":"reference/builtins/#in-checks-and-outputs","title":"In checks and outputs","text":"Name Purpose Type @ The state of the resource (if any) at the end of the operation any $error The error message (if any) at the end of the operation string $stdout The content of the standard console output (if any) at the end of the operation string $stderr The content of the standard console error output (if any) at the end of the operation string

Note

"},{"location":"reference/json-schemas/","title":"JSON schemas","text":"

JSON schemas for Chainsaw are available:

They can be used to enable validation and autocompletion in your IDE.

"},{"location":"reference/json-schemas/#vs-code","title":"VS code","text":"

In VS code, simply add a comment on top of your YAML resources.

"},{"location":"reference/json-schemas/#test","title":"Test","text":"
# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/chainsaw/main/.schemas/json/test-chainsaw-v1alpha1.json\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: basic\nspec:\n  steps:\n  - try:\n    - apply:\n        file: configmap.yaml\n    - assert:\n        file: configmap-assert.yaml\n
"},{"location":"reference/json-schemas/#configuration","title":"Configuration","text":"
# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/chainsaw/main/.schemas/json/configuration-chainsaw-v1alpha2.json\napiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  timeouts:\n    apply: 45s\n    assert: 20s\n    cleanup: 45s\n    delete: 25s\n    error: 10s\n    exec: 45s\n  cleanup:\n    skipDelete: false\n  execution:\n    failFast: true\n    parallel: 4\n
"},{"location":"reference/json-schemas/#exporting-schemas","title":"Exporting schemas","text":"

Chainsaw can also export JSON schemas locally if you don't want to reference them from GitHub:

chainsaw export schemas <local path>\n

See chainsaw export schemas command documentation for more details.

"},{"location":"reference/apis/chainsaw.v1alpha1/","title":"chainsaw (v1alpha1)","text":"

Package v1alpha1 contains API Schema definitions for the v1alpha1 API group.

"},{"location":"reference/apis/chainsaw.v1alpha1/#resource-types","title":"Resource Types","text":""},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Configuration","title":"Configuration","text":"

Configuration is the resource that contains the configuration used to run tests.

Field Type Required Inline Description apiVersion string chainsaw.kyverno.io/v1alpha1 kind string Configuration metadata meta/v1.ObjectMeta

Standard object's metadata.

spec ConfigurationSpec

Configuration spec.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Test","title":"Test","text":"

Test is the resource that contains a test definition.

Field Type Required Inline Description apiVersion string chainsaw.kyverno.io/v1alpha1 kind string Test metadata meta/v1.ObjectMeta

Standard object's metadata.

spec TestSpec

Test spec.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Apply","title":"Apply","text":"

Appears in:

Apply represents a set of configurations or resources that should be applied during testing.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the resources to be applied.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Assert","title":"Assert","text":"

Appears in:

Assert represents a test condition that is expected to hold true during the testing process.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrCheck FileRefOrCheck

FileRefOrAssert provides a reference to the assertion.

template bool

Template determines whether resources should be considered for templating.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Binding","title":"Binding","text":"

Appears in:

Binding represents a key/value set as a binding in an executing test.

Field Type Required Inline Description name string

Name the name of the binding.

value policy/v1alpha1.Any

Value value of the binding.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Catch","title":"Catch","text":"

Appears in:

Catch defines actions to be executed on failure.

Field Type Required Inline Description description string

Description contains a description of the operation.

podLogs PodLogs

PodLogs determines the pod logs collector to execute.

events Events

Events determines the events collector to execute.

describe Describe

Describe determines the resource describe collector to execute.

wait Wait

Wait determines the resource wait collector to execute.

get Get

Get determines the resource get collector to execute.

delete Delete

Delete represents a deletion operation.

command Command

Command defines a command to run.

script Script

Script defines a script to run.

sleep Sleep

Sleep defines zzzz.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Cluster","title":"Cluster","text":"

Appears in:

Cluster defines cluster config and context.

Field Type Required Inline Description kubeconfig string

Kubeconfig is the path to the referenced file.

context string

Context is the name of the context to use.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Command","title":"Command","text":"

Appears in:

Command describes a command to run as a part of a test step.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

env []Binding

Env defines additional environment variables.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

entrypoint string

Entrypoint is the command entry point to run.

args []string

Args is the command arguments.

skipLogOutput bool

SkipLogOutput removes the output from the command. Useful for sensitive logs or to reduce noise.

check policy/v1alpha1.Any

Check is an assertion tree to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Condition","title":"Condition","text":"

Appears in:

Condition represents parameters for waiting on a specific condition of a resource.

Field Type Required Inline Description name string

Name defines the specific condition to wait for, e.g., \"Available\", \"Ready\".

value string

Value defines the specific condition status to wait for, e.g., \"True\", \"False\".

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ConfigurationSpec","title":"ConfigurationSpec","text":"

Appears in:

ConfigurationSpec contains the configuration used to run tests.

Field Type Required Inline Description timeouts Timeouts

Global timeouts configuration. Applies to all tests/test steps if not overridden.

skipDelete bool

If set, do not delete the resources after running the tests (implies SkipClusterDelete).

template bool

Template determines whether resources should be considered for templating.

failFast bool

FailFast determines whether the test should stop upon encountering the first failure.

parallel int

The maximum number of tests to run at once.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation.

reportFormat ReportFormatType

ReportFormat determines test report format (JSON reportPath string

ReportPath defines the path.

reportName string

ReportName defines the name of report to create. It defaults to \"chainsaw-report\".

namespace string

Namespace defines the namespace to use for tests. If not specified, every test will execute in a random ephemeral namespace unless the namespace is overridden in a the test spec.

namespaceTemplate policy/v1alpha1.Any

NamespaceTemplate defines a template to create the test namespace.

fullName bool

FullName makes use of the full test case folder path instead of the folder name.

excludeTestRegex string

ExcludeTestRegex is used to exclude tests based on a regular expression.

includeTestRegex string

IncludeTestRegex is used to include tests based on a regular expression.

repeatCount int

RepeatCount indicates how many times the tests should be executed.

testFile string

TestFile is the name of the file containing the test to run. If no extension is provided, chainsaw will try with .yaml first and .yml if needed.

forceTerminationGracePeriod meta/v1.Duration

ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments.

delayBeforeCleanup meta/v1.Duration

DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts.

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

catch []Catch

Catch defines what the tests steps will execute when an error happens. This will be combined with catch handlers defined at the test and step levels.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Create","title":"Create","text":"

Appears in:

Create represents a set of resources that should be created. If a resource already exists in the cluster it will fail.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the file containing the resources to be created.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Delete","title":"Delete","text":"

Appears in:

Delete is a reference to an object that should be deleted

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

template bool

Template determines whether resources should be considered for templating.

ref ObjectReference

ObjectReference determines objects to be deleted.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation. Overrides the deletion propagation policy set in the Configuration, the Test and the TestStep.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Deletion","title":"Deletion","text":"

Appears in:

Deletion represents parameters for waiting on a resource's deletion.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Describe","title":"Describe","text":"

Appears in:

Describe defines how to describe resources.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ResourceReference ResourceReference

ResourceReference referenced resource type.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

showEvents bool

Show Events indicates whether to include related events.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Error","title":"Error","text":"

Appears in:

Error represents an anticipated error condition that may arise during testing. Instead of treating such an error as a test failure, it acknowledges it as expected.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrCheck FileRefOrCheck

FileRefOrAssert provides a reference to the expected error.

template bool

Template determines whether resources should be considered for templating.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Events","title":"Events","text":"

Appears in:

Events defines how to collect events.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

format Format

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Expectation","title":"Expectation","text":"

Appears in:

Expectation represents a check to be applied on the result of an operation with a match filter to determine if the verification should be considered.

Field Type Required Inline Description match policy/v1alpha1.Any

Match defines the matching statement.

check policy/v1alpha1.Any

Check defines the verification statement.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-FileRef","title":"FileRef","text":"

Appears in:

FileRef represents a file reference.

Field Type Required Inline Description file string

File is the path to the referenced file. This can be a direct path to a file or an expression that matches multiple files, such as \"manifest/*.yaml\" for all YAML files within the \"manifest\" directory.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-FileRefOrCheck","title":"FileRefOrCheck","text":"

Appears in:

FileRefOrCheck represents a file reference or resource.

Field Type Required Inline Description FileRef FileRef

FileRef provides a reference to the file containing the resources to be applied.

resource policy/v1alpha1.Any

Check provides a check used in assertions.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-FileRefOrResource","title":"FileRefOrResource","text":"

Appears in:

FileRefOrResource represents a file reference or resource.

Field Type Required Inline Description FileRef FileRef

FileRef provides a reference to the file containing the resources to be applied.

resource meta/v1/unstructured.Unstructured

Resource provides a resource to be applied.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Finally","title":"Finally","text":"

Appears in:

Finally defines actions to be executed at the end of a test.

Field Type Required Inline Description description string

Description contains a description of the operation.

podLogs PodLogs

PodLogs determines the pod logs collector to execute.

events Events

Events determines the events collector to execute.

describe Describe

Describe determines the resource describe collector to execute.

wait Wait

Wait determines the resource wait collector to execute.

get Get

Get determines the resource get collector to execute.

delete Delete

Delete represents a deletion operation.

command Command

Command defines a command to run.

script Script

Script defines a script to run.

sleep Sleep

Sleep defines zzzz.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-For","title":"For","text":"

Appears in:

For specifies the condition to wait for.

Field Type Required Inline Description deletion Deletion

Deletion specifies parameters for waiting on a resource's deletion.

condition Condition

Condition specifies the condition to wait for.

jsonPath JsonPath

JsonPath specifies the json path condition to wait for.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Format","title":"Format","text":"

(Alias of string)

Appears in:

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Get","title":"Get","text":"

Appears in:

Get defines how to get resources.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ResourceReference ResourceReference

ResourceReference referenced resource type.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

format Format

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-JsonPath","title":"JsonPath","text":"

Appears in:

JsonPath represents parameters for waiting on a json path of a resource.

Field Type Required Inline Description path string

Path defines the json path to wait for, e.g. '{.status.phase}'.

value string

Value defines the expected value to wait for, e.g., \"Running\".

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectLabelsSelector","title":"ObjectLabelsSelector","text":"

Appears in:

ObjectLabelsSelector represents a strategy to select objects. For a single object name and namespace are used to identify the object. For multiple objects use selector.

Field Type Required Inline Description namespace string

Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/

name string

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

selector string

Selector defines labels selector.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectReference","title":"ObjectReference","text":"

Appears in:

ObjectReference represents one or more objects with a specific apiVersion and kind. For a single object name and namespace are used to identify the object. For multiple objects use labels.

Field Type Required Inline Description ObjectType ObjectType

ObjectType determines the type of referenced objects.

ObjectSelector ObjectSelector

ObjectSelector determines the selection process of referenced objects.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectSelector","title":"ObjectSelector","text":"

Appears in:

ObjectSelector represents a strategy to select objects. For a single object name and namespace are used to identify the object. For multiple objects use labels.

Field Type Required Inline Description namespace string

Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/

name string

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

labels map[string]string

Label selector to match objects to delete

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectType","title":"ObjectType","text":"

Appears in:

ObjectType represents a specific apiVersion and kind.

Field Type Required Inline Description apiVersion string

API version of the referent.

kind string

Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Operation","title":"Operation","text":"

Appears in:

Operation defines a single operation, only one action is permitted for a given operation.

Field Type Required Inline Description OperationBase OperationBase

OperationBase defines common elements to all operations.

apply Apply

Apply represents resources that should be applied for this test step. This can include things like configuration settings or any other resources that need to be available during the test.

assert Assert

Assert represents an assertion to be made. It checks whether the conditions specified in the assertion hold true.

command Command

Command defines a command to run.

create Create

Create represents a creation operation.

delete Delete

Delete represents a deletion operation.

error Error

Error represents the expected errors for this test step. If any of these errors occur, the test will consider them as expected; otherwise, they will be treated as test failures.

patch Patch

Patch represents a patch operation.

script Script

Script defines a script to run.

sleep Sleep

Sleep defines zzzz.

update Update

Update represents an update operation.

wait Wait

Wait determines the resource wait collector to execute.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-OperationBase","title":"OperationBase","text":"

Appears in:

OperationBase defines common elements to all operations.

Field Type Required Inline Description description string

Description contains a description of the operation.

continueOnError bool

ContinueOnError determines whether a test should continue or not in case the operation was not successful. Even if the test continues executing, it will still be reported as failed.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Output","title":"Output","text":"

Appears in:

Output represents an output binding with a match to determine if the binding must be considered or not.

Field Type Required Inline Description Binding Binding

Binding determines the binding to create when the match succeeds.

match policy/v1alpha1.Any

Match defines the matching statement.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Patch","title":"Patch","text":"

Appears in:

Patch represents a set of resources that should be patched. If a resource doesn't exist yet in the cluster it will fail.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the file containing the resources to be patched.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-PodLogs","title":"PodLogs","text":"

Appears in:

PodLogs defines how to collect pod logs.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

container string

Container in pod to get logs from else --all-containers is used.

tail int

Tail is the number of last lines to collect from pods. If omitted or zero, then the default is 10 if you use a selector, or -1 (all) if you use a pod name. This matches default behavior of kubectl logs.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ReportFormatType","title":"ReportFormatType","text":"

(Alias of string)

Appears in:

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ResourceReference","title":"ResourceReference","text":"

Appears in:

ResourceReference represents a resource (API), it can be represented with a resource or a kind. Optionally an apiVersion can be specified.

Field Type Required Inline Description apiVersion string

API version of the referent.

kind string

Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

resource string

Resource name of the referent.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Script","title":"Script","text":"

Appears in:

Script describes a script to run as a part of a test step.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

env []Binding

Env defines additional environment variables.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

content string

Content defines a shell script (run with \"sh -c ...\").

skipLogOutput bool

SkipLogOutput removes the output from the command. Useful for sensitive logs or to reduce noise.

check policy/v1alpha1.Any

Check is an assertion tree to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Sleep","title":"Sleep","text":"

Appears in:

Sleep represents a duration while nothing happens.

Field Type Required Inline Description duration meta/v1.Duration

Duration is the delay used for sleeping.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-TestSpec","title":"TestSpec","text":"

Appears in:

TestSpec contains the test spec.

Field Type Required Inline Description description string

Description contains a description of the test.

timeouts Timeouts

Timeouts for the test. Overrides the global timeouts set in the Configuration on a per operation basis.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

skip bool

Skip determines whether the test should skipped.

concurrent bool

Concurrent determines whether the test should run concurrently with other tests.

skipDelete bool

SkipDelete determines whether the resources created by the test should be deleted after the test is executed.

template bool

Template determines whether resources should be considered for templating.

namespace string

Namespace determines whether the test should run in a random ephemeral namespace or not.

namespaceTemplate policy/v1alpha1.Any

NamespaceTemplate defines a template to create the test namespace.

bindings []Binding

Bindings defines additional binding key/values.

steps []TestStep

Steps defining the test.

catch []Catch

Catch defines what the steps will execute when an error happens. This will be combined with catch handlers defined at the step level.

forceTerminationGracePeriod meta/v1.Duration

ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments.

delayBeforeCleanup meta/v1.Duration

DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation. Overrides the deletion propagation policy set in the Configuration.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-TestStep","title":"TestStep","text":"

Appears in:

TestStep contains the test step definition used in a test spec.

Field Type Required Inline Description name string

Name of the step.

TestStepSpec TestStepSpec

TestStepSpec of the step.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-TestStepSpec","title":"TestStepSpec","text":"

Appears in:

TestStepSpec defines the desired state and behavior for each test step.

Field Type Required Inline Description description string

Description contains a description of the test step.

timeouts Timeouts

Timeouts for the test step. Overrides the global timeouts set in the Configuration and the timeouts eventually set in the Test.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation. Overrides the deletion propagation policy set in both the Configuration and the Test.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

skipDelete bool

SkipDelete determines whether the resources created by the step should be deleted after the test step is executed.

template bool

Template determines whether resources should be considered for templating.

bindings []Binding

Bindings defines additional binding key/values.

try []Operation

Try defines what the step will try to execute.

catch []Catch

Catch defines what the step will execute when an error happens.

finally []Finally

Finally defines what the step will execute after the step is terminated.

cleanup []Finally

Cleanup defines what will be executed after the test is terminated.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Timeouts","title":"Timeouts","text":"

Appears in:

Timeouts contains timeouts per operation.

Field Type Required Inline Description apply meta/v1.Duration

Apply defines the timeout for the apply operation

assert meta/v1.Duration

Assert defines the timeout for the assert operation

cleanup meta/v1.Duration

Cleanup defines the timeout for the cleanup operation

delete meta/v1.Duration

Delete defines the timeout for the delete operation

error meta/v1.Duration

Error defines the timeout for the error operation

exec meta/v1.Duration

Exec defines the timeout for exec operations

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Update","title":"Update","text":"

Appears in:

Update represents a set of resources that should be updated. If a resource does not exist in the cluster it will fail.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the file containing the resources to be created.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Wait","title":"Wait","text":"

Appears in:

Wait specifies how to perform wait operations on resources.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Specifies how long to wait for the condition to be met before timing out.

cluster string

Cluster defines the target cluster where the wait operation will be performed (default cluster will be used if not specified).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ResourceReference ResourceReference

ResourceReference referenced resource type.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

for For

For specifies the condition to wait for.

format Format

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha2/","title":"chainsaw (v1alpha2)","text":"

Package v1alpha2 contains API Schema definitions for the v1alpha2 API group.

"},{"location":"reference/apis/chainsaw.v1alpha2/#resource-types","title":"Resource Types","text":""},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Configuration","title":"Configuration","text":"

Configuration is the resource that contains the configuration used to run tests.

Field Type Required Inline Description apiVersion string chainsaw.kyverno.io/v1alpha2 kind string Configuration metadata meta/v1.ObjectMeta

Standard object's metadata.

spec ConfigurationSpec

Configuration spec.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Cleanup","title":"Cleanup","text":"

Appears in:

Cleanup options contain the configuration used for cleaning up resources.

Field Type Required Inline Description skipDelete bool

If set, do not delete the resources after running a test.

delayBeforeCleanup meta/v1.Duration

DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-ConfigurationSpec","title":"ConfigurationSpec","text":"

Appears in:

ConfigurationSpec contains the configuration used to run tests.

Field Type Required Inline Description cleanup Cleanup

Cleanup contains cleanup configuration.

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

deletion DeletionOptions

Deletion contains the global deletion configuration.

discovery Discovery

Discovery contains tests discovery configuration.

error ErrorOptions

Error contains the global error configuration.

execution Execution

Execution contains tests execution configuration.

namespace Namespace

Namespace contains properties for the namespace to use for tests.

report Report

Report contains properties for the report.

templating Templating

Templating contains the templating config.

timeouts Timeouts

Global timeouts configuration. Applies to all tests/test steps if not overridden.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-DeletionOptions","title":"DeletionOptions","text":"

Appears in:

DeletionOptions contains the configuration used for deleting resources.

Field Type Required Inline Description propagation meta/v1.DeletionPropagation

Propagation decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Discovery","title":"Discovery","text":"

Appears in:

Discovery options contain the discovery configuration used when discovering tests in folders.

Field Type Required Inline Description excludeTestRegex string

ExcludeTestRegex is used to exclude tests based on a regular expression.

includeTestRegex string

IncludeTestRegex is used to include tests based on a regular expression.

testFile string

TestFile is the name of the file containing the test to run. If no extension is provided, chainsaw will try with .yaml first and .yml if needed.

fullName bool

FullName makes use of the full test case folder path instead of the folder name.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-ErrorOptions","title":"ErrorOptions","text":"

Appears in:

ErrorOptions contains the global error configuration.

Field Type Required Inline Description catch []Catch

Catch defines what the tests steps will execute when an error happens. This will be combined with catch handlers defined at the test and step levels.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Execution","title":"Execution","text":"

Appears in:

Execution options determine how tests are run.

Field Type Required Inline Description failFast bool

FailFast determines whether the test should stop upon encountering the first failure.

parallel int

The maximum number of tests to run at once.

repeatCount int

RepeatCount indicates how many times the tests should be executed.

forceTerminationGracePeriod meta/v1.Duration

ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Namespace","title":"Namespace","text":"

Appears in:

Namespace options contain the configuration used to allocate a namespace for each test.

Field Type Required Inline Description name string

Name defines the namespace to use for tests. If not specified, every test will execute in a random ephemeral namespace unless the namespace is overridden in a the test spec.

template policy/v1alpha1.Any

Template defines a template to create the test namespace.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Report","title":"Report","text":"

Appears in:

Report options contain the configuration used for reporting.

Field Type Required Inline Description format ReportFormatType

ReportFormat determines test report format (JSON path string

ReportPath defines the path.

name string

ReportName defines the name of report to create. It defaults to \"chainsaw-report\".

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-ReportFormatType","title":"ReportFormatType","text":"

(Alias of string)

Appears in:

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Templating","title":"Templating","text":"

Appears in:

Templating options contain the templating configuration.

Field Type Required Inline Description enabled bool

Enabled determines whether resources should be considered for templating.

"},{"location":"reference/commands/chainsaw/","title":"chainsaw","text":""},{"location":"reference/commands/chainsaw/#chainsaw","title":"chainsaw","text":"

Stronger tool for e2e testing

chainsaw [flags]\n
"},{"location":"reference/commands/chainsaw/#options","title":"Options","text":"
  -h, --help   help for chainsaw\n
"},{"location":"reference/commands/chainsaw/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_assert/","title":"chainsaw assert","text":""},{"location":"reference/commands/chainsaw_assert/#chainsaw-assert","title":"chainsaw assert","text":"

Evaluate assertion

chainsaw assert [flags] [FILE]\n
"},{"location":"reference/commands/chainsaw_assert/#options","title":"Options","text":"
      --clustered                           Defines if the resource is clustered (only applies when resource is loaded from a file)\n  -f, --file string                         Path to the file to assert or '-' to read from stdin\n  -h, --help                                help for assert\n      --kube-as string                      Username to impersonate for the operation\n      --kube-as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.\n      --kube-as-uid string                  UID to impersonate for the operation\n      --kube-certificate-authority string   Path to a cert file for the certificate authority\n      --kube-client-certificate string      Path to a client certificate file for TLS\n      --kube-client-key string              Path to a client key file for TLS\n      --kube-cluster string                 The name of the kubeconfig cluster to use\n      --kube-context string                 The name of the kubeconfig context to use\n      --kube-disable-compression            If true, opt-out of response compression for all requests to the server\n      --kube-insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n  -n, --kube-namespace string               If present, the namespace scope for this CLI request\n      --kube-password string                Password for basic authentication to the API server\n      --kube-proxy-url string               If provided, this URL will be used to connect via proxy\n      --kube-request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default \"0\")\n      --kube-server string                  The address and port of the Kubernetes API server\n      --kube-tls-server-name string         If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used.\n      --kube-token string                   Bearer token for authentication to the API server\n      --kube-user string                    The name of the kubeconfig user to use\n      --kube-username string                Username for basic authentication to the API server\n      --namespace string                    Namespace to use (default \"default\")\n      --no-color                            Removes output colors\n  -r, --resource string                     Path to the file containing the resource\n      --timeout duration                    The assert timeout to use (default 30s)\n
"},{"location":"reference/commands/chainsaw_assert/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_build/","title":"chainsaw build","text":""},{"location":"reference/commands/chainsaw_build/#chainsaw-build","title":"chainsaw build","text":"

Build commands

chainsaw build [flags]\n
"},{"location":"reference/commands/chainsaw_build/#options","title":"Options","text":"
  -h, --help   help for build\n
"},{"location":"reference/commands/chainsaw_build/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_build_docs/","title":"chainsaw build docs","text":""},{"location":"reference/commands/chainsaw_build_docs/#chainsaw-build-docs","title":"chainsaw build docs","text":"

Build tests documentation

chainsaw build docs [flags]\n
"},{"location":"reference/commands/chainsaw_build_docs/#options","title":"Options","text":"
      --catalog string         Path to the built test catalog file\n  -h, --help                   help for docs\n      --readme-file string     Name of the built docs file (default \"README.md\")\n      --test-dir stringArray   Directories containing test cases to run\n      --test-file string       Name of the test file (default \"chainsaw-test\")\n
"},{"location":"reference/commands/chainsaw_build_docs/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion/","title":"chainsaw completion","text":""},{"location":"reference/commands/chainsaw_completion/#chainsaw-completion","title":"chainsaw completion","text":"

Generate the autocompletion script for the specified shell

"},{"location":"reference/commands/chainsaw_completion/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for chainsaw for the specified shell. See each sub-command's help for details on how to use the generated script.

"},{"location":"reference/commands/chainsaw_completion/#options","title":"Options","text":"
  -h, --help   help for completion\n
"},{"location":"reference/commands/chainsaw_completion/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_bash/","title":"chainsaw completion bash","text":""},{"location":"reference/commands/chainsaw_completion_bash/#chainsaw-completion-bash","title":"chainsaw completion bash","text":"

Generate the autocompletion script for bash

"},{"location":"reference/commands/chainsaw_completion_bash/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(chainsaw completion bash)\n

To load completions for every new session, execute once:

"},{"location":"reference/commands/chainsaw_completion_bash/#linux","title":"Linux:","text":"
chainsaw completion bash > /etc/bash_completion.d/chainsaw\n
"},{"location":"reference/commands/chainsaw_completion_bash/#macos","title":"macOS:","text":"
chainsaw completion bash > $(brew --prefix)/etc/bash_completion.d/chainsaw\n

You will need to start a new shell for this setup to take effect.

chainsaw completion bash\n
"},{"location":"reference/commands/chainsaw_completion_bash/#options","title":"Options","text":"
  -h, --help              help for bash\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_bash/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_fish/","title":"chainsaw completion fish","text":""},{"location":"reference/commands/chainsaw_completion_fish/#chainsaw-completion-fish","title":"chainsaw completion fish","text":"

Generate the autocompletion script for fish

"},{"location":"reference/commands/chainsaw_completion_fish/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

chainsaw completion fish | source\n

To load completions for every new session, execute once:

chainsaw completion fish > ~/.config/fish/completions/chainsaw.fish\n

You will need to start a new shell for this setup to take effect.

chainsaw completion fish [flags]\n
"},{"location":"reference/commands/chainsaw_completion_fish/#options","title":"Options","text":"
  -h, --help              help for fish\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_fish/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_powershell/","title":"chainsaw completion powershell","text":""},{"location":"reference/commands/chainsaw_completion_powershell/#chainsaw-completion-powershell","title":"chainsaw completion powershell","text":"

Generate the autocompletion script for powershell

"},{"location":"reference/commands/chainsaw_completion_powershell/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for powershell.

To load completions in your current shell session:

chainsaw completion powershell | Out-String | Invoke-Expression\n

To load completions for every new session, add the output of the above command to your powershell profile.

chainsaw completion powershell [flags]\n
"},{"location":"reference/commands/chainsaw_completion_powershell/#options","title":"Options","text":"
  -h, --help              help for powershell\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_powershell/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_zsh/","title":"chainsaw completion zsh","text":""},{"location":"reference/commands/chainsaw_completion_zsh/#chainsaw-completion-zsh","title":"chainsaw completion zsh","text":"

Generate the autocompletion script for zsh

"},{"location":"reference/commands/chainsaw_completion_zsh/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo \"autoload -U compinit; compinit\" >> ~/.zshrc\n

To load completions in your current shell session:

source <(chainsaw completion zsh)\n

To load completions for every new session, execute once:

"},{"location":"reference/commands/chainsaw_completion_zsh/#linux","title":"Linux:","text":"
chainsaw completion zsh > \"${fpath[1]}/_chainsaw\"\n
"},{"location":"reference/commands/chainsaw_completion_zsh/#macos","title":"macOS:","text":"
chainsaw completion zsh > $(brew --prefix)/share/zsh/site-functions/_chainsaw\n

You will need to start a new shell for this setup to take effect.

chainsaw completion zsh [flags]\n
"},{"location":"reference/commands/chainsaw_completion_zsh/#options","title":"Options","text":"
  -h, --help              help for zsh\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_zsh/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_create/","title":"chainsaw create","text":""},{"location":"reference/commands/chainsaw_create/#chainsaw-create","title":"chainsaw create","text":"

Create Chainsaw resources

chainsaw create [flags]\n
"},{"location":"reference/commands/chainsaw_create/#options","title":"Options","text":"
  -h, --help   help for create\n
"},{"location":"reference/commands/chainsaw_create/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_create_test/","title":"chainsaw create test","text":""},{"location":"reference/commands/chainsaw_create_test/#chainsaw-create-test","title":"chainsaw create test","text":"

Create a Chainsaw test

chainsaw create test [flags]\n
"},{"location":"reference/commands/chainsaw_create_test/#options","title":"Options","text":"
      --description   If set, adds description when applicable (default true)\n      --force         If set, existing test will be deleted if needed\n  -h, --help          help for test\n      --save          If set, created test will be saved\n
"},{"location":"reference/commands/chainsaw_create_test/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_docs/","title":"chainsaw docs","text":""},{"location":"reference/commands/chainsaw_docs/#chainsaw-docs","title":"chainsaw docs","text":"

Generate reference documentation

chainsaw docs [flags]\n
"},{"location":"reference/commands/chainsaw_docs/#options","title":"Options","text":"
      --autogenTag      Determines if the generated docs should contain a timestamp (default true)\n  -h, --help            help for docs\n  -o, --output string   Output path (default \".\")\n      --website         Website version\n
"},{"location":"reference/commands/chainsaw_docs/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_export/","title":"chainsaw export","text":""},{"location":"reference/commands/chainsaw_export/#chainsaw-export","title":"chainsaw export","text":"

Export commands

chainsaw export [flags]\n
"},{"location":"reference/commands/chainsaw_export/#options","title":"Options","text":"
  -h, --help   help for export\n
"},{"location":"reference/commands/chainsaw_export/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_export_schemas/","title":"chainsaw export schemas","text":""},{"location":"reference/commands/chainsaw_export_schemas/#chainsaw-export-schemas","title":"chainsaw export schemas","text":"

Export JSON schemas

chainsaw export schemas [flags]\n
"},{"location":"reference/commands/chainsaw_export_schemas/#options","title":"Options","text":"
  -h, --help   help for schemas\n
"},{"location":"reference/commands/chainsaw_export_schemas/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_lint/","title":"chainsaw lint","text":""},{"location":"reference/commands/chainsaw_lint/#chainsaw-lint","title":"chainsaw lint","text":"

Lint a file or read from standard input

"},{"location":"reference/commands/chainsaw_lint/#synopsis","title":"Synopsis","text":"

Use chainsaw lint to lint a specific file or read from standard input for either test or configuration.

chainsaw lint [test|configuration] [flags]\n
"},{"location":"reference/commands/chainsaw_lint/#options","title":"Options","text":"
  -f, --file string   Specify the file to lint or '-' for standard input\n  -h, --help          help for lint\n
"},{"location":"reference/commands/chainsaw_lint/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate/","title":"chainsaw migrate","text":""},{"location":"reference/commands/chainsaw_migrate/#chainsaw-migrate","title":"chainsaw migrate","text":"

Migrate resources to Chainsaw

chainsaw migrate [flags]\n
"},{"location":"reference/commands/chainsaw_migrate/#options","title":"Options","text":"
  -h, --help   help for migrate\n
"},{"location":"reference/commands/chainsaw_migrate/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl/","title":"chainsaw migrate kuttl","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl/#chainsaw-migrate-kuttl","title":"chainsaw migrate kuttl","text":"

Migrate KUTTL resources to Chainsaw

chainsaw migrate kuttl [flags]\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl/#options","title":"Options","text":"
  -h, --help   help for kuttl\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_config/","title":"chainsaw migrate kuttl config","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_config/#chainsaw-migrate-kuttl-config","title":"chainsaw migrate kuttl config","text":"

Migrate KUTTL config to Chainsaw

chainsaw migrate kuttl config [flags]\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_config/#options","title":"Options","text":"
      --cleanup   If set, delete converted files\n  -h, --help      help for config\n      --save      If set, converted files will be saved\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_config/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/","title":"chainsaw migrate kuttl tests","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/#chainsaw-migrate-kuttl-tests","title":"chainsaw migrate kuttl tests","text":"

Migrate KUTTL tests to Chainsaw

chainsaw migrate kuttl tests [flags]\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/#options","title":"Options","text":"
      --cleanup   If set, delete converted files\n  -h, --help      help for tests\n      --save      If set, converted files will be saved\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_test/","title":"chainsaw test","text":""},{"location":"reference/commands/chainsaw_test/#chainsaw-test","title":"chainsaw test","text":"

Run tests

chainsaw test [flags]... [test directories]...\n
"},{"location":"reference/commands/chainsaw_test/#options","title":"Options","text":"
      --apply-timeout duration                    The apply timeout to use as default for configuration (default 5s)\n      --assert-timeout duration                   The assert timeout to use as default for configuration (default 30s)\n      --cleanup-delay duration                    Adds a delay between the time a test ends and the time cleanup starts\n      --cleanup-timeout duration                  The cleanup timeout to use as default for configuration (default 30s)\n      --cluster strings                           Register cluster (format <cluster name>=<kubeconfig path>:[context name])\n      --config string                             Chainsaw configuration file\n      --delete-timeout duration                   The delete timeout to use as default for configuration (default 15s)\n      --deletion-propagation-policy string        The deletion propagation policy (Foreground|Background|Orphan) (default \"Foreground\")\n      --error-timeout duration                    The error timeout to use as default for configuration (default 30s)\n      --exclude-test-regex string                 Regular expression to exclude tests\n      --exec-timeout duration                     The exec timeout to use as default for configuration (default 5s)\n      --fail-fast                                 Stop the test upon encountering the first failure\n      --force-termination-grace-period duration   If specified, overrides termination grace periods in applicable resources\n      --full-name                                 Use full test case folder path instead of folder name\n  -h, --help                                      help for test\n      --include-test-regex string                 Regular expression to include tests\n      --kube-as string                            Username to impersonate for the operation\n      --kube-as-group stringArray                 Group to impersonate for the operation, this flag can be repeated to specify multiple groups.\n      --kube-as-uid string                        UID to impersonate for the operation\n      --kube-certificate-authority string         Path to a cert file for the certificate authority\n      --kube-client-certificate string            Path to a client certificate file for TLS\n      --kube-client-key string                    Path to a client key file for TLS\n      --kube-cluster string                       The name of the kubeconfig cluster to use\n      --kube-context string                       The name of the kubeconfig context to use\n      --kube-disable-compression                  If true, opt-out of response compression for all requests to the server\n      --kube-insecure-skip-tls-verify             If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n  -n, --kube-namespace string                     If present, the namespace scope for this CLI request\n      --kube-password string                      Password for basic authentication to the API server\n      --kube-proxy-url string                     If provided, this URL will be used to connect via proxy\n      --kube-request-timeout string               The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default \"0\")\n      --kube-server string                        The address and port of the Kubernetes API server\n      --kube-tls-server-name string               If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used.\n      --kube-token string                         Bearer token for authentication to the API server\n      --kube-user string                          The name of the kubeconfig user to use\n      --kube-username string                      Username for basic authentication to the API server\n      --namespace string                          Namespace to use for tests\n      --no-cluster                                Runs without cluster\n      --no-color                                  Removes output colors\n      --parallel int                              The maximum number of tests to run at once\n      --pause-on-failure                          Pause test execution failure (implies no concurrency)\n      --repeat-count int                          Number of times to repeat each test (default 1)\n      --report-format string                      Test report format (JSON|XML|nil)\n      --report-name string                        The name of the report to create (default \"chainsaw-report\")\n      --report-path string                        The path of the report to create\n      --selector strings                          Selector (label query) to filter on\n      --skip-delete                               If set, do not delete the resources after running the tests\n      --template                                  If set, resources will be considered for templating (default true)\n      --test-dir strings                          Directories containing test cases to run\n      --test-file string                          Name of the test file (default \"chainsaw-test\")\n      --values strings                            Values passed to the tests\n
"},{"location":"reference/commands/chainsaw_test/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_version/","title":"chainsaw version","text":""},{"location":"reference/commands/chainsaw_version/#chainsaw-version","title":"chainsaw version","text":"

Print the version informations

chainsaw version [flags]\n
"},{"location":"reference/commands/chainsaw_version/#options","title":"Options","text":"
  -h, --help   help for version\n
"},{"location":"reference/commands/chainsaw_version/#see-also","title":"SEE ALSO","text":""},{"location":"reference/jp/functions/","title":"Functions","text":"

Experimental functions

Experimental functions are denoted by the x_ prefix.

These are functions that are subject to signature change in a future version.

"},{"location":"reference/jp/functions/#built-in-functions","title":"built-in functions","text":"Name Signature abs abs(number) avg avg(array[number]) ceil ceil(number) contains contains(array|string, any) ends_with ends_with(string, string) find_first find_first(string, string, number, number) find_last find_last(string, string, number, number) floor floor(number) from_items from_items(array[array]) group_by group_by(array, expref) items items(object) join join(string, array[string]) keys keys(object) length length(string|array|object) lower lower(string) map map(expref, array) max max(array[number]|array[string]) max_by max_by(array, expref) merge merge(object) min min(array[number]|array[string]) min_by min_by(array, expref) not_null not_null(any) pad_left pad_left(string, number, string) pad_right pad_right(string, number, string) replace replace(string, string, string, number) reverse reverse(array|string) sort sort(array[string]|array[number]) sort_by sort_by(array, expref) split split(string, string, number) starts_with starts_with(string, string) sum sum(array[number]) to_array to_array(any) to_number to_number(any) to_string to_string(any) trim trim(string, string) trim_left trim_left(string, string) trim_right trim_right(string, string) type type(any) upper upper(string) values values(object) zip zip(array, array)"},{"location":"reference/jp/functions/#kyverno-json-functions","title":"kyverno-json functions","text":"Name Signature at at(array, any) concat concat(string, string) json_parse json_parse(string) wildcard wildcard(string, string)"},{"location":"reference/jp/functions/#kyverno-functions","title":"kyverno functions","text":"Name Signature compare compare(string, string) equal_fold equal_fold(string, string) replace replace(string, string, string, number) replace_all replace_all(string, string, string) to_upper to_upper(string) to_lower to_lower(string) trim trim(string, string) trim_prefix trim_prefix(string, string) split split(string, string) regex_replace_all regex_replace_all(string, string|number, string|number) regex_replace_all_literal regex_replace_all_literal(string, string|number, string|number) regex_match regex_match(string, string|number) pattern_match pattern_match(string, string|number) label_match label_match(object, object) to_boolean to_boolean(string) add add(any, any) sum sum(array) subtract subtract(any, any) multiply multiply(any, any) divide divide(any, any) modulo modulo(any, any) round round(number, number) base64_decode base64_decode(string) base64_encode base64_encode(string) time_since time_since(string, string, string) time_now time_now() time_now_utc time_now_utc() path_canonicalize path_canonicalize(string) truncate truncate(string, number) semver_compare semver_compare(string, string) parse_json parse_json(string) parse_yaml parse_yaml(string) lookup lookup(object|array, string|number) items items(object|array, string, string) object_from_lists object_from_lists(array, array) random random(string) x509_decode x509_decode(string) time_to_cron time_to_cron(string) time_add time_add(string, string) time_parse time_parse(string, string) time_utc time_utc(string) time_diff time_diff(string, string) time_before time_before(string, string) time_after time_after(string, string) time_between time_between(string, string, string) time_truncate time_truncate(string, string)"},{"location":"reference/jp/functions/#chainsaw-functions","title":"chainsaw functions","text":"Name Signature env env(string) x_k8s_get x_k8s_get(any, string, string, string, string) x_k8s_list x_k8s_list(any, string, string, string) x_k8s_exists x_k8s_exists(any, string, string, string, string) x_k8s_resource_exists x_k8s_resource_exists(any, string, string) x_k8s_server_version x_k8s_server_version(any)"},{"location":"step/","title":"What is a test step?","text":"

A test step is made of four main components used to determine the actions Chainsaw will perform when executing the step.

  1. The try statement (required)
  2. The catch statement (optional)
  3. The finally statement (optional)
  4. The cleanup statement (optional)
"},{"location":"step/#syntax","title":"Syntax","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # `try` defines operations to execute in the step\n  - try: [...]\n    # `catch` defines operations to execute when the step fails\n    catch: [...]\n    # `finally` defines operations to execute at the end of the step\n    finally: [...]\n    # `cleanup` defines operations to execute at the end of the test\n    cleanup: [...]\n
"},{"location":"step/#reference","title":"Reference","text":"

The full structure of the TestStepSpec is documented here.

"},{"location":"step/#lifecycle","title":"Lifecycle","text":""},{"location":"step/#try-catch-finally-flow","title":"Try, Catch, Finally flow","text":"

Operations defined in the try block are executed first, then:

Tip

Note that all operations coming from the catch or finally blocks are executed. If one operation fails, Chainsaw will mark the test as failed and continue executing with the next operations.

"},{"location":"step/#without-failure","title":"Without failure","text":"
sequenceDiagram\n    autonumber\n\n    participant S as Step N\n\n    box Try block\n    participant T1 as Op 1\n    participant T2 as Op N\n    end\n    box Catch block\n    end\n    box Finally block\n    participant F1 as Op 1\n    participant F2 as Op N\n    end\n    participant S1 as Step N+1\n\n    S  -->> T1 : try\n    T1 ->>  T2 : success\n    T2 -->> S  : done\n    S  -->> F1 : finally\n    F1 ->>  F2 : done\n    F2 -->> S  : done\n    S  -->> S1 : next step
  1. Step starts by executing operations in the try block
  2. Operations in the try block execute sequentially
  3. All operations in the try block terminate
  4. Step starts executing operations in the finally block
  5. Operations in the finally block execute sequentially
  6. All operations in the finally block terminate
  7. Next step starts executing
"},{"location":"step/#with-failure","title":"With failure","text":"
sequenceDiagram\n    autonumber\n\n    participant S as Step N\n\n    box Try block\n    participant T1 as Op 1\n    participant T2 as Op N\n    end\n    box Catch block\n    participant C1 as Op 1\n    participant C2 as Op N\n    end\n    box Finally block\n    participant F1 as Op 1\n    participant F2 as Op N\n    end\n\n    S  -->> T1 : try\n    T1 ->>  T2 : success\n    T2 -->> S  : error\n    S  -->> C1 : catch\n    C1 ->>  C2 : done\n    C2 -->> S  : done\n    S  -->> F1 : finally\n    F1 ->>  F2 : done\n    F2 -->> S  : done
  1. Step starts by executing operations in the try block
  2. Operations in the try block execute sequentially until an error happens
  3. Operations in the try block stop when an error occurs
  4. Step starts executing operations in the catch block
  5. Operations in the catch block execute sequentially
  6. All operations in the catch block terminate
  7. Step starts executing operations in the finally block
  8. Operations in the finally block execute sequentially
  9. All operations in the finally block terminate
"},{"location":"step/#cleanup","title":"Cleanup","text":"

In addition to try, catch and finally blocks, the cleanup block of steps is better illustrated in the Test lifecycle diagrams.

"},{"location":"step/catch/","title":"catch","text":"

A catch statement is also a sequence of operations.

Operations contained in a catch statement will be executed only if the step failed when executing the operations in the step's try statement.

Tip

All operations of a catch statement will be executed regardless of the success or failure of each of them.

"},{"location":"step/catch/#operations","title":"Operations","text":"

A catch statement supports only the following operations:

"},{"location":"step/catch/#inheritance","title":"Inheritance","text":"

Under certain circumstances, it can be useful to configure catch blocks at a higher level than the step grain. At the test or configuration level.

This allows for declaring common catch statements we want to execute when an error occurs. Those catch blocks are combined to produce the final catch block in the following order:

  1. catch statements from the configuration level are executed first (if any)
  2. catch statements from the test level are executed next (if any)
  3. catch statements from the step level are executed last (if any)
"},{"location":"step/cleanup/","title":"cleanup","text":"

A cleanup statement is similar to a finally statement but will execute after the test finishes executing, while finally executes after the step finishes executing.

Tip

All operations of a cleanup statement will be executed regardless of the success or failure of each of them.

"},{"location":"step/cleanup/#operations","title":"Operations","text":"

A cleanup statement supports only the following operations:

"},{"location":"step/finally/","title":"finally","text":"

A finally statement is similar to a catch statement but will always execute after the try and eventual catch statements finished executing regardless of the success or failure of the test step.

Tip

All operations of a finally statement will be executed regardless of the success or failure of each of them.

"},{"location":"step/finally/#operations","title":"Operations","text":"

A finally statement supports only the following operations:

"},{"location":"step/try/","title":"try","text":"

A try statement is a sequence of operations executed in the same order they are declared. If an operation fails the entire step is considered failed.

"},{"location":"step/try/#operations","title":"Operations","text":"

A try statement supports all operations:

"},{"location":"test/","title":"Writing Chainsaw tests","text":"

This documentation focuses on providing a breakdown of the Chainsaw test structure and how to use it.

"},{"location":"test/#what-is-a-test","title":"What is a test?","text":"

To put it simply, a test can be represented as an ordered sequence of test steps.

In turn, a test step can be represented as an ordered sequence of operations.

"},{"location":"test/#definition-approach","title":"Definition approach","text":"

Chainsaw supports two different test definition approaches:

Tip

While Chainsaw supports two test definition approaches, we strongly recommend the explicit one.

"},{"location":"test/#general-concepts","title":"General concepts","text":"

The concepts below are at the heart of Chainsaw:

"},{"location":"test/#test-and-step-specs","title":"Test and Step specs","text":"

Browse the test and step specs to learn all the details and options:

"},{"location":"test/conventional/","title":"Conventional approach","text":"

Warning

While Chainsaw supports the conventional approach, we strongly recommend the explicit one.

If you are new to Chainsaw we suggest you skip this section and jump directly to the Explicit approach.

"},{"location":"test/conventional/#introduction","title":"Introduction","text":"

The conventional approach is the simplest and less verbose one.

You provide bare Kubernetes resource manifests and Chainsaw will use those manifests to create, update, or assert expectations against a cluster.

"},{"location":"test/conventional/#limitations","title":"Limitations","text":"

While this syntax is simple, it suffers lots of limitations. It doesn't support deletion operations, commands, scripts, and all Chainsaw helpers.

It is also impossible to specify additional configuration per test, step or individual operation (timeouts, additional verifications, etc...), making this approach highly limited.

It also relies a lot on file naming conventions which can be error prone.

Finally, this approach doesn't encourage reusing files across tests and leads to duplication, making maintenance harder.

"},{"location":"test/conventional/#file-naming-convention","title":"File naming convention","text":"

Manifest files must follow a specific naming convention: 

<step index>-<name|assert|errors>.yaml\n

As an example, 00-configmap.yaml, 01-assert.yaml and 02-errors.yaml are valid file names.

"},{"location":"test/conventional/#assembling-steps","title":"Assembling steps","text":"

It's perfectly valid to have multiple files for the same step.

Let's say we have the following files 00-resources.yaml, 00-more-resources.yaml, 00-assert.yaml and 00-errors.yaml:

With the four files above, Chainsaw will assemble a test step made of the combination of all those files.

"},{"location":"test/conventional/#loading-process","title":"Loading process","text":"

The logic to determine the content of a step is always:

"},{"location":"test/conventional/#example","title":"Example","text":""},{"location":"test/conventional/#01-configmapyaml","title":"01-configmap.yaml","text":"

The manifest below contains a config map in a file called 01-configmap.yaml. Chainsaw will associate this manifest with an apply operation in step 01.

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  foo: bar\n
"},{"location":"test/conventional/#02-assertyaml","title":"02-assert.yaml","text":"

The manifest below contains an assertion statement in a file called 02-assert.yaml. Chainsaw will associate this manifest with an assert operation in step 02.

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  foo: bar\n
"},{"location":"test/conventional/#03-errorsyaml","title":"03-errors.yaml","text":"

The manifest below contains an error statement in a file called 03-errors.yaml. Chainsaw will associate this manifest with an error operation in step 03.

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  lorem: ipsum\n
"},{"location":"test/conventional/#conclusion","title":"Conclusion","text":"

This test will first create a config map, then assert the content of the config map contains the foo: bar data, and then verify that the config map does not contain the lorem: ipsum data.

For such a simple test, the conventional approach works reasonably well but will quickly become limited when the test scenarios get more complex.

Look at the explicit approach for a lot more flexible solution.

"},{"location":"test/explicit/","title":"Explicit approach","text":"

The explicit is a bit more verbose than the conventional one but offers far more flexibility and features:

"},{"location":"test/explicit/#the-test-resource","title":"The Test resource","text":"

A Test resource, like any other Kubernetes resource, has an apiVersion, kind and metadata section.

It also comes with a spec section used to declaratively represent the test logic, steps and operations, as well as other configuration elements belonging to the test being defined.

Reference documentation

The full structure of the Test resource is documented here.

"},{"location":"test/explicit/#example","title":"Example","text":""},{"location":"test/explicit/#chainsaw-testyaml","title":"chainsaw-test.yaml","text":"

The Test below illustrates a simple test. Chainsaw will load the Test and steps defined in its spec section.

It's worth noting that:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # state that this test should not be executed in parallel with other tests\n  concurrent: false\n  # timeouts for this specific test\n  timeouts:\n    apply: 10s\n    assert: 10s\n    error: 10s\n  steps:\n  # step 1\n  # apply a configmap to the cluster\n  # the path to the configmap is relative to the folder\n  # containing the test, hence allow reusing manifests\n  # across multiple tests\n  - try:\n    - apply:\n        file: ../resources/configmap.yaml\n  # step 2\n  # execute assert statements against existing resources\n  # in the cluster\n  - try:\n    - assert:\n        file: ../resources/configmap-assert.yaml\n  # step 3\n  # execute error statements against existing resources\n  # in the cluster\n  - try:\n    - error:\n        file: ../resources/configmap-error.yaml\n  # step 4\n  # execute an arbitrary shell script\n  - try:\n    - script:\n        content: echo \"goodbye\"\n
"},{"location":"test/explicit/#conclusion","title":"Conclusion","text":"

While this test is simple, it illustrates the differences with the conventional approach.

The purpose here is only to present the explicit approach and there are a lot more features to discuss, we will cover them in the next sections.

"},{"location":"test/spec/","title":"Test spec","text":"

A Chainsaw test is mostly made of steps.

That being said, there are a couple of other interesting fields too.

"},{"location":"test/spec/#syntax","title":"Syntax","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # test configuration\n  concurrent: false\n  bindings:\n  - name: foo\n    value: bar\n  timeouts:\n    apply: 1s\n    assert: 2m\n    delete: 30s\n  ...\n  steps:\n  # step 1\n  - try: ...\n  # step 2\n  - try: ...\n    catch: ...\n  # step 3\n  - try: ...\n    catch: ...\n    finally: ...\n
"},{"location":"test/spec/#reference","title":"Reference","text":"

The full structure of the TestSpec is documented here.

"},{"location":"test/spec/#lifecycle","title":"Lifecycle","text":""},{"location":"test/spec/#cleanup","title":"Cleanup","text":"

At the end of the test, Chainsaw cleans up resources it created during the test, in the opposite order of creation.

By default, when a step fails, Chainsaw stops the execution and the remaining steps are not executed. The cleanup process starts at the moment the test stops executing.

Tip

Note that when a failure happens during cleanup, the test is marked as failed and Chainsaw continues executing cleanup for the remaining steps.

"},{"location":"test/spec/#without-failure","title":"Without failure","text":"
sequenceDiagram\n    autonumber\n    participant T as Test\n    participant S1 as Step 1\n    participant S2 as Step 2\n    participant S3 as Step 3\n\n    T  ->> S1: execute\n    S1 ->> S2: execute\n    S2 ->> S3: execute\n\n    S3 -->> S2: cleanup\n    S2 -->> S1: cleanup\n    S1 -->> T: cleanup
  1. Test starts by executing Step 1
  2. Step 1 terminates -> Step 2 starts executing
  3. Step 2 terminates -> Step 3 starts executing
  4. Step 3 terminates -> Cleanup for Step 3 starts
  5. Cleanup for Step 3 terminates -> Cleanup for Step 2 starts
  6. Cleanup for Step 2 terminates -> Cleanup for Step 1 is executed
"},{"location":"test/spec/#with-failure","title":"With failure","text":"
sequenceDiagram\n    autonumber\n    participant T as Test\n    participant S1 as Step 1\n    participant S2 as Step 2\n    participant S3 as Step 3\n\n    T  ->> S1: execute\n    S1 ->> S2: execute (fail)\n\n    Note left of S3: Step 3 is NOT executed\n\n    S2 -->> S1: cleanup\n    S1 -->> T: cleanup
  1. Test starts by executing Step 1
  2. Step 1 terminates -> Step 2 starts executing
  3. Step 2 fails -> Cleanup for Step 2 starts
  4. Cleanup for Step 2 terminates -> Cleanup for Step 1 is executed
"},{"location":"test/spec/#supported-elements","title":"Supported elements","text":""},{"location":"test/spec/#namespace","title":"Namespace","text":"

The namespace the test should run into, see Namespace selection.

"},{"location":"test/spec/#namespace-template","title":"Namespace template","text":"

Eventually provide a template if you something specific, see Namespace template.

"},{"location":"test/spec/#timeouts","title":"Timeouts","text":"

All timeouts can be specified per test, see Control your timeouts.

"},{"location":"test/spec/#clusters","title":"Clusters","text":"

Additional clusters can be registered at the test level, see Multi-cluster options.

"},{"location":"test/spec/#cluster","title":"Cluster","text":"

The cluster (by name) used to run the test, see Multi-cluster setup.

"},{"location":"test/spec/#bindings","title":"Bindings","text":"

Bindings can be registered at the test level and inherited in all steps, see Bindings.

"},{"location":"test/spec/#catch","title":"Catch","text":"

Catch blocks can be specified at the test level to declare common catch statements.

"},{"location":"test/spec/#template","title":"Template","text":"

Chainsaw allows templating configuration on a per test basis.

"},{"location":"test/spec/#concurrency","title":"Concurrency","text":"

Controlling concurrency per test is also possible, see Concurrency control.

"},{"location":"test/spec/#skip","title":"Skip","text":"

In case you need to skip a test for whatever reason, use skip: true.

"},{"location":"test/spec/#steps","title":"Steps","text":"

Steps are what tests will execute when they are run, see Test step spec dedicated section.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"cicd/gh-action/","title":"GitHub action","text":"

A GitHub action is available to easily install Chainsaw in your workflows.

The GitHub action is available at kyverno/action-install-chainsaw or in the marketplace.

"},{"location":"cicd/gh-action/#usage","title":"Usage","text":"

This action currently supports GitHub-provided Linux, macOS and Windows runners (self-hosted runners may not work).

Add the following entry to your Github workflow YAML file:

uses: kyverno/action-install-chainsaw@v0.1.0\nwith:\n  release: v0.1.0 # optional\n

Example using a pinned version:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw\n    steps:\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n        with:\n          release: v0.0.9\n      - name: Check install\n        run: chainsaw version\n

Example using the default version:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw\n    steps:\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n      - name: Check install\n        run: chainsaw version\n

Example using cosign verification:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw\n    steps:\n      - name: Install Cosign\n        uses: sigstore/cosign-installer@v3.1.1\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n        with:\n          verify: true\n      - name: Check install\n        run: chainsaw version\n

If you want to install Chainsaw from its main version by using go install under the hood, you can set release as main. Once you did that, Chainsaw will be installed via go install which means that please ensure that go is installed.

Example of installing Chainsaw via go install:

jobs:\n  example:\n    runs-on: ubuntu-latest\n\n    permissions: {}\n\n    name: Install Chainsaw via go install\n    steps:\n      - name: Install go\n        uses: actions/setup-go@v4\n        with:\n          go-version: '1.21'\n      - name: Install Chainsaw\n        uses: kyverno/action-install-chainsaw@v0.1.0\n        with:\n          release: main\n      - name: Check install\n        run: chainsaw version\n
"},{"location":"cicd/gh-action/#optional-inputs","title":"Optional Inputs","text":"

The following optional inputs:

Input Description release chainsaw version to use instead of the default. install-dir directory to place the chainsaw binary into instead of the default ($HOME/.chainsaw). use-sudo set to true if install-dir location requires sudo privs. Defaults to false. verify set to true to enable cosign verification of the downloaded archive."},{"location":"community/","title":"Community","text":"

Chainsaw has a growing community and we would definitely love to see you join and contribute.

Everyone is welcome to make suggestions, report bugs, open feature requests, contribute code or docs, participate in discussions, write blogs or anything that can benefit the project.

Chainsaw is built and maintained under the Kyverno umbrella but decisions are Community driven Everyone's voice matters

"},{"location":"community/#slack-channel","title":"Slack channel","text":"

Join our slack channel #kyverno-chainsaw to meet with users, contributors and maintainers.

"},{"location":"community/#community-meetings","title":"Community Meetings","text":"

To attend our community meetings, join the Chainsaw group. You will then be sent a meeting invite and will have access to the agenda and meeting notes. Any member may suggest topics for discussion.

This is a public, weekly for Kyverno-Chainsaw maintainers to make announcements and provide project updates, and request input and feedback. This forum allows community members to raise agenda items of any sort, including but not limited to any PRs or issues on which they are working.

Weekly every Thursday at 2:00 PM UTC

"},{"location":"community/#roadmap","title":"RoadMap","text":"

For detailed information on our planned features and upcoming updates, please view our Roadmap.

"},{"location":"community/#contributing","title":"Contributing","text":"

Please read the contributing guide for details around:

  1. Code of Conduct
  2. Code Culture
  3. Details on how to contribute
"},{"location":"community/#adopters","title":"Adopters","text":"

If you are using Chainsaw and want to share it publicly we always appreciate a bit of support. Pull requests to the ADOPTERS LIST will put a smile on our faces

"},{"location":"configuration/","title":"Configuring Chainsaw","text":"

This documentation focuses on providing a breakdown of the Chainsaw configuration structure and how to use it.

Chainsaw can be configured in two different and complementary ways:

"},{"location":"configuration/#specific-configuration-options","title":"Specific configuration options","text":"

Please pay attention to the configuration options below, they may or may not be relevant in your case but can be useful in certain cases:

"},{"location":"configuration/file/","title":"Configuration file","text":"

Chainsaw prioritizes its configuration in the following order:

  1. User-specified configuration

    If you explicitly provide a configuration file using a command-line flag

  2. Default configuration file

    If no configuration is specified, Chainsaw will look for a default file named .chainsaw.yaml in the current working directory

  3. Internal default configuration

    In the absence of both of the above, Chainsaw will use a default configuration file embedded in the Chainsaw binary

"},{"location":"configuration/file/#example","title":"Example","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  timeouts:\n    apply: 45s\n    assert: 20s\n    cleanup: 45s\n    delete: 25s\n    error: 10s\n    exec: 45s\n  cleanup:\n    skipDelete: false\n  execution:\n    failFast: true\n    parallel: 4\n  # ...\n
"},{"location":"configuration/file/#how-to-specify-a-configuration","title":"How to specify a configuration","text":"

To use a custom configuration file:

chainsaw test --config path/to/your/config.yaml\n
"},{"location":"configuration/file/#default-configuration","title":"Default configuration","text":"

The default configuration below is used by Chainsaw when no configuration file was provided and the default file .chainsaw.yaml does not exist.

apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: default\nspec: {}\n
"},{"location":"configuration/file/#reference-documentation","title":"Reference documentation","text":"

See Configuration API reference for more details.

"},{"location":"configuration/flags/","title":"Command line flags","text":"

After a configuration file is loaded, you can override specific settings using command-line flags.

Precedence

Command-line flags always take precedence over the configuration coming from a configuration file.

"},{"location":"configuration/flags/#example","title":"Example","text":"
chainsaw test                         \\\n  path/to/test/dir                    \\\n  --config path/to/your/config.yaml   \\\n  --assert-timeout 45s                \\\n  --skip-delete false                 \\\n  --fail-fast true                    \\\n  --parallel 4                        \\\n  ...\n

In this example, Chainsaw will load a configuration file but the timeout configuration and other settings will be overridden by the values set in the flags, regardless of the value in the loaded configuration file.

"},{"location":"configuration/flags/#reference-documentation","title":"Reference documentation","text":"

See chainsaw test command reference for the list of all available flags.

"},{"location":"configuration/options/cleanup/","title":"Cleanup options","text":"

Cleanup options contain the configuration used by Chainsaw for cleaning up resources.

"},{"location":"configuration/options/cleanup/#supported-elements","title":"Supported elements","text":"Element Default Description skipDelete false If set, do not delete the resources after running a test. delayBeforeCleanup DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts."},{"location":"configuration/options/cleanup/#delay-before-cleanup","title":"Delay before cleanup","text":"

At the end of each test, Chainsaw will delete the resources it created during the test.

When testing operators, it can be useful to wait a little bit before starting the cleanup process to make sure the operator/controller has the necessary time to update its internal state.

"},{"location":"configuration/options/cleanup/#configuration","title":"Configuration","text":""},{"location":"configuration/options/cleanup/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  cleanup:\n    skipDelete: true\n    delayBeforeCleanup: 5s\n
"},{"location":"configuration/options/cleanup/#with-flags","title":"With flags","text":"
chainsaw test                   \\\n  --skip-delete                 \\\n  --delay-before-cleanup 5s\n
"},{"location":"configuration/options/clusters/","title":"Multi-cluster options","text":"

Multi-cluster options contain the configuration of additional clusters.

"},{"location":"configuration/options/clusters/#supported-elements","title":"Supported elements","text":"

Every cluster is registered by name and supports the following elements:

Element Default Description kubeconfig string Kubeconfig is the path to the referenced file. context string Context is the name of the context to use."},{"location":"configuration/options/clusters/#configuration","title":"Configuration","text":""},{"location":"configuration/options/clusters/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: custom-config\nspec:\n  clusters:\n    # this cluster will use the default (current) context\n    # configured in the kubeconfig file\n    cluster-1:\n      kubeconfig: /path/to/kubeconfig-1\n    # this cluster will use the context named `context-2`\n    # in the kubeconfig file\n    cluster-2:\n      kubeconfig: /path/to/kubeconfig-2\n      context: context-2\n
"},{"location":"configuration/options/clusters/#with-flags","title":"With flags","text":"

Note

The --cluster flag can appear multiple times and is expected to come in the following format:

--cluster cluster-name=/path/to/kubeconfig[:context-name].

chainsaw test                                               \\\n    --cluster cluster-1=/path/to/kubeconfig-1               \\\n    --cluster cluster-2=/path/to/kubeconfig-2:context-2\n
"},{"location":"configuration/options/deletion/","title":"Deletion options","text":"

Deletion options determine the configuration used by Chainsaw for deleting resources.

"},{"location":"configuration/options/deletion/#supported-elements","title":"Supported elements","text":"Element Default Description propagation Background Propagation decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation."},{"location":"configuration/options/deletion/#propagation","title":"Propagation","text":"

This element will affect Kubernetes cascading deletion. Supported values are Orphan, Background and Foreground.

Tip

Setting Orphan is probably never a good idea because it would leak resources in the test cluster. Chainsaw uses Background as its default value which is a reasonable choice.

Note that Foreground can be useful to fail when the dependent resources fail to delete.

"},{"location":"configuration/options/deletion/#configuration","title":"Configuration","text":""},{"location":"configuration/options/deletion/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  deletion:\n    propagation: Foreground\n
"},{"location":"configuration/options/deletion/#with-flags","title":"With flags","text":"
chainsaw test --deletion-propagation-policy Foreground\n
"},{"location":"configuration/options/discovery/","title":"Discovery options","text":"

Discovery options contain the discovery configuration used by Chainsaw when discovering tests in specified folders.

"},{"location":"configuration/options/discovery/#supported-elements","title":"Supported elements","text":"Element Default Description testFile chainsaw-test TestFile is the name of the file containing the test to run. If no extension is provided, chainsaw will try with .yaml first and .yml if needed. fullName false FullName makes use of the full test case folder path instead of the folder name. includeTestRegex IncludeTestRegex is used to include tests based on a regular expression. excludeTestRegex ExcludeTestRegex is used to exclude tests based on a regular expression."},{"location":"configuration/options/discovery/#configuration","title":"Configuration","text":""},{"location":"configuration/options/discovery/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  discovery:\n    testFile: chainsaw-test\n    fullName: true\n    includeTestRegex: chainsaw/.*\n    excludeTestRegex: chainsaw/exclude-.*\n
"},{"location":"configuration/options/discovery/#with-flags","title":"With flags","text":"
chainsaw test                                   \\\n  --test-file chainsaw-test                     \\\n  --full-name                                   \\\n  --include-test-regex 'chainsaw/.*'            \\\n  --exclude-test-regex 'chainsaw/exclude-.*'\n
"},{"location":"configuration/options/error/","title":"Error options","text":"

Error options contain the global error configuration used by Chainsaw.

"},{"location":"configuration/options/error/#supported-elements","title":"Supported elements","text":"Field Default Description catch Catch defines what the tests steps will execute when an error happens. This will be combined with catch handlers defined at the test and step levels."},{"location":"configuration/options/error/#configuration","title":"Configuration","text":""},{"location":"configuration/options/error/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  error:\n    catch:\n    - events: {}\n    - describe:\n        resource: crds\n
"},{"location":"configuration/options/error/#with-flags","title":"With flags","text":"

Note

Error options can't be configured with flags.

"},{"location":"configuration/options/execution/","title":"Execution options","text":"

Execution options determine how tests are run by Chainsaw.

"},{"location":"configuration/options/execution/#supported-elements","title":"Supported elements","text":"Element Default Description failFast false FailFast determines whether the test should stop upon encountering the first failure. parallel auto The maximum number of tests to run at once. repeatCount 1 RepeatCount indicates how many times the tests should be executed. forceTerminationGracePeriod ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments."},{"location":"configuration/options/execution/#termination-grace-period","title":"Termination grace period","text":"

Some Kubernetes resources can take time before being terminated. For example, deleting a pod can take time if the underlying container doesn't quit quickly enough.

Chainsaw can override the grace period for the following resource kinds:

"},{"location":"configuration/options/execution/#configuration","title":"Configuration","text":""},{"location":"configuration/options/execution/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  execution:\n    failFast: true\n    parallel: 8\n    repeatCount: 2\n    forceTerminationGracePeriod: 5s\n
"},{"location":"configuration/options/execution/#with-flags","title":"With flags","text":"
chainsaw test                                   \\\n  --fail-fast                                   \\\n  --parallel 8                                  \\\n  --repeat-count 2                              \\\n  --force-termination-grace-period 5s\n
"},{"location":"configuration/options/label-selectors/","title":"Label selectors","text":"

Chainsaw can filter the tests to run using label selectors.

"},{"location":"configuration/options/label-selectors/#configuration","title":"Configuration","text":""},{"location":"configuration/options/label-selectors/#with-file","title":"With file","text":"

Note

Label selectors can't be configured with a configuration file.

"},{"location":"configuration/options/label-selectors/#with-flags","title":"With flags","text":"
chainsaw test --selector foo=bar\n
"},{"location":"configuration/options/namespace/","title":"Namespace options","text":"

Namespace options contain the configuration used by Chainsaw to allocate a namespace for each test.

"},{"location":"configuration/options/namespace/#supported-elements","title":"Supported elements","text":"Element Default Description name Name defines the namespace to use for tests. If not specified, every test will execute in a random ephemeral namespace unless the namespace is overridden in a the test spec. template Template defines a template to create the test namespace."},{"location":"configuration/options/namespace/#configuration","title":"Configuration","text":""},{"location":"configuration/options/namespace/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  namespace:\n    name: foo\n    template:\n      metadata:\n        annotations:\n          from-config-file: hello\n
"},{"location":"configuration/options/namespace/#with-flags","title":"With flags","text":"

Note

The template element can't be configured with flags.

chainsaw test --namespace foo\n
"},{"location":"configuration/options/no-cluster/","title":"No cluster options","text":"

Chainsaw can be run without any connection to a Kubernetes cluster.

In this case, Chainsaw will not try to create an ephemeral namespace and all operations requiring a Kubernetes cluster will fail.

"},{"location":"configuration/options/no-cluster/#configuration","title":"Configuration","text":""},{"location":"configuration/options/no-cluster/#with-file","title":"With file","text":"

Note

No cluster options can't be configured with a configuration file.

"},{"location":"configuration/options/no-cluster/#with-flags","title":"With flags","text":"
chainsaw test --no-cluster\n
"},{"location":"configuration/options/pause/","title":"Pause options","text":"

Chainsaw can be configured to pause and wait for user input when a failure happens. This is useful when Chainsaw is run locally to allow debugging and troubleshooting failures.

"},{"location":"configuration/options/pause/#configuration","title":"Configuration","text":""},{"location":"configuration/options/pause/#with-file","title":"With file","text":"

Note

Pause options can't be configured with a configuration file.

"},{"location":"configuration/options/pause/#with-flags","title":"With flags","text":"
chainsaw test --pause-on-failure\n
"},{"location":"configuration/options/report/","title":"Reporting options","text":"

Reporting options contain the configuration used by Chainsaw for reporting.

"},{"location":"configuration/options/report/#supported-elements","title":"Supported elements","text":"Element Default Description format JSON ReportFormat determines test report format (JSON path ReportPath defines the path. name chainsaw-report ReportName defines the name of report to create. It defaults to \"chainsaw-report\"."},{"location":"configuration/options/report/#configuration","title":"Configuration","text":""},{"location":"configuration/options/report/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  report:\n    format: JSON\n    name: chainsaw-report\n    path: /home/chainsaw\n
"},{"location":"configuration/options/report/#with-flags","title":"With flags","text":"

Note

The report path can be specified as either a relative or an absolute path.

chainsaw test                             \\\n  --report-format JSON                    \\\n  --report-name chainsaw-report           \\\n  --report-path /path/to/save/report\n
"},{"location":"configuration/options/templating/","title":"Templating options","text":"

Templating options contain the templating configuration.

"},{"location":"configuration/options/templating/#supported-elements","title":"Supported elements","text":"Element Default Description enabled true Enabled determines whether resources should be considered for templating.

Tip

Templating was disabled by default in v0.1.* but is now enabled by default since v0.2.1.

"},{"location":"configuration/options/templating/#configuration","title":"Configuration","text":""},{"location":"configuration/options/templating/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  templating:\n    enabled: false\n
"},{"location":"configuration/options/templating/#with-flags","title":"With flags","text":"
chainsaw test --template=false\n
"},{"location":"configuration/options/timeouts/","title":"Timeouts","text":"

Timeouts in Chainsaw are specified per type of operation. This is required because the timeout varies greatly depending on the nature of an operation.

For example, applying a manifest in a cluster is expected to execute reasonably fast, while validating a resource can be a much longer operation.

"},{"location":"configuration/options/timeouts/#supported-timeouts","title":"Supported timeouts","text":"Element Default Description apply 5s Used when Chainsaw applies manifests in a cluster assert 30s Used when Chainsaw validates resources in a cluster cleanup 30s Used when Chainsaw removes resources created for a test delete 15s Used when Chainsaw deletes resources from a cluster error 30s Used when Chainsaw validates resources in a cluster exec 5s Used when Chainsaw executes arbitrary commands or scripts"},{"location":"configuration/options/timeouts/#configuration","title":"Configuration","text":""},{"location":"configuration/options/timeouts/#with-file","title":"With file","text":"
apiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  timeouts:\n    apply: 45s\n    assert: 20s\n    cleanup: 45s\n    delete: 25s\n    error: 10s\n    exec: 45s\n
"},{"location":"configuration/options/timeouts/#with-flags","title":"With flags","text":"
chainsaw test               \\\n  --apply-timeout 45s       \\\n  --assert-timeout 45s      \\\n  --cleanup-timeout 45s     \\\n  --delete-timeout 45s      \\\n  --error-timeout 45s       \\\n  --exec-timeout 45s\n
"},{"location":"configuration/options/values/","title":"External values","text":"

Chainsaw can pass arbitrary values when running tests using the --values flag. Values will be available to tests under the $values binding.

"},{"location":"configuration/options/values/#configuration","title":"Configuration","text":""},{"location":"configuration/options/values/#with-file","title":"With file","text":"

Note

Values can't be configured with a configuration file.

"},{"location":"configuration/options/values/#with-flags","title":"With flags","text":"
chainsaw test --values ./values.yaml\n
"},{"location":"examples/","title":"Examples","text":"

Info

Select an item in the navigation menu to browse a specific page.

"},{"location":"examples/concurrency/","title":"Concurrency control","text":"

By default, Chainsaw will run tests in parallel.

The number of concurrent tests can be configured globally using a configuration file or with the --parallel flag.

Alternatively, the concurrent nature of a test can specified at the test level:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # concurrency can be specified per test (`true` or `false`)\n  # default value is `true`\n  concurrent: false\n  # ...\n

All non-concurrent tests are executed first, followed by the concurrent tests running in parallel.

"},{"location":"examples/crds/","title":"Work with CRDs","text":"

New CRDs are not immediately available for use in the Kubernetes API until the Kubernetes API has acknowledged them.

If a CRD is being defined inside of a test step, be sure to wait for it to appear.

The test below applies a CRD and waits for it to become available:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: apiextensions.k8s.io/v1\n          kind: CustomResourceDefinition\n          metadata:\n            name: issues.example.com\n          spec:\n            group: example.com\n            names:\n              kind: Issue\n              listKind: IssueList\n              plural: issues\n              singular: issue\n            scope: Namespaced\n            versions: ...\n    - assert:\n        resource:\n          apiVersion: apiextensions.k8s.io/v1\n          kind: CustomResourceDefinition\n          metadata:\n            name: issues.example.com\n          status:\n            acceptedNames:\n              kind: Issue\n              listKind: IssueList\n              plural: issues\n              singular: issue\n            storedVersions:\n            - v1alpha1\n

The CRD can be used in subsequent steps.

"},{"location":"examples/events/","title":"Work with events","text":"

Kubernetes events are regular Kubernetes objects and can be asserted on just like any other object:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: Event\n          reason: Started\n          source:\n            component: kubelet\n          involvedObject:\n            apiVersion: v1\n            kind: Pod\n            name: my-pod\n
"},{"location":"examples/inline/","title":"Inline resources","text":"

When an operation needs to reference a resource, it can do so using a file path or directly specify the resource inline using the resource field.

The test below is equivalent to our first test:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n
"},{"location":"examples/kube-version/","title":"Check Kubernetes version","text":"

The test below fetches the Kubernetes cluster version using the x_k8s_server_version function. It then uses the minor version retrieved to adapt an assertion based on the value in the $minorversion binding.

Tip

You can implement a ternary operator in JMESPath using an expression like this:

<condition> && <value-if-true> || <value-if-false>

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  bindings:\n  - name: version\n    value: (x_k8s_server_version($config))\n  - name: minorversion\n    value: (to_number($version.minor))\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: v1\n          kind: Pod\n          metadata:\n            name: pod01\n          spec:\n            containers:\n            - name: busybox\n              image: busybox:1.35\n    # ...\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: Pod\n          metadata:\n            annotations:\n              # If the minor version of the Kubernetes cluster against\n              # which this is tested is less than 29, the annotation is\n              # expected to have the group 'system:masters' in it.\n              # Otherwise, due to a change in kubeadm, the group should\n              # be 'kubeadm:cluster-admins'.\n              kyverno.io/created-by: (($minorversion < `29` && '{\"groups\":[\"system:masters\",\"system:authenticated\"],\"username\":\"kubernetes-admin\"}') || '{\"groups\":[\"kubeadm:cluster-admins\",\"system:authenticated\"],\"username\":\"kubernetes-admin\"}')\n            name: pod01\n
"},{"location":"examples/label-selectors/","title":"Work with label selectors","text":"

Chainsaw can filter the tests to run using label selectors.

You can pass label selectors using the --selector flag when invoking the chainsaw test command.

Given the test below:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: basic\n  labels:\n    foo: bar\nspec:\n  # ...\n

Invoking Chainsaw with the command below will take the test above into account:

chainsaw test --selector foo=bar\n
"},{"location":"examples/multi-cluster/","title":"Multi-cluster setup","text":"

Chainsaw supports registering and using multiple clusters in tests.

We can also register clusters dynamically and combine this with cluster selection to achieve scenarios where clusters are dynamically allocated in a test step, used in the following steps, and cleaned up at the end.

The following test demonstrates such a scenario by creating a local kind cluster in the first, using it in the second step, and configuring a cleanup script to delete the cluster when the test terminates:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    # create a local cluster\n    - script:\n        timeout: 1m\n        content: |\n          kind create cluster --name dynamic --kubeconfig ./dynamic\n    # register `cleanup` operations to delete the cluster\n    # at the end of the test\n    cleanup:\n    - script:\n        content: |\n          kind delete cluster --name dynamic\n    - script:\n        content: |\n          rm -f ./dynamic\n    # register the `dynamic` cluster in this step\n  - clusters:\n      dynamic:\n        kubeconfig: ./dynamic\n    # and use the `dynamic` cluster for all operations in the step\n    cluster: dynamic\n    try:\n    - apply:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n            namespace: default\n          data:\n            foo: bar\n    - assert:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n            namespace: default\n          data:\n            foo: bar\n

Running the test above will produce the following output:

    | 10:44:53 | example | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-useful-seahorse\n    | 10:44:53 | example | step-1   | TRY       | RUN   |\n    | 10:44:53 | example | step-1   | SCRIPT    | RUN   |\n        === COMMAND\n        /bin/sh -c kind create cluster --name dynamic --kubeconfig ./dynamic\n    | 10:45:10 | example | step-1   | SCRIPT    | LOG   |\n        === STDERR\n        Creating cluster \"dynamic\" ...\n         \u2022 Ensuring node image (kindest/node:v1.27.3) \ud83d\uddbc  ...\n         \u2713 Ensuring node image (kindest/node:v1.27.3) \ud83d\uddbc\n         \u2022 Preparing nodes \ud83d\udce6   ...\n         \u2713 Preparing nodes \ud83d\udce6 \n         \u2022 Writing configuration \ud83d\udcdc  ...\n         \u2713 Writing configuration \ud83d\udcdc\n         \u2022 Starting control-plane \ud83d\udd79\ufe0f  ...\n         \u2713 Starting control-plane \ud83d\udd79\ufe0f\n         \u2022 Installing CNI \ud83d\udd0c  ...\n         \u2713 Installing CNI \ud83d\udd0c\n         \u2022 Installing StorageClass \ud83d\udcbe  ...\n         \u2713 Installing StorageClass \ud83d\udcbe\n        Set kubectl context to \"kind-dynamic\"\n        You can now use your cluster with:\n\n        kubectl cluster-info --context kind-dynamic --kubeconfig ./dynamic\n\n        Thanks for using kind! \ud83d\ude0a\n    | 10:45:10 | example | step-1   | SCRIPT    | DONE  |\n    | 10:45:10 | example | step-1   | TRY       | DONE  |\n    | 10:45:10 | example | step-2   | TRY       | RUN   |\n    | 10:45:10 | example | step-2   | APPLY     | RUN   | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | CREATE    | OK    | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | APPLY     | DONE  | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | ASSERT    | RUN   | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | ASSERT    | DONE  | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | TRY       | DONE  |\n    | 10:45:10 | example | step-2   | CLEANUP   | RUN   |\n    | 10:45:10 | example | step-2   | DELETE    | RUN   | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | DELETE    | OK    | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | DELETE    | DONE  | v1/ConfigMap @ default/quick-start\n    | 10:45:10 | example | step-2   | CLEANUP   | DONE  |\n    | 10:45:10 | example | step-1   | CLEANUP   | RUN   |\n    | 10:45:10 | example | step-1   | SCRIPT    | RUN   |\n        === COMMAND\n        /bin/sh -c kind delete cluster --name dynamic\n    | 10:45:10 | example | step-1   | SCRIPT    | LOG   |\n        === STDERR\n        Deleting cluster \"dynamic\" ...\n        Deleted nodes: [\"dynamic-control-plane\"]\n    | 10:45:10 | example | step-1   | SCRIPT    | DONE  |\n    | 10:45:10 | example | step-1   | SCRIPT    | RUN   |\n        === COMMAND\n        /bin/sh -c rm -f ./dynamic\n    | 10:45:10 | example | step-1   | SCRIPT    | DONE  |\n    | 10:45:10 | example | step-1   | CLEANUP   | DONE  |\n    | 10:45:10 | example | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-useful-seahorse\n    | 10:45:11 | example | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-useful-seahorse\n    | 10:45:16 | example | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-useful-seahorse\n
"},{"location":"examples/negative-testing/","title":"Negative testing","text":"

Negative testing is the process of testing cases that are supposed to fail. That is, a test expects errors to happen and if the expected errors don't occur the test must fail.

Chainsaw supports negative testing by letting you decide what should be considered an error or not.

Tip

By default, Chainsaw will consider an operation failed if there was an error executing it (non-zero exit code in scripts and commands, error returned by the API server when calling into Kubernetes, etc...).

"},{"location":"examples/negative-testing/#script-case","title":"Script case","text":"

The test below expects an error and validates the returned error message:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: kubectl get foo\n        check:\n          ($error != null): true\n          ($stderr): |-\n            error: the server doesn't have a resource type \"foo\"\n

If for whatever reason, the kubectl get foo doesn't return an error, or the message received in standard error output is not error: the server doesn't have a resource type \"foo\", Chainsaw will consider the operation failed.

If it returns an error and the expected error message, Chainsaw will consider the operation successful.

"},{"location":"examples/negative-testing/#working-with-resources","title":"Working with resources","text":"

The test below tries to apply resources in a cluster but expects the operation to fail:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: resources.yaml\n        expect:\n          # check that applying the resource failed\n        - check:\n            ($error != null): true\n

If applying the resource succeeded, Chainsaw will consider the operation failed.

On the other hand, if applying the resource fails, Chainsaw will consider the operation to be successful.

"},{"location":"examples/negative-testing/#resource-matching","title":"Resource matching","text":"

In the previous example, if the resources.yaml contains multiple resources, but only some of them may be expected to fail.

Chainsaw allows matching resources when evaluating checks:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: resources.yaml\n        expect:\n          # the check below only applies if the resource being checked\n          # matches the condition defined in the `match` field\n        - match:\n            apiVersion: v1\n            kind: ConfigMap\n            metadata:\n              name: quick-start\n          check:\n            ($error != null): true\n

Using the match field, we can easily target failures related to specific resources.

"},{"location":"examples/non-resource-assertions/","title":"Non-resource assertions","text":"

Under certain circumstances, it makes sense to evaluate assertions that do not depend on resources. For example, when asserting the number of nodes in a cluster is equal to a known value.

The test below uses the x_k8s_list function to query the list of nodes in the cluster. It uses the results to compare the number of nodes found with a known number (1 in this case).

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          (x_k8s_list($client, 'v1', 'Node')):\n            (length(items)): 1\n
"},{"location":"examples/test-output/","title":"Test command output","text":"

Chainsaw can be used to easily check terminal output from CLIs and other commands. This is useful in that convoluted bash scripts involving chaining together tools like grep can be avoided or at least minimized to only complex use cases. Output to both stdout and stderr can be checked for a given string or precise contents.

"},{"location":"examples/test-output/#checking-output-contains","title":"Checking Output Contains","text":"

One basic use case for content checking is that the output simply contains a given string or piece of content. For example, you might want to run automated tests on a CLI binary you build to ensure that a given command produces output that contains some content you specify somewhere in the output. Let's use the following output from the kubectl version command to show these examples.

kubectl version\n\nClient Version: v1.28.2\nKustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3\nServer Version: v1.27.4+k3s1\n

Below is an example that ensures the string '1.28' is found somewhere in that output. So long as the content is present anywhere, the test will succeed. To perform this check, the contains() JMESPath filter is used.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check kubectl\n    try:\n    - script:\n        content: kubectl version\n        check:\n          # This check ensures that the string '1.28' is found\n          # in stdout or else fails\n          (contains($stdout, '1.28')): true\n

Checks for content containing a given value can be negated as well. For example, checking to ensure the output does NOT contain the string '1.25'.

- script:\n    content: kubectl version\n    check:\n      # This check ensures that the string '1.25' is NOT found\n      # in stdout or else fails\n      (contains($stdout, '1.25')): false\n
"},{"location":"examples/test-output/#checking-output-is-exactly","title":"Checking Output Is Exactly","text":"

In addition to checking that CLI/command output contains some contents, you may need to ensure that the contents are exactly as intended. The Chainsaw test below accomplishes this by comparing the entire contents of stdout with those specified in the block scalar. If so much as one character, space, or line break is off, the test will fail. This is useful in that not only can content be checked but the formatting of that content can be ensured it matches a given declaration.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check kubectl\n    try:\n    - script:\n        content: kubectl version\n        check:\n          # This check ensures the contents of stdout are exactly as shown.\n          # Any deviations will cause a failure.\n          ($stdout): |-\n            Client Version: v1.28.2\n            Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3\n            Server Version: v1.27.4+k3s1\n
"},{"location":"examples/test-output/#checking-output-in-errors","title":"Checking Output In Errors","text":"

In addition to testing that commands succeed and with output in a given shape, it's equally valuable and necessary to perform negative tests; that tests fail and with contents that are as expected. Similarly, those checks can be for output which has some contents as well as output which appears exactly as desired. For example, you may wish to check that running the kubectl foo command not only fails as expected but that the output shown to users contains a certain word or sentence.

kubectl foo\n\nerror: unknown command \"foo\" for \"kubectl\"\n\nDid you mean this?\n        top\n

Below you can see an example where the command kubectl foo is expected to fail but that the error message returned contains some output, in this case the string 'top'.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check bad kubectl command\n    try:\n    - script:\n        content: kubectl foo\n        check:\n          # This checks that the result of the content was an error.\n          ($error != null): true\n          # This check below ensures that the string 'top' is found in stderr or else fails\n          (contains($stderr, 'top')): true\n

Likewise, this failure output can be checked that it is precise. Note that in the example below, due to the use of a tab character in the output of kubectl foo, the value of the ($stderr) field is given as a string to preserve these non-printing characters.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: test\nspec:\n  steps:\n  - name: Check kubectl\n    try:\n    - script:\n        content: kubectl foo\n        check:\n          # This checks that the result of the content was an error.\n          ($error != null): true\n          # This checks that the output is exactly as intended.\n          ($stderr): \"error: unknown command \\\"foo\\\" for \\\"kubectl\\\"\\n\\nDid you mean this?\\n\\ttop\"\n
"},{"location":"examples/values/","title":"Pass data to tests","text":"

Chainsaw can pass arbitrary values when running tests using the --values flag. Values will be available to tests under the $values binding.

This is useful when a test needs to be configured externally.

"},{"location":"examples/values/#reference-external-data","title":"Reference external data","text":"

The test below expects the $value.foo to be provided when chainsaw is invoked.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          ($values.foo): bar\n
"},{"location":"examples/values/#invoking-chainsaw","title":"Invoking Chainsaw","text":""},{"location":"examples/values/#read-values-from-a-file","title":"Read values from a file","text":"
chainsaw test --values ./values.yaml\n
"},{"location":"examples/values/#read-from-stdin","title":"Read from stdin","text":"
echo \"foo: bar\" | chainsaw test --values -\n
"},{"location":"examples/values/#use-heredoc","title":"Use heredoc","text":"
chainsaw test --values - <<EOF\nfoo: bar\nEOF\n
"},{"location":"general/bindings/","title":"Bindings","text":"

You can think of bindings as a side context where you can store and retrieve data by name.

This is particularly useful when some data is only known at runtime. For example, to pass data from one operation to another, to implement resource templating, to fetch data from an external system, or anything that needs to be computed at runtime.

"},{"location":"general/bindings/#syntax","title":"Syntax","text":"

The test below illustrates bindings declaration at different levels:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # bindings can be declared at the test level\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n    # bindings can also be declared at the step level\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        # bindings can also be declared at the operation level\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n          # combined bindings together using the `join` functions and\n          # assign the result to the GREETINGS environment variable\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        content: echo $GREETINGS\n
"},{"location":"general/bindings/#reference","title":"Reference","text":"

Browse the reference documentation to see the syntax details and where bindings can be declared.

"},{"location":"general/bindings/#inheritance","title":"Inheritance","text":"

Bindings can be configured at the test, step or operation level.

All bindings configured at a given level are automatically inherited at lower levels.

"},{"location":"general/bindings/#immutability","title":"Immutability","text":"

Bindings are immutable. This means two bindings can have the same name without overwriting each other.

When a binding is registered it potentially hides other bindings with the same name.

When this binding goes out of scope, previously registered bindings with the same name become visible again.

"},{"location":"general/bindings/#templating","title":"Templating","text":"

Both name and value of a binding can use templating.

"},{"location":"general/bindings/#built-in-bindings","title":"Built-in bindings","text":"

Chainsaw offers some built-in bindings you can directly use in your tests, steps and operations.

Browse the built-in bindings list to find available bindings.

"},{"location":"general/checks/","title":"Operation checks","text":"

Considering an operation's success or failure is not always as simple as checking an error code.

To support those kinds of use cases, some operations support additional checks to evaluate the operation result against an assertion tree.

"},{"location":"general/checks/#input-model","title":"Input model","text":"

Different operations have a different model passed through the assertion tree.

Please consult the Built-in bindings reference documentation to learn what is available depending on the operation.

"},{"location":"general/checks/#expect-vs-check","title":"Expect vs Check","text":"

While a simple check is enough to determine the result of a single operation, we needed a more advanced construct to cover apply, create, delete, patch and update operations. Those operations can operate on files containing multiple resources and every resource can lead to a different result and expectation.

"},{"location":"general/checks/#check","title":"Check","text":"

The example below uses a simple check. The operation is expected to fail (($error != null): true):

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: |\n          exit 1\n        check:\n          # an error is expected, this will:\n          # - succeed if the operation failed\n          # - fail if the operation succeeded\n          ($error != null): true\n
"},{"location":"general/checks/#expect","title":"Expect","text":"

To support more granular checks we use the expect field that contains an array of Expectations.

Every expectation is made of an optional match combined with a check statement.

This way it is possible to control the scope of a check:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        file: resources.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n

In the test above, only config maps are expected to fail. If the resources.yaml file contains other type of resources they are supposed to be created without error (if an error happens for a non config map resource, the operation will be considered a failure).

"},{"location":"general/inheritance/","title":"Inheritance","text":"

Chainsaw has a concept of levels and most of the configuration elements and dynamic elements are inherited from one layer to the next in one way or another.

"},{"location":"general/inheritance/#levels","title":"Levels","text":"
flowchart TD\n    Configuration -. Configuration elements are inherited in tests .-> Test\n    Test -. Test elements are inherited in test steps .-> Step\n    Step -. Step elements are inherited in step operations .-> Operation
"},{"location":"general/inheritance/#configuration","title":"Configuration","text":"

The first layer comes from the Chainsaw configuration. You can think about this layer as the global scope and a way to configure how Chainsaw will behave globally.

Under certain circumstances, lower layers will be allowed to consume and/or override elements from upper layers.

"},{"location":"general/inheritance/#test","title":"Test","text":"

At the test level, you can override or create new elements. They will only be visible to the test, steps and operations that are part of it.

In any case, tests are strongly isolated and have no way to communicate with or depend on other tests.

"},{"location":"general/inheritance/#step","title":"Step","text":"

Again, at the step level, you can override or create new elements and they will only be visible to the step and operations that are part of it.

"},{"location":"general/inheritance/#operation","title":"Operation","text":"

At the operation level, you can override or create new elements and use them in the operation itself.

"},{"location":"general/inheritance/#immutability","title":"Immutability","text":"

Even if elements are inherited, they are immutable.

Some elements can be overridden but never overwritten.

"},{"location":"general/inheritance/#outputs","title":"Outputs","text":"

Inheritance always flows from one level to the next and never propagates back to the upper levels.

There's no exception to this rule, but the only case where one operation can communicate with other ones is when using outputs.

"},{"location":"general/namespace/","title":"Test namespace","text":"

By default, Chainsaw will create an ephemeral namespace with a random name for each test, unless a specific namespace name is provided at the global or test level.

"},{"location":"general/namespace/#selection","title":"Selection","text":""},{"location":"general/namespace/#global","title":"Global","text":"

One way to control the namespace used to run tests is to specify the name in the Chainsaw configuration Namespace options.

If a namespace name is specified at the configuration level Chainsaw will use it to run the tests (unless an individual test overrides the namespace name).

"},{"location":"general/namespace/#per-test","title":"Per test","text":"

If the test name is specified in a test spec, Chainsaw will use it to run the test regardless of whether a namespace name was configured at the global level.

"},{"location":"general/namespace/#random","title":"Random","text":"

If no namespace name was specified at the global or test level, Chainsaw will create a random one for the lifetime of the test.

"},{"location":"general/namespace/#cleanup","title":"Cleanup","text":"

As with any other resource, Chainsaw will clean up the namespace only if the namespace was created by Chainsaw.

If the namespace already exists when the test starts, Chainsaw will use it to run the test but won't delete it after the test terminates.

"},{"location":"general/namespace/#template","title":"Template","text":"

A namespace template can be provided at the global or test level.

This is useful if you want to make something specific with the namespace Chainsaw creates (add labels, add annotations, etc...).

Tip

A namespace template specified at the test level takes precedence over the namespace template specified at the global level.

"},{"location":"general/namespace/#namespace-injection","title":"Namespace injection","text":"

Because the name of the namespace is only known at runtime, depending on the resource being manipulated, Chainsaw will eventually inject the namespace name, except if:

"},{"location":"general/namespace/#example","title":"Example","text":"

The resource below is a namespaced one and has no namespace specified. Chainsaw will automatically inject the namespace name in it:

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\n  # there is no namespace configured and the resource\n  # is a namespaced one.\n  # Chainsaw will automatically inject the test namespace\ndata:\n  foo: bar\n
"},{"location":"general/outputs/","title":"Outputs","text":"

Operation outputs can be useful for communicating and reusing computation results across operations.

Chainsaw evaluates outputs after an operation has finished executing. The results of output evaluations are registered in the bindings and are made available for the following operations.

"},{"location":"general/outputs/#syntax","title":"Syntax","text":""},{"location":"general/outputs/#basic","title":"Basic","text":"

The test below illustrates output usage:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        # output is used to register a new `$OUTPUT` binding\n        outputs:\n        - name: OUTPUT\n          value: ($stdout)\n        content: echo $GREETINGS\n    - script:\n        # output from the previous operation is used\n        # to configure an evironment variable\n        env:\n        - name: INPUT\n          value: ($OUTPUT)\n        content: echo $INPUT\n
"},{"location":"general/outputs/#matching","title":"Matching","text":"

An output supports an optional match field. The match statement is used to conditionally assign the output binding.

The test below illustrates output with matching:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        # output is used to register a new `$OUTPUT` binding\n        outputs:\n          # by default, the `$OUTPUT` binding is assigned\n          # the content of the standard output\n        - name: OUTPUT\n          value: ($stdout)\n          # if the match statement evaluates to true,\n          # the `$OUTPUT` binding will be set to\n          # 'YES! chainsaw is awesome'\n        - match:\n            ($OUTPUT): hello chainsaw is awesome\n          name: OUTPUT\n          value: YES! chainsaw is awesome\n        content: echo $GREETINGS\n    - script:\n        # output from the previous operation is used\n        # to configure an evironment variable\n        env:\n        - name: INPUT\n          value: ($OUTPUT)\n        content: echo $INPUT\n
"},{"location":"general/outputs/#reference","title":"Reference","text":"

Browse the reference documentation to see the syntax details and where outputs can be declared.

"},{"location":"general/outputs/#templating","title":"Templating","text":"

Both name and value of an output can use templating.

"},{"location":"general/references/","title":"References","text":"

Chainsaw tests often need to reference resources. Including references in tests can be done in multiple ways.

"},{"location":"general/references/#inline","title":"Inline","text":"

One way to declare a resource is to do it directly inside the test definition:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n

This doesn't encourage file reuse but can be handy, especially when the resource definition is short or when the execution environment doesn't support file system access.

"},{"location":"general/references/#file-reference","title":"File reference","text":"

Another option is to use the file field. The file can be a specific file, or multiple files declared using a glob pattern:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n
"},{"location":"general/references/#url-reference","title":"URL reference","text":"

A third option is to use a URL. Chainsaw uses https://github.com/hashicorp/go-getter, it will download the content from the remote service and load it in the operation resources:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/step/configmap.yaml\n
"},{"location":"general/references/#cardinality","title":"Cardinality","text":"

When using file-based references, it is important to note that the referenced file(s) can declare multiple resources. Internally, Chainsaw will duplicate the operation once per resource.

This is important to keep this in mind, especially when working with bindings and outputs. Bindings and outputs will be evaluated for every operation instance.

"},{"location":"general/templating/","title":"Templating","text":"

Chainsaw simplifies dynamic configuration with native templating support.

In the past, users have created all sorts of hacks using tools like envsubst for dynamic substitution of env-variables. Those workarounds usually lack flexibility and introduce new problems like hiding the real resources from Chainsaw, preventing it from cleaning resources properly.

Templating in Chainsaw solves exactly this kind of problem.

"},{"location":"general/templating/#syntax","title":"Syntax","text":"

Tip

Resource templating is heavily based on bindings and uses JMESPath language.

"},{"location":"general/templating/#bindings","title":"Bindings","text":"

In the template below, we are using the $namespace binding at two different places, effectively injecting the ephemeral namespace name in the name and the data.foo fields:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - assert:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: ($namespace)\n        data:\n          foo: ($namespace)\n
"},{"location":"general/templating/#jmespath","title":"JMESPath","text":"

In the template below, we are using the JMESPath join function to create a unique resource name:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - apply:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: (join('-', [$namespace, 'cm']))\n        data:\n          foo: bar\n
"},{"location":"guides/kuttl-migration/","title":"Migration from KUTTL","text":""},{"location":"guides/kuttl-migration/#overview","title":"Overview","text":"

The chainsaw migrate kuttl tests and chainsaw migrate kuttl config commands are designed for the migration of KUTTL tests to Chainsaw.

Reference documentation

You can view the full command documentation here.

"},{"location":"guides/kuttl-migration/#examples","title":"Examples","text":""},{"location":"guides/kuttl-migration/#migrate-tests","title":"Migrate tests","text":"

The command below will migrate KUTTL tests to Chainsaw and overwrite original files with converted ones.

chainsaw migrate kuttl tests path/to/kuttl/tests --save --cleanup\n

This will generate a chainsaw-test.yaml for every KUTTL test discovered.

"},{"location":"guides/kuttl-migration/#migrate-configuration","title":"Migrate configuration","text":"

The command below will migrate a KUTTL test suite file to the corresponding Chainsaw Configuration.

chainsaw migrate kuttl config path/to/kuttl/testsuite --save --cleanup\n

This will generate a .chainsaw.yaml configuration file.

"},{"location":"guides/lint/","title":"Lint tests","text":""},{"location":"guides/lint/#overview","title":"Overview","text":"

Chainsaw comes with a lint command to detect ill-formated tests.

Reference documentation

You can view the full command documentation here.

"},{"location":"guides/lint/#usage","title":"Usage","text":"

To build the docs of a test, Chainsaw provides the chainsaw lint test -f path/to/chainsaw-test.yaml command.

chainsaw lint test -f - <<EOF\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: assertion-tree\nspec:\n  steps:\n  - try:\n    - assert:\n        file: assert.yaml\nEOF\n
Processing input...\nThe document is valid\n
"},{"location":"guides/test-docs/","title":"Building test docs","text":""},{"location":"guides/test-docs/#overview","title":"Overview","text":"

Chainsaw makes it simple to build the documentation of your tests.

As test suites grow, it becomes important to document what a test does and how it is supposed to work.

Going through the implementation of a test to understand its purpose is not an efficient strategy.

Reference documentation

You can view the full command documentation here.

"},{"location":"guides/test-docs/#usage","title":"Usage","text":"

To build the docs of a test, Chainsaw provides the chainsaw build docs command.

chainsaw build docs --test-dir path/to/chainsaw/tests\n

This will automatically discover tests and document steps and operations in try, catch and finally statements.

"},{"location":"guides/test-docs/#the-description-field","title":"The description field","text":"

Additionally, you can set the description field in:

Chainsaw will output them nicely in the built docs.

"},{"location":"guides/test-docs/#example","title":"Example","text":"

See below for an example test and the corresponding built docs.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: basic\nspec:\n  description: This is a very simple test that creates a configmap and checks the content is as expected.\n  steps:\n  - description: This steps applies the configmap in the cluster and checks the configmap content.\n    try:\n    - description: Create the configmap.\n      apply:\n        file: configmap.yaml\n    - description: Check the configmap content.\n      assert:\n        file: configmap-assert.yaml\n
"},{"location":"guides/test-docs/#test-basic","title":"Test: basic","text":"

This is a very simple test that creates a configmap and checks the content is as expected.

"},{"location":"guides/test-docs/#steps","title":"Steps","text":"# Name Try Catch Finally 1 step-1 2 0 0"},{"location":"guides/test-docs/#step-step-1","title":"Step: step-1","text":"

This step applies the configmap in the cluster and checks the configmap content.

"},{"location":"guides/test-docs/#try","title":"Try","text":"# Operation Description 1 apply Create the configmap. 2 assert Check the configmap content."},{"location":"operations/","title":"Operations","text":"

Chainsaw supports the following operations:

"},{"location":"operations/#helpers","title":"Helpers","text":"

Chainsaw also supports kubectl helpers.

"},{"location":"operations/#properties","title":"Properties","text":""},{"location":"operations/#action-unicity","title":"Action unicity","text":"

Every operation must consist of a single action.

While it is syntactically possible to create an operation with multiple actions, Chainsaw will verify and reject tests if operations containing multiple actions are found.

The reasoning behind this intentional choice is that it becomes harder to understand in which order actions will be executed when an operation consists of multiple actions. For this reason, operations consisting of multiple actions are not allowed.

"},{"location":"operations/#common-fields","title":"Common fields","text":""},{"location":"operations/#continue-on-error","title":"Continue on error","text":"

The continueOnError field determines whether a test step should continue executing or not if the operation fails (in any case the test will be marked as failed).

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n      # in case of error the test will be marked as failed\n      # but the step will not stop execution and will\n      # continue executing the following operations\n    - continueOnError: true\n      apply:\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/#description","title":"Description","text":"

All operations support a description field that can be used document your tests.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - description: Waits a couple of seconds\n      sleep:\n        duration: 3s\n
"},{"location":"operations/apply/","title":"Apply","text":"

The apply operation defines resources that should be applied to a Kubernetes cluster. If the resource does not exist yet it will be created, otherwise, it will be configured to match the provided configuration.

"},{"location":"operations/apply/#configuration","title":"Configuration","text":"

The full structure of the Apply is documented here.

"},{"location":"operations/apply/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/apply/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/step/configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/apply/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/assert/","title":"Assert","text":"

The assert operation allows you to specify conditions that should hold true for a successful test.

For example, after applying resources, you might want to ensure that a particular pod is running or a service is accessible.

"},{"location":"operations/assert/#configuration","title":"Configuration","text":"

The full structure of the Assert is documented here.

"},{"location":"operations/assert/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support | Operation checks support"},{"location":"operations/assert/#templating","title":"Templating","text":"

When working with assert and error operations, the content is already an assertion tree and therefore mostly represents a logical operation. An exception to this rule is for fields participating in the resource selection process.

For this reason, only elements used for looking up the resources from the cluster will be considered for templating. That is, apiVersion, kind, name, namespace and labels.

"},{"location":"operations/assert/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # use a specific file\n        file: ../resources/deployment-assert.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # use glob pattern\n        file: \"../assertions/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: Deployment\n          metadata:\n            name: foo\n          spec:\n            (replicas > 3): true\n
"},{"location":"operations/command/","title":"Command","text":"

The command operation provides a mean to execute a specific command during the test step.

Warning

Command arguments are not going through shell expansion.

It's crucial to consider potential differences in behavior, as Chainsaw may interpret them differently compared to regular shell environments.

"},{"location":"operations/command/#configuration","title":"Configuration","text":"

The full structure of the Command is documented here.

"},{"location":"operations/command/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/command/#kubeconfig","title":"KUBECONFIG","text":""},{"location":"operations/command/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - command:\n        entrypoint: echo\n        args:\n        - hello chainsaw\n
"},{"location":"operations/command/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - command:\n        entrypoint: echo\n        args:\n        - hello chainsaw\n        check:\n          # an error is expected, this will:\n          # - succeed if the operation failed\n          # - fail if the operation succeeded\n          ($error != null): true\n
"},{"location":"operations/create/","title":"Create","text":"

The create operation defines resources that should be created in a Kubernetes cluster.

If the resource to be created already exists in the cluster, the step will fail.

"},{"location":"operations/create/#configuration","title":"Configuration","text":"

The full structure of the Create is documented here.

"},{"location":"operations/create/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/create/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/create/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - create:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/delete/","title":"Delete","text":"

The delete operation defines resources that should be deleted from a Kubernetes cluster.

Warning

The propagation policy is forced to Background because some types default to Orphan (this is the case for unmanaged jobs for example) and we don't want to let dangling pods run in the cluster after cleanup.

"},{"location":"operations/delete/#configuration","title":"Configuration","text":"

The full structure of the Delete is documented here.

"},{"location":"operations/delete/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/delete/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - delete:\n        ref:\n          apiVersion: v1\n          kind: Pod\n          namespace: default\n          name: my-test-pod\n
"},{"location":"operations/delete/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - delete:\n        ref:\n          apiVersion: v1\n          kind: Pod\n          namespace: default\n          name: my-test-pod\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: Pod\n            metadata:\n              namespace: default\n              name: my-test-pod\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/error/","title":"Error","text":"

The error operation lets you define a set of expected errors for a test step. If any of these errors occur during the test, they are treated as expected outcomes. However, if an error that's not on this list occurs, it will be treated as a test failure.

"},{"location":"operations/error/#configuration","title":"Configuration","text":"

The full structure of the Error is documented here.

"},{"location":"operations/error/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support | Operation checks support"},{"location":"operations/error/#templating","title":"Templating","text":"

When working with assert and error operations, the content is already an assertion tree and therefore mostly represents a logical operation. An exception to this rule is for fields participating in the resource selection process.

For this reason, only elements used for looking up the resources from the cluster will be considered for templating. That is, apiVersion, kind, name, namespace and labels.

"},{"location":"operations/error/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # use a specific file\n        file: ../resources/deployment-error.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # use glob pattern\n        file: \"../errors/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # use an URL\n        file: https://raw.githubusercontent.com/user/repo/branch/path/to/deployment-error.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - error:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: Deployment\n          metadata:\n            name: foo\n          spec:\n            (replicas > 3): true\n
"},{"location":"operations/patch/","title":"Patch","text":"

The patch operation defines resources that should be modified in a Kubernetes cluster.

If the resource to be modified does not exist in the cluster, the step will fail.

"},{"location":"operations/patch/#configuration","title":"Configuration","text":"

The full structure of the Patch is documented here.

"},{"location":"operations/patch/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/patch/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/patch/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - patch:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/script/","title":"Script","text":"

The script operation provides a means to run a script during the test step.

"},{"location":"operations/script/#configuration","title":"Configuration","text":"

The full structure of the Script is documented here.

"},{"location":"operations/script/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/script/#kubeconfig","title":"KUBECONFIG","text":""},{"location":"operations/script/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: |\n          echo \"hello chainsaw\"\n
"},{"location":"operations/script/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: |\n          echo \"hello chainsaw\"\n        check:\n          # an error is expected, this will:\n          # - succeed if the operation failed\n          # - fail if the operation succeeded\n          ($error != null): true\n
"},{"location":"operations/sleep/","title":"Sleep","text":"

The sleep operation provides a means to sleep for a configured duration.

"},{"location":"operations/sleep/#configuration","title":"Configuration","text":"

The full structure of the Sleep is documented here.

"},{"location":"operations/sleep/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/sleep/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - sleep:\n        duration: 30s\n
"},{"location":"operations/update/","title":"Update","text":"

The update operation defines resources that should be updated in a Kubernetes cluster.

If the resource to be updated doesn't exist in the cluster, the step will fail.

"},{"location":"operations/update/#configuration","title":"Configuration","text":"

The full structure of the Update is documented here.

"},{"location":"operations/update/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/update/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        # use a specific file\n        file: my-configmap.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example-multi\nspec:\n  steps:\n  - try:\n    - update:\n        # use glob pattern\n        file: \"configs/*.yaml\"\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        # use an URL\n        file: https://raw.githubusercontent.com/kyverno/chainsaw/main/testdata/resource/valid.yaml\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        # specify resource inline\n        resource:\n          apiVersion: v1\n          kind: ConfigMap\n          metadata:\n            name: chainsaw-quick-start\n          data:\n            foo: bar\n
"},{"location":"operations/update/#operation-check","title":"Operation check","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - update:\n        file: my-configmap.yaml\n        expect:\n        - match:\n            # this check applies only if the match\n            # statement below evaluates to `true`\n            apiVersion: v1\n            kind: ConfigMap\n          check:\n            # an error is expected, this will:\n            # - succeed if the operation failed\n            # - fail if the operation succeeded\n            ($error != null): true\n
"},{"location":"operations/helpers/","title":"Kubectl helpers","text":"

Kubectl helpers are declarative versions of kubectl imperative commands.

"},{"location":"operations/helpers/#implementation","title":"Implementation","text":"

Helpers are implemented as syntactic sugars.

They are translated into their corresponding kubectl commands and executed as such.

"},{"location":"operations/helpers/#kubeconfig","title":"KUBECONFIG","text":""},{"location":"operations/helpers/#helpers","title":"Helpers","text":""},{"location":"operations/helpers/describe/","title":"Describe","text":"

Show details of a specific resource or group of resources.

Deprecated syntax

You can specify the resource directly instead of using apiVersion and kind.

This is a deprecated syntax though and will be removed in a future version.

"},{"location":"operations/helpers/describe/#configuration","title":"Configuration","text":"

The full structure of the Describe resource is documented here.

"},{"location":"operations/helpers/describe/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/describe/#clustered-resources","title":"Clustered resources","text":"

When used with a clustered resource, the namespace is ignored and is not added to the corresponding kubectl command.

"},{"location":"operations/helpers/describe/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/describe/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/describe/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        # describe all pods in the test namespace\n        apiVersion: v1\n        kind: Pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        # describe pods that have a name starting with the provided `my-pod`\n        name: my-pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        # describe pods in the namespace `foo`\n        namespace: foo\n
"},{"location":"operations/helpers/describe/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        # describe pods using a label selector query\n        selector: app=my-app\n
"},{"location":"operations/helpers/describe/#show-events","title":"Show events","text":"

Tip

By default, showEventsis true.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - describe:\n        apiVersion: v1\n        kind: Pod\n        showEvents: false\n
"},{"location":"operations/helpers/events/","title":"Events","text":"

Display one or many events.

"},{"location":"operations/helpers/events/#configuration","title":"Configuration","text":"

The full structure of the Events resource is documented here.

"},{"location":"operations/helpers/events/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/events/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/events/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/events/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get all events in the test namespace\n    - events: {}\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get events in a specific namespace\n    - events:\n        namespace: foo\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get event by name\n    - events:\n        name: my-event\n
"},{"location":"operations/helpers/events/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - events:\n        # get events using a label selector query\n        selector: app=my-app\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - events:\n        # get events using a label selector query\n        selector: app=my-app\n        namespace: foo\n
"},{"location":"operations/helpers/events/#format","title":"Format","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - events:\n        format: json\n
"},{"location":"operations/helpers/get/","title":"Get","text":"

Display one or many resources.

Deprecated syntax

You can specify the resource directly instead of using apiVersion and kind.

This is a deprecated syntax though and will be removed in a future version.

"},{"location":"operations/helpers/get/#configuration","title":"Configuration","text":"

The full structure of the Get resource is documented here.

"},{"location":"operations/helpers/get/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/get/#clustered-resources","title":"Clustered resources","text":"

When used with a clustered resource, the namespace is ignored and is not added to the corresponding kubectl command.

"},{"location":"operations/helpers/get/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/get/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/get/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # get all pods in the test namespace\n    - get:\n        apiVersion: v1\n        kind: Pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        # get pods that have a name starting with the provided `my-pod`\n        name: my-pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        # get pods in the namespace `foo`\n        namespace: foo\n
"},{"location":"operations/helpers/get/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        # get pods using a label selector query\n        selector: app=my-app\n
"},{"location":"operations/helpers/get/#format","title":"Format","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - get:\n        apiVersion: v1\n        kind: Pod\n        format: json\n
"},{"location":"operations/helpers/logs/","title":"Pods logs","text":"

Print the logs for a container in a pod or specified resource.

"},{"location":"operations/helpers/logs/#configuration","title":"Configuration","text":"

The full structure of the PodLogs resource is documented here.

"},{"location":"operations/helpers/logs/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/logs/#test-namespace","title":"Test namespace","text":"

Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/logs/#all-namespaces","title":"All namespaces","text":"

It is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/logs/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    # all pods in the test namespace\n    - podLogs: {}\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        # pods that have a name starting with the provided `my-pod`\n        name: my-pod\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        # pods in the namespace `foo`\n        namespace: foo\n
"},{"location":"operations/helpers/logs/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        # match pods using a label selector query\n        selector: app=my-app\n
"},{"location":"operations/helpers/logs/#tail","title":"Tail","text":"

Tip

By default, tail will be 10 when a label selector is used, and all if a pod name is specified.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        tail: 30\n
"},{"location":"operations/helpers/logs/#container","title":"Container","text":"

Tip

By default logs from all containers will be fetched.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try: ...\n    catch:\n    - podLogs:\n        container: nginx\n
"},{"location":"operations/helpers/wait/","title":"Wait","text":"

Wait for a specific condition on one or many resources.

Deprecated syntax

You can specify the resource directly instead of using apiVersion and kind.

This is a deprecated syntax though and will be removed in a future version.

"},{"location":"operations/helpers/wait/#configuration","title":"Configuration","text":"

The full structure of the Wait resource is documented here.

"},{"location":"operations/helpers/wait/#features","title":"Features","text":"Supported features Bindings support Outputs support Templating support Operation checks support"},{"location":"operations/helpers/wait/#clustered-resources","title":"Clustered resources","text":"

When used with a clustered resource, the namespace is ignored and is not added to the corresponding kubectl command.

"},{"location":"operations/helpers/wait/#all-resources","title":"All resources","text":"

If you don't specify a name or a selector, the wait operation will consider all resources.

"},{"location":"operations/helpers/wait/#test-namespace","title":"Test namespace","text":"

When used with a namespaced resource, Chainsaw will default the scope to the ephemeral test namespace.

"},{"location":"operations/helpers/wait/#all-namespaces","title":"All namespaces","text":"

When used with a namespaced resource, it is possible to consider all namespaces in the cluster by setting namespace: '*'.

"},{"location":"operations/helpers/wait/#examples","title":"Examples","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    # wait all pods are ready in the test namespace\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        # wait a specific pod is ready in the test namespace\n        name: my-pod\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n---\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        # wait all pods are ready in the namespace `foo`\n        namespace: foo\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n
"},{"location":"operations/helpers/wait/#label-selector","title":"Label selector","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        # match pods using a label selector query\n        selector: app=foo\n        timeout: 1m\n        for:\n          condition:\n            name: Ready\n            value: 'true'\n
"},{"location":"operations/helpers/wait/#deletion","title":"Deletion","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        timeout: 1m\n        for:\n          # wait for deletion\n          deletion: {}\n
"},{"location":"operations/helpers/wait/#format","title":"Format","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - wait:\n        apiVersion: v1\n        kind: Pod\n        format: json\n
"},{"location":"quick-start/","title":"Getting started","text":"

Chainsaw is a tool primarily developed to run end-to-end tests in Kubernetes clusters.

It is meant to test Kubernetes operators work as expected by running a sequence of steps and asserting various conditions.

"},{"location":"quick-start/#why-we-made-it","title":"Why we made it?","text":"

While developing Kyverno we need to run end-to-end tests to make sure our admission controller works as expected.

A typical Kyverno end-to-end test

Kyverno can validate, mutate and generate resources based on policies installed in a cluster and a typical test is:

  1. Create a policy
  2. Create a resource
  3. Check that Kyverno acted as expected
  4. Cleanup and move to the next test
"},{"location":"quick-start/#how-to-use-it","title":"How to use it?","text":"

Chainsaw is built with CI tools in mind - you only really need to download and execute it in your build script.

However, installing it on your local machine is entirely possible.

"},{"location":"quick-start/assertion-trees/","title":"Use assertions","text":"

Chainsaw allows declaring complex assertions with a simple and no-code approach, allowing assertions based on comparisons beyond simple equality, working with arrays, and other scenarios that could not be achieved before.

Tip

Under the hood, Chainsaw uses kyverno-json assertion trees. Refer to the assertion trees documentation for more details on the supported syntax.

"},{"location":"quick-start/assertion-trees/#basic-assertion","title":"Basic assertion","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            name: coredns\n            namespace: kube-system\n          spec:\n            replicas: 2\n

When asking Chainsaw to execute the assertion above, it will look for a deployment named coredns in the kube-system namespace and will compare the existing resource with the (partial) resource definition contained in the assertion.

In this specific case, if the field spec.replicas is set to 2 in the existing resource, the assertion will be considered valid. If it is not equal to 2 the assertion will be considered failed.

This is the most basic assertion Chainsaw can evaluate.

"},{"location":"quick-start/assertion-trees/#slightly-less-basic-assertion","title":"Slightly less basic assertion","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            labels:\n              k8s-app: kube-dns\n            namespace: kube-system\n          spec:\n            replicas: 2\n

This time we are not providing a resource name.

Chainsaw will look up all deployments with the k8s-app: kube-dns label in the kube-system namespace. The assertion will be considered valid if at least one deployment matches the (partial) resource definition contained in the assertion. If none match, the assertion will be considered failed.

Apart from the resource lookup process being a little bit more interesting, this kind of assertion is essentially the same as the previous one. Chainsaw is basically making a decision by comparing an actual and expected resource.

"},{"location":"quick-start/assertion-trees/#beyond-simple-equality","title":"Beyond simple equality","text":"

The assertion below will check that the number of replicas for a deployment is greater than 1 AND less than 4.

Chainsaw doesn't need to know the exact expected number of replicas. The (replicas > 1 && replicas < 4) expression will be evaluated until the result is true or the operation timeout expires (making the assertion fail).

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            name: coredns\n            namespace: kube-system\n          spec:\n            (replicas > `1` && replicas < `4`): true\n

Tip

To indicate that a key or value in the YAML document is an expression, simply place the element between parentheses:

"},{"location":"quick-start/assertion-trees/#working-with-arrays","title":"Working with arrays","text":"

Chainsaw query language makes it easy to assert on arrays. You can filter and transform arrays to select what you want to assert.

"},{"location":"quick-start/assertion-trees/#filtering","title":"Filtering","text":"

In the example below we are creating a resource, then we assert that a condition with type == 'Ready' exists and has a field matching status: 'True':

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            ...\n    - assert:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            # filter conditions array to keep elements where `type == 'Ready'`\n            # and assert there's a single element matching the filter\n            # and that this element status is `True`\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/assertion-trees/#iterating","title":"Iterating","text":"

Being able to filter arrays allows selecting the elements to be processed.

On top of that, Chainsaw allows iterating over array elements to validate each item separately.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - assert:\n        resource:\n          apiVersion: apps/v1\n          kind: Deployment\n          metadata:\n            labels:\n              k8s-app: kube-dns\n            namespace: kube-system\n          spec:\n            template:\n              spec:\n                # the `~` modifier tells Chainsaw to iterate over the array elements\n                ~.(containers):\n                  securityContext: {}\n

This assertion uses the ~ modifier and Chainsaw will evaluate descendants once per element in the array.

"},{"location":"quick-start/assertion-trees/#comprehensive-reporting","title":"Comprehensive reporting","text":"

Chainsaw offers detailed resource diffs upon assertion failures.

In the example below, the assertion failure message (metadata.annotations.foo: Invalid value: \"null\": Expected value: \"bar\") is augmented with a resource diff.

It provides a clear view of discrepancies between expected and actual resources and gives more context around the specific failure (we can easily identify the owner of the offending pod for example).

| 09:55:50 | deployment | step-1   | ASSERT    | RUN   | v1/Pod @ chainsaw-rare-liger/*\n| 09:56:20 | deployment | step-1   | ASSERT    | ERROR | v1/Pod @ chainsaw-rare-liger/*\n    === ERROR\n    ---------------------------------------------------\n    v1/Pod/chainsaw-rare-liger/example-5477b4ff8c-tnhd9\n    ---------------------------------------------------\n    * metadata.annotations.foo: Invalid value: \"null\": Expected value: \"bar\"\n\n    --- expected\n    +++ actual\n    @@ -1,10 +1,16 @@\n      apiVersion: v1\n      kind: Pod\n      metadata:\n    -  annotations:\n    -    foo: bar\n        labels:\n          app: nginx\n    +  name: example-5477b4ff8c-tnhd9\n        namespace: chainsaw-rare-liger\n    +  ownerReferences:\n    +  - apiVersion: apps/v1\n    +    blockOwnerDeletion: true\n    +    controller: true\n    +    kind: ReplicaSet\n    +    name: example-5477b4ff8c\n    +    uid: 118abe16-ec42-4894-83db-64479c4aac6f\n      spec: {}\n| 09:56:20 | deployment | step-1   | TRY       | DONE  |\n
"},{"location":"quick-start/assertion-trees/#next-step","title":"Next step","text":"

To continue our exploration of the main Chainsaw features, let's look at bindings and resource templating next.

"},{"location":"quick-start/bindings/","title":"Use bindings","text":"

You can think of bindings as a side context where you can store and retrieve data based on keys.

This is particularly useful when some data is only known at runtime. For example, to pass data from one operation to another, to implement resource templating, to fetch data from an external system, etc.

Chainsaw offers some built-in bindings you can directly use in your tests but you can also create your own bindings if needed.

"},{"location":"quick-start/bindings/#inheritance","title":"Inheritance","text":"

Bindings can be configured at the test, step or operation level.

All bindings configured at a given level are automatically inherited in child levels.

JMESPath

Chainsaw uses the JMESPath language, and bindings are implemented using lexical scoping.

"},{"location":"quick-start/bindings/#immutability","title":"Immutability","text":"

Bindings are immutable. This means two bindings can have the same name without overwriting each other.

When a binding is registered it potentially hides other bindings with the same name.

When this binding goes out of scope, previously registered bindings with the same name become visible again.

"},{"location":"quick-start/bindings/#built-in-bindings","title":"Built-in bindings","text":"

The $namespace binding is a good example of a built-in binding provided by Chainsaw. It contains the name of the ephemeral namespace used to execute a test (by default Chainsaw will create an ephemeral namespace for each test).

In the operation below, we are assigning the value of the $namespace binding to an environment variable, and echo it in a script:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        env:\n          # assign the value of the `$namespace` binding\n          # to the environment variable `FOO`\n        - name: FOO\n          value: ($namespace)\n        content: echo $FOO\n
"},{"location":"quick-start/bindings/#custom-bindings","title":"Custom bindings","text":"

On top of built-in bindings, you can also create your own ones, combine bindings together, call JMESPath functions using bindings as arguments, etc.

In the test below we create custom bindings at different levels in the test, combine them by calling the join function, assign the result to an environment variable, and echo it in a script:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # bindings can be declared at the test level\n  bindings:\n  - name: chainsaw\n    value: chainsaw\n  steps:\n    # bindings can also be declared at the step level\n  - bindings:\n    - name: hello\n      value: hello\n    try:\n    - script:\n        # bindings can also be declared at the operation level\n        bindings:\n        - name: awesome\n          value: awesome\n        env:\n          # combined bindings together using the `join` functions and\n          # assign the result to the GREETINGS environment variable\n        - name: GREETINGS\n          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))\n        content: echo $GREETINGS\n
"},{"location":"quick-start/bindings/#next-step","title":"Next step","text":"

Let's see how bindings can be useful with resource templating.

"},{"location":"quick-start/cleanup/","title":"Control your cleanup","text":"

Unless configured differently, by default Chainsaw will automatically remove the resources it created after a test finishes.

Cleanup happens in reverse order of creation (created last, cleaned up first). This is important, especially when the controller being tested makes use of finalizers.

Overriding cleanup timeout

Note that Chainsaw performs a blocking deletion, that is, it will wait until the resource is not present anymore in the cluster before proceeding with the next resource cleanup.

"},{"location":"quick-start/cleanup/#timeout","title":"Timeout","text":"

A global cleanup timeout can be defined at the configuration level or using command line flags.

It can also be overridden on a per-test or per-step basis but not at the operation level.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  timeouts:\n    # cleanup timeout at the test level\n    cleanup: 30s\n  steps:\n  - timeouts:\n      # cleanup timeout at the step level\n      cleanup: 2m\n    try: ...\n
"},{"location":"quick-start/cleanup/#automatic-cleanup","title":"Automatic cleanup","text":"

After a test, every resource created by Chainsaw will be automatically deleted. This applies to create and apply operations.

In the logs below we can see Chainsaw deletes the previously created resource:

    | 15:21:29 | quick-start | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-cute-cod\n    | 15:21:29 | quick-start | step-1   | TRY       | RUN   |\n    | 15:21:29 | quick-start | step-1   | APPLY     | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | CREATE    | OK    | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | APPLY     | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | ASSERT    | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | ASSERT    | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | TRY       | DONE  |\n    === step cleanup process start ===\n    | 15:21:29 | quick-start | step-1   | CLEANUP   | RUN   |\n    | 15:21:29 | quick-start | step-1   | DELETE    | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | DELETE    | OK    | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | DELETE    | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start\n    | 15:21:29 | quick-start | step-1   | CLEANUP   | DONE  |\n    === step cleanup process end ===\n    === test cleanup process start ===\n    | 15:21:29 | quick-start | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-cute-cod\n    | 15:21:29 | quick-start | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-cute-cod\n    | 15:21:34 | quick-start | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-cute-cod\n    === test cleanup process end ===\n
"},{"location":"quick-start/cleanup/#manual-cleanup","title":"Manual cleanup","text":"

Under certain circumstances, automatic cleanup is not enough and we want to execute custom operations.

Chainsaw allows registering cleanup operations that will be run after automatic cleanup. Custom cleanup operations live at the test step level:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # this step will create a local cluster\n  - try:\n    - script:\n        timeout: 1m\n        content: |\n          kind create cluster --name dynamic --kubeconfig ./dynamic\n    # at cleanup time, we want to delete the local cluster we created\n    # and remove the associated kubeconfig\n    cleanup:\n    - script:\n        content: |\n          kind delete cluster --name dynamic\n    - script:\n        content: |\n          rm -f ./dynamic\n
"},{"location":"quick-start/cleanup/#next-step","title":"Next step","text":"

At this point, we covered the main Chainsaw features.

Look at the next steps section to find out what to do next.

"},{"location":"quick-start/completion/","title":"Shell completion","text":"

Once installed, use chainsaw completion command to generate and register the autocompletion script for the specified shell.

Supported shells are:

"},{"location":"quick-start/first-test/","title":"Create a test","text":"

To create a Chainsaw test all you need to do is to create one (or more) YAML file(s).

The recommended approach is to create one folder per test, with a chainsaw-test.yaml file containing one (or more) test definition(s). The test definition can reference other files in the same folder or anywhere else on the file system as needed.

Tip

While chainsaw supports other syntaxes, we strongly recommend the explicit approach.

"},{"location":"quick-start/first-test/#what-is-a-test","title":"What is a test?","text":"

To put it simply, a test can be represented as an ordered sequence of test steps.

In turn, a test step can be represented as an ordered sequence of operations.

When one of the operations fails the test is considered failed.

If all operations succeed the test is considered successful.

"},{"location":"quick-start/first-test/#lets-write-our-first-test","title":"Let's write our first test","text":"

For this quick start, we will create a (very simple) Test with one step and two operations:

  1. Create a ConfigMap from a manifest
  2. Verify the ConfigMap was created and contains the expected data

Follow the instructions below to create the folder and files defining our first test.

"},{"location":"quick-start/first-test/#create-a-test-folder","title":"Create a test folder","text":"
# create test folder\nmkdir chainsaw-quick-start\n\n# enter test folder\ncd chainsaw-quick-start\n
"},{"location":"quick-start/first-test/#create-a-configmap-manifest","title":"Create a ConfigMap manifest","text":"
# create a ConfigMap\ncat > configmap.yaml << EOF\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  foo: bar\nEOF\n
"},{"location":"quick-start/first-test/#create-a-test-manifest","title":"Create a test manifest","text":"

By default, Chainsaw will look for a file named chainsaw-test.yaml in every folder.

# create test file\ncat > chainsaw-test.yaml << EOF\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: quick-start\nspec:\n  steps:\n  - try:\n    # first operation: create the config map\n    - apply:\n        # file is relative to the test folder\n        file: configmap.yaml\n    # second operation: verify the config map exists and contains the expected data\n    - assert:\n        # file is relative to the test folder\n        file: configmap.yaml\nEOF\n
"},{"location":"quick-start/first-test/#next-step","title":"Next step","text":"

Now we have created our first test, you can continue to the next section to execute it.

"},{"location":"quick-start/install/","title":"Installation","text":"

You can install the pre-compiled binary (in several ways), compile from sources, or run with Docker.

We also provide a GitHub action to easily install Chainsaw in your workflows.

"},{"location":"quick-start/install/#install-the-pre-compiled-binary","title":"Install the pre-compiled binary","text":""},{"location":"quick-start/install/#homebrew-tap","title":"Homebrew tap","text":"

add tap:

brew tap kyverno/chainsaw https://github.com/kyverno/chainsaw\n

install chainsaw:

brew install kyverno/chainsaw/chainsaw\n

Don't forget to specify the tap name

Homebrew core already has a tool named chainsaw.

Be sure that you specify the tap name when installing to install the right tool.

"},{"location":"quick-start/install/#manually","title":"Manually","text":"

Download the pre-compiled binaries for your system from the releases page and copy them to the desired location.

"},{"location":"quick-start/install/#install-using-go-install","title":"Install using go install","text":"

You can install with go install with:

go install github.com/kyverno/chainsaw@latest\n
"},{"location":"quick-start/install/#run-with-docker","title":"Run with Docker","text":"

Chainsaw is also available as a Docker image which you can pull and run:

docker pull ghcr.io/kyverno/chainsaw:<version>\n

Warning

Since Chainsaw relies on files for its operation (like test definitions), you will need to bind mount the necessary directories when running it via Docker.

docker run --rm                             \\\n    -v ./testdata/e2e/:/chainsaw/           \\\n    -v ${HOME}/.kube/:/etc/kubeconfig/      \\\n    -e KUBECONFIG=/etc/kubeconfig/config    \\\n    --network=host                          \\\n    ghcr.io/kyverno/chainsaw:<version>      \\\n    test /chainsaw --config /chainsaw/config.yaml\n
"},{"location":"quick-start/install/#compile-from-sources","title":"Compile from sources","text":"

clone:

git clone https://github.com/kyverno/chainsaw.git\n

build the binaries:

cd chainsaw\ngo mod tidy\nmake build\n

verify it works:

./chainsaw version\n
"},{"location":"quick-start/install/#install-using-nix-package","title":"Install using Nix Package","text":"

To install kyverno-chainsaw, refer to the documentation.

"},{"location":"quick-start/install/#on-nixos","title":"On NixOS","text":"
nix-env -iA nixos.kyverno-chainsaw\n
"},{"location":"quick-start/install/#on-non-nixos","title":"On Non-NixOS","text":"
nix-env -iA nixpkgs.kyverno-chainsaw\n

Warning

Using nix-env permanently modifies a local profile of installed packages. This must be updated and maintained by the user in the same way as with a traditional package manager, foregoing many of the benefits that make Nix uniquely powerful. Using nix-shell or a NixOS configuration is recommended instead.

"},{"location":"quick-start/install/#using-nixos-configuration","title":"Using NixOS Configuration","text":"

Add the following Nix code to your NixOS Configuration, usually located in /etc/nixos/configuration.nix :

environment.systemPackages = [\n  pkgs.kyverno-chainsaw\n];\n
"},{"location":"quick-start/install/#using-nix-shell","title":"Using nix-shell","text":"

A nix-shell will temporarily modify your $PATH environment variable. This can be used to try a piece of software before deciding to permanently install it. Use the following command to install kyverno-chainsaw :

nix-shell -p kyverno-chainsaw\n
"},{"location":"quick-start/install/#github-action","title":"GitHub action","text":"

A GitHub action is available to install Chainsaw in your workflows. See the GitHub action dedicated documentation.

"},{"location":"quick-start/next-steps/","title":"Next steps","text":"

We covered the main features of Chainsaw in this Getting started sections.

While this should help you understand Chainsaw better, there are a lot of other things Chainsaw can do for you.

Tip

If there's anything you would like to be improved, please reach out, we will be happy to discuss and improve as much as we can.

To continue exploring the capabilities of Chainsaw:

"},{"location":"quick-start/operation-outputs/","title":"Use operation outputs","text":"

Operation outputs can be useful for communicating and reusing computation results across operations.

"},{"location":"quick-start/operation-outputs/#lifetime-of-outputs","title":"Lifetime of outputs","text":"

Once an output has been added to the bindings context, this binding will be available to all following operations in the same step.

Currently, outputs do not cross the step boundaries.

"},{"location":"quick-start/operation-outputs/#matching","title":"Matching","text":"

An output supports an optional match field. The match is used to conditionally create a binding.

In the case of applying a file, for example, the file may contain multiple resources. The match can be used to select the resource to use for creating the binding.

"},{"location":"quick-start/operation-outputs/#load-an-existing-resource","title":"Load an existing resource","text":"

The example below invokes a kubectl command to get a configmap from the cluster in json format.

The json output is then parsed and added to the $cm binding and the next operation performs an assertion on it by reading the binding instead of querying the cluster.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - script:\n        content: kubectl get cm quick-start -n $NAMESPACE -o json\n        outputs:\n          # parse stdout json output and bind the result to `$cm`\n        - name: cm\n          value: (json_parse($stdout))\n    - assert:\n        resource:\n          ($cm):\n            metadata:\n              (uid != null): true\n
"},{"location":"quick-start/operation-outputs/#match-a-resource","title":"Match a resource","text":"

The example below applies resources from a file.

When the resource being applied is a configmap, we bind the resource to an output to print its UID in the next operation.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        file: ./resources.yaml\n        outputs:\n          # match the configmap resource and bind it to `$cm`\n        - match:\n            apiVersion: v1\n            kind: ConfigMap\n          name: cm\n          value: (@)\n    - script:\n        env:\n        - name: UID\n          value: ($cm.metadata.uid)\n        content: echo $UID\n
"},{"location":"quick-start/operation-outputs/#next-step","title":"Next step","text":"

In the next section, we will look at the three main elements of a test step, the try, catch and finally blocks.

"},{"location":"quick-start/resource-templating/","title":"Use resource templating","text":"

Chainsaw simplifies dynamic resource configuration with native resource templating support.

Sometimes things we need to create resources or assertions are only known at runtime.

In the past, users have created all sorts of hacks using tools like envsubst for dynamic substitution of env-variables. Those workarounds usually lack flexibility and introduce new problems like hiding the real resources from Chainsaw, preventing it from cleaning resources properly.

Tip

Resource templating is heavily based on bindings and uses JMESPath language.

"},{"location":"quick-start/resource-templating/#leverage-bindings","title":"Leverage bindings","text":"

In the template below, we are using the $namespace binding at two different places, effectively injecting the ephemeral namespace name in the name and the data.foo fields:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - assert:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: ($namespace)\n        data:\n          foo: ($namespace)\n
"},{"location":"quick-start/resource-templating/#leverage-jmespath","title":"Leverage JMESPath","text":"

In the template below, we are using the JMESPath join function to create a unique resource name:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - apply:\n      resource:\n        apiVersion: v1\n        kind: ConfigMap\n        metadata:\n          name: (join('-', [$namespace, 'cm']))\n        data:\n          foo: bar\n
"},{"location":"quick-start/resource-templating/#next-step","title":"Next step","text":"

Combining bindings and templates with operation outputs allows even more flexibility to pass arbitrary data from one operation to another.

"},{"location":"quick-start/resources/","title":"Additional resources","text":"

Resources, blog posts and videos talking about Chainsaw:

"},{"location":"quick-start/resources/#chainsaw-video-review","title":"Chainsaw video review","text":"

If you haven't watched the video below yet, we strongly recommend watching it to discover Chainsaw!

"},{"location":"quick-start/run-tests/","title":"Run tests","text":"

After installing chainsaw and writing tests, the next natural step is to run Chainsaw to execute the tests.

"},{"location":"quick-start/run-tests/#create-a-local-cluster","title":"Create a local cluster","text":"

To use Chainsaw you will need a Kubernetes cluster, Chainsaw won't create one for you.

Not a cluster management tool

We consider this is not the responsibility of Chainsaw to manage clusters. There are plenty of solutions to create and manage local clusters that will do that better than Chainsaw.

The command below will create a local cluster using kind. Use the tool of your choice or directly jump to the next section if you already have a KUBECONFIG configured and pointing to a valid cluster.

# create cluster\nkind create cluster --image \"kindest/node:v1.29.4\"\n
"},{"location":"quick-start/run-tests/#run-chainsaw","title":"Run Chainsaw","text":"

Now you can run the chainsaw test command.

> chainsaw test\n\nVersion: (devel)\nLoading default configuration...\n- Using test file: chainsaw-test.yaml\n- TestDirs [.]\n- SkipDelete false\n- FailFast false\n- ReportFormat ''\n- ReportName ''\n- Namespace ''\n- FullName false\n- IncludeTestRegex ''\n- ExcludeTestRegex ''\n- ApplyTimeout 5s\n- AssertTimeout 30s\n- CleanupTimeout 30s\n- DeleteTimeout 15s\n- ErrorTimeout 30s\n- ExecTimeout 5s\nLoading tests...\n- quick-start (.)\nRunning tests...\n=== RUN   chainsaw\n=== PAUSE chainsaw\n=== CONT  chainsaw\n=== RUN   chainsaw/quick-start\n=== PAUSE chainsaw/quick-start\n=== CONT  chainsaw/quick-start\n    | 10:44:26 | quick-start | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-immense-jay\n    | 10:44:26 | quick-start | step-1   | TRY       | RUN   |\n    | 10:44:26 | quick-start | step-1   | APPLY     | RUN   | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | CREATE    | OK    | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | APPLY     | DONE  | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | ASSERT    | RUN   | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | ASSERT    | DONE  | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | step-1   | TRY       | DONE  |\n    | 10:44:26 | quick-start | @cleanup | DELETE    | RUN   | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | @cleanup | DELETE    | OK    | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | @cleanup | DELETE    | DONE  | v1/ConfigMap @ chainsaw-immense-jay/chainsaw-quick-start\n    | 10:44:26 | quick-start | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-immense-jay\n    | 10:44:26 | quick-start | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-immense-jay\n    | 10:44:31 | quick-start | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-immense-jay\n--- PASS: chainsaw (0.00s)\n    --- PASS: chainsaw/quick-start (5.25s)\nPASS\nTests Summary...\n- Passed  tests 1\n- Failed  tests 0\n- Skipped tests 0\nDone.\n

Tip

Chainsaw expects a path to the test folder and will discover tests by analyzing files recursively. When no path is provided Chainsaw will use the current path by default (.).

"},{"location":"quick-start/run-tests/#next-step","title":"Next step","text":"

The test above demonstrates the most basic usage of Chainsaw. In the next sections, we will look at the main features that make Chainsaw a very unique tool.

"},{"location":"quick-start/timeouts/","title":"Control your timeouts","text":"

Timeouts in Chainsaw are specified per type of operation. This is handy because the timeout varies greatly depending on the nature of an operation.

For example, applying a manifest in a cluster is expected to be reasonably fast, while validating a resource can be a long operation.

"},{"location":"quick-start/timeouts/#inheritance","title":"Inheritance","text":"

Timeouts can be configured globally and at the test, step or individual operation level.

All timeouts configured at a given level are automatically inherited in child levels. When looking up a timeout, the most specific one takes precedence over the others.

Info

To learn more about timeouts and how to configure global values, see the timeouts configuration page.

"},{"location":"quick-start/timeouts/#at-the-test-level","title":"At the test level","text":"

When a timeout is configured at the test level it will apply to all operations and steps in the test, unless overridden at a more specific level.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # timeouts configured at the test level will apply to all operations and steps\n  # unless overriden at the step level and/or individual operation level\n  timeouts:\n    apply: 5s\n    assert: 1m\n    # ...\n  steps:\n  - try:\n    - apply:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            # ...\n    - assert:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/timeouts/#at-the-step-level","title":"At the step level","text":"

When a timeout is configured at the step level it will apply to all operations in the step, unless overridden at a more specific level.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # timeouts configured at the step level will apply to all operations\n    # in the step unless overriden at the individual operation level\n  - timeouts:\n      apply: 5s\n      # ...\n    try:\n    - apply:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            # ...\n    # timeouts configured at the step level will apply to all operations\n    # in the step unless overriden at the individual operation level\n  - timeouts:\n      assert: 1m\n      # ...\n    try:\n    - assert:\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/timeouts/#at-the-operation-level","title":"At the operation level","text":"

When a timeout is configured at the operation level, it takes precedence over all timeouts configured at upper levels.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # timeout configured at the operation level takes precedence\n        # over timeouts configured at upper levels\n        timeout: 5s\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          spec:\n            storage:\n              secret:\n                name: minio\n                type: s3\n            # ...\n    - assert:\n        # timeout configured at the operation level takes precedence\n        # over timeouts configured at upper levels\n        timeout: 1m\n        resource:\n          apiVersion: tempo.grafana.com/v1alpha1\n          kind: TempoStack\n          metadata:\n            name: simplest\n          status:\n            (conditions[?type == 'Ready']):\n            - status: 'True'\n
"},{"location":"quick-start/timeouts/#next-step","title":"Next step","text":"

In the next section, we will see how Chainsaw manages cleanup.

"},{"location":"quick-start/try-catch/","title":"Use try, catch and finally","text":"

A test step is made of 3 main blocks used to determine the actions Chainsaw will perform when executing the step, depending on operations outcome.

Operations defined in the try block are executed first, then:

Note

Note that all operations coming from the catch or finally blocks are executed. If one operation fails, Chainsaw will mark the test as failed and continue executing with the next operation.

"},{"location":"quick-start/try-catch/#cleanup","title":"Cleanup","text":"

At the end of a test, Chainsaw automatically cleans up the resources created during the test (cleanup is done in the opposite order of creation).

All operations from the catch and finally blocks are executed before the cleanup process kicks in. This order allows analyzing the resources that potentially caused the step failure before they are deleted.

"},{"location":"quick-start/try-catch/#catch","title":"Catch","text":"

Operations in a catch block are executed only when the step is considered failed.

This is particularly useful to collect additional information to help understand what caused the failure.

In the example below, the test contains a catch block to collect events in the cluster when an operation fails in the step.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n  - try:\n    - apply:\n        # ...\n    - assert:\n        # ...\n    # collect events in the `catch` block\n    # will be executed only if an operation failed\n    catch:\n    - events: {}\n
"},{"location":"quick-start/try-catch/#finally","title":"Finally","text":"

Operations in a finally block will always execute regardless of the success or failure of the test step.

This is particularly useful to perform manual cleanup.

In the example below we create a local cluster in a script operation. The cluster deletion script is added to the finally block, guaranteeing the cluster will be deleted regardless of the test outcome.

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # create a local cluster\n  - try:\n    - script:\n        timeout: 1m\n        content: |\n          kind create cluster --name dynamic --kubeconfig ./dynamic\n    - apply:\n        # ...\n    - assert:\n        # ...\n    # add cluster deletion script in the `finally` block\n    # to guarantee the cluster will be deleted after the test\n    finally:\n    - script:\n        content: |\n          kind delete cluster --name dynamic\n    - script:\n        content: |\n          rm -f ./dynamic\n
"},{"location":"quick-start/try-catch/#next-step","title":"Next step","text":"

Every operation in a test must be executed in a timely fashion. In the next section, we will see how you can control your timeouts.

"},{"location":"reference/","title":"Reference documentation","text":"

Info

Select an item in the navigation menu to browse a specific page.

"},{"location":"reference/builtins/","title":"Built-in bindings","text":"

Chainsaw provides built-in bindings listed below.

"},{"location":"reference/builtins/#common","title":"Common","text":"Name Purpose Type $values Values provided when invoking chainsaw with --values flag any $namespace Name of the current test namespace string $client Kubernetes client chainsaw is connected to (if not running with --no-cluster) object $config Kubernetes client config chainsaw is connected to (if not running with --no-cluster) object"},{"location":"reference/builtins/#in-tests","title":"In tests","text":"Name Purpose Type $test.id Current test id int

Note

"},{"location":"reference/builtins/#in-steps","title":"In steps","text":"Name Purpose Type $step.id Current step id int

Note

"},{"location":"reference/builtins/#in-operations","title":"In operations","text":"Name Purpose Type $operation.id Current operation id int $operation.resourceId Current resource id int

Note

"},{"location":"reference/builtins/#in-checks-and-outputs","title":"In checks and outputs","text":"Name Purpose Type @ The state of the resource (if any) at the end of the operation any $error The error message (if any) at the end of the operation string $stdout The content of the standard console output (if any) at the end of the operation string $stderr The content of the standard console error output (if any) at the end of the operation string

Note

"},{"location":"reference/json-schemas/","title":"JSON schemas","text":"

JSON schemas for Chainsaw are available:

They can be used to enable validation and autocompletion in your IDE.

"},{"location":"reference/json-schemas/#vs-code","title":"VS code","text":"

In VS code, simply add a comment on top of your YAML resources.

"},{"location":"reference/json-schemas/#test","title":"Test","text":"
# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/chainsaw/main/.schemas/json/test-chainsaw-v1alpha1.json\napiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: basic\nspec:\n  steps:\n  - try:\n    - apply:\n        file: configmap.yaml\n    - assert:\n        file: configmap-assert.yaml\n
"},{"location":"reference/json-schemas/#configuration","title":"Configuration","text":"
# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/chainsaw/main/.schemas/json/configuration-chainsaw-v1alpha2.json\napiVersion: chainsaw.kyverno.io/v1alpha2\nkind: Configuration\nmetadata:\n  name: example\nspec:\n  timeouts:\n    apply: 45s\n    assert: 20s\n    cleanup: 45s\n    delete: 25s\n    error: 10s\n    exec: 45s\n  cleanup:\n    skipDelete: false\n  execution:\n    failFast: true\n    parallel: 4\n
"},{"location":"reference/json-schemas/#exporting-schemas","title":"Exporting schemas","text":"

Chainsaw can also export JSON schemas locally if you don't want to reference them from GitHub:

chainsaw export schemas <local path>\n

See chainsaw export schemas command documentation for more details.

"},{"location":"reference/apis/chainsaw.v1alpha1/","title":"chainsaw (v1alpha1)","text":"

Package v1alpha1 contains API Schema definitions for the v1alpha1 API group.

"},{"location":"reference/apis/chainsaw.v1alpha1/#resource-types","title":"Resource Types","text":""},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Configuration","title":"Configuration","text":"

Configuration is the resource that contains the configuration used to run tests.

Field Type Required Inline Description apiVersion string chainsaw.kyverno.io/v1alpha1 kind string Configuration metadata meta/v1.ObjectMeta

Standard object's metadata.

spec ConfigurationSpec

Configuration spec.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Test","title":"Test","text":"

Test is the resource that contains a test definition.

Field Type Required Inline Description apiVersion string chainsaw.kyverno.io/v1alpha1 kind string Test metadata meta/v1.ObjectMeta

Standard object's metadata.

spec TestSpec

Test spec.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Apply","title":"Apply","text":"

Appears in:

Apply represents a set of configurations or resources that should be applied during testing.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the resources to be applied.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Assert","title":"Assert","text":"

Appears in:

Assert represents a test condition that is expected to hold true during the testing process.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrCheck FileRefOrCheck

FileRefOrAssert provides a reference to the assertion.

template bool

Template determines whether resources should be considered for templating.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Binding","title":"Binding","text":"

Appears in:

Binding represents a key/value set as a binding in an executing test.

Field Type Required Inline Description name string

Name the name of the binding.

value policy/v1alpha1.Any

Value value of the binding.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Catch","title":"Catch","text":"

Appears in:

Catch defines actions to be executed on failure.

Field Type Required Inline Description description string

Description contains a description of the operation.

podLogs PodLogs

PodLogs determines the pod logs collector to execute.

events Events

Events determines the events collector to execute.

describe Describe

Describe determines the resource describe collector to execute.

wait Wait

Wait determines the resource wait collector to execute.

get Get

Get determines the resource get collector to execute.

delete Delete

Delete represents a deletion operation.

command Command

Command defines a command to run.

script Script

Script defines a script to run.

sleep Sleep

Sleep defines zzzz.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Cluster","title":"Cluster","text":"

Appears in:

Cluster defines cluster config and context.

Field Type Required Inline Description kubeconfig string

Kubeconfig is the path to the referenced file.

context string

Context is the name of the context to use.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Command","title":"Command","text":"

Appears in:

Command describes a command to run as a part of a test step.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

env []Binding

Env defines additional environment variables.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

entrypoint string

Entrypoint is the command entry point to run.

args []string

Args is the command arguments.

skipLogOutput bool

SkipLogOutput removes the output from the command. Useful for sensitive logs or to reduce noise.

check policy/v1alpha1.Any

Check is an assertion tree to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Condition","title":"Condition","text":"

Appears in:

Condition represents parameters for waiting on a specific condition of a resource.

Field Type Required Inline Description name string

Name defines the specific condition to wait for, e.g., \"Available\", \"Ready\".

value string

Value defines the specific condition status to wait for, e.g., \"True\", \"False\".

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ConfigurationSpec","title":"ConfigurationSpec","text":"

Appears in:

ConfigurationSpec contains the configuration used to run tests.

Field Type Required Inline Description timeouts Timeouts

Global timeouts configuration. Applies to all tests/test steps if not overridden.

skipDelete bool

If set, do not delete the resources after running the tests (implies SkipClusterDelete).

template bool

Template determines whether resources should be considered for templating.

failFast bool

FailFast determines whether the test should stop upon encountering the first failure.

parallel int

The maximum number of tests to run at once.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation.

reportFormat ReportFormatType

ReportFormat determines test report format (JSON reportPath string

ReportPath defines the path.

reportName string

ReportName defines the name of report to create. It defaults to \"chainsaw-report\".

namespace string

Namespace defines the namespace to use for tests. If not specified, every test will execute in a random ephemeral namespace unless the namespace is overridden in a the test spec.

namespaceTemplate policy/v1alpha1.Any

NamespaceTemplate defines a template to create the test namespace.

fullName bool

FullName makes use of the full test case folder path instead of the folder name.

excludeTestRegex string

ExcludeTestRegex is used to exclude tests based on a regular expression.

includeTestRegex string

IncludeTestRegex is used to include tests based on a regular expression.

repeatCount int

RepeatCount indicates how many times the tests should be executed.

testFile string

TestFile is the name of the file containing the test to run. If no extension is provided, chainsaw will try with .yaml first and .yml if needed.

forceTerminationGracePeriod meta/v1.Duration

ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments.

delayBeforeCleanup meta/v1.Duration

DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts.

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

catch []Catch

Catch defines what the tests steps will execute when an error happens. This will be combined with catch handlers defined at the test and step levels.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Create","title":"Create","text":"

Appears in:

Create represents a set of resources that should be created. If a resource already exists in the cluster it will fail.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the file containing the resources to be created.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Delete","title":"Delete","text":"

Appears in:

Delete is a reference to an object that should be deleted

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

template bool

Template determines whether resources should be considered for templating.

ref ObjectReference

ObjectReference determines objects to be deleted.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation. Overrides the deletion propagation policy set in the Configuration, the Test and the TestStep.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Deletion","title":"Deletion","text":"

Appears in:

Deletion represents parameters for waiting on a resource's deletion.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Describe","title":"Describe","text":"

Appears in:

Describe defines how to describe resources.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ResourceReference ResourceReference

ResourceReference referenced resource type.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

showEvents bool

Show Events indicates whether to include related events.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Error","title":"Error","text":"

Appears in:

Error represents an anticipated error condition that may arise during testing. Instead of treating such an error as a test failure, it acknowledges it as expected.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrCheck FileRefOrCheck

FileRefOrAssert provides a reference to the expected error.

template bool

Template determines whether resources should be considered for templating.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Events","title":"Events","text":"

Appears in:

Events defines how to collect events.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

format Format

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Expectation","title":"Expectation","text":"

Appears in:

Expectation represents a check to be applied on the result of an operation with a match filter to determine if the verification should be considered.

Field Type Required Inline Description match policy/v1alpha1.Any

Match defines the matching statement.

check policy/v1alpha1.Any

Check defines the verification statement.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-FileRef","title":"FileRef","text":"

Appears in:

FileRef represents a file reference.

Field Type Required Inline Description file string

File is the path to the referenced file. This can be a direct path to a file or an expression that matches multiple files, such as \"manifest/*.yaml\" for all YAML files within the \"manifest\" directory.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-FileRefOrCheck","title":"FileRefOrCheck","text":"

Appears in:

FileRefOrCheck represents a file reference or resource.

Field Type Required Inline Description FileRef FileRef

FileRef provides a reference to the file containing the resources to be applied.

resource policy/v1alpha1.Any

Check provides a check used in assertions.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-FileRefOrResource","title":"FileRefOrResource","text":"

Appears in:

FileRefOrResource represents a file reference or resource.

Field Type Required Inline Description FileRef FileRef

FileRef provides a reference to the file containing the resources to be applied.

resource meta/v1/unstructured.Unstructured

Resource provides a resource to be applied.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Finally","title":"Finally","text":"

Appears in:

Finally defines actions to be executed at the end of a test.

Field Type Required Inline Description description string

Description contains a description of the operation.

podLogs PodLogs

PodLogs determines the pod logs collector to execute.

events Events

Events determines the events collector to execute.

describe Describe

Describe determines the resource describe collector to execute.

wait Wait

Wait determines the resource wait collector to execute.

get Get

Get determines the resource get collector to execute.

delete Delete

Delete represents a deletion operation.

command Command

Command defines a command to run.

script Script

Script defines a script to run.

sleep Sleep

Sleep defines zzzz.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-For","title":"For","text":"

Appears in:

For specifies the condition to wait for.

Field Type Required Inline Description deletion Deletion

Deletion specifies parameters for waiting on a resource's deletion.

condition Condition

Condition specifies the condition to wait for.

jsonPath JsonPath

JsonPath specifies the json path condition to wait for.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Format","title":"Format","text":"

(Alias of string)

Appears in:

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Get","title":"Get","text":"

Appears in:

Get defines how to get resources.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ResourceReference ResourceReference

ResourceReference referenced resource type.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

format Format

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-JsonPath","title":"JsonPath","text":"

Appears in:

JsonPath represents parameters for waiting on a json path of a resource.

Field Type Required Inline Description path string

Path defines the json path to wait for, e.g. '{.status.phase}'.

value string

Value defines the expected value to wait for, e.g., \"Running\".

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectLabelsSelector","title":"ObjectLabelsSelector","text":"

Appears in:

ObjectLabelsSelector represents a strategy to select objects. For a single object name and namespace are used to identify the object. For multiple objects use selector.

Field Type Required Inline Description namespace string

Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/

name string

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

selector string

Selector defines labels selector.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectReference","title":"ObjectReference","text":"

Appears in:

ObjectReference represents one or more objects with a specific apiVersion and kind. For a single object name and namespace are used to identify the object. For multiple objects use labels.

Field Type Required Inline Description ObjectType ObjectType

ObjectType determines the type of referenced objects.

ObjectSelector ObjectSelector

ObjectSelector determines the selection process of referenced objects.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectSelector","title":"ObjectSelector","text":"

Appears in:

ObjectSelector represents a strategy to select objects. For a single object name and namespace are used to identify the object. For multiple objects use labels.

Field Type Required Inline Description namespace string

Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/

name string

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

labels map[string]string

Label selector to match objects to delete

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ObjectType","title":"ObjectType","text":"

Appears in:

ObjectType represents a specific apiVersion and kind.

Field Type Required Inline Description apiVersion string

API version of the referent.

kind string

Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Operation","title":"Operation","text":"

Appears in:

Operation defines a single operation, only one action is permitted for a given operation.

Field Type Required Inline Description OperationBase OperationBase

OperationBase defines common elements to all operations.

apply Apply

Apply represents resources that should be applied for this test step. This can include things like configuration settings or any other resources that need to be available during the test.

assert Assert

Assert represents an assertion to be made. It checks whether the conditions specified in the assertion hold true.

command Command

Command defines a command to run.

create Create

Create represents a creation operation.

delete Delete

Delete represents a deletion operation.

error Error

Error represents the expected errors for this test step. If any of these errors occur, the test will consider them as expected; otherwise, they will be treated as test failures.

patch Patch

Patch represents a patch operation.

script Script

Script defines a script to run.

sleep Sleep

Sleep defines zzzz.

update Update

Update represents an update operation.

wait Wait

Wait determines the resource wait collector to execute.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-OperationBase","title":"OperationBase","text":"

Appears in:

OperationBase defines common elements to all operations.

Field Type Required Inline Description description string

Description contains a description of the operation.

continueOnError bool

ContinueOnError determines whether a test should continue or not in case the operation was not successful. Even if the test continues executing, it will still be reported as failed.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Output","title":"Output","text":"

Appears in:

Output represents an output binding with a match to determine if the binding must be considered or not.

Field Type Required Inline Description Binding Binding

Binding determines the binding to create when the match succeeds.

match policy/v1alpha1.Any

Match defines the matching statement.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Patch","title":"Patch","text":"

Appears in:

Patch represents a set of resources that should be patched. If a resource doesn't exist yet in the cluster it will fail.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the file containing the resources to be patched.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-PodLogs","title":"PodLogs","text":"

Appears in:

PodLogs defines how to collect pod logs.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

container string

Container in pod to get logs from else --all-containers is used.

tail int

Tail is the number of last lines to collect from pods. If omitted or zero, then the default is 10 if you use a selector, or -1 (all) if you use a pod name. This matches default behavior of kubectl logs.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ReportFormatType","title":"ReportFormatType","text":"

(Alias of string)

Appears in:

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-ResourceReference","title":"ResourceReference","text":"

Appears in:

ResourceReference represents a resource (API), it can be represented with a resource or a kind. Optionally an apiVersion can be specified.

Field Type Required Inline Description apiVersion string

API version of the referent.

kind string

Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

resource string

Resource name of the referent.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Script","title":"Script","text":"

Appears in:

Script describes a script to run as a part of a test step.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

env []Binding

Env defines additional environment variables.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

content string

Content defines a shell script (run with \"sh -c ...\").

skipLogOutput bool

SkipLogOutput removes the output from the command. Useful for sensitive logs or to reduce noise.

check policy/v1alpha1.Any

Check is an assertion tree to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Sleep","title":"Sleep","text":"

Appears in:

Sleep represents a duration while nothing happens.

Field Type Required Inline Description duration meta/v1.Duration

Duration is the delay used for sleeping.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-TestSpec","title":"TestSpec","text":"

Appears in:

TestSpec contains the test spec.

Field Type Required Inline Description description string

Description contains a description of the test.

timeouts Timeouts

Timeouts for the test. Overrides the global timeouts set in the Configuration on a per operation basis.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

skip bool

Skip determines whether the test should skipped.

concurrent bool

Concurrent determines whether the test should run concurrently with other tests.

skipDelete bool

SkipDelete determines whether the resources created by the test should be deleted after the test is executed.

template bool

Template determines whether resources should be considered for templating.

namespace string

Namespace determines whether the test should run in a random ephemeral namespace or not.

namespaceTemplate policy/v1alpha1.Any

NamespaceTemplate defines a template to create the test namespace.

bindings []Binding

Bindings defines additional binding key/values.

steps []TestStep

Steps defining the test.

catch []Catch

Catch defines what the steps will execute when an error happens. This will be combined with catch handlers defined at the step level.

forceTerminationGracePeriod meta/v1.Duration

ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments.

delayBeforeCleanup meta/v1.Duration

DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation. Overrides the deletion propagation policy set in the Configuration.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-TestStep","title":"TestStep","text":"

Appears in:

TestStep contains the test step definition used in a test spec.

Field Type Required Inline Description name string

Name of the step.

TestStepSpec TestStepSpec

TestStepSpec of the step.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-TestStepSpec","title":"TestStepSpec","text":"

Appears in:

TestStepSpec defines the desired state and behavior for each test step.

Field Type Required Inline Description description string

Description contains a description of the test step.

timeouts Timeouts

Timeouts for the test step. Overrides the global timeouts set in the Configuration and the timeouts eventually set in the Test.

deletionPropagationPolicy meta/v1.DeletionPropagation

DeletionPropagationPolicy decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation. Overrides the deletion propagation policy set in both the Configuration and the Test.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

skipDelete bool

SkipDelete determines whether the resources created by the step should be deleted after the test step is executed.

template bool

Template determines whether resources should be considered for templating.

bindings []Binding

Bindings defines additional binding key/values.

try []Operation

Try defines what the step will try to execute.

catch []Catch

Catch defines what the step will execute when an error happens.

finally []Finally

Finally defines what the step will execute after the step is terminated.

cleanup []Finally

Cleanup defines what will be executed after the test is terminated.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Timeouts","title":"Timeouts","text":"

Appears in:

Timeouts contains timeouts per operation.

Field Type Required Inline Description apply meta/v1.Duration

Apply defines the timeout for the apply operation

assert meta/v1.Duration

Assert defines the timeout for the assert operation

cleanup meta/v1.Duration

Cleanup defines the timeout for the cleanup operation

delete meta/v1.Duration

Delete defines the timeout for the delete operation

error meta/v1.Duration

Error defines the timeout for the error operation

exec meta/v1.Duration

Exec defines the timeout for exec operations

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Update","title":"Update","text":"

Appears in:

Update represents a set of resources that should be updated. If a resource does not exist in the cluster it will fail.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Overrides the global timeout set in the Configuration.

bindings []Binding

Bindings defines additional binding key/values.

outputs []Output

Outputs defines output bindings.

cluster string

Cluster defines the target cluster (default cluster will be used if not specified and/or overridden).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

FileRefOrResource FileRefOrResource

FileRefOrResource provides a reference to the file containing the resources to be created.

template bool

Template determines whether resources should be considered for templating.

dryRun bool

DryRun determines whether the file should be applied in dry run mode.

expect []Expectation

Expect defines a list of matched checks to validate the operation outcome.

"},{"location":"reference/apis/chainsaw.v1alpha1/#chainsaw-kyverno-io-v1alpha1-Wait","title":"Wait","text":"

Appears in:

Wait specifies how to perform wait operations on resources.

Field Type Required Inline Description timeout meta/v1.Duration

Timeout for the operation. Specifies how long to wait for the condition to be met before timing out.

cluster string

Cluster defines the target cluster where the wait operation will be performed (default cluster will be used if not specified).

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

ResourceReference ResourceReference

ResourceReference referenced resource type.

ObjectLabelsSelector ObjectLabelsSelector

ObjectLabelsSelector determines the selection process of referenced objects.

for For

For specifies the condition to wait for.

format Format

Format determines the output format (json or yaml).

"},{"location":"reference/apis/chainsaw.v1alpha2/","title":"chainsaw (v1alpha2)","text":"

Package v1alpha2 contains API Schema definitions for the v1alpha2 API group.

"},{"location":"reference/apis/chainsaw.v1alpha2/#resource-types","title":"Resource Types","text":""},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Configuration","title":"Configuration","text":"

Configuration is the resource that contains the configuration used to run tests.

Field Type Required Inline Description apiVersion string chainsaw.kyverno.io/v1alpha2 kind string Configuration metadata meta/v1.ObjectMeta

Standard object's metadata.

spec ConfigurationSpec

Configuration spec.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Cleanup","title":"Cleanup","text":"

Appears in:

Cleanup options contain the configuration used for cleaning up resources.

Field Type Required Inline Description skipDelete bool

If set, do not delete the resources after running a test.

delayBeforeCleanup meta/v1.Duration

DelayBeforeCleanup adds a delay between the time a test ends and the time cleanup starts.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-ConfigurationSpec","title":"ConfigurationSpec","text":"

Appears in:

ConfigurationSpec contains the configuration used to run tests.

Field Type Required Inline Description cleanup Cleanup

Cleanup contains cleanup configuration.

clusters map[string]Cluster

Clusters holds a registry to clusters to support multi-cluster tests.

deletion DeletionOptions

Deletion contains the global deletion configuration.

discovery Discovery

Discovery contains tests discovery configuration.

error ErrorOptions

Error contains the global error configuration.

execution Execution

Execution contains tests execution configuration.

namespace Namespace

Namespace contains properties for the namespace to use for tests.

report Report

Report contains properties for the report.

templating Templating

Templating contains the templating config.

timeouts Timeouts

Global timeouts configuration. Applies to all tests/test steps if not overridden.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-DeletionOptions","title":"DeletionOptions","text":"

Appears in:

DeletionOptions contains the configuration used for deleting resources.

Field Type Required Inline Description propagation meta/v1.DeletionPropagation

Propagation decides if a deletion will propagate to the dependents of the object, and how the garbage collector will handle the propagation.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Discovery","title":"Discovery","text":"

Appears in:

Discovery options contain the discovery configuration used when discovering tests in folders.

Field Type Required Inline Description excludeTestRegex string

ExcludeTestRegex is used to exclude tests based on a regular expression.

includeTestRegex string

IncludeTestRegex is used to include tests based on a regular expression.

testFile string

TestFile is the name of the file containing the test to run. If no extension is provided, chainsaw will try with .yaml first and .yml if needed.

fullName bool

FullName makes use of the full test case folder path instead of the folder name.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-ErrorOptions","title":"ErrorOptions","text":"

Appears in:

ErrorOptions contains the global error configuration.

Field Type Required Inline Description catch []Catch

Catch defines what the tests steps will execute when an error happens. This will be combined with catch handlers defined at the test and step levels.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Execution","title":"Execution","text":"

Appears in:

Execution options determine how tests are run.

Field Type Required Inline Description failFast bool

FailFast determines whether the test should stop upon encountering the first failure.

parallel int

The maximum number of tests to run at once.

repeatCount int

RepeatCount indicates how many times the tests should be executed.

forceTerminationGracePeriod meta/v1.Duration

ForceTerminationGracePeriod forces the termination grace period on pods, statefulsets, daemonsets and deployments.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Namespace","title":"Namespace","text":"

Appears in:

Namespace options contain the configuration used to allocate a namespace for each test.

Field Type Required Inline Description name string

Name defines the namespace to use for tests. If not specified, every test will execute in a random ephemeral namespace unless the namespace is overridden in a the test spec.

template policy/v1alpha1.Any

Template defines a template to create the test namespace.

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Report","title":"Report","text":"

Appears in:

Report options contain the configuration used for reporting.

Field Type Required Inline Description format ReportFormatType

ReportFormat determines test report format (JSON path string

ReportPath defines the path.

name string

ReportName defines the name of report to create. It defaults to \"chainsaw-report\".

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-ReportFormatType","title":"ReportFormatType","text":"

(Alias of string)

Appears in:

"},{"location":"reference/apis/chainsaw.v1alpha2/#chainsaw-kyverno-io-v1alpha2-Templating","title":"Templating","text":"

Appears in:

Templating options contain the templating configuration.

Field Type Required Inline Description enabled bool

Enabled determines whether resources should be considered for templating.

"},{"location":"reference/commands/chainsaw/","title":"chainsaw","text":""},{"location":"reference/commands/chainsaw/#chainsaw","title":"chainsaw","text":"

Stronger tool for e2e testing

chainsaw [flags]\n
"},{"location":"reference/commands/chainsaw/#options","title":"Options","text":"
  -h, --help   help for chainsaw\n
"},{"location":"reference/commands/chainsaw/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_assert/","title":"chainsaw assert","text":""},{"location":"reference/commands/chainsaw_assert/#chainsaw-assert","title":"chainsaw assert","text":"

Evaluate assertion

chainsaw assert [flags] [FILE]\n
"},{"location":"reference/commands/chainsaw_assert/#options","title":"Options","text":"
      --clustered                           Defines if the resource is clustered (only applies when resource is loaded from a file)\n  -f, --file string                         Path to the file to assert or '-' to read from stdin\n  -h, --help                                help for assert\n      --kube-as string                      Username to impersonate for the operation\n      --kube-as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.\n      --kube-as-uid string                  UID to impersonate for the operation\n      --kube-certificate-authority string   Path to a cert file for the certificate authority\n      --kube-client-certificate string      Path to a client certificate file for TLS\n      --kube-client-key string              Path to a client key file for TLS\n      --kube-cluster string                 The name of the kubeconfig cluster to use\n      --kube-context string                 The name of the kubeconfig context to use\n      --kube-disable-compression            If true, opt-out of response compression for all requests to the server\n      --kube-insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n  -n, --kube-namespace string               If present, the namespace scope for this CLI request\n      --kube-password string                Password for basic authentication to the API server\n      --kube-proxy-url string               If provided, this URL will be used to connect via proxy\n      --kube-request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default \"0\")\n      --kube-server string                  The address and port of the Kubernetes API server\n      --kube-tls-server-name string         If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used.\n      --kube-token string                   Bearer token for authentication to the API server\n      --kube-user string                    The name of the kubeconfig user to use\n      --kube-username string                Username for basic authentication to the API server\n      --namespace string                    Namespace to use (default \"default\")\n      --no-color                            Removes output colors\n  -r, --resource string                     Path to the file containing the resource\n      --timeout duration                    The assert timeout to use (default 30s)\n
"},{"location":"reference/commands/chainsaw_assert/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_build/","title":"chainsaw build","text":""},{"location":"reference/commands/chainsaw_build/#chainsaw-build","title":"chainsaw build","text":"

Build commands

chainsaw build [flags]\n
"},{"location":"reference/commands/chainsaw_build/#options","title":"Options","text":"
  -h, --help   help for build\n
"},{"location":"reference/commands/chainsaw_build/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_build_docs/","title":"chainsaw build docs","text":""},{"location":"reference/commands/chainsaw_build_docs/#chainsaw-build-docs","title":"chainsaw build docs","text":"

Build tests documentation

chainsaw build docs [flags]\n
"},{"location":"reference/commands/chainsaw_build_docs/#options","title":"Options","text":"
      --catalog string         Path to the built test catalog file\n  -h, --help                   help for docs\n      --readme-file string     Name of the built docs file (default \"README.md\")\n      --test-dir stringArray   Directories containing test cases to run\n      --test-file string       Name of the test file (default \"chainsaw-test\")\n
"},{"location":"reference/commands/chainsaw_build_docs/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion/","title":"chainsaw completion","text":""},{"location":"reference/commands/chainsaw_completion/#chainsaw-completion","title":"chainsaw completion","text":"

Generate the autocompletion script for the specified shell

"},{"location":"reference/commands/chainsaw_completion/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for chainsaw for the specified shell. See each sub-command's help for details on how to use the generated script.

"},{"location":"reference/commands/chainsaw_completion/#options","title":"Options","text":"
  -h, --help   help for completion\n
"},{"location":"reference/commands/chainsaw_completion/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_bash/","title":"chainsaw completion bash","text":""},{"location":"reference/commands/chainsaw_completion_bash/#chainsaw-completion-bash","title":"chainsaw completion bash","text":"

Generate the autocompletion script for bash

"},{"location":"reference/commands/chainsaw_completion_bash/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(chainsaw completion bash)\n

To load completions for every new session, execute once:

"},{"location":"reference/commands/chainsaw_completion_bash/#linux","title":"Linux:","text":"
chainsaw completion bash > /etc/bash_completion.d/chainsaw\n
"},{"location":"reference/commands/chainsaw_completion_bash/#macos","title":"macOS:","text":"
chainsaw completion bash > $(brew --prefix)/etc/bash_completion.d/chainsaw\n

You will need to start a new shell for this setup to take effect.

chainsaw completion bash\n
"},{"location":"reference/commands/chainsaw_completion_bash/#options","title":"Options","text":"
  -h, --help              help for bash\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_bash/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_fish/","title":"chainsaw completion fish","text":""},{"location":"reference/commands/chainsaw_completion_fish/#chainsaw-completion-fish","title":"chainsaw completion fish","text":"

Generate the autocompletion script for fish

"},{"location":"reference/commands/chainsaw_completion_fish/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

chainsaw completion fish | source\n

To load completions for every new session, execute once:

chainsaw completion fish > ~/.config/fish/completions/chainsaw.fish\n

You will need to start a new shell for this setup to take effect.

chainsaw completion fish [flags]\n
"},{"location":"reference/commands/chainsaw_completion_fish/#options","title":"Options","text":"
  -h, --help              help for fish\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_fish/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_powershell/","title":"chainsaw completion powershell","text":""},{"location":"reference/commands/chainsaw_completion_powershell/#chainsaw-completion-powershell","title":"chainsaw completion powershell","text":"

Generate the autocompletion script for powershell

"},{"location":"reference/commands/chainsaw_completion_powershell/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for powershell.

To load completions in your current shell session:

chainsaw completion powershell | Out-String | Invoke-Expression\n

To load completions for every new session, add the output of the above command to your powershell profile.

chainsaw completion powershell [flags]\n
"},{"location":"reference/commands/chainsaw_completion_powershell/#options","title":"Options","text":"
  -h, --help              help for powershell\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_powershell/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_completion_zsh/","title":"chainsaw completion zsh","text":""},{"location":"reference/commands/chainsaw_completion_zsh/#chainsaw-completion-zsh","title":"chainsaw completion zsh","text":"

Generate the autocompletion script for zsh

"},{"location":"reference/commands/chainsaw_completion_zsh/#synopsis","title":"Synopsis","text":"

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo \"autoload -U compinit; compinit\" >> ~/.zshrc\n

To load completions in your current shell session:

source <(chainsaw completion zsh)\n

To load completions for every new session, execute once:

"},{"location":"reference/commands/chainsaw_completion_zsh/#linux","title":"Linux:","text":"
chainsaw completion zsh > \"${fpath[1]}/_chainsaw\"\n
"},{"location":"reference/commands/chainsaw_completion_zsh/#macos","title":"macOS:","text":"
chainsaw completion zsh > $(brew --prefix)/share/zsh/site-functions/_chainsaw\n

You will need to start a new shell for this setup to take effect.

chainsaw completion zsh [flags]\n
"},{"location":"reference/commands/chainsaw_completion_zsh/#options","title":"Options","text":"
  -h, --help              help for zsh\n      --no-descriptions   disable completion descriptions\n
"},{"location":"reference/commands/chainsaw_completion_zsh/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_create/","title":"chainsaw create","text":""},{"location":"reference/commands/chainsaw_create/#chainsaw-create","title":"chainsaw create","text":"

Create Chainsaw resources

chainsaw create [flags]\n
"},{"location":"reference/commands/chainsaw_create/#options","title":"Options","text":"
  -h, --help   help for create\n
"},{"location":"reference/commands/chainsaw_create/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_create_test/","title":"chainsaw create test","text":""},{"location":"reference/commands/chainsaw_create_test/#chainsaw-create-test","title":"chainsaw create test","text":"

Create a Chainsaw test

chainsaw create test [flags]\n
"},{"location":"reference/commands/chainsaw_create_test/#options","title":"Options","text":"
      --description   If set, adds description when applicable (default true)\n      --force         If set, existing test will be deleted if needed\n  -h, --help          help for test\n      --save          If set, created test will be saved\n
"},{"location":"reference/commands/chainsaw_create_test/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_docs/","title":"chainsaw docs","text":""},{"location":"reference/commands/chainsaw_docs/#chainsaw-docs","title":"chainsaw docs","text":"

Generate reference documentation

chainsaw docs [flags]\n
"},{"location":"reference/commands/chainsaw_docs/#options","title":"Options","text":"
      --autogenTag      Determines if the generated docs should contain a timestamp (default true)\n  -h, --help            help for docs\n  -o, --output string   Output path (default \".\")\n      --website         Website version\n
"},{"location":"reference/commands/chainsaw_docs/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_export/","title":"chainsaw export","text":""},{"location":"reference/commands/chainsaw_export/#chainsaw-export","title":"chainsaw export","text":"

Export commands

chainsaw export [flags]\n
"},{"location":"reference/commands/chainsaw_export/#options","title":"Options","text":"
  -h, --help   help for export\n
"},{"location":"reference/commands/chainsaw_export/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_export_schemas/","title":"chainsaw export schemas","text":""},{"location":"reference/commands/chainsaw_export_schemas/#chainsaw-export-schemas","title":"chainsaw export schemas","text":"

Export JSON schemas

chainsaw export schemas [flags]\n
"},{"location":"reference/commands/chainsaw_export_schemas/#options","title":"Options","text":"
  -h, --help   help for schemas\n
"},{"location":"reference/commands/chainsaw_export_schemas/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_lint/","title":"chainsaw lint","text":""},{"location":"reference/commands/chainsaw_lint/#chainsaw-lint","title":"chainsaw lint","text":"

Lint a file or read from standard input

"},{"location":"reference/commands/chainsaw_lint/#synopsis","title":"Synopsis","text":"

Use chainsaw lint to lint a specific file or read from standard input for either test or configuration.

chainsaw lint [test|configuration] [flags]\n
"},{"location":"reference/commands/chainsaw_lint/#options","title":"Options","text":"
  -f, --file string   Specify the file to lint or '-' for standard input\n  -h, --help          help for lint\n
"},{"location":"reference/commands/chainsaw_lint/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate/","title":"chainsaw migrate","text":""},{"location":"reference/commands/chainsaw_migrate/#chainsaw-migrate","title":"chainsaw migrate","text":"

Migrate resources to Chainsaw

chainsaw migrate [flags]\n
"},{"location":"reference/commands/chainsaw_migrate/#options","title":"Options","text":"
  -h, --help   help for migrate\n
"},{"location":"reference/commands/chainsaw_migrate/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl/","title":"chainsaw migrate kuttl","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl/#chainsaw-migrate-kuttl","title":"chainsaw migrate kuttl","text":"

Migrate KUTTL resources to Chainsaw

chainsaw migrate kuttl [flags]\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl/#options","title":"Options","text":"
  -h, --help   help for kuttl\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_config/","title":"chainsaw migrate kuttl config","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_config/#chainsaw-migrate-kuttl-config","title":"chainsaw migrate kuttl config","text":"

Migrate KUTTL config to Chainsaw

chainsaw migrate kuttl config [flags]\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_config/#options","title":"Options","text":"
      --cleanup   If set, delete converted files\n  -h, --help      help for config\n      --save      If set, converted files will be saved\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_config/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/","title":"chainsaw migrate kuttl tests","text":""},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/#chainsaw-migrate-kuttl-tests","title":"chainsaw migrate kuttl tests","text":"

Migrate KUTTL tests to Chainsaw

chainsaw migrate kuttl tests [flags]\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/#options","title":"Options","text":"
      --cleanup   If set, delete converted files\n  -h, --help      help for tests\n      --save      If set, converted files will be saved\n
"},{"location":"reference/commands/chainsaw_migrate_kuttl_tests/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_test/","title":"chainsaw test","text":""},{"location":"reference/commands/chainsaw_test/#chainsaw-test","title":"chainsaw test","text":"

Run tests

chainsaw test [flags]... [test directories]...\n
"},{"location":"reference/commands/chainsaw_test/#options","title":"Options","text":"
      --apply-timeout duration                    The apply timeout to use as default for configuration (default 5s)\n      --assert-timeout duration                   The assert timeout to use as default for configuration (default 30s)\n      --cleanup-delay duration                    Adds a delay between the time a test ends and the time cleanup starts\n      --cleanup-timeout duration                  The cleanup timeout to use as default for configuration (default 30s)\n      --cluster strings                           Register cluster (format <cluster name>=<kubeconfig path>:[context name])\n      --config string                             Chainsaw configuration file\n      --delete-timeout duration                   The delete timeout to use as default for configuration (default 15s)\n      --deletion-propagation-policy string        The deletion propagation policy (Foreground|Background|Orphan) (default \"Background\")\n      --error-timeout duration                    The error timeout to use as default for configuration (default 30s)\n      --exclude-test-regex string                 Regular expression to exclude tests\n      --exec-timeout duration                     The exec timeout to use as default for configuration (default 5s)\n      --fail-fast                                 Stop the test upon encountering the first failure\n      --force-termination-grace-period duration   If specified, overrides termination grace periods in applicable resources\n      --full-name                                 Use full test case folder path instead of folder name\n  -h, --help                                      help for test\n      --include-test-regex string                 Regular expression to include tests\n      --kube-as string                            Username to impersonate for the operation\n      --kube-as-group stringArray                 Group to impersonate for the operation, this flag can be repeated to specify multiple groups.\n      --kube-as-uid string                        UID to impersonate for the operation\n      --kube-certificate-authority string         Path to a cert file for the certificate authority\n      --kube-client-certificate string            Path to a client certificate file for TLS\n      --kube-client-key string                    Path to a client key file for TLS\n      --kube-cluster string                       The name of the kubeconfig cluster to use\n      --kube-context string                       The name of the kubeconfig context to use\n      --kube-disable-compression                  If true, opt-out of response compression for all requests to the server\n      --kube-insecure-skip-tls-verify             If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n  -n, --kube-namespace string                     If present, the namespace scope for this CLI request\n      --kube-password string                      Password for basic authentication to the API server\n      --kube-proxy-url string                     If provided, this URL will be used to connect via proxy\n      --kube-request-timeout string               The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default \"0\")\n      --kube-server string                        The address and port of the Kubernetes API server\n      --kube-tls-server-name string               If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used.\n      --kube-token string                         Bearer token for authentication to the API server\n      --kube-user string                          The name of the kubeconfig user to use\n      --kube-username string                      Username for basic authentication to the API server\n      --namespace string                          Namespace to use for tests\n      --no-cluster                                Runs without cluster\n      --no-color                                  Removes output colors\n      --parallel int                              The maximum number of tests to run at once\n      --pause-on-failure                          Pause test execution failure (implies no concurrency)\n      --repeat-count int                          Number of times to repeat each test (default 1)\n      --report-format string                      Test report format (JSON|XML|nil)\n      --report-name string                        The name of the report to create (default \"chainsaw-report\")\n      --report-path string                        The path of the report to create\n      --selector strings                          Selector (label query) to filter on\n      --skip-delete                               If set, do not delete the resources after running the tests\n      --template                                  If set, resources will be considered for templating (default true)\n      --test-dir strings                          Directories containing test cases to run\n      --test-file string                          Name of the test file (default \"chainsaw-test\")\n      --values strings                            Values passed to the tests\n
"},{"location":"reference/commands/chainsaw_test/#see-also","title":"SEE ALSO","text":""},{"location":"reference/commands/chainsaw_version/","title":"chainsaw version","text":""},{"location":"reference/commands/chainsaw_version/#chainsaw-version","title":"chainsaw version","text":"

Print the version informations

chainsaw version [flags]\n
"},{"location":"reference/commands/chainsaw_version/#options","title":"Options","text":"
  -h, --help   help for version\n
"},{"location":"reference/commands/chainsaw_version/#see-also","title":"SEE ALSO","text":""},{"location":"reference/jp/functions/","title":"Functions","text":"

Experimental functions

Experimental functions are denoted by the x_ prefix.

These are functions that are subject to signature change in a future version.

"},{"location":"reference/jp/functions/#built-in-functions","title":"built-in functions","text":"Name Signature abs abs(number) avg avg(array[number]) ceil ceil(number) contains contains(array|string, any) ends_with ends_with(string, string) find_first find_first(string, string, number, number) find_last find_last(string, string, number, number) floor floor(number) from_items from_items(array[array]) group_by group_by(array, expref) items items(object) join join(string, array[string]) keys keys(object) length length(string|array|object) lower lower(string) map map(expref, array) max max(array[number]|array[string]) max_by max_by(array, expref) merge merge(object) min min(array[number]|array[string]) min_by min_by(array, expref) not_null not_null(any) pad_left pad_left(string, number, string) pad_right pad_right(string, number, string) replace replace(string, string, string, number) reverse reverse(array|string) sort sort(array[string]|array[number]) sort_by sort_by(array, expref) split split(string, string, number) starts_with starts_with(string, string) sum sum(array[number]) to_array to_array(any) to_number to_number(any) to_string to_string(any) trim trim(string, string) trim_left trim_left(string, string) trim_right trim_right(string, string) type type(any) upper upper(string) values values(object) zip zip(array, array)"},{"location":"reference/jp/functions/#kyverno-json-functions","title":"kyverno-json functions","text":"Name Signature at at(array, any) concat concat(string, string) json_parse json_parse(string) wildcard wildcard(string, string)"},{"location":"reference/jp/functions/#kyverno-functions","title":"kyverno functions","text":"Name Signature compare compare(string, string) equal_fold equal_fold(string, string) replace replace(string, string, string, number) replace_all replace_all(string, string, string) to_upper to_upper(string) to_lower to_lower(string) trim trim(string, string) trim_prefix trim_prefix(string, string) split split(string, string) regex_replace_all regex_replace_all(string, string|number, string|number) regex_replace_all_literal regex_replace_all_literal(string, string|number, string|number) regex_match regex_match(string, string|number) pattern_match pattern_match(string, string|number) label_match label_match(object, object) to_boolean to_boolean(string) add add(any, any) sum sum(array) subtract subtract(any, any) multiply multiply(any, any) divide divide(any, any) modulo modulo(any, any) round round(number, number) base64_decode base64_decode(string) base64_encode base64_encode(string) time_since time_since(string, string, string) time_now time_now() time_now_utc time_now_utc() path_canonicalize path_canonicalize(string) truncate truncate(string, number) semver_compare semver_compare(string, string) parse_json parse_json(string) parse_yaml parse_yaml(string) lookup lookup(object|array, string|number) items items(object|array, string, string) object_from_lists object_from_lists(array, array) random random(string) x509_decode x509_decode(string) time_to_cron time_to_cron(string) time_add time_add(string, string) time_parse time_parse(string, string) time_utc time_utc(string) time_diff time_diff(string, string) time_before time_before(string, string) time_after time_after(string, string) time_between time_between(string, string, string) time_truncate time_truncate(string, string)"},{"location":"reference/jp/functions/#chainsaw-functions","title":"chainsaw functions","text":"Name Signature env env(string) x_k8s_get x_k8s_get(any, string, string, string, string) x_k8s_list x_k8s_list(any, string, string, string) x_k8s_exists x_k8s_exists(any, string, string, string, string) x_k8s_resource_exists x_k8s_resource_exists(any, string, string) x_k8s_server_version x_k8s_server_version(any)"},{"location":"step/","title":"What is a test step?","text":"

A test step is made of four main components used to determine the actions Chainsaw will perform when executing the step.

  1. The try statement (required)
  2. The catch statement (optional)
  3. The finally statement (optional)
  4. The cleanup statement (optional)
"},{"location":"step/#syntax","title":"Syntax","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  steps:\n    # `try` defines operations to execute in the step\n  - try: [...]\n    # `catch` defines operations to execute when the step fails\n    catch: [...]\n    # `finally` defines operations to execute at the end of the step\n    finally: [...]\n    # `cleanup` defines operations to execute at the end of the test\n    cleanup: [...]\n
"},{"location":"step/#reference","title":"Reference","text":"

The full structure of the TestStepSpec is documented here.

"},{"location":"step/#lifecycle","title":"Lifecycle","text":""},{"location":"step/#try-catch-finally-flow","title":"Try, Catch, Finally flow","text":"

Operations defined in the try block are executed first, then:

Tip

Note that all operations coming from the catch or finally blocks are executed. If one operation fails, Chainsaw will mark the test as failed and continue executing with the next operations.

"},{"location":"step/#without-failure","title":"Without failure","text":"
sequenceDiagram\n    autonumber\n\n    participant S as Step N\n\n    box Try block\n    participant T1 as Op 1\n    participant T2 as Op N\n    end\n    box Catch block\n    end\n    box Finally block\n    participant F1 as Op 1\n    participant F2 as Op N\n    end\n    participant S1 as Step N+1\n\n    S  -->> T1 : try\n    T1 ->>  T2 : success\n    T2 -->> S  : done\n    S  -->> F1 : finally\n    F1 ->>  F2 : done\n    F2 -->> S  : done\n    S  -->> S1 : next step
  1. Step starts by executing operations in the try block
  2. Operations in the try block execute sequentially
  3. All operations in the try block terminate
  4. Step starts executing operations in the finally block
  5. Operations in the finally block execute sequentially
  6. All operations in the finally block terminate
  7. Next step starts executing
"},{"location":"step/#with-failure","title":"With failure","text":"
sequenceDiagram\n    autonumber\n\n    participant S as Step N\n\n    box Try block\n    participant T1 as Op 1\n    participant T2 as Op N\n    end\n    box Catch block\n    participant C1 as Op 1\n    participant C2 as Op N\n    end\n    box Finally block\n    participant F1 as Op 1\n    participant F2 as Op N\n    end\n\n    S  -->> T1 : try\n    T1 ->>  T2 : success\n    T2 -->> S  : error\n    S  -->> C1 : catch\n    C1 ->>  C2 : done\n    C2 -->> S  : done\n    S  -->> F1 : finally\n    F1 ->>  F2 : done\n    F2 -->> S  : done
  1. Step starts by executing operations in the try block
  2. Operations in the try block execute sequentially until an error happens
  3. Operations in the try block stop when an error occurs
  4. Step starts executing operations in the catch block
  5. Operations in the catch block execute sequentially
  6. All operations in the catch block terminate
  7. Step starts executing operations in the finally block
  8. Operations in the finally block execute sequentially
  9. All operations in the finally block terminate
"},{"location":"step/#cleanup","title":"Cleanup","text":"

In addition to try, catch and finally blocks, the cleanup block of steps is better illustrated in the Test lifecycle diagrams.

"},{"location":"step/catch/","title":"catch","text":"

A catch statement is also a sequence of operations.

Operations contained in a catch statement will be executed only if the step failed when executing the operations in the step's try statement.

Tip

All operations of a catch statement will be executed regardless of the success or failure of each of them.

"},{"location":"step/catch/#operations","title":"Operations","text":"

A catch statement supports only the following operations:

"},{"location":"step/catch/#inheritance","title":"Inheritance","text":"

Under certain circumstances, it can be useful to configure catch blocks at a higher level than the step grain. At the test or configuration level.

This allows for declaring common catch statements we want to execute when an error occurs. Those catch blocks are combined to produce the final catch block in the following order:

  1. catch statements from the configuration level are executed first (if any)
  2. catch statements from the test level are executed next (if any)
  3. catch statements from the step level are executed last (if any)
"},{"location":"step/cleanup/","title":"cleanup","text":"

A cleanup statement is similar to a finally statement but will execute after the test finishes executing, while finally executes after the step finishes executing.

Tip

All operations of a cleanup statement will be executed regardless of the success or failure of each of them.

"},{"location":"step/cleanup/#operations","title":"Operations","text":"

A cleanup statement supports only the following operations:

"},{"location":"step/finally/","title":"finally","text":"

A finally statement is similar to a catch statement but will always execute after the try and eventual catch statements finished executing regardless of the success or failure of the test step.

Tip

All operations of a finally statement will be executed regardless of the success or failure of each of them.

"},{"location":"step/finally/#operations","title":"Operations","text":"

A finally statement supports only the following operations:

"},{"location":"step/try/","title":"try","text":"

A try statement is a sequence of operations executed in the same order they are declared. If an operation fails the entire step is considered failed.

"},{"location":"step/try/#operations","title":"Operations","text":"

A try statement supports all operations:

"},{"location":"test/","title":"Writing Chainsaw tests","text":"

This documentation focuses on providing a breakdown of the Chainsaw test structure and how to use it.

"},{"location":"test/#what-is-a-test","title":"What is a test?","text":"

To put it simply, a test can be represented as an ordered sequence of test steps.

In turn, a test step can be represented as an ordered sequence of operations.

"},{"location":"test/#definition-approach","title":"Definition approach","text":"

Chainsaw supports two different test definition approaches:

Tip

While Chainsaw supports two test definition approaches, we strongly recommend the explicit one.

"},{"location":"test/#general-concepts","title":"General concepts","text":"

The concepts below are at the heart of Chainsaw:

"},{"location":"test/#test-and-step-specs","title":"Test and Step specs","text":"

Browse the test and step specs to learn all the details and options:

"},{"location":"test/conventional/","title":"Conventional approach","text":"

Warning

While Chainsaw supports the conventional approach, we strongly recommend the explicit one.

If you are new to Chainsaw we suggest you skip this section and jump directly to the Explicit approach.

"},{"location":"test/conventional/#introduction","title":"Introduction","text":"

The conventional approach is the simplest and less verbose one.

You provide bare Kubernetes resource manifests and Chainsaw will use those manifests to create, update, or assert expectations against a cluster.

"},{"location":"test/conventional/#limitations","title":"Limitations","text":"

While this syntax is simple, it suffers lots of limitations. It doesn't support deletion operations, commands, scripts, and all Chainsaw helpers.

It is also impossible to specify additional configuration per test, step or individual operation (timeouts, additional verifications, etc...), making this approach highly limited.

It also relies a lot on file naming conventions which can be error prone.

Finally, this approach doesn't encourage reusing files across tests and leads to duplication, making maintenance harder.

"},{"location":"test/conventional/#file-naming-convention","title":"File naming convention","text":"

Manifest files must follow a specific naming convention: 

<step index>-<name|assert|errors>.yaml\n

As an example, 00-configmap.yaml, 01-assert.yaml and 02-errors.yaml are valid file names.

"},{"location":"test/conventional/#assembling-steps","title":"Assembling steps","text":"

It's perfectly valid to have multiple files for the same step.

Let's say we have the following files 00-resources.yaml, 00-more-resources.yaml, 00-assert.yaml and 00-errors.yaml:

With the four files above, Chainsaw will assemble a test step made of the combination of all those files.

"},{"location":"test/conventional/#loading-process","title":"Loading process","text":"

The logic to determine the content of a step is always:

"},{"location":"test/conventional/#example","title":"Example","text":""},{"location":"test/conventional/#01-configmapyaml","title":"01-configmap.yaml","text":"

The manifest below contains a config map in a file called 01-configmap.yaml. Chainsaw will associate this manifest with an apply operation in step 01.

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  foo: bar\n
"},{"location":"test/conventional/#02-assertyaml","title":"02-assert.yaml","text":"

The manifest below contains an assertion statement in a file called 02-assert.yaml. Chainsaw will associate this manifest with an assert operation in step 02.

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  foo: bar\n
"},{"location":"test/conventional/#03-errorsyaml","title":"03-errors.yaml","text":"

The manifest below contains an error statement in a file called 03-errors.yaml. Chainsaw will associate this manifest with an error operation in step 03.

apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: chainsaw-quick-start\ndata:\n  lorem: ipsum\n
"},{"location":"test/conventional/#conclusion","title":"Conclusion","text":"

This test will first create a config map, then assert the content of the config map contains the foo: bar data, and then verify that the config map does not contain the lorem: ipsum data.

For such a simple test, the conventional approach works reasonably well but will quickly become limited when the test scenarios get more complex.

Look at the explicit approach for a lot more flexible solution.

"},{"location":"test/explicit/","title":"Explicit approach","text":"

The explicit is a bit more verbose than the conventional one but offers far more flexibility and features:

"},{"location":"test/explicit/#the-test-resource","title":"The Test resource","text":"

A Test resource, like any other Kubernetes resource, has an apiVersion, kind and metadata section.

It also comes with a spec section used to declaratively represent the test logic, steps and operations, as well as other configuration elements belonging to the test being defined.

Reference documentation

The full structure of the Test resource is documented here.

"},{"location":"test/explicit/#example","title":"Example","text":""},{"location":"test/explicit/#chainsaw-testyaml","title":"chainsaw-test.yaml","text":"

The Test below illustrates a simple test. Chainsaw will load the Test and steps defined in its spec section.

It's worth noting that:

apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # state that this test should not be executed in parallel with other tests\n  concurrent: false\n  # timeouts for this specific test\n  timeouts:\n    apply: 10s\n    assert: 10s\n    error: 10s\n  steps:\n  # step 1\n  # apply a configmap to the cluster\n  # the path to the configmap is relative to the folder\n  # containing the test, hence allow reusing manifests\n  # across multiple tests\n  - try:\n    - apply:\n        file: ../resources/configmap.yaml\n  # step 2\n  # execute assert statements against existing resources\n  # in the cluster\n  - try:\n    - assert:\n        file: ../resources/configmap-assert.yaml\n  # step 3\n  # execute error statements against existing resources\n  # in the cluster\n  - try:\n    - error:\n        file: ../resources/configmap-error.yaml\n  # step 4\n  # execute an arbitrary shell script\n  - try:\n    - script:\n        content: echo \"goodbye\"\n
"},{"location":"test/explicit/#conclusion","title":"Conclusion","text":"

While this test is simple, it illustrates the differences with the conventional approach.

The purpose here is only to present the explicit approach and there are a lot more features to discuss, we will cover them in the next sections.

"},{"location":"test/spec/","title":"Test spec","text":"

A Chainsaw test is mostly made of steps.

That being said, there are a couple of other interesting fields too.

"},{"location":"test/spec/#syntax","title":"Syntax","text":"
apiVersion: chainsaw.kyverno.io/v1alpha1\nkind: Test\nmetadata:\n  name: example\nspec:\n  # test configuration\n  concurrent: false\n  bindings:\n  - name: foo\n    value: bar\n  timeouts:\n    apply: 1s\n    assert: 2m\n    delete: 30s\n  ...\n  steps:\n  # step 1\n  - try: ...\n  # step 2\n  - try: ...\n    catch: ...\n  # step 3\n  - try: ...\n    catch: ...\n    finally: ...\n
"},{"location":"test/spec/#reference","title":"Reference","text":"

The full structure of the TestSpec is documented here.

"},{"location":"test/spec/#lifecycle","title":"Lifecycle","text":""},{"location":"test/spec/#cleanup","title":"Cleanup","text":"

At the end of the test, Chainsaw cleans up resources it created during the test, in the opposite order of creation.

By default, when a step fails, Chainsaw stops the execution and the remaining steps are not executed. The cleanup process starts at the moment the test stops executing.

Tip

Note that when a failure happens during cleanup, the test is marked as failed and Chainsaw continues executing cleanup for the remaining steps.

"},{"location":"test/spec/#without-failure","title":"Without failure","text":"
sequenceDiagram\n    autonumber\n    participant T as Test\n    participant S1 as Step 1\n    participant S2 as Step 2\n    participant S3 as Step 3\n\n    T  ->> S1: execute\n    S1 ->> S2: execute\n    S2 ->> S3: execute\n\n    S3 -->> S2: cleanup\n    S2 -->> S1: cleanup\n    S1 -->> T: cleanup
  1. Test starts by executing Step 1
  2. Step 1 terminates -> Step 2 starts executing
  3. Step 2 terminates -> Step 3 starts executing
  4. Step 3 terminates -> Cleanup for Step 3 starts
  5. Cleanup for Step 3 terminates -> Cleanup for Step 2 starts
  6. Cleanup for Step 2 terminates -> Cleanup for Step 1 is executed
"},{"location":"test/spec/#with-failure","title":"With failure","text":"
sequenceDiagram\n    autonumber\n    participant T as Test\n    participant S1 as Step 1\n    participant S2 as Step 2\n    participant S3 as Step 3\n\n    T  ->> S1: execute\n    S1 ->> S2: execute (fail)\n\n    Note left of S3: Step 3 is NOT executed\n\n    S2 -->> S1: cleanup\n    S1 -->> T: cleanup
  1. Test starts by executing Step 1
  2. Step 1 terminates -> Step 2 starts executing
  3. Step 2 fails -> Cleanup for Step 2 starts
  4. Cleanup for Step 2 terminates -> Cleanup for Step 1 is executed
"},{"location":"test/spec/#supported-elements","title":"Supported elements","text":""},{"location":"test/spec/#namespace","title":"Namespace","text":"

The namespace the test should run into, see Namespace selection.

"},{"location":"test/spec/#namespace-template","title":"Namespace template","text":"

Eventually provide a template if you something specific, see Namespace template.

"},{"location":"test/spec/#timeouts","title":"Timeouts","text":"

All timeouts can be specified per test, see Control your timeouts.

"},{"location":"test/spec/#clusters","title":"Clusters","text":"

Additional clusters can be registered at the test level, see Multi-cluster options.

"},{"location":"test/spec/#cluster","title":"Cluster","text":"

The cluster (by name) used to run the test, see Multi-cluster setup.

"},{"location":"test/spec/#bindings","title":"Bindings","text":"

Bindings can be registered at the test level and inherited in all steps, see Bindings.

"},{"location":"test/spec/#catch","title":"Catch","text":"

Catch blocks can be specified at the test level to declare common catch statements.

"},{"location":"test/spec/#template","title":"Template","text":"

Chainsaw allows templating configuration on a per test basis.

"},{"location":"test/spec/#concurrency","title":"Concurrency","text":"

Controlling concurrency per test is also possible, see Concurrency control.

"},{"location":"test/spec/#skip","title":"Skip","text":"

In case you need to skip a test for whatever reason, use skip: true.

"},{"location":"test/spec/#steps","title":"Steps","text":"

Steps are what tests will execute when they are run, see Test step spec dedicated section.

"}]} \ No newline at end of file