Documentation
¶
Overview ¶
Package probe implements readiness and liveness checks the controller runs against a container: an HTTP(S) request to its published port, or a command exec'd inside it. See ADR 002 for why the controller probes rather than trusting Docker's own HEALTHCHECK state.
WaitReady polls until a freshly started container is ready, gating a deploy's cutover. Check runs a single attempt, for the level-triggered liveness check, where the reconcile loop itself is the retry loop.
Index ¶
Constants ¶
const ( DefaultMaxRedirects = 10 DefaultExecOutputBytes = 512 DefaultTimeout = 2 * time.Second DefaultInterval = 2 * time.Second )
Defaults applied by Limits' zero fields. MaxRedirects matches net/http's own client default, which is what probes followed before it was configurable.
const ( EnvMaxRedirects = "APP_PROBE_MAX_REDIRECTS" EnvExecOutputBytes = "APP_PROBE_EXEC_OUTPUT_BYTES" EnvDefaultTimeout = "APP_PROBE_DEFAULT_TIMEOUT" EnvDefaultInterval = "APP_PROBE_DEFAULT_INTERVAL" )
Environment variables LimitsFromEnv reads.
const ( SchemeHTTP = "http" SchemeHTTPS = "https" )
Supported HTTP probe schemes.
const DefaultExpectedStatus = "200-299"
DefaultExpectedStatus is the status set a probe with no expected_status accepts.
Variables ¶
This section is empty.
Functions ¶
func DescribeCommand ¶
DescribeCommand renders cmd for a status message, unwrapping the ["/bin/sh", "-c", script] form back to the script the operator wrote.
func ShellCommand ¶
ShellCommand wraps script as the argv an exec probe runs it through.
Types ¶
type Attempt ¶
type Attempt struct {
Time time.Time
Target string
Latency time.Duration
Success bool
StatusCode int // HTTP status; 0 for an exec probe or a response-less HTTP failure
ExitCode int // exec exit code; 0 for an HTTP probe
Error string
}
Attempt is one individual probe attempt's outcome, reported via WithOnAttempt strictly as a side channel: it is built and delivered after attempt()'s own pass/fail decision is already made, and nothing it does can feed back into WaitReady's retry loop or Check's return value. Target is the same descriptive string a Failure's own Reason would use (e.g. "GET http://addr/healthz", or an exec command), so a caller rendering this needs no separate formatting.
type Config ¶
type Config struct {
Path string
Scheme string
Host string
TLSSkipVerify bool
// FollowRedirects nil keeps the historical behavior (follow, bounded by
// Limits.MaxRedirects); an explicit false judges the 3xx itself.
FollowRedirects *bool
ExpectedStatus string
Exec []string
Interval time.Duration
Timeout time.Duration
}
Config is one probe's settings. A non-empty Exec makes it an exec probe; otherwise it is an HTTP probe against Path. Zero Interval or Timeout means "not specified" and falls back to the Prober's Limits.
type Executor ¶
type Executor interface {
ExecProbe(ctx context.Context, containerID string, cmd []string) (exitCode int, output string, err error)
}
Executor runs cmd inside a container and reports its exit code and combined output. err is for failures to run the command at all.
type Failure ¶
type Failure struct {
Kind FailureKind
Reason string
Err error
}
Failure is one failed probe attempt. Its Error text is written for an operator: it names the request or command and exactly what went wrong.
type FailureKind ¶
type FailureKind string
FailureKind classifies why a probe attempt failed.
const ( FailureStatus FailureKind = "UnexpectedStatus" FailureRedirect FailureKind = "UnexpectedRedirect" FailureTooManyHops FailureKind = "TooManyRedirects" FailureConnect FailureKind = "ConnectionFailed" FailureTLS FailureKind = "TLSVerifyFailed" FailureTimeout FailureKind = "Timeout" FailureExitCode FailureKind = "ExecNonZeroExit" FailureExecError FailureKind = "ExecFailed" FailureExecNotReady FailureKind = "ExecUnavailable" )
Failure kinds.
type Limits ¶
type Limits struct {
MaxRedirects int
ExecOutputBytes int
DefaultTimeout time.Duration
DefaultInterval time.Duration
}
Limits bounds probe behavior. Zero fields take the package defaults.
type Option ¶
type Option func(*Prober)
Option configures an optional Prober behavior.
func WithOnAttempt ¶
WithOnAttempt reports every individual probe attempt to fn, once per call to attempt() (so once per WaitReady retry, once per Check), as a side effect after that attempt's outcome is already decided. fn runs synchronously on the calling goroutine and must not block; its behavior can never change what WaitReady/Check return. Exists so an operator-facing recorder can see per-attempt detail (status code, latency) that a reconcile condition's own single Reason/Message summary never captures.
type Prober ¶
type Prober struct {
// contains filtered or unexported fields
}
Prober runs probes with shared transport and limits.
func New ¶
New builds a Prober. A nil client means http.DefaultClient; a nil exec makes every exec probe fail with FailureExecNotReady.
type StatusSet ¶
type StatusSet struct {
// contains filtered or unexported fields
}
StatusSet is a parsed expected_status value: a union of status codes and ranges.
func ParseStatusSet ¶
ParseStatusSet parses "200-399", "200,204,301-302" or a single code. Commas and whitespace both separate entries; an empty string yields the 2xx default.
Source Files