api

Documentation

Index

• type Client
• type CmdHandler
  • func (CmdHandler) Type() InterceptHandlerType
• type ConnectRequest
• type Connection
• type DockerBuildInterceptHandler
  • func (DockerBuildInterceptHandler) Type() InterceptHandlerType
• type DockerRunInterceptHandler
  • func (DockerRunInterceptHandler) Type() InterceptHandlerType
• type InterceptHandler
• type InterceptHandlerType
• type InterceptRequest
• type SubnetViaWorkload

Types

type Client

type Client interface {
	// Connect returns a connection that corresponds to the given connect request.
	Connect(cr ConnectRequest) (Connection, error)

	// Connection returns an existing connection. An empty name can be used when only one
	// connection exists.
	Connection(name string) (Connection, error)

	// Connections returns a list of existing connections.
	Connections() ([]*daemon.Info, error)

	// Helm will install, upgrade, or uninstall the traffic-manager.
	Helm(hr *helm.Request, cr ConnectRequest) error

	// QuitAllDaemons will quit all running daemons
	QuitAllDaemons()

	// Version returns the client version
	Version() semver.Version
}

type CmdHandler

type CmdHandler struct {
	// MountPoint is the path to where the remote container's mounts will be mounted. A temporary directory
	// will be used if MountPoint is unset.
	//
	// MountPoint is either a path indicating where to mount the intercepted container's volumes, the string
	// "true", to mount to a generated temporary folder, or empty to disable mounting altogether.
	MountPoint string

	// CmdLine a command to execute during the time when the intercept is active.
	Cmdline []string
}

func (CmdHandler) Type

func (CmdHandler) Type() InterceptHandlerType

type ConnectRequest

type ConnectRequest struct {
	// Kubernetes flags to use when connecting. Multi-values must be in CSV form
	KubeFlags map[string]string

	// KubeConfig YAML, if not to be loaded from file.
	KubeConfigData []byte

	// Name of this connection
	Name string

	// MappedNamespaces can be used to limit the namespaces that the DNS will
	// treat as top level domain names.
	MappedNamespaces []string

	// ManagerNamespace is the namespace where the traffic-manager lives. Will
	// default to "ambassador".
	ManagerNamespace string

	// AlsoProxy are subnets that the VIF will route in addition to the subnets
	// that the traffic-manager announces from the cluster.
	AlsoProxy []netip.Prefix

	// NeverProxy are subnets that the VIF will refrain from routing although they
	// were announced by the traffic-manager.
	NeverProxy []netip.Prefix

	// AllowConflictingSubnets are subnets that are allowed to be in conflict with
	// other subnets in the client's network. Telepresence will try to give the VIF
	// higher priority for those subnets.
	AllowConflictingSubnets []netip.Prefix

	// SubnetVieWorkloads are subnet to workload mappings that will cause virtual subnets
	// to be used in the client and the routed to the given workload.
	SubnetViaWorkloads []SubnetViaWorkload

	// If set, then use a containerized daemon for the connection.
	Docker bool

	// Ports exposed by a containerized daemon. Only valid when Docker == true
	ExposedPorts []string

	// Hostname used by a containerized daemon. Only valid when Docker == true
	Hostname string

	// UserDaemonProfilingPort port to use when profiling the user daemon
	UserDaemonProfilingPort uint16

	// RootDaemonProfilingPort port to use when profiling the root daemon
	RootDaemonProfilingPort uint16

	// Stdout is the stream that receives messages during connect
	Stdout io.Writer
}

type Connection

type Connection interface {
	io.Closer

	// Namespace returns the connected namespace
	Namespace() string

	// AgentImage returns the Reference that denotes the image used by the traffic-agent.
	AgentImage() (reference.Reference, error)

	// StartIntercept starts a new intercept. The mountPoint is either a path indicating
	// where to mount the intercepted container's volumes, the string "true" to
	// mount to a generated temporary folder, or empty to disable mounting altogether.
	StartIntercept(rq InterceptRequest, mountPoint string) (*intercept.Info, error)

	// RunIntercept starts a new intercept, executes the given command, then ends the intercept.
	RunIntercept(InterceptRequest, InterceptHandler) (*intercept.Info, error)

	// Info returns the ConnectInfo for the connection.
	Info() *connector.ConnectInfo

	// DaemonInfo returns information about the daemon that manages the current connection.
	DaemonInfo() (*daemon.Info, error)

	// Disconnect tells the daemon to disconnect from the cluster and end the session.
	Disconnect() error

	// List lists the workloads in the given namespace that are possible to intercept. If
	// namespace is an empty string, the current namespace will be used.
	List(namespace string) ([]*connector.WorkloadInfo, error)

	// EndIntercept ends a previously started intercept.
	EndIntercept(name string) error
}

Connection represents a Telepresence client connection to a namespace in a cluster.

type DockerBuildInterceptHandler

type DockerBuildInterceptHandler struct {
	// Mount if true, will cause the volumes of the remote container to be mounted using
	// the telemount Docker volume plugin.
	Mount bool

	// Context docker context, in the form of a path or a URL.
	Context string

	// Options for the docker build command. Must be in the form <key>=<value> or just <key>
	// for boolean options. Short form options are not supported.
	BuildOptions []string

	// Options for the docker run command. Must be in the form <key>=<value> or just <key>
	// for boolean options. Short form options are not supported so `-it` must be added as
	// []string{"interactive", "tty"}
	Options []string

	// Arguments for to pass to the container
	Arguments []string

	// Debug uses relaxed security to allow a debugger run in the container.
	// Mutually exclusive to DockerRun and DockerBuild.
	Debug bool
}

func (DockerBuildInterceptHandler) Type

func (DockerBuildInterceptHandler) Type() InterceptHandlerType

type DockerRunInterceptHandler

type DockerRunInterceptHandler struct {
	// Mount if true, will cause the volumes of the remote container to be mounted using
	// the telemount Docker volume plugin.
	Mount bool

	// Image is the image tag
	Image string

	// Options for the docker run command. Must be in the form <key>=<value> or just <key>
	// for boolean options. Short form options are not supported so `-it` must be added as
	// []string{"interactive", "tty"}
	Options []string

	// Arguments for to pass to the container
	Arguments []string
}

func (DockerRunInterceptHandler) Type

func (DockerRunInterceptHandler) Type() InterceptHandlerType

type InterceptHandler

type InterceptHandler interface {
	Type() InterceptHandlerType
}

type InterceptHandlerType

type InterceptHandlerType int

const (
	CommandHandler InterceptHandlerType = iota
	DockerRunHandler
	DockerBuildHandler
)

type InterceptRequest

type InterceptRequest struct {
	// Name of the intercept.
	Name string

	// Name of the intercepted workload. Will default to intercept name.
	WorkloadName string

	// Port string. Can contain three fields separated by colon. The interpretation of
	// the fields differ depending on if Docker is true or false.
	//
	//   With Docker == false
	//     <local port number>
	//     <local port number>:<service port identifier>
	//
	//   With Docker == true
	//     <local port number>:<container port number>
	//     <local port number>:<container port number>:<service port identifier>
	Port string

	// ServiceName is the name of the intercepted service. Only needed to resolve ambiguities in
	// case multiple services use the same workload.
	ServiceName string

	// Address The local IP address, in case the intercepted traffic should be sent to something other
	// than localhost.
	Address netip.Addr

	// LocalMountPort is a port where the remote sftp server can be reached. If set, then Telepresence
	// will assume that the caller is responsible for starting the sshfs client that will do the mounting.
	LocalMountPort uint16

	// Replace indicates that the intercepted container should be replaced by the intercept, and then
	// restored when the intercept ends.
	Replace bool

	// EnvFile denotes the path to a file that will receive the intercepted containers environment in a
	// Docker Compose format. See https://docs.docker.com/compose/env-file/ for details.
	EnvFile string

	// EnvJSON denotes the path to a file that will receive the intercepted environment as a JSON object.
	EnvJSON string

	// ToPod adds additional ports to forward from the intercepted pod, will be made available at localhost:PORT.
	// Use this to, for example, access proxy/helper sidecars in the intercepted pod.
	ToPod []netip.AddrPort

	// ToPodUDP is like ToPod, but uses UDP protocol.
	ToPodUDP []netip.AddrPort

	// Silent will silence the intercept information. It will not silence the intercept handler.
	Silent bool
}

type SubnetViaWorkload

type SubnetViaWorkload struct {
	Subnet   string
	Workload string
}