client

package
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2026 License: Apache-2.0 Imports: 62 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CaddyServiceName = "caddy"
	// CaddyImage is the Uncloud Caddy image that is deployed by default. It includes the Uncloud storage module for
	// sharing TLS certificates across machines: https://github.com/unlabs-dev/caddy-uncloud
	CaddyImage = "ghcr.io/unlabs-dev/caddy-uncloud"
	// DefaultCaddyConfig is the default global Caddyfile. It must be compatible with all versions of CaddyImage allowed
	// by caddyImageConstraint.
	DefaultCaddyConfig = "{\n\tstorage uncloud\n}"
	// CaddyStorageFileSystem is the name of the default Caddy storage module that stores TLS assets locally.
	CaddyStorageFileSystem = "file_system"
	// CaddyStorageUncloud is the name of the Caddy storage module that stores TLS assets in the cluster.
	CaddyStorageUncloud = "uncloud"
	// MinCaddyDaemonVersion is the minimum daemon version required for 'uc caddy deploy'. Older daemons don't store
	// service labels that mark the service as managed by this command. Distributed locks were introduced in 0.21.0,
	// which is the minimum required by the cluster storage even on machines that don't run the Caddy service.
	MinCaddyDaemonVersion = "0.22.0"
)

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 CaddyStorageModule added in v0.22.0 

func CaddyStorageModule(config string) string

CaddyStorageModule returns the name of the storage module set in the global options of a Caddyfile.

func IsDefaultCaddyImage added in v0.22.0 

func IsDefaultCaddyImage(image string) bool

IsDefaultCaddyImage returns whether the image is any version of CaddyImage.

func IsNewerCaddyImage added in v0.22.0 

func IsNewerCaddyImage(image, other string) bool

IsNewerCaddyImage returns whether the image is a newer version of CaddyImage than the other image. It returns false if any of the images isn't a version of CaddyImage.

func ProxyMachinesContext added in v0.21.0 

func ProxyMachinesContext(ctx context.Context, namesOrIDs []string) context.Context

ProxyMachinesContext returns a new context that proxies gRPC requests to the specified machines. If namesOrIDs is nil or empty, all machines are included. This triggers One2Many proxying, which always injects metadata into the response. TODO: validate namesOrIDs can't contain "*" as this is reserved as internal value and may break the caller logic.

func ProxySingleMachineContext added in v0.21.0 

func ProxySingleMachineContext(ctx context.Context, nameOrID string) context.Context

ProxySingleMachineContext returns a new context that proxies gRPC requests to a single specified machine. This triggers One2One proxying, which does NOT inject metadata into the response. Use this for requests that expect a single response message without metadata wrapper.

Types

type CaddyClient added in v0.21.0 

type CaddyClient struct {
	// Storage provides low-level access to Caddy's cluster-backed storage.
	Storage pb.CaddyStorageClient
	// contains filtered or unexported fields
}

CaddyClient provides Caddy operations over its parent Client's connection. The parent client owns the connection and must be used to close it.

func (*CaddyClient) CheckDaemonVersions added in v0.22.0 

func (c *CaddyClient) CheckDaemonVersions(ctx context.Context) error

CheckDaemonVersions returns an error naming the available machines whose daemons are older than MinCaddyDaemonVersion. Machines that are down are skipped because a deployment doesn't touch them.

func (*CaddyClient) Config added in v0.21.0 

func (c *CaddyClient) Config(ctx context.Context, opts CaddyConfigOptions) (api.CaddyConfig, error)

Config retrieves the saved Caddy configuration from the machine selected by opts.

func (*CaddyClient) ListCertificates added in v0.21.0 

func (c *CaddyClient) ListCertificates(ctx context.Context, opts CaddyListCertificatesOptions) ([]api.IssuedCertificate, error)

ListCertificates lists issued certificates from the Caddy's managed certificate storage backed by the distributed cluster store. It doesn't verify trust or whether Caddy serves them and may include expired certificates. Private key assets are never read or returned.

This is a non-atomic inventory of one store replica. It does not wait for replication. It returns parsing errors as a combined error, but still returns successfully read certificates regardless of errors.

func (*CaddyClient) NewDeployment added in v0.21.0 

func (c *CaddyClient) NewDeployment(ctx context.Context, opts CaddyDeploymentOptions) (*deploy.Deployment, error)

NewDeployment creates a new managed deployment for a Caddy reverse proxy service. The service is deployed in global mode to all machines in the cluster or the machines set in the placement.

type CaddyConfigOptions added in v0.21.0 

type CaddyConfigOptions struct {
	// Machine is the machine name or ID. If empty, the configuration is retrieved from the machine the client
	// is connected to.
	Machine string
}

CaddyConfigOptions controls which machine's saved Caddy configuration is retrieved.

type CaddyDeploymentOptions added in v0.21.0 

type CaddyDeploymentOptions struct {
	// Image defaults to the latest version of CaddyImage. A non-empty value is marked as custom.
	// Custom images must include curl and start Caddy with /etc/caddy/Caddyfile. They must also include the Uncloud
	// storage module if the config uses 'storage uncloud'.
	Image string
	// Config is the global Caddyfile. Nil means DefaultCaddyConfig. Any other value, even empty, is marked as custom.
	Config    *string
	Placement api.Placement
}

CaddyDeploymentOptions configures a Caddy reverse proxy deployment. The zero value deploys the latest version of CaddyImage with DefaultCaddyConfig to all machines.

func (CaddyDeploymentOptions) ConfigOrDefault added in v0.22.0 

func (o CaddyDeploymentOptions) ConfigOrDefault() string

ConfigOrDefault returns the global Caddyfile of the deployment.

type CaddyListCertificatesOptions added in v0.21.0 

type CaddyListCertificatesOptions struct {
	// Machine is the machine name or ID. If empty, the machine the client is connected to is used.
	Machine string
}

CaddyListCertificatesOptions controls which machine's certificate storage replica is queried.

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 provides Caddy configuration, deployment, and certificate storage operations.
	Caddy *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.LogEntry, 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,
) (api.CreateContainerResponse, 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. The domain must be reserved in Uncloud DNS. Returns the created DNS records or an error.

func (*Client) CreatePreDeployHookContainer added in v0.18.0 

func (cli *Client) CreatePreDeployHookContainer(
	ctx context.Context, serviceID string, spec api.ServiceSpec, machineID string,
) (api.CreateContainerResponse, error)

CreatePreDeployHookContainer creates a one-shot container for a pre-deploy hook for the given service on the specified machine.

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) Dialer added in v0.20.0 

func (cli *Client) Dialer() (proxy.ContextDialer, error)

Dialer returns a proxy dialer for establishing connections within the cluster if supported by the connector.

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) (api.ClusterDomain, error)

GetDomain returns the cluster domain or api.ErrNotFound if none is configured.

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) MachineLogs added in v0.19.0 

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

MachineLogs streams logs for the given system service across one or more machines in chronological order based on timestamps. If opts.Machines is empty, logs are streamed from all machines in the cluster.

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) NewLocker added in v0.21.0 

func (cli *Client) NewLocker(config distlock.Config) (*distlock.Locker, error)

NewLocker creates a distlock.Locker that acquires automatically renewed distributed leases over the machines in the cluster. The Locker uses the client's connection, so callers must release its active leases before closing the client.

func (*Client) ProxyMachinesContext added in v0.15.0 

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

ProxyMachinesContext returns a new context that proxies gRPC requests to the specified machines.

func (*Client) ProxySingleMachineContext added in v0.20.0 

func (cli *Client) ProxySingleMachineContext(ctx context.Context, nameOrID string) context.Context

ProxySingleMachineContext returns a new context that proxies gRPC requests to a single specified machine.

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) RemoveImage added in v0.22.0 

func (cli *Client) RemoveImage(
	ctx context.Context, imageNameOrID string, opts api.RemoveImageOptions,
) ([]api.MachineImageRemoval, error)

RemoveImage removes one exact image name or ID on the selected machines with protection of used references. Results include the outcome of removing an image on each machine.

An absent image on some machines is normal if removal succeeds on at least one machine. If every selected machine reports NotFound, the returned error is api.ErrNotFound. Other machine failures are combined, with successful results still returned.

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) 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) UpdateContainer added in v0.22.0 

func (cli *Client) UpdateContainer(
	ctx context.Context, serviceNameOrID, containerNameOrID string, opts api.UpdateContainerOptions,
) error

UpdateContainer updates the requested properties of the container within the service in place without recreating it.

func (*Client) UpdateMachine added in v0.10.0 

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

UpdateMachine updates the configuration of the machine identified by nameOrID.

func (*Client) WaitClusterReady added in v0.16.0 

func (cli *Client) WaitClusterReady(ctx context.Context, timeout time.Duration) error

WaitClusterReady waits for the connected machine to be ready to serve cluster requests.

func (*Client) WaitContainerHealthy added in v0.17.0 

func (cli *Client) WaitContainerHealthy(
	ctx context.Context, serviceNameOrID, containerNameOrID string, opts api.WaitContainerHealthyOptions,
) error

WaitContainerHealthy polls the container until it is considered running and healthy.

For containers without a health check, it waits for the monitor period and then verifies the container is still running and not restarting.

For containers with a health check, it waits until Docker reports healthy or unhealthy. During the monitor period, unhealthy status is treated as retryable (the container may be recovering from a transient crash). After the monitor period, unhealthy becomes a permanent failure.

func (*Client) WaitForStoreVersion added in v0.21.0 

func (cli *Client) WaitForStoreVersion(ctx context.Context, minVersion api.StoreVersion) error

WaitForStoreVersion waits until the cluster store on the target machine has reached each requested actor version in minVersion, with no known missing or pending transactions through those versions from active members. The context controls cancellation and the deadline. An empty minVersion requires no replication. This method observes replication without initiating synchronisation.

Corrosion may satisfy a version by applying its surviving changes or by marking it complete because its changes have been superseded.

Waiting normally makes the captured data available on the machine. However, another write may replace some of that data before it arrives. Corrosion can then complete the older version without transferring the replaced data. If the replacement is outside the requested versions, this method can succeed while the affected data is still missing or outdated. This can happen during concurrent updates even when all machines are well connected.

Success does not guarantee an exact snapshot or delivery of every historical value. Callers that require a specific record or condition should verify it after waiting.

func (*Client) WaitMachineReady added in v0.16.0 

func (cli *Client) WaitMachineReady(ctx context.Context, timeout time.Duration) error

WaitMachineReady waits for the machine API on the connected machine to respond.

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 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
}

TODO: move PushImageOptions to api package and include PushImage in ImageClient interface.

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.