Documentation
¶
Overview ¶
Package rendered is the algebra of the rendered policy model: the canonical form of a WorkloadPolicy, the diff between two consecutive versions expressed as the wire contract's DeltaChange set, and the application of such a delta to a policy (ADR-0015, ADR-0018).
The control plane uses Diff to decide whether a workload's version advances and what to push; the agent uses Apply to turn a delta into the next complete policy before installing it atomically. Both sides share this one implementation so that the contract's defining property,
Apply(snapshot(v_n), Diff(v_n, v_{n+1})) == Canonical(snapshot(v_{n+1})),
is tested in one place and holds on both ends of the wire. The package depends only on the generated wire contract; it links into the agent.
Index ¶
- Variables
- func Apply(base *innerwallv1.WorkloadPolicy, delta *innerwallv1.PolicyDelta) (*innerwallv1.WorkloadPolicy, error)
- func Canonical(p *innerwallv1.WorkloadPolicy) *innerwallv1.WorkloadPolicy
- func Delta(from, to *innerwallv1.WorkloadPolicy) *innerwallv1.PolicyDelta
- func Describe(ch *innerwallv1.DeltaChange) string
- func Diff(from, to *innerwallv1.WorkloadPolicy) []*innerwallv1.DeltaChange
- func Empty() *innerwallv1.WorkloadPolicy
- func Equal(a, b *innerwallv1.WorkloadPolicy) bool
- func HostRoute(addr netip.Addr) string
- func Marshal(p *innerwallv1.WorkloadPolicy) ([]byte, error)
- func NormalizeCIDR(s string) string
- func Provenance(ruleID string) (authoredID string, p innerwallv1.Protocol, err error)
- func RuleID(authoredID string, p innerwallv1.Protocol) string
- func Unmarshal(b []byte) (*innerwallv1.WorkloadPolicy, error)
Constants ¶
This section is empty.
Variables ¶
var ErrBaseMismatch = errors.New("rendered: delta base version does not match the applied version")
ErrBaseMismatch is returned by Apply when the delta's from_version is not the base policy's version. Per the wire contract the delta must then be discarded and a snapshot requested; it is never applied to a different base.
var ErrMalformedChange = errors.New("rendered: delta change carries no variant")
ErrMalformedChange is returned by Apply for a change with no variant set.
var ErrUnknownRule = errors.New("rendered: peer change names a rule the policy does not contain")
ErrUnknownRule is returned by Apply when a peer change names a rule the base policy does not contain.
Functions ¶
func Apply ¶
func Apply(base *innerwallv1.WorkloadPolicy, delta *innerwallv1.PolicyDelta) (*innerwallv1.WorkloadPolicy, error)
Apply returns the canonical policy that results from applying delta to base. It returns ErrBaseMismatch when the delta was computed against a different version than base carries, and never modifies base: a failed apply leaves the caller holding exactly what it had, which is what lets the agent acknowledge FAILED and stay on its last good version.
func Canonical ¶
func Canonical(p *innerwallv1.WorkloadPolicy) *innerwallv1.WorkloadPolicy
Canonical returns a copy of p in canonical form: rules sorted by id, each rule's peers deduplicated and sorted, each rule's ports deduplicated and sorted. Two policies that permit the same traffic have identical canonical forms, so Equal on canonical forms is exact, and a persisted policy and a freshly rendered one can be compared byte for byte.
func Delta ¶
func Delta(from, to *innerwallv1.WorkloadPolicy) *innerwallv1.PolicyDelta
Delta builds the PolicyDelta that moves an agent from from to to. The version numbers are taken from the two policies.
func Describe ¶
func Describe(ch *innerwallv1.DeltaChange) string
Describe renders a change as a short human-readable string for logs.
func Diff ¶
func Diff(from, to *innerwallv1.WorkloadPolicy) []*innerwallv1.DeltaChange
Diff returns the minimal DeltaChange set that turns from into to. It is empty exactly when Equal(from, to). The result is deterministic: a mode change first, then rule changes ordered by rule id, so that two renders of the same pair produce the same delta.
A rule present only in to is an upsert; a rule present only in from is a removal; a rule in both whose protocol or ports differ is an upsert (wholesale replacement); a rule in both that differs only in peers is an add_peers and/or remove_peers, which is the common case when a workload joins or leaves a label.
func Empty ¶
func Empty() *innerwallv1.WorkloadPolicy
Empty returns the policy an agent holds before any snapshot: version 0, visibility mode, no rules. It is the base every first snapshot replaces.
func Equal ¶
func Equal(a, b *innerwallv1.WorkloadPolicy) bool
Equal reports whether a and b permit the same traffic in the same mode. Versions are not compared: equality is about content, and the version is a consequence of content changing.
func Marshal ¶
func Marshal(p *innerwallv1.WorkloadPolicy) ([]byte, error)
Marshal serializes the canonical form of p deterministically, so that the persisted bytes of equal policies are equal.
func NormalizeCIDR ¶
NormalizeCIDR returns the canonical textual form of a prefix: the masked network address with its prefix length. A bare address becomes a host route (/32 or /128). Input that does not parse is returned unchanged.
func Provenance ¶
func Provenance(ruleID string) (authoredID string, p innerwallv1.Protocol, err error)
Provenance splits a resolved-rule id into the authored rule id and the protocol it was rendered for.
func RuleID ¶
func RuleID(authoredID string, p innerwallv1.Protocol) string
RuleID returns the identity of the resolved rule rendered from authored rule authoredID for one protocol. A resolved rule carries exactly one protocol while an authored rule may permit several, so an authored rule renders to one resolved rule per protocol; the wire contract's rule removals and peer changes are keyed by resolved-rule id and therefore need each of those to be distinct. The authored id is the prefix, so provenance is a string split away (ADR-0018).
func Unmarshal ¶
func Unmarshal(b []byte) (*innerwallv1.WorkloadPolicy, error)
Unmarshal parses a persisted policy.
Types ¶
This section is empty.
Source Files