cli

Documentation

Overview

Package cli wraps invocations of the telepresence binary under test.

Index

• type ConnectOpt
• type IngestInfo
• type InterceptInfo
• type InterceptOpt
  • func EnvFile(path string) InterceptOpt
  • func HTTPHeader(k, v string) InterceptOpt
  • func HTTPPathPrefix(p string) InterceptOpt
  • func MountFalse() InterceptOpt
  • func Port(local int, remote string) InterceptOpt
  • func Replace() InterceptOpt
  • func WorkloadFlag(name string) InterceptOpt
• type ListEntry
• type ListEntryIngest
• type ListEntryIntercept
• type Proc
  • func (p *Proc) Signal(sig os.Signal) error
  • func (p *Proc) Wait(timeout time.Duration) (stdout, stderr string, err error)
• type RootDaemonStatus
• type Status
• type TP
  • func (tp *TP) JSON(ctx context.Context, out any, args ...string) error
  • func (tp *TP) OK(t testing.TB, args ...string) string
  • func (tp *TP) Run(ctx context.Context, args ...string) (stdout, stderr string, err error)
  • func (tp *TP) Start(ctx context.Context, args ...string) (*Proc, error)
• type TrafficManagerStatus
• type UserDaemonStatus
• type Version

Types

type ConnectOpt

type ConnectOpt func() []string

ConnectOpt produces extra arguments for a `telepresence connect` invocation.

type IngestInfo

type IngestInfo struct {
	WorkloadName string            `json:"workload_name,omitempty"`
	WorkloadKind string            `json:"workload_kind,omitempty"`
	Container    string            `json:"container,omitempty"`
	Environment  map[string]string `json:"environment,omitempty"`
}

IngestInfo mirrors the fields the framework asserts on in the JSON object produced by `telepresence ingest --format json` (pkg/client/cli/ingest/info.go: Info).

type InterceptInfo

type InterceptInfo struct {
	ID           string `json:"id,omitempty"`
	Name         string `json:"name,omitempty"`
	Disposition  string `json:"disposition,omitempty"`
	WorkloadKind string `json:"workload_kind,omitempty"`
	// PortID identifies the service port the intercept targets (name or
	// number, pkg/client/cli/intercept/info.go's Info.PortID, spec.PortIdentifier).
	PortID string `json:"port_id,omitempty"`
	// TargetPort/ContainerPort are the intercept's local port and the
	// container port it replaces, respectively.
	TargetPort    int32 `json:"target_port,omitempty"`
	ContainerPort int32 `json:"container_port,omitempty"`
	Replace       bool  `json:"replace,omitempty"`
	Wiretap       bool  `json:"wiretap,omitempty"`
	// Environment carries the intercepted container's environment plus the
	// TELEPRESENCE_ROOT/TELEPRESENCE_INTERCEPT_ID/TELEPRESENCE_API_HOST
	// entries the CLI adds locally before printing (pkg/client/cli/
	// intercept/info.go's Info.Environment, json tag "environment"; see
	// rt.MountRoot's doc comment for how those additions reach here).
	Environment map[string]string `json:"environment,omitempty"`
}

InterceptInfo mirrors the fields the framework asserts on in the JSON object produced by `telepresence intercept|replace|wiretap --format json --detailed-output` (pkg/client/cli/intercept/info.go: Info; field names verified against that file's json tags). replace and wiretap share this same output type with intercept, distinguished by the Replace/Wiretap flags.

type InterceptOpt

type InterceptOpt func() []string

InterceptOpt produces extra arguments for a `telepresence intercept` or `telepresence ingest` invocation.

func EnvFile

func EnvFile(path string) InterceptOpt

EnvFile sets --env-file path.

func HTTPHeader

func HTTPHeader(k, v string) InterceptOpt

HTTPHeader adds an --http-header key=value filter.

func HTTPPathPrefix

func HTTPPathPrefix(p string) InterceptOpt

HTTPPathPrefix adds an --http-path-prefix filter.

func MountFalse

func MountFalse() InterceptOpt

MountFalse sets --mount false, disabling filesystem mounting.

func Port

func Port(local int, remote string) InterceptOpt

Port sets --port local:remote, where remote identifies the service port by name or number.

func Replace

func Replace() InterceptOpt

Replace sets --replace, so the traffic-agent replaces the application container instead of running alongside it.

func WorkloadFlag

func WorkloadFlag(name string) InterceptOpt

WorkloadFlag sets --workload name.

type ListEntry

type ListEntry struct {
	Name                   string `json:"name,omitempty"`
	Namespace              string `json:"namespace,omitempty"`
	WorkloadResourceType   string `json:"workload_resource_type,omitempty"`
	AgentVersion           string `json:"agent_version,omitempty"`
	NotInterceptableReason string `json:"not_interceptable_reason,omitempty"`
	// InterceptInfo/IngestInfo are non-empty exactly when the workload
	// currently carries an intercept/replace/wiretap or an ingest,
	// respectively: a suite can assert attach/detach visibility by checking
	// their length, and (via ListEntryIntercept.Spec.Name/ListEntryIngest.
	// Workload) which attachment.
	InterceptInfo []ListEntryIntercept `json:"intercept_info,omitempty"`
	IngestInfo    []ListEntryIngest    `json:"ingest_info,omitempty"`
}

ListEntry mirrors the fields the framework asserts on in one element of the JSON array produced by `telepresence list --format json` (pkg/client/cli/cmd/list.go, rpc/connector.WorkloadInfo; field names verified against rpc/connector/connector.pb.go's WorkloadInfo json tags: intercept_info, ingest_info).

type ListEntryIngest

type ListEntryIngest struct {
	Workload  string `json:"workload,omitempty"`
	Container string `json:"container,omitempty"`
}

ListEntryIngest mirrors the fields the framework asserts on in one element of ListEntry.IngestInfo: rpc/connector.IngestInfo (rpc/connector/ connector.pb.go's json tags: workload, container).

type ListEntryIntercept

type ListEntryIntercept struct {
	ID   string `json:"id,omitempty"`
	Spec struct {
		Name string `json:"name,omitempty"`
	} `json:"spec"`
}

ListEntryIntercept mirrors the fields the framework asserts on in one element of ListEntry.InterceptInfo: rpc/manager.InterceptInfo, whose Name is nested under Spec (rpc/manager/manager.pb.go's InterceptInfo/ InterceptSpec json tags: id, spec.name).

type Proc

type Proc struct {
	// contains filtered or unexported fields
}

Proc is a background CLI invocation started by Start: its stdout/stderr are captured into buffers as it runs, exactly like Run's, but Start returns as soon as the process has launched instead of waiting for it to exit. Signal delivers a signal to it; Wait blocks for completion.

func (*Proc) Signal

func (p *Proc) Signal(sig os.Signal) error

Signal delivers sig to the running process.

func (*Proc) Wait

func (p *Proc) Wait(timeout time.Duration) (stdout, stderr string, err error)

Wait blocks until the process exits, or kills it once timeout elapses; it always releases the context Start armed, either way. It returns the process's captured stdout/stderr; err is the process's own exit error (nil on a clean exit), or a "did not exit" error naming timeout when Wait had to kill it.

type RootDaemonStatus

type RootDaemonStatus struct {
	Running bool   `json:"running,omitempty"`
	Version string `json:"version,omitempty"`
}

RootDaemonStatus is the subset of pkg/client/cli/cmd/status.go's RootDaemonStatus the framework asserts on.

type Status

type Status struct {
	UserDaemon     UserDaemonStatus     `json:"user_daemon"`
	RootDaemon     RootDaemonStatus     `json:"root_daemon"`
	TrafficManager TrafficManagerStatus `json:"traffic_manager"`
}

Status mirrors the fields the framework asserts on in the JSON object produced by `telepresence status --output json` (pkg/client/cli/cmd/status.go: StatusInfo/RootDaemonStatus/UserDaemonStatus/ TrafficManagerStatus).

type TP

type TP struct {
	Exe  string
	Env  []string
	Dir  string
	Logf func(string, ...any)
}

TP wraps the binary under test: env-scrubbed subprocess, stdout/stderr capture.

func (*TP) JSON

func (tp *TP) JSON(ctx context.Context, out any, args ...string) error

JSON runs the binary and unmarshals its stdout into out. Callers pass whichever of --output json / --format json the invoked command supports.

func (*TP) OK

func (tp *TP) OK(t testing.TB, args ...string) string

OK runs the binary and requires it to succeed. A single-line "Warning:" or deprecation notice on stderr is tolerated (and logged); anything else on stderr fails the test, matching the old TelepresenceOk behavior.

func (*TP) Run

func (tp *TP) Run(ctx context.Context, args ...string) (stdout, stderr string, err error)

Run executes the binary with args and returns its captured stdout and stderr.

func (*TP) Start

func (tp *TP) Start(ctx context.Context, args ...string) (*Proc, error)

Start begins the binary with args and returns once it has launched, without waiting for it to exit: for an invocation a test needs to signal or otherwise interact with while it keeps running, e.g. an `intercept --docker-run` handed off to a container and torn down by SIGINT/detach/ disconnect/quit (integration_test/docker_run_test.go:17's runDockerRun). Mirrors Run's env/dir/logging and defaultInvocationTimeout safety net; the timeout bounds the whole Start-to-Wait lifetime (released by Wait), so a Proc nobody ever waits on still gets killed instead of leaking.

type TrafficManagerStatus

type TrafficManagerStatus struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
}

TrafficManagerStatus is the subset of pkg/client/cli/cmd/status.go's TrafficManagerStatus the framework asserts on.

type UserDaemonStatus

type UserDaemonStatus struct {
	Running          bool   `json:"running,omitempty"`
	Version          string `json:"version,omitempty"`
	Namespace        string `json:"namespace,omitempty"`
	ManagerNamespace string `json:"manager_namespace,omitempty"`
}

UserDaemonStatus is the subset of pkg/client/cli/cmd/status.go's UserDaemonStatus the framework asserts on.

type Version

type Version struct {
	Client         string `json:"client,omitempty"`
	RootDaemon     string `json:"root_daemon,omitempty"`
	UserDaemon     string `json:"user_daemon,omitempty"`
	TrafficManager string `json:"traffic_manager,omitempty"`
}

Version mirrors the fields the framework asserts on in the JSON object produced by `telepresence version --output json` (pkg/client/cli/cmd/version.go: versionInfo).