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
- Variables
- func DropBinding(policies ...string) func(context.Context, *Env) (func(context.Context) error, error)
- func DropValidations(policy, message string) func(context.Context, *Env) (func(context.Context) error, error)
- func RefuseEverything(policy string) func(context.Context, *Env) (func(context.Context) error, error)
- func RewriteValidations(policy, message, old, replacement string) func(context.Context, *Env) (func(context.Context) error, error)
- func Scheme() (*runtime.Scheme, error)
- func SetVariables(policy string, expressions map[string]string) func(context.Context, *Env) (func(context.Context) error, error)
- func WidenMatch(policy string) func(context.Context, *Env) (func(context.Context) error, error)
- type Chart
- type Env
- func (env *Env) As(identity Identity) (client.Client, error)
- func (env *Env) Check(ctx context.Context, row Row) error
- func (env *Env) Manager() Identity
- func (env *Env) Prove(ctx context.Context, mutation Mutation, rows map[string]Row) error
- func (env *Env) WaitFor(ctx context.Context, rows []Row, within time.Duration) error
- type Identity
- type Mutation
- type Names
- type Row
- type Verdict
Constants ¶
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.
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 ¶
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 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.
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 (*Chart) Binding ¶
func (chart *Chart) Binding(policy string) (*admissionregistrationv1.ValidatingAdmissionPolicyBinding, error)
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 ¶
func (chart *Chart) Policy(prefix string) (*admissionregistrationv1.ValidatingAdmissionPolicy, error)
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 ¶
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 ¶
As returns a client that acts as identity. Clients are cached: each one discovers the API on first use.
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 ¶
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.
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.
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.