Documentation
¶
Overview ¶
Package client is a thin, ready-to-use gRPC client for the LabManager agent. It handles connection setup and mutual TLS so a caller (e.g. the control plane) only imports this package and calls the typed LabManager RPCs.
Ported from the legacy agent's client wrapper, adapted to the LabManager contract and to mTLS (the LabManager agent authenticates callers by client certificate + CN allowlist, not a JWT token).
Index ¶
- Constants
- Variables
- func Compatible(built, agent string) (bool, error)
- func CountMismatch(err error) (actual int, ok bool)
- func CreationDefinitionHash(specJSON []byte, group string, after []string) (string, error)
- func IsCredentialNotSupported(err error) bool
- func IsImageNotPlatform(err error) bool
- func IsRegistryNotAllowed(err error) bool
- func IsTerminating(err error) bool
- type Client
- type Config
- type GroupLifecycleSpec
- type GroupPodFormula
- type GroupPodsFeature
- type GroupPodsSizingProfile
- type GroupPodsSizingV2
- type GroupRetirementTarget
- type GroupSizingInputs
- type GroupTarget
- type GroupTrafficEnvelope
- type LabLifecycleStatus
- type LabLifecycleTarget
- type LabRetirementTarget
- type LifecycleFeature
- type PodSize
- type ResourceAllocation
- type ResourceAmounts
- type RetireLabGroupsRequest
- type RetireLabsRequest
- type RetirementStatus
- type StartLabGroupsRequest
- type StartLabsRequest
- type StopLabGroupItem
- type StopLabGroupsRequest
- type StopLabItem
- type StopLabsRequest
- type StopSnapshotMode
- type TLS
Constants ¶
const ( MaxMessageSize = 64 << 20 MaxRequestSize = 4 << 20 MaxItems = 5000 )
MaxMessageSize is the largest answer the client accepts, equal to the agent's send limit; MaxRequestSize is the largest request it sends, equal to what the agent reads (a bigger one is refused locally); MaxItems is the most items one call may carry.
const ( StopSnapshotMode_STOP_SNAPSHOT_MODE_UNSPECIFIED = protobuf.StopSnapshotMode_STOP_SNAPSHOT_MODE_UNSPECIFIED StopSnapshotMode_STOP_SNAPSHOT_MODE_SKIP = protobuf.StopSnapshotMode_STOP_SNAPSHOT_MODE_SKIP StopSnapshotMode_STOP_SNAPSHOT_MODE_REQUIRED = protobuf.StopSnapshotMode_STOP_SNAPSHOT_MODE_REQUIRED )
const ( ContractMajor = 3 ContractMinor = 0 )
The API contract of the management agent, "major.minor", is what a caller needs to be compatible with an agent; the image tag says nothing about it (a patch release of the laboratory that touches no call must not stop the daemon).
- A minor is bumped for every additive change of agent.proto (a field, a message, an RPC, an error reason).
- The major is bumped for a change that breaks an existing caller.
- A caller built against contract A.B works with an agent of contract C.D when C == A and D >= B (see Compatible).
pkg/agent/protobuf/contract.lock holds the version and a fingerprint of agent.proto's descriptor; TestContractLock fails when the proto changed without a new version, which forces the bump to be made deliberately. The agent reports the version in GetFeatures (contract_version) and the agent image carries it as the label com.cybericebox.laboratory.api-contract.
const ( // ReasonReservationRequired: a LabGroup or Lab without reservation_id. ReasonReservationRequired = "RESERVATION_REQUIRED" // ReasonReservationNotFound: no reservation with that id in the caller's tenant. ReasonReservationNotFound = "RESERVATION_NOT_FOUND" // ReasonReservationEnded: the reservation takes no more work (ended, being deleted, past its end, or its tenant is // gone). ReasonReservationEnded = "RESERVATION_ENDED" // ReasonReservationFull: the item does not fit the rest of the reservation ("not enough room in this reservation"). // Retryable: room may come back. ReasonReservationFull = "RESERVATION_FULL" // ReasonReservationMismatch: the item's deploy group already runs under another reservation, or an object that has a // reservation would be moved to another one. ReasonReservationMismatch = "RESERVATION_MISMATCH" // ReasonOverQuota: the tenant's overlapping reservations would peak above its quota. ReasonOverQuota = "OVER_QUOTA" // ReasonCooldown: RunChecks came inside the cooldown between manual runs of a lab; ItemResult.retry_after says how // long to wait. ReasonCooldown = "COOLDOWN" )
Reasons of a FAILED ItemResult (ItemResult.reason) for the reservation rules. Every other failure has an empty reason and only the error text.
const ( // ReasonStaleLabReplacing: the name was taken by a Lab of an older generation (an older creation operation of the // same tenant and group); the agent has started deleting it. Retryable: repeat the same create until it succeeds. ReasonStaleLabReplacing = "STALE_LAB_REPLACING" // ReasonLabNameConflict: the name is taken by a Lab the agent will not replace on its own (a newer or an unrelated // generation, or no generation to compare). Not retryable; the caller must delete the Lab or choose another name. ReasonLabNameConflict = "LAB_NAME_CONFLICT" )
Reasons of a FAILED Lab create item whose name is taken by a Lab of another generation.
const ( ProfileContainer = "container" ProfileMicroVM = "microvm" // ProfileVM is reserved: the agent refuses it. ProfileVM = "vm" )
Device profiles (devices[].profile of a lab spec; empty is container).
const ( // ReasonProfileUnsupported: the profile is vm, unknown, or switched off in this laboratory. Not retryable. ReasonProfileUnsupported = "PROFILE_UNSUPPORTED" // known to add one (CapacityResponse.node_profiles: available_now false and not available_after_scale_up). // Not retryable now. ReasonProfileUnavailable = "PROFILE_UNAVAILABLE" )
Reasons of a FAILED Lab create item whose devices ask for a profile that cannot run.
const ( // switch is asked for, and this laboratory runs no VPN. ReasonVPNUnavailable = "VPN_UNAVAILABLE" // laboratory has no internet gateway. ReasonInternetUnavailable = "INTERNET_UNAVAILABLE" ReasonAccessUnavailable = "ACCESS_UNAVAILABLE" ReasonChecksUnavailable = "CHECKS_UNAVAILABLE" )
Reasons of a FAILED item for the feature switches of the laboratory (chart vpn.enabled, inetGateway.enabled, proxy.enabled and its accesses, checks.enabled; contract 2.8). Not retryable: the laboratory does not serve it.
const ( // ReasonGroupVPNOff: a lab with a VPN gateway, or a LabGroupClient, in a group whose VPN is off. Not retryable // until the group's vpn_enabled is turned on (UpdateLabGroups). ReasonGroupVPNOff = "GROUP_VPN_OFF" // ReasonGroupInternetOff: a lab with an Internet gateway in a group whose internet is off. Not retryable until the // group's internet_enabled is turned on. ReasonGroupInternetOff = "GROUP_INTERNET_OFF" // ReasonGroupServerInUse: a switch turned off while a lab of the group uses that server (a VPN gateway, an Internet // gateway). The text names the labs; nothing changed. Delete the labs first. ReasonGroupServerInUse = "GROUP_SERVER_IN_USE" )
Reasons of a FAILED item for the switches of a LabGroup's servers (LabGroupItem.vpn_enabled, internet_enabled; contract 2.7).
const ( // ErrorDomain is the errdetails.ErrorInfo domain of agent-specific errors. ErrorDomain = "agent.cybericebox" // ReasonTerminating is the ErrorInfo reason of a write refused because the // object with that deterministic name is still being deleted (finalizers run // asynchronously). The write was NOT applied; retry after a short delay. ReasonTerminating = "TERMINATING" )
const ReasonCountMismatch = "COUNT_MISMATCH"
ReasonCountMismatch is the ErrorInfo reason of a selector call refused because more objects matched than the call's expected_count. Nothing was done.
const ReasonCredentialNotSupported = "CREDENTIAL_NOT_SUPPORTED"
ReasonCredentialNotSupported is the ErrorInfo reason (domain ErrorDomain, codes.InvalidArgument) of a request refused because a registry credential has no username while the laboratory's image cache is on: the cache carries the tenant in the username ("<tenant>~<user>"), so a credential made of a token alone cannot reach the registry through it. The message names the registry.
const ReasonImageNotPlatform = "IMAGE_NOT_PLATFORM"
ReasonImageNotPlatform is the ErrorInfo reason (domain ErrorDomain, codes.PermissionDenied) of a lab refused because a device image is not an image of the platform registry pinned by digest (platform:<name>@sha256:<hex>) while the tenant or the platform runs platform images only. The message names the variant, the device and the image.
const ReasonLabNotInGroup = "LAB_NOT_IN_GROUP"
ReasonLabNotInGroup: an access policy names Labs that are not in the LabGroup (removed, never created, or of another group). Not retryable. The text lists every such lab id as `lab "id"` / `labs "id1", "id2"`; the caller drops them from the policy and sends it again.
ReasonPersistenceUnavailable: the lab asks for state persistence (devices[].persistence.enabled) and the lab nodes do not confirm that they can keep it (GetFeatures: state_persistence.available false, with an unavailable_reason). Nothing is created or started; the text carries only the fixed reason (`<CODE>:<n>/<m>`). Not retryable until the cluster is repaired.
const ReasonRegistryNotAllowed = "REGISTRY_NOT_ALLOWED"
ReasonRegistryNotAllowed is the ErrorInfo reason (domain ErrorDomain, codes.PermissionDenied) of a lab refused because a device image comes from a registry that is not on the laboratory's list of allowed registries (chart registry.allowedRegistries; GetFeatures reports the list). The message names the variant, the device, the image and its registry.
const ReasonUnsupported = "UNSUPPORTED"
ReasonUnsupported: the agent does not advertise the capability the call needs (GetFeatures.lifecycle: per_lab_stop for StopLabs, retained_restart for StartLabs, full_group_stop for StopLabGroups and StartLabGroups). Not retryable; nothing was changed. The caller must check the capability before it dispatches.
Variables ¶
var ContractVersion = fmt.Sprintf("%d.%d", ContractMajor, ContractMinor)
ContractVersion is the contract of this build of the SDK.
Functions ¶
func Compatible ¶ added in v1.8.0
Compatible says whether a caller built against contract `built` can use an agent that reports contract `agent`. An empty `agent` (an agent older than the field) is compatible only with a caller built against 1.0.
func CountMismatch ¶
CountMismatch reports whether err is the agent's expected_count refusal (codes.FailedPrecondition + reason COUNT_MISMATCH) and the actual number of objects the selector matched.
func CreationDefinitionHash ¶ added in v1.1.0
CreationDefinitionHash binds immutable dispatch evidence to the exact JSON definition before Create. Lifecycle is separate mutable intent; environment values and labels never enter this public fingerprint.
func IsCredentialNotSupported ¶ added in v1.10.0
IsCredentialNotSupported reports whether err is the refusal of a registry credential that has no username.
func IsImageNotPlatform ¶ added in v1.10.0
IsImageNotPlatform reports whether err is the refusal of an image that is not a platform image.
func IsRegistryNotAllowed ¶ added in v1.10.0
IsRegistryNotAllowed reports whether err is the refusal of an image from a registry that is not allowed.
func IsTerminating ¶
IsTerminating reports whether err is the agent's retryable "object is still being deleted" refusal (codes.Unavailable + ErrorInfo reason TERMINATING). The object's deletion is finished once Get* returns codes.NotFound.
Types ¶
type Client ¶
type Client interface {
protobuf.LabManagerClient
Close() error
}
Client is the typed LabManager client plus connection ownership.
func NewConnection ¶
NewConnection dials the LabManager agent and returns a typed client. The caller owns the connection and must Close it. grpc.NewClient is lazy — the actual connection is established on the first RPC.
type Config ¶
type Config struct {
// Endpoint is the agent address, host:port. Dial the agent by its
// certificate hostname (the agent's domain): gRPC then uses that as the
// TLS SNI and verifies it against the server certificate SAN, so no
// separate server-name setting is needed.
Endpoint string
TLS TLS
}
Config describes how to reach a LabManager agent.
type GroupLifecycleSpec ¶ added in v1.1.0
type GroupLifecycleSpec = protobuf.GroupLifecycleSpec
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type GroupPodFormula ¶ added in v1.1.0
type GroupPodFormula = protobuf.GroupPodFormula
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type GroupPodsFeature ¶ added in v1.1.0
type GroupPodsFeature = protobuf.GroupPodsFeature
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type GroupPodsSizingProfile ¶ added in v1.1.0
type GroupPodsSizingProfile = protobuf.GroupPodsSizingProfile
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type GroupPodsSizingV2 ¶ added in v1.1.0
type GroupPodsSizingV2 = protobuf.GroupPodsSizingV2
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type GroupRetirementTarget ¶ added in v1.1.0
type GroupRetirementTarget = protobuf.GroupRetirementTarget
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type GroupSizingInputs ¶ added in v1.1.0
type GroupSizingInputs = protobuf.GroupSizingInputs
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type GroupTarget ¶ added in v1.1.0
type GroupTarget = protobuf.GroupTarget
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type GroupTrafficEnvelope ¶ added in v1.1.0
type GroupTrafficEnvelope = protobuf.GroupTrafficEnvelope
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type LabLifecycleStatus ¶ added in v1.1.0
type LabLifecycleStatus = protobuf.LabLifecycleStatus
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type LabLifecycleTarget ¶ added in v1.1.0
type LabLifecycleTarget = protobuf.LabLifecycleTarget
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type LabRetirementTarget ¶ added in v1.1.0
type LabRetirementTarget = protobuf.LabRetirementTarget
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type LifecycleFeature ¶ added in v1.1.0
type LifecycleFeature = protobuf.LifecycleFeature
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type PodSize ¶ added in v1.1.0
Sizing v2 aliases describe validated profiles without selecting one or changing defaults.
type ResourceAllocation ¶ added in v1.1.0
type ResourceAllocation = protobuf.ResourceAllocation
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type ResourceAmounts ¶ added in v1.1.0
type ResourceAmounts = protobuf.ResourceAmounts
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type RetireLabGroupsRequest ¶ added in v1.1.0
type RetireLabGroupsRequest = protobuf.RetireLabGroupsRequest
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type RetireLabsRequest ¶ added in v1.1.0
type RetireLabsRequest = protobuf.RetireLabsRequest
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type RetirementStatus ¶ added in v1.1.0
type RetirementStatus = protobuf.RetirementStatus
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StartLabGroupsRequest ¶ added in v1.1.0
type StartLabGroupsRequest = protobuf.StartLabGroupsRequest
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StartLabsRequest ¶ added in v1.1.0
type StartLabsRequest = protobuf.StartLabsRequest
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StopLabGroupItem ¶ added in v1.1.0
type StopLabGroupItem = protobuf.StopLabGroupItem
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StopLabGroupsRequest ¶ added in v1.1.0
type StopLabGroupsRequest = protobuf.StopLabGroupsRequest
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StopLabItem ¶ added in v1.1.0
type StopLabItem = protobuf.StopLabItem
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StopLabsRequest ¶ added in v1.1.0
type StopLabsRequest = protobuf.StopLabsRequest
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type StopSnapshotMode ¶ added in v1.1.0
type StopSnapshotMode = protobuf.StopSnapshotMode
Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.
type TLS ¶
type TLS struct {
Enabled bool
CertFile string // client certificate (PEM) presented for mTLS
KeyFile string // client private key (PEM)
CAFile string // CA (PEM) that signed the agent's server certificate; empty = system roots
}
TLS configures the transport. When Enabled, the connection is mutual TLS: the client presents CertFile/KeyFile (whose CN must be a Tenant) and verifies the server against CAFile, or against the system roots when CAFile is empty (a publicly trusted certificate). With no CertFile and KeyFile it is server-authenticated TLS only, for Enroll.