nvfleetint

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Aug 12, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package nvfleetint provides a Go SDK for the Fleet Intelligence customer API.

Index

Constants

View Source
const (
	AlertSeverityCritical AlertSeverity = "Critical"
	AlertSeverityWarning  AlertSeverity = "Warning"

	AlertStateDetected  AlertState = "Detected"
	AlertStateTriggered AlertState = "Triggered"
	AlertStateResolved  AlertState = "Resolved"

	AlertTimelineStateCritical AlertTimelineState = "Critical"
	AlertTimelineStateWarning  AlertTimelineState = "Warning"
	AlertTimelineStateResolved AlertTimelineState = "Resolved"

	AlertTimelineNodeSortByHostname    AlertTimelineNodeSortBy = "hostname"
	AlertTimelineNodeSortByAlert       AlertTimelineNodeSortBy = "alert"
	AlertTimelineNodeSortByGPUType     AlertTimelineNodeSortBy = "gpuType"
	AlertTimelineNodeSortByNodeGroup   AlertTimelineNodeSortBy = "nodeGroup"
	AlertTimelineNodeSortByComputeZone AlertTimelineNodeSortBy = "computeZone"
	AlertTimelineNodeSortByLastUpdate  AlertTimelineNodeSortBy = "lastUpdate"

	AlertTimelineAlertSortByComponent  AlertTimelineAlertSortBy = "component"
	AlertTimelineAlertSortByStartTime  AlertTimelineAlertSortBy = "startTime"
	AlertTimelineAlertSortByLastUpdate AlertTimelineAlertSortBy = "lastUpdate"

	AlertTimelineOrderAsc  AlertTimelineSortOrder = "asc"
	AlertTimelineOrderDesc AlertTimelineSortOrder = "desc"
)
View Source
const (
	NodeViewDetail NodeView = "detail"
	NodeViewBasic  NodeView = "basic"

	NodeHealthHealthy   NodeHealthStatus = "Healthy"
	NodeHealthDegraded  NodeHealthStatus = "Degraded"
	NodeHealthUnhealthy NodeHealthStatus = "Unhealthy"
	NodeHealthUnknown   NodeHealthStatus = "Unknown"

	NodeIntegrityVerified    NodeIntegrityCheck = "Verified"
	NodeIntegrityUnverified  NodeIntegrityCheck = "Unverified"
	NodeIntegrityDegraded    NodeIntegrityCheck = "Degraded"
	NodeIntegrityPending     NodeIntegrityCheck = "Pending"
	NodeIntegrityUnsupported NodeIntegrityCheck = "Unsupported"
	NodeIntegrityUnknown     NodeIntegrityCheck = "Unknown"
	// Deprecated: use NodeIntegrityVerified
	NodeIntegrityPassed NodeIntegrityCheck = NodeIntegrityVerified
	// Deprecated: use NodeIntegrityUnverified
	NodeIntegrityFailed NodeIntegrityCheck = NodeIntegrityUnverified

	NodeFirmwarePassed  NodeFirmwareCheck = "Passed"
	NodeFirmwareFailed  NodeFirmwareCheck = "Failed"
	NodeFirmwareUnknown NodeFirmwareCheck = "Unknown"

	NodeAgentOnline  NodeAgentStatus = "Online"
	NodeAgentOffline NodeAgentStatus = "Offline"
	NodeAgentUnknown NodeAgentStatus = "Unknown"

	NodeSortByHostname            NodeSortBy = "hostname"
	NodeSortByUUID                NodeSortBy = "nodeUUID"
	NodeSortByHealthStatus        NodeSortBy = "healthStatus"
	NodeSortByNodeGroup           NodeSortBy = "nodegroup"
	NodeSortByComputeZone         NodeSortBy = "computezone"
	NodeSortByGPUType             NodeSortBy = "gpuType"
	NodeSortByGPUCount            NodeSortBy = "gpuCount"
	NodeSortByIntegrityCheck      NodeSortBy = "integrityCheck"
	NodeSortByAgentStatus         NodeSortBy = "agentStatus"
	NodeSortByAgentVersion        NodeSortBy = "agentVersion"
	NodeSortByKernelVersion       NodeSortBy = "kernelVersion"
	NodeSortByGPUDriverVersion    NodeSortBy = "gpuDriverVersion"
	NodeSortByGPUFirmwareVersions NodeSortBy = "gpuFirmwareVersions"

	NodeOrderAsc  NodeSortOrder = "asc"
	NodeOrderDesc NodeSortOrder = "desc"
)
View Source
const (
	NodeGroupViewDetail NodeGroupView = "detail"
	NodeGroupViewBasic  NodeGroupView = "basic"

	NodeGroupHealthHealthy   NodeGroupHealthStatus = "Healthy"
	NodeGroupHealthDegraded  NodeGroupHealthStatus = "Degraded"
	NodeGroupHealthUnhealthy NodeGroupHealthStatus = "Unhealthy"
	NodeGroupHealthUnknown   NodeGroupHealthStatus = "Unknown"

	NodeGroupSortByHealth NodeGroupSortBy = "health"
	NodeGroupSortByNodes  NodeGroupSortBy = "nodes"

	NodeGroupOrderAsc  NodeGroupSortOrder = "asc"
	NodeGroupOrderDesc NodeGroupSortOrder = "desc"
)
View Source
const (
	ReportFormatJSON ReportFormat = "json"
	ReportFormatCSV  ReportFormat = "csv"

	ErrorReportViewList     ErrorReportView = "list"
	ErrorReportViewGraph    ErrorReportView = "graph"
	ErrorReportViewOverview ErrorReportView = "overview"

	ErrorReportGroupByError ErrorReportGroupBy = "error"
	ErrorReportGroupByNode  ErrorReportGroupBy = "node"

	ErrorReportTimeModeAbsolute ErrorReportTimeMode = "absolute"
	ErrorReportTimeModeRelative ErrorReportTimeMode = "relative"

	InventoryReportSortByHostname       InventoryReportSortBy = "hostname"
	InventoryReportSortByNodeUUID       InventoryReportSortBy = "nodeUUID"
	InventoryReportSortByNodeGroup      InventoryReportSortBy = "nodegroup"
	InventoryReportSortByComputeZone    InventoryReportSortBy = "computezone"
	InventoryReportSortByGPUType        InventoryReportSortBy = "gpuType"
	InventoryReportSortByGPUCount       InventoryReportSortBy = "gpuCount"
	InventoryReportSortByPublicIP       InventoryReportSortBy = "publicIP"
	InventoryReportSortByPrivateIP      InventoryReportSortBy = "privateIP"
	InventoryReportSortByIntegrityCheck InventoryReportSortBy = "integrityCheck"
	InventoryReportSortByGeoLocation    InventoryReportSortBy = "geoLocation"

	InventoryReportOrderAsc  InventoryReportSortOrder = "asc"
	InventoryReportOrderDesc InventoryReportSortOrder = "desc"
)
View Source
const DefaultTimeout = 2 * time.Minute

DefaultTimeout is the per-request timeout applied when none is configured.

View Source
const MaxEventBuckets = 1000

MaxEventBuckets is the largest number of histogram buckets the events buckets endpoint accepts.

Variables

View Source
var (
	ErrMissingBaseURL = errors.New("base URL is required")
	ErrMissingAPIKey  = errors.New("API key is required")
)
View Source
var (
	// ErrInvalidKey means the supplied data is not a PEM-encoded public key.
	ErrInvalidKey = errors.New("invalid public key: expected a PEM-encoded public key")
	// ErrInvalidBundle means the supplied data is not a Sigstore .sig.bundle.
	ErrInvalidBundle = errors.New("invalid signature bundle: expected a Sigstore .sig.bundle file")
	// ErrVerificationFailed means the report does not match the signature.
	ErrVerificationFailed = errors.New("signature verification failed: the report does not match the signature")
)

Errors returned by VerifySignedReport. They are sentinels so callers can distinguish the failure mode (e.g. with errors.Is) and present their own messages instead of the underlying sigstore/proto details.

View Source
var ErrInsecureBaseURL = errors.New("insecure base URL: https is required")

ErrInsecureBaseURL indicates the base URL would send the API key over an unencrypted connection. Plain http is accepted only for loopback hosts.

View Source
var ErrResponseTooLarge = errors.New("API response exceeded the maximum allowed size")

ErrResponseTooLarge reports that an API response outgrew the size the SDK is willing to buffer and was refused before being parsed.

Functions

func ValidateBaseURL

func ValidateBaseURL(rawURL string) error

ValidateBaseURL reports whether rawURL is usable as a Fleet Intelligence API root. It must be an absolute https URL, except that plain http is permitted for loopback hosts (127.0.0.0/8, ::1, localhost) so local mock servers and tests keep working without exposing credentials off the machine.

func VerifySignedReport

func VerifySignedReport(csv, bundleJSON, publicKeyPEM []byte) error

VerifySignedReport verifies that csv was signed with the public key in publicKeyPEM, using the Sigstore bundle in bundleJSON. It mirrors `cosign verify-blob --key <key> --bundle <bundle> --insecure-ignore-tlog <csv>`: the signature is checked against an out-of-band public key while the transparency log and observer timestamps are intentionally not required. It returns nil when verification succeeds and a descriptive error otherwise.

Types

type APIError

type APIError struct {
	StatusCode int
	Status     string
	Message    string
	Details    string
}

Represents a non-success API response

func (*APIError) Error

func (e *APIError) Error() string

Formats API failures with status and response details

type Alert

type Alert struct {
	UUID                 string `json:"alertUUID"`
	NodeUUID             string `json:"nodeUUID,omitempty"`
	Component            string `json:"component,omitempty"`
	ComponentDisplayName string `json:"componentDisplayName,omitempty"`
	Severity             string `json:"severity,omitempty"`
	State                string `json:"state,omitempty"`
	Message              string `json:"message,omitempty"`
	Error                string `json:"error,omitempty"`
	DetectedAt           string `json:"detectedAt,omitempty"`
	TriggeredAt          string `json:"triggeredAt,omitempty"`
	EventTimestamp       string `json:"eventTimestamp,omitempty"`
	LastUpdated          string `json:"lastUpdated,omitempty"`
	FiredAt              string `json:"firedAt,omitempty"`
}

Represents an alert

type AlertSeverity

type AlertSeverity string

Represents supported alert severity filters

func (AlertSeverity) Valid

func (severity AlertSeverity) Valid() bool

Reports whether the alert severity is accepted by the API

type AlertState

type AlertState string

Represents supported alert state filters

func (AlertState) Valid

func (state AlertState) Valid() bool

Reports whether the alert state is accepted by the API

type AlertTimelineAlertSortBy

type AlertTimelineAlertSortBy string

Represents supported sort fields for alerts within one node

func (AlertTimelineAlertSortBy) Valid

func (sortBy AlertTimelineAlertSortBy) Valid() bool

Reports whether the alert sort field is accepted by the API

type AlertTimelineDetails

type AlertTimelineDetails struct {
	AlertUUID            string               `json:"alertUuid"`
	NodeUUID             string               `json:"nodeUuid,omitempty"`
	Component            string               `json:"component,omitempty"`
	ComponentDisplayName string               `json:"componentDisplayName,omitempty"`
	AlertStatus          string               `json:"alertStatus,omitempty"`
	NodeGroup            string               `json:"nodeGroup,omitempty"`
	ComputeZone          string               `json:"computeZone,omitempty"`
	CustomerID           string               `json:"customerID,omitempty"`
	IsBackendComponent   bool                 `json:"isBackendComponent,omitempty"`
	HasMore              bool                 `json:"hasMore,omitempty"`
	Page                 int                  `json:"page,omitempty"`
	PageSize             int                  `json:"pageSize,omitempty"`
	Total                int                  `json:"total,omitempty"`
	Timeline             []AlertTimelineEvent `json:"timeline"`
	RawJSON              []byte               `json:"-"`
}

Represents the full timeline for one alert

type AlertTimelineEvent

type AlertTimelineEvent struct {
	EventType      string            `json:"eventType,omitempty"`
	AlertStatus    string            `json:"alertStatus,omitempty"`
	EventTimestamp string            `json:"eventTimestamp,omitempty"`
	Message        string            `json:"message,omitempty"`
	Error          string            `json:"error,omitempty"`
	ExtraInfo      map[string]any    `json:"extraInfo,omitempty"`
	Incidents      []any             `json:"incidents,omitempty"`
	Actions        []SuggestedAction `json:"suggestedActions,omitempty"`
}

Represents one event in an alert timeline

type AlertTimelineFilterField

type AlertTimelineFilterField struct {
	Name    string                      `json:"name"`
	Options []AlertTimelineFilterOption `json:"options"`
}

Represents one alert timeline filter and its available values.

type AlertTimelineFilterOption

type AlertTimelineFilterOption struct {
	ID    string `json:"-"`
	Value string `json:"-"`
}

Represents either a simple string option or an object option with an ID and display value.

func (AlertTimelineFilterOption) MarshalJSON

func (option AlertTimelineFilterOption) MarshalJSON() ([]byte, error)

Preserves the option's original string or object shape when marshaling.

func (*AlertTimelineFilterOption) UnmarshalJSON

func (option *AlertTimelineFilterOption) UnmarshalJSON(data []byte) error

Decodes the string and object forms used by the shared options API.

type AlertTimelineFilterOptions

type AlertTimelineFilterOptions struct {
	Filters AlertTimelineFilters        `json:"filters"`
	Sorting AlertTimelineSortingOptions `json:"sorting"`
	RawJSON []byte                      `json:"-"`
}

Represents the alert timeline filters and sorting choices available to the caller.

type AlertTimelineFilters

type AlertTimelineFilters struct {
	Fields []AlertTimelineFilterField `json:"fields"`
}

Contains the filter fields available for the selected alert timeline view.

type AlertTimelineNode

type AlertTimelineNode struct {
	NodeUUID      string `json:"nodeUuid"`
	Hostname      string `json:"hostname,omitempty"`
	ComputeZone   string `json:"computeZone,omitempty"`
	NodeGroup     string `json:"nodeGroup,omitempty"`
	GPUType       string `json:"gpuType,omitempty"`
	CriticalCount int    `json:"criticalCount,omitempty"`
	WarningCount  int    `json:"warningCount,omitempty"`
	ResolvedCount int    `json:"resolvedCount,omitempty"`
	HostStatus    string `json:"hostStatus,omitempty"`
	LastAlertTime string `json:"lastAlertTime,omitempty"`
}

Represents a node that has alert timeline history

type AlertTimelineNodeAlert

type AlertTimelineNodeAlert struct {
	AlertUUID            string `json:"alertUuid"`
	Component            string `json:"component,omitempty"`
	ComponentDisplayName string `json:"componentDisplayName,omitempty"`
	AlertStatus          string `json:"alertStatus,omitempty"`
	StartTime            string `json:"startTime,omitempty"`
	LastEventTime        string `json:"lastEventTime,omitempty"`
}

Represents one alert in a node's timeline history

type AlertTimelineNodeSortBy

type AlertTimelineNodeSortBy string

Represents supported sort fields for alert timeline nodes

func (AlertTimelineNodeSortBy) Valid

func (sortBy AlertTimelineNodeSortBy) Valid() bool

Reports whether the node sort field is accepted by the API

type AlertTimelineNodesPage

type AlertTimelineNodesPage struct {
	Nodes                    []AlertTimelineNode `json:"nodes"`
	HasMore                  bool                `json:"hasMore"`
	Page                     int                 `json:"page"`
	PageSize                 int                 `json:"pageSize"`
	Total                    int                 `json:"total"`
	TotalCritical            int                 `json:"totalCritical"`
	TotalWarning             int                 `json:"totalWarning"`
	TotalResolved            int                 `json:"totalResolved"`
	DistinctGPUTypeCount     int                 `json:"distinctGpuTypeCount"`
	DistinctNodeGroupCount   int                 `json:"distinctNodeGroupCount"`
	DistinctComputeZoneCount int                 `json:"distinctComputeZoneCount"`
	RawJSON                  []byte              `json:"-"`
}

Represents a paginated alert timeline node response

type AlertTimelineSortOrder

type AlertTimelineSortOrder string

Represents supported sort orders for alert timeline endpoints

func (AlertTimelineSortOrder) Valid

func (order AlertTimelineSortOrder) Valid() bool

Reports whether the sort order is accepted by alert timeline endpoints

type AlertTimelineSortingDefaults

type AlertTimelineSortingDefaults struct {
	Field string `json:"field"`
	Order string `json:"order"`
}

Describes the default alert timeline sort.

type AlertTimelineSortingOptions

type AlertTimelineSortingOptions struct {
	Fields   []string                     `json:"fields"`
	Orders   []string                     `json:"orders"`
	Defaults AlertTimelineSortingDefaults `json:"defaults"`
}

Describes the supported alert timeline sort fields, orders, and defaults.

type AlertTimelineState

type AlertTimelineState string

Represents alert states accepted by alert timeline filters

func (AlertTimelineState) Valid

func (state AlertTimelineState) Valid() bool

Reports whether the alert timeline state is accepted by the API

type AlertsPage

type AlertsPage struct {
	Alerts         []Alert `json:"alerts"`
	Page           int     `json:"page"`
	PageSize       int     `json:"pageSize"`
	Total          int     `json:"total"`
	PageCursorNext string  `json:"pageCursorNext,omitempty"`
	RawJSON        []byte  `json:"-"`
}

Represents a paginated alert response with the raw backend payload

type AuthStatus

type AuthStatus struct {
	// Authenticated is true when the request reached the backend through the
	// authenticated path.
	Authenticated bool   `json:"authenticated"`
	RawJSON       []byte `json:"-"`
}

AuthStatus reports whether the configured credentials authenticate against the API.

type BlockDevice

type BlockDevice struct {
	FSType     string   `json:"fsType,omitempty"`
	MountPoint string   `json:"mountPoint,omitempty"`
	Name       string   `json:"name,omitempty"`
	Parents    []string `json:"parents,omitempty"`
	PartUUID   string   `json:"partUUID,omitempty"`
	Size       *int     `json:"size,omitempty"`
	Type       string   `json:"type,omitempty"`
	Used       *int     `json:"used,omitempty"`
	WWN        string   `json:"wwn,omitempty"`
}

Represents a node disk block device

type CPUInfo

type CPUInfo struct {
	Architecture string `json:"architecture,omitempty"`
	LogicalCores string `json:"logicalCores,omitempty"`
	Manufacturer string `json:"manufacturer,omitempty"`
	Type         string `json:"type,omitempty"`
}

Represents CPU metadata for a node

type Client

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

Calls the Fleet Intelligence customer API

func NewClient

func NewClient(baseURL, apiKey string, opts ...Option) (*Client, error)

Creates a Fleet Intelligence API client

func (*Client) APIKeyConfigured

func (c *Client) APIKeyConfigured() bool

Reports whether a non-empty API key is configured

func (*Client) BaseURL

func (c *Client) BaseURL() string

Returns the configured API base URL

func (*Client) DescribeAlertTimeline

func (c *Client) DescribeAlertTimeline(ctx context.Context, nodeUUID, alertUUID string) (AlertTimelineDetails, error)

Retrieves the full event timeline for one alert

func (*Client) DescribeAlertTimelineWithOptions

func (c *Client) DescribeAlertTimelineWithOptions(ctx context.Context, nodeUUID, alertUUID string, opts DescribeAlertTimelineOptions) (AlertTimelineDetails, error)

Retrieves one alert's event timeline with optional sorting and pagination

func (*Client) DescribeNode

func (c *Client) DescribeNode(ctx context.Context, nodeUUID string) (NodeDetails, error)

Retrieves detail for a single node using the configured API client

func (*Client) FetchSigningKey

func (c *Client) FetchSigningKey(ctx context.Context) ([]byte, error)

FetchSigningKey downloads the PEM-encoded public key used to sign inventory reports from the configured API's well-known endpoint. It is used by `report verify` when no local key is supplied.

func (*Client) GetAlertTimelineFilterOptions

func (c *Client) GetAlertTimelineFilterOptions(ctx context.Context, active bool) (AlertTimelineFilterOptions, error)

Gets alert timeline filter and sorting options for the active or historical view.

func (*Client) GetAuthStatus

func (c *Client) GetAuthStatus(ctx context.Context) (AuthStatus, error)

GetAuthStatus verifies the configured API key against the API by calling GET /v1/auth/status. A non-2xx response is returned as an *APIError so callers can distinguish rejected credentials (401/403) from other failures.

func (*Client) GetErrorReport

func (c *Client) GetErrorReport(ctx context.Context, opts ErrorReportOptions) (ErrorReport, error)

Retrieves an error report using the configured API client

func (*Client) GetEventBuckets

func (c *Client) GetEventBuckets(ctx context.Context, opts EventBucketsOptions) (EventBuckets, error)

GetEventBuckets retrieves time-bucketed event counts for histogram display

func (*Client) GetInventoryReport

func (c *Client) GetInventoryReport(ctx context.Context, opts InventoryReportOptions) (InventoryReport, error)

Retrieves an inventory report using the configured API client

func (*Client) GetOverview

func (c *Client) GetOverview(ctx context.Context, opts OverviewOptions) (Overview, error)

Fetches the system and fleet overview using the configured API client

func (*Client) ListAlertTimelineNodes

func (c *Client) ListAlertTimelineNodes(ctx context.Context, opts ListAlertTimelineNodesOptions) (AlertTimelineNodesPage, error)

Lists nodes with alert timeline history

func (*Client) ListAlerts

func (c *Client) ListAlerts(ctx context.Context, opts ListAlertsOptions) (AlertsPage, error)

Lists alerts using the configured API client

func (*Client) ListComputeZones

func (c *Client) ListComputeZones(ctx context.Context, opts ListComputeZonesOptions) (ComputeZonesPage, error)

Lists compute zones using the configured API client

func (*Client) ListEvents

func (c *Client) ListEvents(ctx context.Context, opts EventListOptions) (EventsPage, error)

ListEvents retrieves events filtered by node, component, and time range

func (*Client) ListNodeAlertTimeline

func (c *Client) ListNodeAlertTimeline(ctx context.Context, opts ListNodeAlertTimelineOptions) (NodeAlertTimelinePage, error)

Lists alert timeline history for a specific node

func (*Client) ListNodeGroups

func (c *Client) ListNodeGroups(ctx context.Context, opts ListNodeGroupsOptions) (NodeGroupsPage, error)

Lists node groups using the configured API client

func (*Client) ListNodes

func (c *Client) ListNodes(ctx context.Context, opts ListNodesOptions) (NodesPage, error)

Lists nodes using the configured API client

func (*Client) ListTags

func (c *Client) ListTags(ctx context.Context, opts TagListOptions) (TagList, error)

ListTags retrieves the unique customer tags, optionally filtered by prefix and a single node, node group, or compute zone.

func (*Client) NodeHealthHistory

func (c *Client) NodeHealthHistory(ctx context.Context, nodeUUID string, opts NodeHealthHistoryOptions) (NodeHealthHistory, error)

NodeHealthHistory retrieves the health timeline and summary for a single node

type ComputeZone

type ComputeZone struct {
	ID          string       `json:"id"`
	Name        string       `json:"name"`
	Type        string       `json:"type,omitempty"`
	GeoLocation *GeoLocation `json:"geoLocation,omitempty"`
	NodeCount   *int         `json:"nodeCount,omitempty"`
}

Represents a compute zone

type ComputeZoneView

type ComputeZoneView string

Represents supported response shapes for listing compute zones

const (
	ComputeZoneViewDetail ComputeZoneView = "detail"
	ComputeZoneViewBasic  ComputeZoneView = "basic"
)

func (ComputeZoneView) Valid

func (view ComputeZoneView) Valid() bool

Reports whether the view is accepted by the API

type ComputeZonesPage

type ComputeZonesPage struct {
	ComputeZones []ComputeZone `json:"computezones"`
	HasMore      bool          `json:"hasMore"`
	Page         int           `json:"page"`
	PageSize     int           `json:"pageSize"`
	Total        int           `json:"total"`
	RawJSON      []byte        `json:"-"`
}

Represents a paginated compute zone response with the raw backend payload

type DescribeAlertTimelineOptions

type DescribeAlertTimelineOptions struct {
	Order    AlertTimelineSortOrder
	Page     *int
	PageSize *int
}

Represents request options for retrieving one alert's event timeline

type DiskInfo

type DiskInfo struct {
	BlockDevices      []BlockDevice `json:"blockDevices,omitempty"`
	ContainerRootDisk string        `json:"containerRootDisk,omitempty"`
}

Represents disk metadata for a node

type ErrorReport

type ErrorReport struct {
	View     ErrorReportView      `json:"view"`
	GroupBy  ErrorReportGroupBy   `json:"groupBy,omitempty"`
	Errors   []ErrorReportError   `json:"errors,omitempty"`
	Nodes    []ErrorReportNode    `json:"nodes,omitempty"`
	Overview *ErrorReportOverview `json:"overview,omitempty"`
	Graph    *ErrorReportGraph    `json:"graph,omitempty"`
	HasMore  bool                 `json:"hasMore"`
	Page     int                  `json:"page"`
	PageSize int                  `json:"pageSize"`
	Total    int                  `json:"total"`
	RawJSON  []byte               `json:"-"`
	RawCSV   []byte               `json:"-"`
}

Represents an error report response

type ErrorReportError

type ErrorReportError struct {
	Name            string           `json:"name,omitempty"`
	Count           *int             `json:"count,omitempty"`
	NodeCount       *int             `json:"nodeCount,omitempty"`
	SuggestedAction *SuggestedAction `json:"suggestedAction,omitempty"`
}

Represents one error grouping row in an error list report

type ErrorReportGraph

type ErrorReportGraph struct {
	Result    []ErrorTimeSeries `json:"result,omitempty"`
	TimeRange *TimeRange        `json:"timeRange,omitempty"`
}

Represents time-series error report data

type ErrorReportGroupBy

type ErrorReportGroupBy string

Represents supported groupings for error list reports

func (ErrorReportGroupBy) Valid

func (groupBy ErrorReportGroupBy) Valid() bool

Reports whether the error report grouping is accepted by the API

type ErrorReportNode

type ErrorReportNode struct {
	NodeUUID string   `json:"nodeUUID,omitempty"`
	Hostname string   `json:"hostname,omitempty"`
	Errors   []string `json:"errors,omitempty"`
}

Represents one node grouping row in an error list report

type ErrorReportOptions

type ErrorReportOptions struct {
	View           ErrorReportView
	GroupBy        ErrorReportGroupBy
	Format         ReportFormat
	Page           *int
	PageSize       *int
	Step           string
	ComputeZoneIDs []string
	NodeGroupIDs   []string
	Tags           []string
	Errors         []string
	TimeMode       ErrorReportTimeMode
	Window         string
	StartTime      string
	EndTime        string
}

Represents request options for error reports

type ErrorReportOverview

type ErrorReportOverview struct {
	TotalErrorNodes *int `json:"totalErrorNodes,omitempty"`
	TotalErrorTypes *int `json:"totalErrorTypes,omitempty"`
	TotalErrors     *int `json:"totalErrors,omitempty"`
}

Represents aggregate error report statistics

type ErrorReportTimeMode

type ErrorReportTimeMode string

Represents supported time filter modes for error reports

func (ErrorReportTimeMode) Valid

func (mode ErrorReportTimeMode) Valid() bool

Reports whether the error report time mode is accepted by the API

type ErrorReportView

type ErrorReportView string

Represents supported error report views

func (ErrorReportView) Valid

func (view ErrorReportView) Valid() bool

Reports whether the error report view is accepted by the API

type ErrorTimeSeries

type ErrorTimeSeries struct {
	Error  string `json:"error,omitempty"`
	Values string `json:"values,omitempty"`
}

Represents one error time-series result

type Event

type Event struct {
	EventID          string            `json:"eventId,omitempty"`
	NodeUUID         string            `json:"nodeUUID,omitempty"`
	Component        string            `json:"component,omitempty"`
	Name             string            `json:"name,omitempty"`
	Type             string            `json:"type,omitempty"`
	Message          string            `json:"message,omitempty"`
	Timestamp        string            `json:"timestamp,omitempty"`
	CreatedAt        string            `json:"createdAt,omitempty"`
	SuggestedActions []SuggestedAction `json:"suggestedActions,omitempty"`
}

Event represents a single fleet event

type EventBucket

type EventBucket struct {
	StartTime      string `json:"startTime,omitempty"`
	EndTime        string `json:"endTime,omitempty"`
	FirstEventTime string `json:"firstEventTime,omitempty"`
	Count          *int   `json:"count,omitempty"`
}

EventBucket represents the event count for a single time interval

type EventBuckets

type EventBuckets struct {
	BucketInterval string        `json:"bucketInterval,omitempty"`
	Buckets        []EventBucket `json:"buckets,omitempty"`
	RawJSON        []byte        `json:"-"`
}

EventBuckets represents time-bucketed event counts with the raw backend payload

type EventBucketsOptions

type EventBucketsOptions struct {
	NodeUUID   string
	Component  string
	Window     string
	StartTime  string
	EndTime    string
	MaxBuckets *int
}

EventBucketsOptions represents request options for time-bucketed event counts. A time range is required, following the same rules as EventListOptions.

type EventListOptions

type EventListOptions struct {
	NodeUUID  string
	Component string
	Window    string
	StartTime string
	EndTime   string
	Page      *int
	PageSize  *int
}

EventListOptions represents request options for listing events. A time range is required: supply either Window (relative) or StartTime and EndTime (absolute), but not both.

type EventsPage

type EventsPage struct {
	Events   []Event `json:"events"`
	HasMore  bool    `json:"hasMore"`
	Page     int     `json:"page"`
	PageSize int     `json:"pageSize"`
	Total    int     `json:"total"`
	RawJSON  []byte  `json:"-"`
}

EventsPage represents a paginated event list with the raw backend payload

type GPUDevice

type GPUDevice struct {
	BoardID      *int   `json:"boardID,omitempty"`
	BusID        string `json:"busID,omitempty"`
	ChassisSN    string `json:"chassisSN,omitempty"`
	GPUIndex     string `json:"gpuIndex,omitempty"`
	MinorID      string `json:"minorID,omitempty"`
	SerialNumber string `json:"sn,omitempty"`
	UUID         string `json:"uuid,omitempty"`
	VBIOSVersion string `json:"vbiosVersion,omitempty"`
}

Represents a GPU device on a node

type GPUInfo

type GPUInfo struct {
	Architecture string      `json:"architecture,omitempty"`
	GPUs         []GPUDevice `json:"gpus,omitempty"`
	Manufacturer string      `json:"manufacturer,omitempty"`
	Memory       string      `json:"memory,omitempty"`
	Product      string      `json:"product,omitempty"`
}

Represents GPU metadata for a node

type GeoLocation

type GeoLocation struct {
	City      string   `json:"city,omitempty"`
	Country   string   `json:"country,omitempty"`
	Region    string   `json:"region,omitempty"`
	Latitude  *float32 `json:"latitude,omitempty"`
	Longitude *float32 `json:"longitude,omitempty"`
}

Represents physical location metadata for a fleet resource. This retains the backend "geoLocation" vocabulary; the CLI surfaces it to users as "location".

type InventoryNode

type InventoryNode struct {
	NodeUUID               string       `json:"nodeUUID"`
	Hostname               string       `json:"hostname,omitempty"`
	ComputeZone            string       `json:"computeZone,omitempty"`
	NodeGroup              string       `json:"nodeGroup,omitempty"`
	GPUType                string       `json:"gpuType,omitempty"`
	GPUCount               *int         `json:"gpuCount,omitempty"`
	PublicIP               string       `json:"publicIP,omitempty"`
	PrivateIP              string       `json:"privateIP,omitempty"`
	IntegrityCheck         string       `json:"integrityCheck,omitempty"`
	IntegrityCheckReason   string       `json:"integrityCheckReason,omitempty"`
	LastIntegrityCheckTime string       `json:"lastIntegrityCheckTS,omitempty"`
	FirmwareCheck          string       `json:"firmwareCheck,omitempty"`
	EnrolledAt             string       `json:"enrolledAt,omitempty"`
	RemovedAt              string       `json:"removedAt,omitempty"`
	GeoLocation            *GeoLocation `json:"geoLocation,omitempty"`
	SerialNumbers          []string     `json:"serialNumbers,omitempty"`
}

Represents one inventory row in an inventory report

type InventoryReport

type InventoryReport struct {
	Nodes    []InventoryNode `json:"nodes"`
	HasMore  bool            `json:"hasMore"`
	Page     int             `json:"page"`
	PageSize int             `json:"pageSize"`
	Total    int             `json:"total"`
	RawJSON  []byte          `json:"-"`
	RawCSV   []byte          `json:"-"`

	// RawSigned holds the signed CSV bundle (a zip) when Signed is requested.
	RawSigned []byte `json:"-"`
	// Filename is the server-suggested filename for a signed bundle download.
	Filename string `json:"-"`
}

Represents an inventory report response

type InventoryReportOptions

type InventoryReportOptions struct {
	Format         ReportFormat
	Signed         bool
	ComputeZoneIDs []string
	NodeGroupIDs   []string
	Tags           []string
	StartTime      string
	EndTime        string
	SortBy         InventoryReportSortBy
	Order          InventoryReportSortOrder
	Page           *int
	PageSize       *int
}

Represents request options for inventory reports

type InventoryReportSortBy

type InventoryReportSortBy string

Represents supported inventory report sort fields

func (InventoryReportSortBy) Valid

func (sortBy InventoryReportSortBy) Valid() bool

Reports whether the inventory report sort field is accepted by the API

type InventoryReportSortOrder

type InventoryReportSortOrder string

Represents supported inventory report sort orders

func (InventoryReportSortOrder) Valid

func (order InventoryReportSortOrder) Valid() bool

Reports whether the inventory report sort order is accepted by the API

type ListAlertTimelineNodesOptions

type ListAlertTimelineNodesOptions struct {
	Active         bool
	Hostname       string
	SortBy         AlertTimelineNodeSortBy
	Order          AlertTimelineSortOrder
	GPUTypes       []string
	NodeGroupIDs   []string
	ComputeZoneIDs []string
	AlertStates    []AlertTimelineState
	ComponentTypes []string
	Page           *int
	PageSize       *int
}

Represents request options for listing alert timeline nodes

type ListAlertsOptions

type ListAlertsOptions struct {
	NodeUUID  string
	Component string
	State     AlertState
	Severity  AlertSeverity
	Page      *int
	PageSize  *int
}

Represents request options for listing alerts

type ListComputeZonesOptions

type ListComputeZonesOptions struct {
	View     ComputeZoneView
	ZoneIDs  []string
	Page     *int
	PageSize *int
}

Represents request options for listing compute zones

type ListNodeAlertTimelineOptions

type ListNodeAlertTimelineOptions struct {
	NodeUUID       string
	Active         bool
	WithoutPSIRT   bool
	SortBy         AlertTimelineAlertSortBy
	Order          AlertTimelineSortOrder
	AlertStates    []AlertTimelineState
	ComponentTypes []string
	GPUTypes       []string
	NodeGroupIDs   []string
	ComputeZoneIDs []string
	Page           *int
	PageSize       *int
}

Represents request options for listing alert history for one node

type ListNodeGroupsOptions

type ListNodeGroupsOptions struct {
	View           NodeGroupView
	NodeGroupIDs   []string
	HealthStatuses []NodeGroupHealthStatus
	GPUTypes       []string
	SortBy         NodeGroupSortBy
	Order          NodeGroupSortOrder
	Page           *int
	PageSize       *int
}

Represents request options for listing node groups

type ListNodesOptions

type ListNodesOptions struct {
	View             NodeView
	NodeUUIDs        []string
	HealthStatuses   []NodeHealthStatus
	ComputeZoneIDs   []string
	ComputeZoneNames []string
	NodeGroupIDs     []string
	NodeGroupNames   []string
	GPUTypes         []string
	GPUCounts        []int
	PublicIPs        []string
	PrivateIPs       []string
	Hostname         string
	AgentStatuses    []NodeAgentStatus
	IntegrityChecks  []NodeIntegrityCheck
	FirmwareChecks   []NodeFirmwareCheck
	SortBy           NodeSortBy
	Order            NodeSortOrder
	Page             *int
	PageSize         *int
}

Represents request options for listing nodes

type MemoryInfo

type MemoryInfo struct {
	TotalBytes string `json:"totalBytes,omitempty"`
}

Represents memory metadata for a node

type NICInfo

type NICInfo struct {
	PrivateIPInterfaces []NICInterface `json:"privateIPInterfaces,omitempty"`
}

Represents network interface metadata for a node

type NICInterface

type NICInterface struct {
	Interface string `json:"interface,omitempty"`
	IP        string `json:"ip,omitempty"`
	MAC       string `json:"mac,omitempty"`
}

Represents private network interface metadata for a node

type Node

type Node struct {
	UUID                   string `json:"nodeUUID"`
	Hostname               string `json:"hostname"`
	ComputeZone            string `json:"computeZone,omitempty"`
	NodeGroup              string `json:"nodeGroup,omitempty"`
	Health                 string `json:"healthStatus,omitempty"`
	GPUType                string `json:"gpuType,omitempty"`
	GPUCount               *int   `json:"gpuCount,omitempty"`
	AgentStatus            string `json:"agentStatus,omitempty"`
	IntegrityCheck         string `json:"integrityCheck,omitempty"`
	IntegrityCheckReason   string `json:"integrityCheckReason,omitempty"`
	FirmwareCheck          string `json:"firmwareCheck,omitempty"`
	PublicIP               string `json:"publicIP,omitempty"`
	PrivateIP              string `json:"privateIP,omitempty"`
	LastIntegrityCheckTime string `json:"lastIntegrityCheckTS,omitempty"`
	LastUpdatedTime        string `json:"lastUpdatedTS,omitempty"`
}

Represents a node

type NodeAgentStatus

type NodeAgentStatus string

Represents supported agent status filters for listing nodes

func (NodeAgentStatus) Valid

func (status NodeAgentStatus) Valid() bool

Reports whether the agent status is accepted by the API

type NodeAlertTimelinePage

type NodeAlertTimelinePage struct {
	NodeUUID string                   `json:"nodeUuid"`
	Hostname string                   `json:"hostname,omitempty"`
	Alerts   []AlertTimelineNodeAlert `json:"alerts"`
	HasMore  bool                     `json:"hasMore"`
	Page     int                      `json:"page"`
	PageSize int                      `json:"pageSize"`
	Total    int                      `json:"total"`
	RawJSON  []byte                   `json:"-"`
}

Represents a paginated alert history response for one node

type NodeDetails

type NodeDetails struct {
	Node
	ComputeZoneID           string         `json:"computeZoneId,omitempty"`
	NodeGroupID             string         `json:"nodeGroupId,omitempty"`
	EnrolledAt              string         `json:"enrolledAt,omitempty"`
	GeoLocation             *GeoLocation   `json:"geoLocation,omitempty"`
	HealthyComponentCount   *int           `json:"healthyComponentCount,omitempty"`
	DegradedComponentCount  *int           `json:"degradedComponentCount,omitempty"`
	UnhealthyComponentCount *int           `json:"unhealthyComponentCount,omitempty"`
	Resources               *NodeResources `json:"resources,omitempty"`
	SystemInfo              *SystemInfo    `json:"systemInfo,omitempty"`
	Tags                    []string       `json:"tags,omitempty"`
	RawJSON                 []byte         `json:"-"`
}

Represents detailed node metadata

type NodeFirmwareCheck

type NodeFirmwareCheck string

Represents supported firmware check filters for listing nodes

func (NodeFirmwareCheck) Valid

func (check NodeFirmwareCheck) Valid() bool

Reports whether the firmware check status is accepted by the API

type NodeGroup

type NodeGroup struct {
	ID               string   `json:"id"`
	Name             string   `json:"name"`
	ComputeZoneID    string   `json:"computeZoneId,omitempty"`
	ComputeZoneName  string   `json:"computeZoneName,omitempty"`
	Health           string   `json:"health,omitempty"`
	HealthPercentage *float32 `json:"healthPercentage,omitempty"`
	NodeCount        *int     `json:"nodeCount,omitempty"`
}

Represents a node group

type NodeGroupHealthStatus

type NodeGroupHealthStatus string

Represents supported health filters for listing node groups

func (NodeGroupHealthStatus) Valid

func (status NodeGroupHealthStatus) Valid() bool

Reports whether the health status is accepted by the API

type NodeGroupSortBy

type NodeGroupSortBy string

Represents supported sort fields for listing node groups

func (NodeGroupSortBy) Valid

func (sortBy NodeGroupSortBy) Valid() bool

Reports whether the sort field is accepted by the API

type NodeGroupSortOrder

type NodeGroupSortOrder string

Represents supported sort orders for listing node groups

func (NodeGroupSortOrder) Valid

func (order NodeGroupSortOrder) Valid() bool

Reports whether the sort order is accepted by the API

type NodeGroupView

type NodeGroupView string

Represents supported response shapes for listing node groups

func (NodeGroupView) Valid

func (view NodeGroupView) Valid() bool

Reports whether the view is accepted by the API

type NodeGroupsPage

type NodeGroupsPage struct {
	NodeGroups []NodeGroup `json:"nodeGroups"`
	HasMore    bool        `json:"hasMore"`
	Page       int         `json:"page"`
	PageSize   int         `json:"pageSize"`
	Total      int         `json:"total"`
	RawJSON    []byte      `json:"-"`
}

Represents a paginated node group response with the raw backend payload

type NodeHealthHistory

type NodeHealthHistory struct {
	EnrolledAt    string              `json:"enrolledAt,omitempty"`
	HealthSummary *NodeHealthSummary  `json:"healthSummary,omitempty"`
	Segments      []NodeHealthSegment `json:"machineStatus,omitempty"`
	RawJSON       []byte              `json:"-"`
}

NodeHealthHistory represents a node's health timeline and summary over a window

type NodeHealthHistoryOptions

type NodeHealthHistoryOptions struct {
	// StartTime is the start of the window in RFC3339 format (required)
	StartTime string
	// EndTime is the end of the window in RFC3339 format (required)
	EndTime string
}

NodeHealthHistoryOptions represents the time window for a node health history query

type NodeHealthSegment

type NodeHealthSegment struct {
	Status    string `json:"status,omitempty"`
	StartTime string `json:"startTime,omitempty"`
	EndTime   string `json:"endTime,omitempty"`
}

NodeHealthSegment represents a single health state interval in a node's timeline

type NodeHealthStatus

type NodeHealthStatus string

Represents supported health filters for listing nodes

func (NodeHealthStatus) Valid

func (status NodeHealthStatus) Valid() bool

Reports whether the health status is accepted by the API

type NodeHealthSummary

type NodeHealthSummary struct {
	HealthyPercentage        *float32 `json:"healthyPercentage,omitempty"`
	DegradedPercentage       *float32 `json:"degradedPercentage,omitempty"`
	UnhealthyPercentage      *float32 `json:"unhealthyPercentage,omitempty"`
	HealthyDurationSeconds   *float32 `json:"healthyDurationSeconds,omitempty"`
	DegradedDurationSeconds  *float32 `json:"degradedDurationSeconds,omitempty"`
	UnhealthyDurationSeconds *float32 `json:"unhealthyDurationSeconds,omitempty"`
}

NodeHealthSummary represents aggregate health durations and percentages for a node

type NodeIntegrityCheck

type NodeIntegrityCheck string

Represents supported integrity check filters for listing nodes. This retains the backend "integrity check" vocabulary; the CLI surfaces it to users as "verification check".

func (NodeIntegrityCheck) Valid

func (check NodeIntegrityCheck) Valid() bool

Reports whether the integrity check status is accepted by the API

type NodeResources

type NodeResources struct {
	CPUInfo    *CPUInfo    `json:"cpuInfo,omitempty"`
	DiskInfo   *DiskInfo   `json:"diskInfo,omitempty"`
	GPUInfo    *GPUInfo    `json:"gpuInfo,omitempty"`
	MemoryInfo *MemoryInfo `json:"memoryInfo,omitempty"`
	NICInfo    *NICInfo    `json:"nicInfo,omitempty"`
}

Represents hardware and network resource metadata for a node

type NodeSortBy

type NodeSortBy string

Represents supported sort fields for listing nodes

func (NodeSortBy) Valid

func (sortBy NodeSortBy) Valid() bool

Reports whether the sort field is accepted by the API

type NodeSortOrder

type NodeSortOrder string

Represents supported sort orders for listing nodes

func (NodeSortOrder) Valid

func (order NodeSortOrder) Valid() bool

Reports whether the sort order is accepted by the API

type NodeView

type NodeView string

Represents supported response shapes for listing nodes

func (NodeView) Valid

func (view NodeView) Valid() bool

Reports whether the view is accepted by the API

type NodesPage

type NodesPage struct {
	Nodes    []Node `json:"nodes"`
	HasMore  bool   `json:"hasMore"`
	Page     int    `json:"page"`
	PageSize int    `json:"pageSize"`
	Total    int    `json:"total"`
	RawJSON  []byte `json:"-"`
}

Represents a paginated node response with the raw backend payload

type Option

type Option func(*Client)

Customizes client construction behavior

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

Configures the HTTP client used for API requests. The client is used through a shallow copy carrying the redirect guard (see guardRedirect), so a client shared across callers is never mutated and its transport, cookie jar, and timeout are preserved.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

Sets the per-request timeout applied to API calls. The timeout is enforced via the request context rather than the HTTP client, so it is unaffected by WithHTTPClient (which replaces the HTTP client) and never mutates an *http.Client that may be shared across clients. Non-positive values are ignored, leaving the existing timeout in place.

type Overview

type Overview struct {
	NodesCount         *int             `json:"nodesCount,omitempty"`
	HealthyNodeCount   *int             `json:"healthNodeCount,omitempty"`
	DegradedNodeCount  *int             `json:"degradedNodeCount,omitempty"`
	UnhealthyNodeCount *int             `json:"unhealthyNodeCount,omitempty"`
	UnknownNodeCount   *int             `json:"unknownNodeCount,omitempty"`
	HealthPercentage   *float32         `json:"healthPercentage,omitempty"`
	NodeGroupCount     *int             `json:"nodeGroupCount,omitempty"`
	ComputeZoneCount   *int             `json:"computeZoneCount,omitempty"`
	GPUsCount          *int             `json:"gpusCount,omitempty"`
	CPUCoresCount      *int             `json:"cpuCoresCount,omitempty"`
	Metrics            []OverviewMetric `json:"metrics,omitempty"`
	RawJSON            []byte           `json:"-"`
}

Represents the overall system and fleet summary

type OverviewMetric

type OverviewMetric struct {
	Name        string   `json:"name,omitempty"`
	Description string   `json:"description,omitempty"`
	Unit        string   `json:"unit,omitempty"`
	Value       *float32 `json:"value,omitempty"`
	Aggregation string   `json:"aggregation,omitempty"`
	LastUpdated string   `json:"lastUpdated,omitempty"`
}

Represents a single fleet-level metric in the overview

type OverviewOptions

type OverviewOptions struct {
	// IncludeMetrics toggles the API's metrics payload. Nil uses the API
	// default (metrics included).
	IncludeMetrics *bool
}

Represents request options for fetching the fleet overview

type ReportFormat

type ReportFormat string

Represents supported report response formats

func (ReportFormat) Valid

func (format ReportFormat) Valid() bool

Reports whether the report format is accepted by the API

type SuggestedAction

type SuggestedAction struct {
	Action  string `json:"action,omitempty"`
	Code    string `json:"code,omitempty"`
	Persona string `json:"persona,omitempty"`
	Type    string `json:"type,omitempty"`
}

Represents an operator action attached to an alert event

type SystemInfo

type SystemInfo struct {
	AgentVersion            string `json:"agentVersion,omitempty"`
	BootID                  string `json:"bootID,omitempty"`
	ContainerRuntimeVersion string `json:"containerRuntimeVersion,omitempty"`
	CUDAVersion             string `json:"cudaVersion,omitempty"`
	DCGMVersion             string `json:"dcgmVersion,omitempty"`
	GPUDriverVersion        string `json:"gpuDriverVersion,omitempty"`
	Hostname                string `json:"hostname,omitempty"`
	KernelVersion           string `json:"kernelVersion,omitempty"`
	OperatingSystem         string `json:"operatingSystem,omitempty"`
	OSImage                 string `json:"osImage,omitempty"`
	StartedAt               string `json:"startedAt,omitempty"`
	SystemUUID              string `json:"systemUUID,omitempty"`
}

Represents system metadata reported by the node agent

type TagList

type TagList struct {
	Tags    []string `json:"tags,omitempty"`
	RawJSON []byte   `json:"-"`
}

TagList represents the unique customer tags with the raw backend payload

type TagListOptions

type TagListOptions struct {
	Prefix        string
	NodeUUID      string
	NodeGroupID   string
	ComputeZoneID string
}

TagListOptions represents request options for listing unique tags. At most one of NodeUUID, NodeGroupID, or ComputeZoneID may be set; Prefix may be combined with one resource filter.

type TimeRange

type TimeRange struct {
	Start string `json:"start,omitempty"`
	End   string `json:"end,omitempty"`
}

Represents an inclusive report time range

Jump to

Keyboard shortcuts

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