policyenv

package
v0.2.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package policyenv installs the chart's admission policies into an envtest API server in the state a completed install leaves them, and decides requests against them: which policy refused a request, and with what.

Every name the suite relies on -- ServiceAccounts, Deployments and policies -- is read out of the rendered chart rather than written down here, so a renamed identity or a new digest moves the suite with the chart instead of leaving it asserting the old one.

Index

Constants

View Source
const OrdinaryUser = "envtest-ordinary-user"

OrdinaryUser is a person with write access and no admission authority. Install grants it exactly the RBAC the rows need, so a request it makes that is refused is refused by admission, not by authorization.

View Source
const WebhookDisabledLabel = "policyenv.envtest.operator.ptah.run/webhook-disabled"

WebhookDisabledLabel is the only label the installed webhook entries select. Nothing carries it, so the API server never calls them: the chart's webhooks point at a Service no envtest process serves, and a webhook that fails closed would otherwise refuse every request it matches before a policy is asked. The webhook suite serves them for real; here they exist because a completed install leaves them.

Variables

View Source
var ErrNotInstalled = errors.New("not rendered by the chart")

ErrNotInstalled reports a policy or binding the chart does not render.

Functions

func DropBinding

func DropBinding(policies ...string) func(context.Context, *Env) (func(context.Context) error, error)

DropBinding deletes the bindings of the named policies, which is what a chart that stopped rendering them would leave: the policies exist and judge nothing.

func DropValidations added in v0.2.10

func DropValidations(policy, message string) func(context.Context, *Env) (func(context.Context) error, error)

DropValidations removes the policy's validations whose message contains message, and fails the mutation if none does: dropping nothing would prove nothing, and the rows would say so only as a timeout.

func RefuseEverything

func RefuseEverything(policy string) func(context.Context, *Env) (func(context.Context) error, error)

RefuseEverything replaces the policy's validations with one that refuses every request the policy matches. A row that stays admitted under it was never inside the policy's scope, whatever its name says.

func RewriteValidations added in v0.2.11

func RewriteValidations(policy, message, old, replacement string) func(context.Context, *Env) (func(context.Context) error, error)

RewriteValidations replaces old with replacement in the expression of every validation of the policy whose message contains message, which is how a chart that rendered one clause of a rule differently would read. It fails the mutation if no such expression holds old: rewriting nothing would prove nothing, and the rows would say so only as a timeout.

func Scheme

func Scheme() (*runtime.Scheme, error)

Scheme knows the built-in kinds and the operator's own.

func SetVariables

func SetVariables(policy string, expressions map[string]string) func(context.Context, *Env) (func(context.Context) error, error)

SetVariables rewrites the named variables of the policy, which is how a chart that inlined another release's values would render it. A row refused for carrying another release's value is admitted once the policy carries that value itself, and that is what shows the variable is what refused it.

func WidenMatch

func WidenMatch(policy string) func(context.Context, *Env) (func(context.Context) error, error)

WidenMatch removes the policy's match conditions, so it judges every request its resource rules match rather than the identities and objects it was written for.

Types

type Chart

type Chart struct {
	Release harness.Release
	// Rendered is every document helm printed.
	Rendered []*unstructured.Unstructured
	// Installed are the objects applied before any policy: the identities and
	// their RBAC, the runtime Deployments and the webhook configurations.
	// Hook objects are not among them: Helm deletes each one once its hook
	// succeeds, so a completed install leaves none.
	Installed []*unstructured.Unstructured
	// Policies and Bindings are the admission policies an install leaves
	// bound. Each is an ordinary release object; the chart renders none as a
	// hook.
	Policies []*admissionregistrationv1.ValidatingAdmissionPolicy
	Bindings []*admissionregistrationv1.ValidatingAdmissionPolicyBinding
	Names    Names
}

Chart is one rendered release, sorted into what a completed install leaves in the cluster.

func Render

func Render(ctx context.Context, release harness.Release) (*Chart, error)

Render renders release and sorts it.

func (*Chart) Binding

Binding returns the binding of the named policy. Each policy has one.

func (*Chart) Object

func (chart *Chart) Object(kind, name string) (*unstructured.Unstructured, error)

Object returns the rendered object of kind named name.

func (*Chart) Policy

Policy returns the policy whose name starts with prefix. The prefix is the stable part of a name; the chart appends a release digest.

type Env

type Env struct {
	Chart  *Chart
	Plane  *harness.ControlPlane
	Scheme *runtime.Scheme
	// Admin is the envtest administrator, a member of system:masters. RBAC
	// does not constrain it and the policies still judge it.
	Admin client.Client
	// contains filtered or unexported fields
}

Env is a release installed on a running control plane.

func Install

func Install(ctx context.Context, plane *harness.ControlPlane, chart *Chart) (*Env, error)

Install puts chart into the state a completed install leaves: every object of the release, and the policies bound. It installs the policies last, so nothing it creates is judged by them.

func (*Env) As

func (env *Env) As(identity Identity) (client.Client, error)

As returns a client that acts as identity. Clients are cached: each one discovers the API on first use.

func (*Env) Check

func (env *Env) Check(ctx context.Context, row Row) error

Check sends row's request and compares the verdict with what row owes.

func (*Env) Manager

func (env *Env) Manager() Identity

Manager is the manager's ServiceAccount as its own Pod presents it.

func (*Env) Prove

func (env *Env) Prove(ctx context.Context, mutation Mutation, rows map[string]Row) error

Prove applies mutation, waits until every row it names fails, and puts the policies back, waiting until those rows pass again. rows maps row names to rows. The error names what did not happen and what the rows saw instead.

func (*Env) WaitFor

func (env *Env) WaitFor(ctx context.Context, rows []Row, within time.Duration) error

WaitFor polls until every row passes, which is how the suite knows the API server has compiled the policies it just installed.

type Identity

type Identity struct {
	Username string
	// Groups left empty let the API server derive them, which for a
	// ServiceAccount is exactly the groups its token would carry.
	Groups []string
	Extra  map[string][]string
}

Identity is who a request claims to be. The suite impersonates it, which is the same user information a real token would give the API server: admission sees the username, the groups and the extras, and nothing else.

func ServiceAccount

func ServiceAccount(namespace, name string) Identity

ServiceAccount is the identity of a ServiceAccount token with no Pod bound.

func User

func User() Identity

User is an ordinary user: RBAC lets it write, and nothing makes it an administrator of admission.

func (Identity) BoundTo

func (identity Identity) BoundTo(pod, uid string) Identity

BoundTo returns identity as a token bound to the named Pod presents it.

func (Identity) String

func (identity Identity) String() string

type Mutation

type Mutation struct {
	Name string
	// Policies are the policies the mutation weakens.
	Policies []string
	// Apply weakens them and returns what puts them back.
	Apply func(ctx context.Context, env *Env) (restore func(context.Context) error, err error)
	// Breaks names the rows that must fail while the mutation holds.
	Breaks []string
	// Admits makes the rows it breaks owe more than a failure: each one must be
	// admitted while the mutation holds. A mutation that writes the value a
	// refused request carries into the policy has to reverse that verdict. A
	// policy the mutation left malformed refuses everything instead, and that
	// failure proves nothing about the value.
	Admits bool
}

Mutation weakens installed policies the way a regression in the chart would: a binding left out, a match widened, validations that refuse everything. A row that still passes while a mutation holds does not depend on what the mutation changed, and so does not prove what it is named for.

type Names

type Names struct {
	Namespace string
	// Manager is the manager's ServiceAccount, in Namespace.
	Manager string
	// ManagerDeployment is the Deployment the manager runs in, in Namespace.
	ManagerDeployment string
	// WebhookConfiguration names both the mutating and the validating one.
	WebhookConfiguration string
}

Names are the identities and objects the policies are written against.

type Row

type Row struct {
	Name string
	// Deny names the policies a refusal may be attributed to. Empty means the
	// request must be admitted. More than one name is for requests two
	// policies refuse on purpose -- a boundary held twice so either can be
	// replaced without a gap -- and the API server reports only the first it
	// evaluated, in no fixed order.
	Deny []string
	// Message must appear in the refusal.
	Message string
	// Do sends the request.
	Do func(ctx context.Context, env *Env) error
}

Row is one request and the verdict the installed release owes it.

func (Row) Judge

func (row Row) Judge(verdict Verdict) error

Judge exposes the matcher to the suite's own self-test.

type Verdict

type Verdict struct {
	Admitted bool
	// Policy and Binding name the admission policy that refused the request.
	// Both are empty when something else refused it: RBAC, a schema, or the
	// request itself.
	Policy  string
	Binding string
	Message string
	Err     error
}

Verdict is what the API server answered one request, and on whose word.

func Decide

func Decide(err error) Verdict

Decide reads the outcome of a request.

func (Verdict) String

func (verdict Verdict) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL