landscape_hostagent_api

package module
v0.0.0-...-590e7d7 Latest Latest
Warning

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

Go to latest
Published: Sep 19, 2025 License: MIT Imports: 9 Imported by: 2

README

Welcome to Landscape to host agent API

License MIR Go Reference documentation

This is the code repository for Landscape to host agent API, referencing the protobuf and gRPC contracts between the landscape server and host agent.

This API allows to communicates actions from Landscape to subsystems installed on a given host. You can think of VMs, containers, WSL instances… Landscape server will instruct the host agent daemon on which machines he needs up and down.

This project does provides Go and Python bindings from the reference protobuf file by autogenerating them.

Get involved

This is an open source project and we warmly welcome community contributions, suggestions, and constructive feedback. If you're interested in contributing, please take a look at our Contribution guidelines first.

  • to report an issue, please file a bug report against our repository, using a bug template.
  • for suggestions and constructive feedback, report a feature request bug report, using the proposed template.

Get in touch

We're friendly! We have a community forum at https://discourse.ubuntu.com where we discuss feature plans, development news, issues, updates and troubleshooting.

For news and updates, follow the Ubuntu twitter account and on Facebook.

Documentation

Index

Constants

View Source
const (
	LandscapeHostAgent_Connect_FullMethodName           = "/landscapehostagentapi.LandscapeHostAgent/Connect"
	LandscapeHostAgent_SendCommandStatus_FullMethodName = "/landscapehostagentapi.LandscapeHostAgent/SendCommandStatus"
)

Variables

View Source
var (
	InstanceState_name = map[int32]string{
		0: "Stopped",
		1: "Running",
	}
	InstanceState_value = map[string]int32{
		"Stopped": 0,
		"Running": 1,
	}
)

Enum value maps for InstanceState.

View Source
var (
	CommandState_name = map[int32]string{
		0: "Queued",
		1: "InProgress",
		2: "Completed",
	}
	CommandState_value = map[string]int32{
		"Queued":     0,
		"InProgress": 1,
		"Completed":  2,
	}
)

Enum value maps for CommandState.

View Source
var File_hostagent_proto protoreflect.FileDescriptor
View Source
var LandscapeHostAgent_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "landscapehostagentapi.LandscapeHostAgent",
	HandlerType: (*LandscapeHostAgentServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "SendCommandStatus",
			Handler:    _LandscapeHostAgent_SendCommandStatus_Handler,
		},
	},
	Streams: []grpc.StreamDesc{
		{
			StreamName:    "Connect",
			Handler:       _LandscapeHostAgent_Connect_Handler,
			ServerStreams: true,
			ClientStreams: true,
		},
	},
	Metadata: "hostagent.proto",
}

LandscapeHostAgent_ServiceDesc is the grpc.ServiceDesc for LandscapeHostAgent service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func RegisterLandscapeHostAgentServer

func RegisterLandscapeHostAgentServer(s grpc.ServiceRegistrar, srv LandscapeHostAgentServer)

Types

type Command

type Command struct {

	// only one command can be passed at a time.
	//
	// Types that are valid to be assigned to Cmd:
	//
	//	*Command_AssignHost_
	//	*Command_Start_
	//	*Command_Stop_
	//	*Command_Install_
	//	*Command_Uninstall_
	//	*Command_SetDefault_
	//	*Command_ShutdownHost_
	Cmd isCommand_Cmd `protobuf_oneof:"cmd"`
	// request_id is a  unique identifier assigned by landscape to each command request.
	RequestId string `protobuf:"bytes,8,opt,name=request_id,json=requestId,proto3" json:"request_id,omitempty"`
	// contains filtered or unexported fields
}

Command is an instruction that landscape can send via its stream to the host agent. The command is self-explanatory or specified.

func (*Command) Descriptor deprecated

func (*Command) Descriptor() ([]byte, []int)

Deprecated: Use Command.ProtoReflect.Descriptor instead.

func (*Command) GetAssignHost

func (x *Command) GetAssignHost() *Command_AssignHost

func (*Command) GetCmd

func (x *Command) GetCmd() isCommand_Cmd

func (*Command) GetInstall

func (x *Command) GetInstall() *Command_Install

func (*Command) GetRequestId

func (x *Command) GetRequestId() string

func (*Command) GetSetDefault

func (x *Command) GetSetDefault() *Command_SetDefault

func (*Command) GetShutdownHost

func (x *Command) GetShutdownHost() *Command_ShutdownHost

func (*Command) GetStart

func (x *Command) GetStart() *Command_Start

func (*Command) GetStop

func (x *Command) GetStop() *Command_Stop

func (*Command) GetUninstall

func (x *Command) GetUninstall() *Command_Uninstall

func (*Command) ProtoMessage

func (*Command) ProtoMessage()

func (*Command) ProtoReflect

func (x *Command) ProtoReflect() protoreflect.Message

func (*Command) Reset

func (x *Command) Reset()

func (*Command) String

func (x *Command) String() string

type CommandState

type CommandState int32

CommandState reports the current state of a command sent from Landscape

const (
	CommandState_Queued     CommandState = 0
	CommandState_InProgress CommandState = 1
	CommandState_Completed  CommandState = 2
)

func (CommandState) Descriptor

func (CommandState) Enum

func (x CommandState) Enum() *CommandState

func (CommandState) EnumDescriptor deprecated

func (CommandState) EnumDescriptor() ([]byte, []int)

Deprecated: Use CommandState.Descriptor instead.

func (CommandState) Number

func (CommandState) String

func (x CommandState) String() string

func (CommandState) Type

type CommandStatus

type CommandStatus struct {

	// request_id is the unique identifier of the command request this message is about.
	RequestId string `protobuf:"bytes,1,opt,name=request_id,json=requestId,proto3" json:"request_id,omitempty"`
	// command_state is the current state of handling for the spcific command being reported.
	CommandState CommandState `` /* 138-byte string literal not displayed */
	// error is the reason of failure to complete such command or empty on the success case.
	Error string `protobuf:"bytes,3,opt,name=error,proto3" json:"error,omitempty"`
	// contains filtered or unexported fields
}

CommandStatus is a message sent by the host agent reporting the current status of a Command.

func (*CommandStatus) Descriptor deprecated

func (*CommandStatus) Descriptor() ([]byte, []int)

Deprecated: Use CommandStatus.ProtoReflect.Descriptor instead.

func (*CommandStatus) GetCommandState

func (x *CommandStatus) GetCommandState() CommandState

func (*CommandStatus) GetError

func (x *CommandStatus) GetError() string

func (*CommandStatus) GetRequestId

func (x *CommandStatus) GetRequestId() string

func (*CommandStatus) ProtoMessage

func (*CommandStatus) ProtoMessage()

func (*CommandStatus) ProtoReflect

func (x *CommandStatus) ProtoReflect() protoreflect.Message

func (*CommandStatus) Reset

func (x *CommandStatus) Reset()

func (*CommandStatus) String

func (x *CommandStatus) String() string

type Command_AssignHost

type Command_AssignHost struct {
	Uid string `protobuf:"bytes,1,opt,name=uid,proto3" json:"uid,omitempty"`
	// contains filtered or unexported fields
}

func (*Command_AssignHost) Descriptor deprecated

func (*Command_AssignHost) Descriptor() ([]byte, []int)

Deprecated: Use Command_AssignHost.ProtoReflect.Descriptor instead.

func (*Command_AssignHost) GetUid

func (x *Command_AssignHost) GetUid() string

func (*Command_AssignHost) ProtoMessage

func (*Command_AssignHost) ProtoMessage()

func (*Command_AssignHost) ProtoReflect

func (x *Command_AssignHost) ProtoReflect() protoreflect.Message

func (*Command_AssignHost) Reset

func (x *Command_AssignHost) Reset()

func (*Command_AssignHost) String

func (x *Command_AssignHost) String() string

type Command_AssignHost_

type Command_AssignHost_ struct {
	AssignHost *Command_AssignHost `protobuf:"bytes,1,opt,name=assign_host,json=assignHost,proto3,oneof"`
}

type Command_Install

type Command_Install struct {
	Id        string  `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	Cloudinit *string `protobuf:"bytes,2,opt,name=cloudinit,proto3,oneof" json:"cloudinit,omitempty"` // cloudinit is the yaml configuration to optionally pass to an instance.
	// URL to a WSL rootfs image we will download and import from. It will be registered under "id".
	// If this entry is not set, Ubuntu Pro for WSL will download a package from the Microsoft store
	// matching WSL distribution name as available in wsl --install.
	RootfsURL *string `protobuf:"bytes,3,opt,name=rootfsURL,proto3,oneof" json:"rootfsURL,omitempty"`
	// contains filtered or unexported fields
}

func (*Command_Install) Descriptor deprecated

func (*Command_Install) Descriptor() ([]byte, []int)

Deprecated: Use Command_Install.ProtoReflect.Descriptor instead.

func (*Command_Install) GetCloudinit

func (x *Command_Install) GetCloudinit() string

func (*Command_Install) GetId

func (x *Command_Install) GetId() string

func (*Command_Install) GetRootfsURL

func (x *Command_Install) GetRootfsURL() string

func (*Command_Install) ProtoMessage

func (*Command_Install) ProtoMessage()

func (*Command_Install) ProtoReflect

func (x *Command_Install) ProtoReflect() protoreflect.Message

func (*Command_Install) Reset

func (x *Command_Install) Reset()

func (*Command_Install) String

func (x *Command_Install) String() string

type Command_Install_

type Command_Install_ struct {
	Install *Command_Install `protobuf:"bytes,4,opt,name=install,proto3,oneof"`
}

type Command_SetDefault

type Command_SetDefault struct {
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// contains filtered or unexported fields
}

SetDefault changes the default instance on the host.

func (*Command_SetDefault) Descriptor deprecated

func (*Command_SetDefault) Descriptor() ([]byte, []int)

Deprecated: Use Command_SetDefault.ProtoReflect.Descriptor instead.

func (*Command_SetDefault) GetId

func (x *Command_SetDefault) GetId() string

func (*Command_SetDefault) ProtoMessage

func (*Command_SetDefault) ProtoMessage()

func (*Command_SetDefault) ProtoReflect

func (x *Command_SetDefault) ProtoReflect() protoreflect.Message

func (*Command_SetDefault) Reset

func (x *Command_SetDefault) Reset()

func (*Command_SetDefault) String

func (x *Command_SetDefault) String() string

type Command_SetDefault_

type Command_SetDefault_ struct {
	SetDefault *Command_SetDefault `protobuf:"bytes,6,opt,name=set_default,json=setDefault,proto3,oneof"`
}

type Command_ShutdownHost

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

ShutdownHost forces a shut down of the agent/controller from landscape perspective (it may autorestart).

func (*Command_ShutdownHost) Descriptor deprecated

func (*Command_ShutdownHost) Descriptor() ([]byte, []int)

Deprecated: Use Command_ShutdownHost.ProtoReflect.Descriptor instead.

func (*Command_ShutdownHost) ProtoMessage

func (*Command_ShutdownHost) ProtoMessage()

func (*Command_ShutdownHost) ProtoReflect

func (x *Command_ShutdownHost) ProtoReflect() protoreflect.Message

func (*Command_ShutdownHost) Reset

func (x *Command_ShutdownHost) Reset()

func (*Command_ShutdownHost) String

func (x *Command_ShutdownHost) String() string

type Command_ShutdownHost_

type Command_ShutdownHost_ struct {
	ShutdownHost *Command_ShutdownHost `protobuf:"bytes,7,opt,name=shutdown_host,json=shutdownHost,proto3,oneof"`
}

type Command_Start

type Command_Start struct {
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// contains filtered or unexported fields
}

func (*Command_Start) Descriptor deprecated

func (*Command_Start) Descriptor() ([]byte, []int)

Deprecated: Use Command_Start.ProtoReflect.Descriptor instead.

func (*Command_Start) GetId

func (x *Command_Start) GetId() string

func (*Command_Start) ProtoMessage

func (*Command_Start) ProtoMessage()

func (*Command_Start) ProtoReflect

func (x *Command_Start) ProtoReflect() protoreflect.Message

func (*Command_Start) Reset

func (x *Command_Start) Reset()

func (*Command_Start) String

func (x *Command_Start) String() string

type Command_Start_

type Command_Start_ struct {
	Start *Command_Start `protobuf:"bytes,2,opt,name=start,proto3,oneof"`
}

type Command_Stop

type Command_Stop struct {
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// contains filtered or unexported fields
}

func (*Command_Stop) Descriptor deprecated

func (*Command_Stop) Descriptor() ([]byte, []int)

Deprecated: Use Command_Stop.ProtoReflect.Descriptor instead.

func (*Command_Stop) GetId

func (x *Command_Stop) GetId() string

func (*Command_Stop) ProtoMessage

func (*Command_Stop) ProtoMessage()

func (*Command_Stop) ProtoReflect

func (x *Command_Stop) ProtoReflect() protoreflect.Message

func (*Command_Stop) Reset

func (x *Command_Stop) Reset()

func (*Command_Stop) String

func (x *Command_Stop) String() string

type Command_Stop_

type Command_Stop_ struct {
	Stop *Command_Stop `protobuf:"bytes,3,opt,name=stop,proto3,oneof"`
}

type Command_Uninstall

type Command_Uninstall struct {
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// contains filtered or unexported fields
}

func (*Command_Uninstall) Descriptor deprecated

func (*Command_Uninstall) Descriptor() ([]byte, []int)

Deprecated: Use Command_Uninstall.ProtoReflect.Descriptor instead.

func (*Command_Uninstall) GetId

func (x *Command_Uninstall) GetId() string

func (*Command_Uninstall) ProtoMessage

func (*Command_Uninstall) ProtoMessage()

func (*Command_Uninstall) ProtoReflect

func (x *Command_Uninstall) ProtoReflect() protoreflect.Message

func (*Command_Uninstall) Reset

func (x *Command_Uninstall) Reset()

func (*Command_Uninstall) String

func (x *Command_Uninstall) String() string

type Command_Uninstall_

type Command_Uninstall_ struct {
	Uninstall *Command_Uninstall `protobuf:"bytes,5,opt,name=uninstall,proto3,oneof"`
}

type Empty

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

func (*Empty) Descriptor deprecated

func (*Empty) Descriptor() ([]byte, []int)

Deprecated: Use Empty.ProtoReflect.Descriptor instead.

func (*Empty) ProtoMessage

func (*Empty) ProtoMessage()

func (*Empty) ProtoReflect

func (x *Empty) ProtoReflect() protoreflect.Message

func (*Empty) Reset

func (x *Empty) Reset()

func (*Empty) String

func (x *Empty) String() string

type HostAgentInfo

type HostAgentInfo struct {
	Token              string                        `protobuf:"bytes,1,opt,name=token,proto3" json:"token,omitempty"`                                                          // token corresponds to the Pro token subscription. Discared on on-prem landscape server.
	Uid                string                        `protobuf:"bytes,2,opt,name=uid,proto3" json:"uid,omitempty"`                                                              // uid is empty on the first request if the host never contacted landscape. Landscape generates one for the hostagent to send it back with each transaction.
	Hostname           string                        `protobuf:"bytes,3,opt,name=hostname,proto3" json:"hostname,omitempty"`                                                    // hostname is literally the name of the host itself.
	Instances          []*HostAgentInfo_InstanceInfo `protobuf:"bytes,4,rep,name=instances,proto3" json:"instances,omitempty"`                                                  // instances are all the machine instances registered on the machine.
	AccountName        string                        `protobuf:"bytes,5,opt,name=account_name,json=accountName,proto3" json:"account_name,omitempty"`                           // account_name is the account used in Landscape SaaS.
	RegistrationKey    *string                       `protobuf:"bytes,6,opt,name=registration_key,json=registrationKey,proto3,oneof" json:"registration_key,omitempty"`         // registration_key is an optional account-wide key used to register clients.
	DefaultInstanceId  *string                       `protobuf:"bytes,7,opt,name=default_instance_id,json=defaultInstanceId,proto3,oneof" json:"default_instance_id,omitempty"` // default_instance_id is the id of the default instance.
	UnmanagedInstances []*HostAgentInfo_InstanceInfo `protobuf:"bytes,8,rep,name=unmanaged_instances,json=unmanagedInstances,proto3" json:"unmanaged_instances,omitempty"`      // unmanaged_instances are all Ubuntu instances
	// contains filtered or unexported fields
}

func (*HostAgentInfo) Descriptor deprecated

func (*HostAgentInfo) Descriptor() ([]byte, []int)

Deprecated: Use HostAgentInfo.ProtoReflect.Descriptor instead.

func (*HostAgentInfo) GetAccountName

func (x *HostAgentInfo) GetAccountName() string

func (*HostAgentInfo) GetDefaultInstanceId

func (x *HostAgentInfo) GetDefaultInstanceId() string

func (*HostAgentInfo) GetHostname

func (x *HostAgentInfo) GetHostname() string

func (*HostAgentInfo) GetInstances

func (x *HostAgentInfo) GetInstances() []*HostAgentInfo_InstanceInfo

func (*HostAgentInfo) GetRegistrationKey

func (x *HostAgentInfo) GetRegistrationKey() string

func (*HostAgentInfo) GetToken

func (x *HostAgentInfo) GetToken() string

func (*HostAgentInfo) GetUid

func (x *HostAgentInfo) GetUid() string

func (*HostAgentInfo) GetUnmanagedInstances

func (x *HostAgentInfo) GetUnmanagedInstances() []*HostAgentInfo_InstanceInfo

func (*HostAgentInfo) ProtoMessage

func (*HostAgentInfo) ProtoMessage()

func (*HostAgentInfo) ProtoReflect

func (x *HostAgentInfo) ProtoReflect() protoreflect.Message

func (*HostAgentInfo) Reset

func (x *HostAgentInfo) Reset()

func (*HostAgentInfo) String

func (x *HostAgentInfo) String() string

type HostAgentInfo_InstanceInfo

type HostAgentInfo_InstanceInfo struct {
	Id            string        `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	Name          string        `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`                            // name is the hostname of the instance.
	VersionId     string        `protobuf:"bytes,3,opt,name=version_id,json=versionId,proto3" json:"version_id,omitempty"` // version_id string as in VERSION_ID in /etc/os-release
	InstanceState InstanceState ``                                                                                         // instance_state are the defined states of the instances.
	/* 142-byte string literal not displayed */
	// contains filtered or unexported fields
}

InstanceInfo gather all the information of a given instance.

func (*HostAgentInfo_InstanceInfo) Descriptor deprecated

func (*HostAgentInfo_InstanceInfo) Descriptor() ([]byte, []int)

Deprecated: Use HostAgentInfo_InstanceInfo.ProtoReflect.Descriptor instead.

func (*HostAgentInfo_InstanceInfo) GetId

func (*HostAgentInfo_InstanceInfo) GetInstanceState

func (x *HostAgentInfo_InstanceInfo) GetInstanceState() InstanceState

func (*HostAgentInfo_InstanceInfo) GetName

func (x *HostAgentInfo_InstanceInfo) GetName() string

func (*HostAgentInfo_InstanceInfo) GetVersionId

func (x *HostAgentInfo_InstanceInfo) GetVersionId() string

func (*HostAgentInfo_InstanceInfo) ProtoMessage

func (*HostAgentInfo_InstanceInfo) ProtoMessage()

func (*HostAgentInfo_InstanceInfo) ProtoReflect

func (*HostAgentInfo_InstanceInfo) Reset

func (x *HostAgentInfo_InstanceInfo) Reset()

func (*HostAgentInfo_InstanceInfo) String

func (x *HostAgentInfo_InstanceInfo) String() string

type InstanceState

type InstanceState int32

InstanceState reports the supported states of an instance communicated by the agent.

const (
	InstanceState_Stopped InstanceState = 0
	InstanceState_Running InstanceState = 1
)

func (InstanceState) Descriptor

func (InstanceState) Enum

func (x InstanceState) Enum() *InstanceState

func (InstanceState) EnumDescriptor deprecated

func (InstanceState) EnumDescriptor() ([]byte, []int)

Deprecated: Use InstanceState.Descriptor instead.

func (InstanceState) Number

func (InstanceState) String

func (x InstanceState) String() string

func (InstanceState) Type

type LandscapeHostAgentClient

type LandscapeHostAgentClient interface {
	Connect(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[HostAgentInfo, Command], error)
	SendCommandStatus(ctx context.Context, in *CommandStatus, opts ...grpc.CallOption) (*Empty, error)
}

LandscapeHostAgentClient is the client API for LandscapeHostAgent service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

LandscapeHostAgent service. The connection is made from the hostagent (client) to the landscape server (sass or on-prem).

type LandscapeHostAgentServer

type LandscapeHostAgentServer interface {
	Connect(grpc.BidiStreamingServer[HostAgentInfo, Command]) error
	SendCommandStatus(context.Context, *CommandStatus) (*Empty, error)
	// contains filtered or unexported methods
}

LandscapeHostAgentServer is the server API for LandscapeHostAgent service. All implementations must embed UnimplementedLandscapeHostAgentServer for forward compatibility.

LandscapeHostAgent service. The connection is made from the hostagent (client) to the landscape server (sass or on-prem).

type LandscapeHostAgent_ConnectClient

type LandscapeHostAgent_ConnectClient = grpc.BidiStreamingClient[HostAgentInfo, Command]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type LandscapeHostAgent_ConnectServer

type LandscapeHostAgent_ConnectServer = grpc.BidiStreamingServer[HostAgentInfo, Command]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type UnimplementedLandscapeHostAgentServer

type UnimplementedLandscapeHostAgentServer struct{}

UnimplementedLandscapeHostAgentServer must be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedLandscapeHostAgentServer) Connect

func (UnimplementedLandscapeHostAgentServer) SendCommandStatus

type UnsafeLandscapeHostAgentServer

type UnsafeLandscapeHostAgentServer interface {
	// contains filtered or unexported methods
}

UnsafeLandscapeHostAgentServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to LandscapeHostAgentServer will result in compilation errors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL