Documentation
¶
Overview ¶
Package probe runs readiness and liveness checks against a container: an HTTP(S) request to its address, or a command executed inside it. WaitReady polls until the target is ready, and Check runs a single attempt.
Index ¶
Examples ¶
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.
func (Config) Validate ¶
Validate checks c for contradictory or malformed settings.
Example ¶
package main
import (
"fmt"
"github.com/GLINCKER/levelrail/kit/probe"
)
func main() {
fmt.Println(probe.Config{Path: "/healthz", ExpectedStatus: "200-299"}.Validate())
fmt.Println(probe.Config{Path: "healthz"}.Validate())
}
Output: <nil> path "healthz" must start with /
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.
func (*Prober) Check ¶
Check runs exactly one probe attempt, bounded by cfg.Timeout. cfg.Interval is ignored: a caller wanting repetition owns it.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"time"
"github.com/GLINCKER/levelrail/kit/probe"
)
func main() {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusOK)
}))
defer srv.Close()
p := probe.New(srv.Client(), nil, probe.Limits{})
target := probe.Target{Addr: strings.TrimPrefix(srv.URL, "http://")}
err := p.Check(context.Background(), target, probe.Config{Path: "/healthz", Timeout: 2 * time.Second})
fmt.Println(err)
}
Output: <nil>
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