Documentation
¶
Index ¶
- Constants
- Variables
- func ComposeEnvironment(environ []string) ([]string, error)
- func EnvValue(environ []string, name string) (string, bool)
- func FileLevelMount(m Mount, path string) bool
- func HeldFor(name string) string
- func HeldName(name string) string
- func ImageDefines(imageEnv []string, name string) bool
- func ResolverControlName(networkName string) string
- func ResolverControlURL(address string) string
- func SelfContainerID() string
- func SelfStatic() error
- func ShadowedEmpty(environ []string, name string) []string
- func ShortID(id string) string
- func Variables(environ []string) []string
- func WithoutVariable(environ []string, name string) []string
- type Check
- type Client
- func (c *Client) APIVersion() string
- func (c *Client) Accept(ctx context.Context, name string, filter Filter, guard Guard) (Target, error)
- func (c *Client) BridgeGateway(ctx context.Context) (string, error)
- func (c *Client) Capture(ctx context.Context, containerID string) (Spec, error)
- func (c *Client) Close() error
- func (c *Client) Connect(ctx context.Context, networkID, containerID string, ...) error
- func (c *Client) ContainerEnv(ctx context.Context, containerID string) (map[string]string, error)
- func (c *Client) Daemon() string
- func (c *Client) DiscardResolver(ctx context.Context, id string, cause error) error
- func (c *Client) Disconnect(ctx context.Context, networkID, containerID string) error
- func (c *Client) Endpoint() Endpoint
- func (c *Client) Endpoints(ctx context.Context, containerID string) (map[string]*network.EndpointSettings, error)
- func (c *Client) FindResolver(ctx context.Context, networkName string) (Resolver, error)
- func (c *Client) Gateways(ctx context.Context) ([]string, error)
- func (c *Client) Identify(ctx context.Context, ref string) (string, error)
- func (c *Client) ImageEnv(ctx context.Context, image string) ([]string, error)
- func (c *Client) ImportResolverImage(ctx context.Context) (string, error)
- func (c *Client) Lookup(ctx context.Context, name string, filter Filter) (Target, error)
- func (c *Client) Mutators(ctx context.Context) ([]string, error)
- func (c *Client) NetworkAddress(ctx context.Context, containerID, networkName string) (string, error)
- func (c *Client) OwnAddress(ctx context.Context, containerID string) (string, string, error)
- func (c *Client) Pause(ctx context.Context, containerID string) error
- func (c *Client) Paused(ctx context.Context, containerID string) (bool, error)
- func (c *Client) PublishedPort(ctx context.Context, containerID string, internal int) (int, error)
- func (c *Client) Recreate(ctx context.Context, spec Spec, environ []string) (string, error)
- func (c *Client) Remove(ctx context.Context, containerID string) error
- func (c *Client) RemoveMutator(ctx context.Context, containerID string) error
- func (c *Client) RemoveResolver(ctx context.Context, containerID string) error
- func (c *Client) Rename(ctx context.Context, containerID, name string) error
- func (c *Client) Resolvers(ctx context.Context) ([]Resolver, error)
- func (c *Client) RunMutator(ctx context.Context, spec MutatorSpec) (string, error)
- func (c *Client) RunResolver(ctx context.Context, spec ResolverSpec) (Resolver, error)
- func (c *Client) Running(ctx context.Context, containerID string) (bool, error)
- func (c *Client) ServerVersion() string
- func (c *Client) Start(ctx context.Context, containerID string) error
- func (c *Client) StatSecret(ctx context.Context, containerID, path string) (SecretStat, error)
- func (c *Client) Stop(ctx context.Context, containerID string) error
- func (c *Client) Targets(ctx context.Context, filter Filter) ([]Target, error)
- func (c *Client) Unpause(ctx context.Context, containerID string) error
- type Endpoint
- type Filter
- type Guard
- type Mount
- type MutatorSpec
- type Predicate
- type Refusal
- type Resolver
- type ResolverSpec
- type SecretStat
- type Spec
- type Status
- type Target
Constants ¶
const ( EnvDockerHost = "DOCKER_HOST" EnvDockerContext = "DOCKER_CONTEXT" EnvDockerConfig = "DOCKER_CONFIG" EnvXDGRuntime = "XDG_RUNTIME_DIR" SourceEnvHost = "DOCKER_HOST" SourceEnvContext = "DOCKER_CONTEXT" SourceConfigContext = "docker context" SourceRootless = "rootless socket" SourceDefault = "default socket" SourceNone = "none" )
const ( MutatorLabel = "khaos.mutator" MutatorValue = "true" MutatorRun = "khaos.mutator.run" // MutatorNonce authorises the subcommand this container runs. The command // writes to a path it is given, so on the HOST it must refuse: khaos never // writes host-global state, and a command that would truncate any file it // is pointed at cannot be reachable by accident. MutatorNonce = "KHAOS_MUTATOR_NONCE" )
const ( // HeldSuffix is where the ORIGINAL container goes while a replacement runs // under its name. khaos never destroys it: a recreate from an inspection // loses the anonymous volume with its data stranded, every prior log line, // and the container id that invariant 8 re-verifies against. A rename // keeps all three and makes the revert a rename back. HeldSuffix = "-khaos-held" // HeldVarPrefix carries a variable's original value inside the container // while khaos is pretending it is absent, so the value never reaches // khaos's journal or its state directory. Same rule as the secret tier's // aside copy. HeldVarPrefix = "KHAOS_HELD_" )
const ( PredicateNotInspected = "incomplete-inspection" PredicateConsentMissing = "consent-label-missing" PredicateConsentNotTrue = "consent-label-not-true" PredicateIdentityChanged = "identity-changed" PredicateSelfTarget = "self-target" PredicateHostNetwork = "host-network-mode" PredicateNamespacePeer = "namespace-joined-by-peer" PredicateHostNamespace = "host-namespace" PredicatePrivileged = "privileged-container" PredicateDangerousCap = "dangerous-capability" PredicateDeviceAccess = "host-device-access" PredicateUnconfined = "unconfined-security-profile" PredicateSocketReachable = "docker-socket-reachable" PredicateScopeMismatch = "outside-declared-scope" PredicateNotRunning = "container-not-running" )
const ( // These labels let an orphan survive khaos's death and be reclaimed by // label rather than by khaos remembering what it started. ResolverLabel = "khaos.resolver" ResolverNetworkLabel = "khaos.resolver.network" ResolverNonceLabel = "khaos.resolver.nonce" ResolverValue = "true" // The tag carries a digest of khaos's binary, so a rebuilt khaos imports a // new image instead of running the previous build's resolver. ResolverImagePrefix = "khaos-dnsrv" ResolverEntrypoint = "/khaos" ResolverCommand = "serve-resolver" // Where the control nonce travels; see resolverArgs for why not a flag. EnvResolverNonce = "KHAOS_RESOLVER_NONCE" )
const ( LabelConsent = "khaos.target" ConsentValue = "true" LabelComposeProject = "com.docker.compose.project" LabelComposeService = "com.docker.compose.service" )
const ( NetworkModeHost = "host" NetworkModeContainerPfx = "container:" ModeHost = "host" )
const (
DockerSocketPath = "/var/run/docker.sock"
)
const (
FixNoTargets = "add `labels: [\"" + LabelConsent + "=" + ConsentValue + "\"]` to a service and recreate it, or run `khaos range up`"
)
const ShortIDLen = 12
Variables ¶
var ( ErrNoEndpoint = errors.New("no Docker endpoint found") ErrSocketMissing = errors.New("the Docker socket does not exist") ErrSocketDenied = errors.New("permission denied on the Docker socket") ErrNotASocket = errors.New("the Docker endpoint path is not a socket") ErrNothingListening = errors.New( "the Docker socket exists but nothing is listening on it", ) ErrDaemonSilent = errors.New( "the Docker endpoint is reachable but the daemon did not answer", ) )
var ( ErrNoHostConfig = errors.New( "the daemon returned a container with no host configuration, so khaos cannot tell whether it is safe to touch", ) ErrEmptyName = errors.New("a target name is required") )
var ErrContainerGone = errors.New("the container no longer exists")
var ErrContextUnresolvable = errors.New(
"the selected Docker context could not be resolved",
)
var ErrDynamicSelf = errors.New(
"this khaos binary is dynamically linked and cannot be its own container image",
)
var ErrImageDefinesVariable = errors.New(
"the image defines that variable, so removing the container's copy changes nothing",
)
var ErrNetworkGone = errors.New(
"the network no longer exists, so the container could not be reattached to it",
)
var ErrNoContainerConfig = errors.New(
"the daemon returned no configuration to rebuild from",
)
var ErrResolverExists = errors.New(
"a khaos resolver is already serving that network",
)
var ErrResolverNotFound = errors.New("no chaos resolver exists on that network")
var ErrUnreachableSecret = errors.New(
"that path is not somewhere khaos can act and then undo",
)
var ErrVariableAbsent = errors.New(
"that variable is not in the target's environment",
)
Functions ¶
func ComposeEnvironment ¶
func EnvValue ¶
EnvValue reads one variable out of a captured environment, taking the LAST occurrence. Docker deduplicates on the whole `KEY=VALUE` string rather than on the key, so a shadowed variable appears twice and the last one is what the process sees - khaos has to read it the same way or it mis-reports its own fault.
func FileLevelMount ¶
FileLevelMount reports whether the path IS the mount point rather than a file inside it. Renaming a mount point is impossible, which is the one mutation khaos has to refuse on that shape rather than approximate.
func HeldFor ¶
HeldFor is where an unset keeps the original value: inside the replacement's own environment, under a name the target does not read.
func ImageDefines ¶
ImageDefines reports whether the image bakes this variable in, which is the one precondition `env_unset` cannot work around.
func ResolverControlName ¶
ResolverControlName is generated when the operator named no control. It is in `.invalid`, reserved by RFC 2606, so it can never collide with a real name.
func ResolverControlURL ¶
ResolverControlURL is on the container's own address, which the host routes to directly, so nothing is ever published.
func SelfContainerID ¶
func SelfContainerID() string
func SelfStatic ¶
func SelfStatic() error
SelfStatic refuses a khaos binary that cannot be its own container image. The check is on the ELF rather than a build tag because what matters is the artifact: cgo links libc for `net`, and that dies in a base-less image.
func ShadowedEmpty ¶
ShadowedEmpty appends `NAME=` rather than replacing the original entry, which is what makes the fault reversible without khaos holding the value: the revert removes the LAST occurrence and the original is still underneath.
func Variables ¶
Variables is every key a captured environment carries, for a refusal that names what IS there rather than only what is not.
func WithoutVariable ¶
WithoutVariable removes every occurrence of a key, which is what an unset needs: leaving one behind would shadow the removal.
Types ¶
type Check ¶
func DiagnoseWith ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func (*Client) APIVersion ¶
func (*Client) BridgeGateway ¶
BridgeGateway is the address a container reaches the host on: the DEFAULT bridge's gateway, discovered rather than assumed, since it is not 172.17.0.1 on every host. A user-defined network's own gateway is that network's default route and answers a ping, but a HOST LISTENER bound on it is refused from containers on the network, which is why this is not that address.
func (*Client) Capture ¶
Capture reads a container back. The per-network EndpointSettings travel whole and are cleaned of the daemon's own identifiers: reconnecting with only a network NAME silently drops the static address, the MAC and every alias, and on a compose project the service name lives in the aliases, so every peer addressing it by name would get NXDOMAIN forever.
func (*Client) ContainerEnv ¶
func (c *Client) ContainerEnv( ctx context.Context, containerID string, ) (map[string]string, error)
ContainerEnv reads where a target is ALREADY addressing its dependency. Environment is fixed at creation, so the container is the only authority on what it will dial.
func (*Client) Daemon ¶
Daemon is a stable identity for the daemon this client is attached to, empty when the daemon would not say, which callers must treat as unknown rather than as a match.
func (*Client) DiscardResolver ¶
func (*Client) Disconnect ¶
func (*Client) FindResolver ¶
FindResolver matches by LABEL and not by name, because reclaim works from a cold start and a renamed resolver would otherwise be duplicated.
func (*Client) Gateways ¶
Gateways is every address DOCKER manages as a network gateway, which is a narrower question than "is this a bridge". `/sys/class/net/<if>/bridge` exists for every kernel bridge device: measured on this host, that includes a CNI pod bridge, a swarm overlay's gateway bridge and forty-nine user-defined ones carrying unrelated projects' containers -- and on a host whose LAN interface is enslaved to a bridge, the routable LAN address itself. khaos binds listeners that answer whatever asks them, so the allowed set has to come from the daemon rather than from sysfs.
func (*Client) Identify ¶
Identify resolves a name to the IMMUTABLE container id behind it, or ErrContainerGone when nothing answers to it. A name is a label the daemon lets any container hold, and the environment tier hands one container's name to another on purpose, so anything destructive resolves first.
func (*Client) ImageEnv ¶
ImageEnv is what the IMAGE bakes in, which is not the same question as what the container carries. The daemon merges the image's environment into any key a create request omits, so a variable defined in both places cannot be taken away by omission.
func (*Client) ImportResolverImage ¶
ImportResolverImage builds a single-layer image out of khaos's own binary, with no base image, no registry and no network, because a published image needs a registry and building one needs a source tree khaos may not have.
func (*Client) Mutators ¶
Mutators lists the helper containers khaos has left behind. Filtered by label=KEY=VALUE, never label=KEY: moby's MatchKVList splits on the first `=` and never compares a missing value, and this list is what a reclaim would force-remove.
func (*Client) NetworkAddress ¶
func (*Client) OwnAddress ¶
OwnAddress is where khaos dials a target DIRECTLY, on the container's own address rather than on a published host port. The host routes to a bridge network's addresses, which is what makes a stateful dependency reachable with nothing published, and the network with the lowest name is chosen so two runs against a multi-homed container agree.
func (*Client) PublishedPort ¶
func (*Client) Recreate ¶
Recreate creates and starts a container from a captured spec with a replaced environment, and returns its id. The caller has already renamed the original aside, so this is additive: nothing has been destroyed when it fails.
func (*Client) Remove ¶
Remove removes a container khaos CREATED, and only ever the replacement it made itself. A container that is already gone is success, because a revert runs again after a reclaim.
func (*Client) RemoveMutator ¶
func (*Client) RemoveResolver ¶
RemoveResolver treats a missing container as success: the resolver went with it, and an error would wedge a journal record and stop `khaos reap` sweeping.
func (*Client) Rename ¶
Rename is how the original is kept. The replacement takes the name, so every peer addressing the service by name reaches the replacement.
func (*Client) RunMutator ¶
RunMutator creates the container, waits for it, and removes it. The exit code is read from the daemon rather than from the logs, and a non-zero one carries the container's own output, because a mutation that failed silently would leave khaos measuring an unfaulted target.
func (*Client) RunResolver ¶
RunResolver reads the address back out of the daemon rather than choosing one, because Docker refuses `--ip` on a network whose subnet it picked, which is also why arming happens in band instead of by recreating the container.
func (*Client) Running ¶
Running reports whether the container is up, which is how a restart obligation knows there is still something to put back.
func (*Client) ServerVersion ¶
func (*Client) StatSecret ¶
StatSecret never turns a missing file into an error, because absence is one of the four faults and has to be reportable as an observation.
func (*Client) Stop ¶
Stop stops a container before it is renamed aside, because two containers cannot both hold a network's static address and a service's aliases. A container that is already stopped is success.
type Mount ¶
type Mount struct {
Type string `json:"type"`
Source string `json:"source"`
Destination string `json:"destination"`
ReadWrite bool `json:"read_write"`
Name string `json:"name,omitempty"`
}
Mount is one of the target's own mounts, read off its inspection. khaos replicates exactly the one containing the file it acts on, and never anything else the target can see.
type ResolverSpec ¶
type ResolverSpec struct {
Network string
// Carries the network, so two resolvers on two networks cannot collide.
Name string
// Stored as a LABEL as well as passed in, so khaos reads it back off the
// container rather than remembering what it chose.
Nonce string
Zone map[string]string
Control string
}
ResolverSpec is what khaos needs to stand one up.
type SecretStat ¶
SecretStat is the TARGET's own view of a file, read through the archive endpoint's HEAD. It is the confirmation read-back for every secret fault: the mutator writes through a helper, and this is khaos asking the container under test what it now has. Measured to work on every mount shape, including the one the archive API cannot write.
type Spec ¶
type Spec struct {
Name string
Config *container.Config
HostConfig *container.HostConfig
Networks map[string]*network.EndpointSettings
}
Spec is everything needed to recreate one container. It is captured from the daemon rather than assembled, so nothing khaos forgot to copy can go missing.
type Target ¶
type Target struct {
ID string
Name string
Image string
ImageID string
Project string
Service string
Labels map[string]string
Running bool
NetworkMode string
PidMode string
IpcMode string
UsernsMode string
Privileged bool
Capabilities []string
Devices []string
SecurityOpt []string
BindSources []string
// Mounts is every mount with its type and destination, which is what the
// mutator tier needs to reach a file inside one. BindSources carries only
// the sources, because the refusal predicates judge by resolved path.
Mounts []Mount
NamespacePeers []string
Inspected bool
}