Documentation
¶
Overview ¶
Package chainsaw executes Chainsaw-style assertions against a live Kubernetes cluster, in-process. It supports two modes:
- Raw K8s resource YAML: pure field matching via the chainsaw Go library (assertRawResources → checks.Check).
- Chainsaw Test format (apiVersion: chainsaw.kyverno.io/v1alpha1): walks Spec.Steps[].Try[] and dispatches the assert / error operations to the same checks.Check engine (runChainsawTestInProcess in inprocess.go).
The earlier `runChainsawBinary` path that exec'd /usr/local/bin/chainsaw was removed in #1236; the read-only allowlist (validators/chainsaw/allowlist.go) restricts registry- declared content to assert/error only, which is exactly the subset the in-process executor implements. No external binary is shipped or invoked.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsChainsawTest ¶ added in v0.15.0
IsChainsawTest returns true if the YAML content is a Chainsaw Test (apiVersion: chainsaw.kyverno.io/v1alpha1, kind: Test). Exported so the deployment validator can partition Test-format asserts (which dispatch to the in-process executor with allowlist enforcement) from raw K8s resource YAML (which uses the Go assertion library directly). Originally added in PR #1231 to gate the binary-shipping path; retained in #1236 because the dispatch split is still useful — Test-format content runs through the read-only allowlist guard before evaluation; raw K8s YAML bypasses that guard (it has no operations to gate).
func ValidateTestReadOnly ¶ added in v0.15.0
ValidateTestReadOnly parses chainsaw Test YAML content (possibly multi-document) and rejects any operation other than `assert` or `error`. Used at runtime to bound the blast radius of registry-declared health checks: the deployment validator Job runs under a ServiceAccount bound to cluster-admin (pkg/validator/job/rbac.go:41-67), so registry content must not be able to invoke state-changing chainsaw operations (apply, create, delete, patch, update) or side-effecting collectors (script, command, wait, sleep, podLogs, events, describe, get, proxy).
Multi-document support: a single `---`-separated stream may carry more than one Test; each is unmarshaled and validated independently. Empty documents and non-Test documents (different apiVersion/kind) are skipped. Per PR #1235 review.
Both per-step (`spec.steps[].try/catch/finally/cleanup`) and top-level (`spec.catch`) operation lists are validated.
Caller contract: invoke only on content that IsChainsawTest reports as Test format. Raw K8s YAML asserts have no operations and are unaffected.
Returns ErrCodeInvalidRequest naming the offending document index + step + operation so the operator can pinpoint the registry entry that violated the allowlist. PR #1223 will surface the same rule at lint time so violations are caught before they ever reach the validator.
Types ¶
type ComponentAssert ¶
type ComponentAssert struct {
// Name is the component name (e.g., "gpu-operator").
Name string
// AssertYAML is the raw Chainsaw assert file content.
AssertYAML string
}
ComponentAssert holds the data needed to run assertions for one component.
type ResourceFetcher ¶
type ResourceFetcher interface {
// Fetch retrieves a single Kubernetes resource as an unstructured map.
// Returns ErrCodeNotFound when the resource doesn't exist.
Fetch(ctx context.Context, apiVersion, kind, namespace, name string) (map[string]interface{}, error)
// List enumerates Kubernetes resources of the given kind in the
// given namespace, optionally narrowed by labels (empty = no
// selector). Cluster-scoped resources should pass an empty
// namespace. Returns an empty slice (not error) when no resources
// match — the caller distinguishes "list returned empty" from
// "list call failed".
//
// Added in #1236 so the in-process Chainsaw Test executor can
// handle assertions / error blocks that target a namespace + label
// selector without specifying a resource name (the pod-phase /
// container-state patterns that dominate the registry-declared
// health checks).
List(ctx context.Context, apiVersion, kind, namespace string, labels map[string]string) ([]map[string]interface{}, error)
}
ResourceFetcher abstracts fetching Kubernetes resources for testability.
func NewClusterFetcher ¶
func NewClusterFetcher(client dynamic.Interface, mapper meta.RESTMapper) ResourceFetcher
NewClusterFetcher creates a ResourceFetcher that queries a live Kubernetes cluster.
type Result ¶
type Result struct {
// Component is the component name.
Component string
// Passed indicates whether the assertion passed.
Passed bool
// Output contains diagnostic detail for failures.
Output string
// Error contains any error from executing the assertion.
Error error
}
Result holds the outcome of an assertion run for one component.
func Run ¶
func Run(ctx context.Context, asserts []ComponentAssert, timeout time.Duration, fetcher ResourceFetcher) []Result
Run executes assertions for a set of components against live cluster resources. Components are run concurrently with bounded parallelism. Chainsaw Test format dispatches to the in-process executor (runChainsawTestInProcess); raw K8s resource YAML uses the Go library assertion engine (assertRawResources).
Source Files