client

package
v0.15.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2025 License: Apache-2.0 Imports: 52 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CaddyServiceName = "caddy"
	// CaddyImage is the official Caddy Docker image on Docker Hub: https://hub.docker.com/_/caddy
	CaddyImage = "caddy"
)

Variables

View Source 
var DefaultLogMergerOptions = LogMergerOptions{
	StallTimeout:       10 * time.Second,
	StallCheckInterval: 1 * time.Second,
}

DefaultLogMergerOptions provides sensible default options that enable stall detection for LogMerger.

View Source 
var ErrNoReachableMachines = errors.New("no internet-reachable machines running service containers")

Functions

func LatestCaddyImage 

func LatestCaddyImage() (reference.NamedTagged, error)

LatestCaddyImage returns the latest image of the official Caddy Docker image on Docker Hub. The latest image is determined by the latest version tag 2.x.x.

func PrintWarning added in v0.6.0 

func PrintWarning(msg string)

Types

type Client 

type Client struct {

	// TODO: refactor to not embed MachineClient and instead expose only required methods.
	//  Methods such as Reset or Inspect are ambiguous in the context of a machine+cluster client.
	pb.MachineClient
	pb.ClusterClient
	Caddy pb.CaddyClient
	// Docker is a namespaced client for the Docker service to distinguish Uncloud-specific service container operations
	// from generic Docker operations.
	Docker *docker.Client
	// contains filtered or unexported fields
}

Client is a client for the machine API.

func New 

func New(ctx context.Context, connector Connector) (*Client, error)

New creates a new client for the machine API. The connector is used to establish the connection either locally or remotely. The client is responsible for closing the connector.

func (*Client) Close 

func (cli *Client) Close() error

func (*Client) ContainerLogs added in v0.15.0 

func (cli *Client) ContainerLogs(
	ctx context.Context, machineNameOrID string, containerID string, opts api.ServiceLogsOptions,
) (<-chan api.ContainerLogEntry, error)

ContainerLogs streams log entries from a single container on a specified machine.

func (*Client) CreateContainer 

func (cli *Client) CreateContainer(
	ctx context.Context, serviceID string, spec api.ServiceSpec, machineID string,
) (container.CreateResponse, error)

CreateContainer creates a new container for the given service on the specified machine.

func (*Client) CreateIngressRecords 

func (cli *Client) CreateIngressRecords(ctx context.Context, serviceID string) ([]*pb.DNSRecord, error)

CreateIngressRecords verifies which machines running the specified service (typically Caddy) are reachable from the internet, then creates DNS records for the cluster domain pointing to those machines. It tests each machine by sending HTTP requests to their public IPs. Only machines that respond correctly with their machine ID are included in the resulting DNS configuration. Returns the created DNS records or an error.

func (*Client) CreateVolume added in v0.6.0 

func (cli *Client) CreateVolume(
	ctx context.Context, machineNameOrID string, opts volume.CreateOptions,
) (api.MachineVolume, error)

CreateVolume creates a new volume on the specified machine.

func (*Client) ExecContainer added in v0.14.0 

func (cli *Client) ExecContainer(
	ctx context.Context, serviceNameOrID, containerNameOrID string, execOpts api.ExecOptions,
) (int, error)

ExecContainer executes a command in a container within the service. If containerNameOrID is empty, the first container in the service will be used.

func (*Client) GetDomain 

func (cli *Client) GetDomain(ctx context.Context) (string, error)

GetDomain returns the cluster domain name or ErrNotFound if it hasn't been reserved yet.

func (*Client) InspectContainer 

func (cli *Client) InspectContainer(
	ctx context.Context, serviceNameOrID, containerNameOrID string,
) (api.MachineServiceContainer, error)

InspectContainer returns the information about the specified container within the service. containerNameOrID can be name, full ID, or ID prefix of the container.

func (*Client) InspectImage 

func (cli *Client) InspectImage(ctx context.Context, id string) ([]api.MachineImage, error)

func (*Client) InspectMachine 

func (cli *Client) InspectMachine(ctx context.Context, nameOrID string) (*pb.MachineMember, error)

func (*Client) InspectRemoteImage 

func (cli *Client) InspectRemoteImage(ctx context.Context, id string) ([]api.MachineRemoteImage, error)

func (*Client) InspectService 

func (cli *Client) InspectService(ctx context.Context, nameOrID string) (api.Service, error)

InspectService returns detailed information about a service and its containers. The nameOrID parameter can be either a service name or ID.

func (*Client) InspectServiceFromStore 

func (cli *Client) InspectServiceFromStore(ctx context.Context, id string) (api.Service, error)

InspectServiceFromStore returns detailed information about a service and its containers from the distributed store. Due to eventual consistency of the store, the returned information may not reflect the most recent changes. The id parameter can be either a service ID or name.

func (*Client) ListImages added in v0.13.0 

func (cli *Client) ListImages(ctx context.Context, filter api.ImageFilter) ([]api.MachineImages, error)

ListImages returns a list of images on specified machines in the cluster. If no machines are specified in the filter, it lists images on all machines.

func (*Client) ListMachines 

func (cli *Client) ListMachines(ctx context.Context, filter *api.MachineFilter) (api.MachineMembersList, error)

ListMachines returns a list of all machines registered in the cluster that match the filter.

func (*Client) ListServices 

func (cli *Client) ListServices(ctx context.Context) ([]api.Service, error)

ListServices returns a list of all services and their containers.

func (*Client) ListVolumes added in v0.6.0 

func (cli *Client) ListVolumes(ctx context.Context, filter *api.VolumeFilter) ([]api.MachineVolume, error)

ListVolumes returns a list of all volumes on the cluster machines that match the filter.

func (*Client) NewCaddyDeployment 

func (cli *Client) NewCaddyDeployment(image, config string, placement api.Placement) (*deploy.Deployment, error)

NewCaddyDeployment creates a new deployment for a Caddy reverse proxy service. The service is deployed in global mode to all machines in the cluster. If the image is not provided, the latest version of the official Caddy Docker image is used.

func (*Client) NewDeployment 

func (cli *Client) NewDeployment(spec api.ServiceSpec, strategy deploy.Strategy) *deploy.Deployment

NewDeployment creates a new deployment for the given service specification. If strategy is nil, a default deploy.RollingStrategy will be used.

func (*Client) ProxyMachinesContext added in v0.15.0 

func (cli *Client) ProxyMachinesContext(
	ctx context.Context, namesOrIDs []string,
) (context.Context, api.MachineMembersList, error)

ProxyMachinesContext returns a new context that proxies gRPC requests to the specified machines. If namesOrIDs is nil, all machines are included.

func (*Client) PushImage added in v0.13.0 

func (cli *Client) PushImage(ctx context.Context, image string, opts PushImageOptions) error

PushImage pushes a local Docker image to the specified machines. If no machines are specified, it pushes to the machine the client is connected to.

func (*Client) RemoveContainer 

func (cli *Client) RemoveContainer(
	ctx context.Context, serviceNameOrID, containerNameOrID string, opts container.RemoveOptions,
) error

RemoveContainer removes the specified container within the service.

func (*Client) RemoveService 

func (cli *Client) RemoveService(ctx context.Context, id string) error

RemoveService removes all containers on all machines that belong to the specified service. The id parameter can be either a service ID or name.

func (*Client) RemoveVolume added in v0.6.0 

func (cli *Client) RemoveVolume(ctx context.Context, machineNameOrID, volumeName string, force bool) error

RemoveVolume removes a volume from the specified machine.

func (*Client) RenameMachine added in v0.10.0 

func (cli *Client) RenameMachine(ctx context.Context, nameOrID, newName string) (*pb.MachineInfo, error)

RenameMachine renames an existing machine in the cluster.

func (*Client) RunService 

func (cli *Client) RunService(ctx context.Context, spec api.ServiceSpec) (api.RunServiceResponse, error)

func (*Client) ServiceLogs added in v0.15.0 

func (cli *Client) ServiceLogs(
	ctx context.Context, serviceNameOrID string, opts api.ServiceLogsOptions,
) (api.Service, <-chan api.ServiceLogEntry, error)

ServiceLogs streams log entries from all service containers in chronological order based on timestamps. Keep in mind that perfect ordering of log events across multiple machines can't be guaranteed due to the imperfection of physical clocks or potential clock skew between machines. It uses a low watermark algorithm to ensure proper ordering across multiple machines. Heartbeat entries from the server advance the watermark to enable timely emission of buffered logs.

func (*Client) ServiceOperationNameResolver 

func (cli *Client) ServiceOperationNameResolver(ctx context.Context, svc api.Service) (*MapNameResolver, error)

ServiceOperationNameResolver returns a machine and container name resolver for a service that can be used to format deployment operations.

func (*Client) StartContainer 

func (cli *Client) StartContainer(ctx context.Context, serviceNameOrID, containerNameOrID string) error

StartContainer starts the specified container within the service.

func (*Client) StartService added in v0.15.0 

func (cli *Client) StartService(ctx context.Context, id string) error

StartService starts all containers on all machines that belong to the specified service. The id parameter can be either a service ID or name.

func (*Client) StopContainer 

func (cli *Client) StopContainer(
	ctx context.Context, serviceNameOrID, containerNameOrID string, opts container.StopOptions,
) error

StopContainer stops the specified container within the service.

func (*Client) StopService added in v0.15.0 

func (cli *Client) StopService(ctx context.Context, id string, opts container.StopOptions) error

StopService stops all containers on all machines that belong to the specified service. The id parameter can be either a service ID or name.

func (*Client) UpdateMachine added in v0.10.0 

func (cli *Client) UpdateMachine(ctx context.Context, req *pb.UpdateMachineRequest) (*pb.MachineInfo, error)

UpdateMachine updates machine configuration in the cluster.

type Connector 

type Connector interface {
	// Connect establishes a gRPC client connection to the machine API.
	Connect(ctx context.Context) (*grpc.ClientConn, error)
	// Dialer returns a proxy dialer for establishing connections within the cluster if supported by the connector.
	Dialer() (proxy.ContextDialer, error)
	Close() error
}

Connector is an interface for establishing a connection to the cluster.

type LogMerger added in v0.15.0 

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

LogMerger merges multiple log streams into a single chronologically ordered stream based on timestamps. It uses a low watermark algorithm to ensure proper ordering across streams. Heartbeat entries from streams advance the watermark to enable timely emission of buffered logs.

func NewLogMerger added in v0.15.0 

func NewLogMerger(streams []<-chan api.ServiceLogEntry, opts LogMergerOptions) *LogMerger

NewLogMerger creates a new LogMerger for the given input streams with the specified options.

func (*LogMerger) Stream added in v0.15.0 

func (m *LogMerger) Stream() <-chan api.ServiceLogEntry

Stream starts the merge process and returns a channel that emits log entries in chronological order. The returned channel is closed when all input streams are closed.

type LogMergerOptions added in v0.15.0 

type LogMergerOptions struct {
	// StallTimeout specifies how long a stream can go without receiving any data before it's considered
	// stalled and excluded from watermark calculation. A zero timeout disables stall detection.
	StallTimeout time.Duration
	// StallCheckInterval specifies how often to check for stalled streams.
	StallCheckInterval time.Duration
}

LogMergerOptions configures the behavior of LogMerger.

type MapNameResolver 

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

MapNameResolver resolves machine and container IDs to their names using a static map.

func NewNameResolver 

func NewNameResolver(machines, containers map[string]string) *MapNameResolver

func (*MapNameResolver) ContainerName 

func (r *MapNameResolver) ContainerName(containerID string) string

func (*MapNameResolver) MachineName 

func (r *MapNameResolver) MachineName(machineID string) string

type PushImageOptions added in v0.13.0 

type PushImageOptions struct {
	// AllMachines pushes the image to all machines in the cluster. Takes precedence over Machines field.
	AllMachines bool
	// Machines is a list of machine names or IDs to push the image to. If empty and AllMachines is false,
	// pushes to the machine the client is connected to.
	Machines []string
	// Platform to push for a multi-platform image. Local Docker must use containerd image store
	// to support multi-platform images.
	Platform *ocispec.Platform
}

type User 

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

func NewUser 

func NewUser(privateKey secret.Secret) (*User, error)

func (*User) ManagementIP 

func (u *User) ManagementIP() netip.Addr

func (*User) PrivateKey 

func (u *User) PrivateKey() secret.Secret

func (*User) PublicKey 

func (u *User) PublicKey() secret.Secret

Source Files

View all Source files

Directories

Path Synopsis
scheduler

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.