Documentation
¶
Index ¶
- Constants
- type Client
- type ClientWithLegacySupport
- type Cluster
- type ClusterClient
- type Disk
- type DiskClient
- type DiskStatus
- type EngineError
- type ErrorCode
- type Host
- type HostClient
- type HostStatus
- type ImageDownload
- type ImageDownloadReader
- type ImageFormat
- type Logger
- type MockClient
- type RetryInstance
- type RetryStrategy
- type StorageDomain
- type StorageDomainClient
- type StorageDomainExternalStatus
- type StorageDomainStatus
- type Template
- type TemplateClient
- type TestConnectionClient
- type TestHelper
- type UploadImageProgress
- type UploadImageResult
- type VMBlockDevice
- type VMCPUTopo
- type VMClient
Constants ¶
const BlankTemplateID = "00000000-0000-0000-0000-000000000000"
BlankTemplateID is the blank template in oVirt.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// GetURL returns the oVirt engine base URL.
GetURL() string
DiskClient
VMClient
ClusterClient
StorageDomainClient
HostClient
TemplateClient
TestConnectionClient
}
Client is a simplified client for the oVirt API.
type ClientWithLegacySupport ¶
type ClientWithLegacySupport interface {
// GetSDKClient returns a configured oVirt SDK client for the use cases that are not covered by goVirt.
GetSDKClient() *ovirtsdk4.Connection
// GetHTTPClient returns a configured HTTP client for the oVirt engine. This can be used to send manual
// HTTP request to the oVirt engine.
GetHTTPClient() http.Client
Client
}
ClientWithLegacySupport is an extension of Client that also offers the ability to retrieve the underlying SDK connection or a configured HTTP client.
func New ¶
func New( url string, username string, password string, caFile string, caCert []byte, insecure bool, extraHeaders map[string]string, logger Logger, ) (ClientWithLegacySupport, error)
New creates a new copy of the enhanced oVirt client.
func NewWithVerify ¶ added in v0.5.0
func NewWithVerify( url string, username string, password string, caFile string, caCert []byte, insecure bool, extraHeaders map[string]string, logger Logger, verify func(connection *ovirtsdk4.Connection) error, ) (ClientWithLegacySupport, error)
NewWithVerify allows customizing the verification function for the connection. Alternatively, a nil can be passed to disable connection verification.
type Cluster ¶
type Cluster interface {
// ID returns the UUID of the cluster.
ID() string
// Name returns the textual name of the cluster.
Name() string
}
Cluster represents a cluster returned from a ListClusters or GetCluster call.
type ClusterClient ¶
type ClusterClient interface {
// ListClusters returns a list of all clusters in the oVirt engine.
ListClusters(retries ...RetryStrategy) ([]Cluster, error)
// GetCluster returns a specific cluster based on the cluster ID. An error is returned if the cluster doesn't exist.
GetCluster(id string, retries ...RetryStrategy) (Cluster, error)
}
ClusterClient is a part of the Client that deals with clusters in the oVirt Engine.
type Disk ¶
type Disk interface {
// ID is the unique ID for this disk.
ID() string
// Alias is the name for this disk set by the user.
Alias() string
// ProvisionedSize is the size visible to the virtual machine.
ProvisionedSize() uint64
// TotalSize is the size of the image file.
// This value can be zero in some cases, for example when the disk upload wasn't properly finalized.
TotalSize() uint64
// Format is the format of the image.
Format() ImageFormat
// StorageDomainID is the ID of the storage system used for this disk.
StorageDomainID() string
// Status returns the status the disk is in.
Status() DiskStatus
}
Disk is a disk in oVirt.
type DiskClient ¶
type DiskClient interface {
// StartImageUpload uploads an image file into a disk. The actual upload takes place in the
// background and can be tracked using the returned UploadImageProgress object.
//
// Parameters are as follows:
//
// - alias: this is the name used for the uploaded image.
// - storageDomainID: this is the UUID of the storage domain that the image should be uploaded to.
// - sparse: use sparse provisioning
// - size: this is the file size of the image. This must match the bytes read.
// - reader: this is the source of the image data.
// - retries: a set of optional retry options.
//
// You can wait for the upload to complete using the Done() method:
//
// progress, err := cli.StartImageUpload(...)
// if err != nil {
// //...
// }
// <-progress.Done()
//
// After the upload is complete you can check the Err() method if it completed successfully:
//
// if err := progress.Err(); err != nil {
// //...
// }
//
StartImageUpload(
alias string,
storageDomainID string,
sparse bool,
size uint64,
reader io.ReadSeekCloser,
retries ...RetryStrategy,
) (UploadImageProgress, error)
// UploadImage is identical to StartImageUpload, but waits until the upload is complete. It returns the disk ID
// as a result, or the error if one happened.
UploadImage(
alias string,
storageDomainID string,
sparse bool,
size uint64,
reader io.ReadSeekCloser,
retries ...RetryStrategy,
) (UploadImageResult, error)
// StartImageDownload starts the download of the image file of a specific disk.
// The caller can then wait for the initialization using the Initialized() call:
//
// <-download.Initialized()
//
// Alternatively, the downloader can use the Read() function to wait for the download to become available
// and then read immediately.
//
// The caller MUST close the returned reader, otherwise the disk will remain locked in the oVirt engine.
// The passed context is observed only for the initialization phase.
StartImageDownload(
diskID string,
format ImageFormat,
retries ...RetryStrategy,
) (ImageDownload, error)
// DownloadImage runs StartImageDownload, then waits for the download to be ready before returning the reader.
// The caller MUST close the ImageDownloadReader in order to properly unlock the disk in the oVirt engine.
DownloadImage(
diskID string,
format ImageFormat,
retries ...RetryStrategy,
) (ImageDownloadReader, error)
// ListDisks lists all disks.
ListDisks(retries ...RetryStrategy) ([]Disk, error)
// GetDisk fetches a disk with a specific ID from the oVirt Engine.
GetDisk(diskID string, retries ...RetryStrategy) (Disk, error)
// RemoveDisk removes a disk with a specific ID.
RemoveDisk(diskID string, retries ...RetryStrategy) error
}
DiskClient is the client interface part that deals with disks.
type DiskStatus ¶ added in v0.5.0
type DiskStatus string
DiskStatus shows the status of a disk. Certain operations lock a disk, which is important because the disk can then not be changed.
const ( DiskStatusOK DiskStatus = "ok" DiskStatusLocked DiskStatus = "locked" DiskStatusIllegal DiskStatus = "illegal" )
type EngineError ¶ added in v0.5.0
type EngineError interface {
error
// String returns the string representation for this error.
String() string
// HasCode returns true if the current error, or any preceding error has the specified error code.
HasCode(ErrorCode) bool
// Code returns an error code for the failure.
Code() ErrorCode
// Unwrap returns the underlying error
Unwrap() error
// CanAutoRetry returns false if an automatic retry should not be attempted.
CanAutoRetry() bool
}
EngineError is an error representation for errors received while interacting with the oVirt engine.
Usage:
if err != nil {
var realErr ovirtclient.EngineError
if errors.As(err, &realErr) {
// deal with EngineError
} else {
// deal with other errors
}
}
type ErrorCode ¶ added in v0.5.0
type ErrorCode string
ErrorCode is a code that can be used to identify error types. These errors are identified on a best effort basis from the underlying oVirt connection.
const EAccessDenied ErrorCode = "access_denied"
EAccessDenied signals that the provided credentials for the oVirt engine were incorrect.
const EBadArgument ErrorCode = "bad_argument"
EBadArgument indicates that an input parameter was incorrect.
const EBug ErrorCode = "bug"
EBug signals an error that should never happen. Please report this.
const EConnection ErrorCode = "connection"
EConnection signals a problem with the connection.
const EDiskLocked ErrorCode = "disk_locked"
EDiskLocked indicates that the disk in question is locked.
const EFieldMissing ErrorCode = "field_missing"
EFieldMissing indicates that the oVirt API did not return a specific field. This is most likely a bug, please report it.
const EFileReadFailed ErrorCode = "file_read_failed"
EFileReadFailed indicates that reading a local file failed.
const ELocalIO ErrorCode = "local_io_error"
ELocalIO indicates an input/output error on the client side. For example, a disk could not be read.
const ENotAnOVirtEngine ErrorCode = "not_ovirt_engine"
ENotAnOVirtEngine signals that the server did not respond with a proper oVirt response. the cre
const ENotFound ErrorCode = "not_found"
ENotFound signals that the resource requested was not found.
const EPending ErrorCode = "pending"
EPending signals that the client library is still waiting for an action to be completed.
const EPermanentHTTPError ErrorCode = "permanent_http_error"
EPermanentHTTPError indicates a HTTP error code that should not be retried.
const ERelatedOperationInProgress ErrorCode = "related_operation_in_progress"
ERelatedOperationInProgress means that the engine is busy working on something else on the same resource.
const ETLSError ErrorCode = "tls_error"
ETLSError signals that the provided CA certificate did not match the server that was attempted to connect.
const ETemporaryHTTPError ErrorCode = "temporary_http_error"
ETemporaryHTTPError indicates a HTTP error that can be retried.
const ETimeout ErrorCode = "timeout"
ETimeout signals that the client library has timed out waiting for an action to be completed.
const EUnexpectedImageTransferPhase ErrorCode = "unexpected_image_transfer_phase"
EUnexpectedImageTransferPhase indicates that an image transfer was in an unexpected phase.
const EUnidentified ErrorCode = "generic_error"
EUnidentified is an unidentified oVirt error. When passed to the wrap() function this error code will cause the wrap function to look at the wrapped error and either fetch the error code from that error, or identify the error from its text.
If you see this error type in a log please report this error so we can add an error code for it.
const EUnsupported ErrorCode = "unsupported"
EUnsupported signals that an action is not supported. This can indicate a disk format or a combination of parameters.
func (ErrorCode) CanAutoRetry ¶ added in v0.5.0
CanAutoRetry returns false if the given error code is permanent and an automatic retry should not be attempted.
type Host ¶
type Host interface {
ID() string
ClusterID() string
Status() HostStatus
}
Host is the representation of a host returned from the oVirt Engine API.
type HostClient ¶
type HostClient interface {
ListHosts(retries ...RetryStrategy) ([]Host, error)
GetHost(id string, retries ...RetryStrategy) (Host, error)
}
HostClient contains the API portion that deals with hosts.
type HostStatus ¶
type HostStatus string
HostStatus represents the complex states an oVirt host can be in.
const ( HostStatusConnecting HostStatus = "connecting" HostStatusDown HostStatus = "down" HostStatusError HostStatus = "error" HostStatusInitializing HostStatus = "initializing" HostStatusInstallFailed HostStatus = "install_failed" HostStatusInstalling HostStatus = "installing" HostStatusInstallingOS HostStatus = "installing_os" HostStatusKDumping HostStatus = "kdumping" HostStatusMaintenance HostStatus = "maintenance" HostStatusNonOperational HostStatus = "non_operational" HostStatusNonResponsive HostStatus = "non_responsive" HostStatusPendingApproval HostStatus = "pending_approval" HostStatusPreparingForMaintenance HostStatus = "preparing_for_maintenance" HostStatusReboot HostStatus = "reboot" HostStatusUnassigned HostStatus = "unassigned" HostStatusUp HostStatus = "up" )
type ImageDownload ¶ added in v0.5.0
type ImageDownload interface {
ImageDownloadReader
// Err returns the error that happened during initializing the download, or the last error reading from the
// image server.
Err() error
// Initialized returns a channel that will be closed when the initialization is complete. This can be either
// in an errored state (check Err()) or when the image is ready.
Initialized() <-chan struct{}
}
ImageDownload represents an image download in progress. The caller MUST close the image download when it is finished otherwise the disk will not be unlocked.
type ImageDownloadReader ¶ added in v0.5.0
type ImageDownloadReader interface {
io.Reader
// Read reads the specified bytes from the disk image. This call will block if
// the image is not yet ready for download.
Read(p []byte) (n int, err error)
// Close closes the image download and unlocks the disk.
Close() error
// BytesRead returns the number of bytes read so far. This can be used to
// provide a progress bar.
BytesRead() uint64
// Size returns the size of the disk image in bytes. This is ONLY available after the initialization is complete and
// MAY return 0 before.
Size() uint64
}
type ImageFormat ¶
type ImageFormat string
ImageFormat is a constant for representing the format that images can be in.
const ( ImageFormatCow ImageFormat = "cow" ImageFormatRaw ImageFormat = "raw" )
type Logger ¶
type Logger interface {
ovirtclientlog.Logger
}
type MockClient ¶
type MockClient interface {
Client
// GenerateUUID generates a UUID for testing purposes.
GenerateUUID() string
}
MockClient provides in-memory client functions, and additionally provides the ability to inject information.
func NewMock ¶
func NewMock() MockClient
NewMock creates a new in-memory mock client. This client can be used as a testing facility for higher level code.
type RetryInstance ¶ added in v0.5.0
type RetryInstance interface {
// Continue returns an error if no more tries should be attempted. The error will be returned directly from the
// retry function. The passed action parameters can be used to create a meaningful error message.
Continue(err error, action string) error
// Wait returns a channel that is closed when the wait time expires. The channel can have any content, so it is
// provided as an interface{}. This function may return nil if it doesn't provide a wait time.
Wait(err error) interface{}
// OnWaitExpired is a hook that gives the strategy the option to return an error if its wait has expired. It will
// only be called if it is the first to reach its wait. If no error is returned the loop is continued. The passed
// action names can be incorporated into an error message.
OnWaitExpired(err error, action string) error
}
type RetryStrategy ¶ added in v0.5.0
type RetryStrategy interface {
// Get returns an actual copy of the retry strategy. This can be used to initialize individual timers for
// separate API calls within a larger call structure.
Get() RetryInstance
// CanClassifyErrors indicates if the strategy can determine if an error is retryable. At least one strategy with
// this capability needs to be passed.
CanClassifyErrors() bool
// CanWait indicates if the retry strategy can wait in a loop. At least one strategy with this capability
// needs to be passed.
CanWait() bool
// CanTimeout indicates that the retry strategy can properly abort a loop. At least one retry strategy with
// this capability needs to be passed.
CanTimeout() bool
}
RetryStrategy is a function that creates a new copy of a RetryInstance. It is important because each RetryInstance may have an internal state, so reusing a RetryInstance won't work. RetryStrategy copies can be safely passed around between functions and reused multiple times.
func AutoRetry ¶ added in v0.5.0
func AutoRetry() RetryStrategy
AutoRetry retries an action only if it doesn't return a non-retryable error.
func CallTimeout ¶ added in v0.5.0
func CallTimeout(timeout time.Duration) RetryStrategy
CallTimeout is a strategy that will timeout individual API call retries.
func ContextStrategy ¶ added in v0.5.0
func ContextStrategy(ctx context.Context) RetryStrategy
ContextStrategy provides a timeout based on a context in the ctx parameter. If the context is canceled the retry loop is aborted.
func ExponentialBackoff ¶ added in v0.5.0
func ExponentialBackoff(factor uint8) RetryStrategy
ExponentialBackoff is a retry strategy that increases the wait time after each call by the specified factor.
func MaxTries ¶ added in v0.5.0
func MaxTries(tries uint16) RetryStrategy
MaxTries is a strategy that will timeout individual API calls based on a maximum number of retries. The total number of API calls can be higher in case of a complex functions that involve multiple API calls.
func Timeout ¶ added in v0.5.0
func Timeout(timeout time.Duration) RetryStrategy
Timeout is a strategy that will time out complex calls based on a timeout from the time the strategy factory was created. This is contrast to CallTimeout, which will evaluate timeouts for each individual API call.
type StorageDomain ¶
type StorageDomain interface {
// ID is the unique identified for the storage system connected to oVirt.
ID() string
// Name is the user-given name for the storage domain.
Name() string
// Available returns the number of available bytes on the storage domain
Available() uint64
// Status returns the status of the storage domain. This status may be unknown if the storage domain is external.
// Check ExternalStatus as well.
Status() StorageDomainStatus
// ExternalStatus returns the external status of a storage domain.
ExternalStatus() StorageDomainExternalStatus
}
StorageDomain represents a storage domain returned from the oVirt Engine API.
type StorageDomainClient ¶
type StorageDomainClient interface {
// ListStorageDomains lists all storage domains.
ListStorageDomains(retries ...RetryStrategy) ([]StorageDomain, error)
// GetStorageDomain returns a single storage domain, or an error if the storage domain could not be found.
GetStorageDomain(id string, retries ...RetryStrategy) (StorageDomain, error)
}
StorageDomainClient contains the portion of the goVirt API that deals with storage domains.
type StorageDomainExternalStatus ¶
type StorageDomainExternalStatus string
StorageDomainExternalStatus represents the status of an external storage domain.
const ( StorageDomainExternalStatusNA StorageDomainExternalStatus = "" StorageDomainExternalStatusError StorageDomainExternalStatus = "error" StorageDomainExternalStatusFailure StorageDomainExternalStatus = "failure" StorageDomainExternalStatusInfo StorageDomainExternalStatus = "info" StorageDomainExternalStatusOk StorageDomainExternalStatus = "ok" StorageDomainExternalStatusWarning StorageDomainExternalStatus = "warning" )
type StorageDomainStatus ¶
type StorageDomainStatus string
StorageDomainStatus represents the status a domain can be in. Either this status field, or the StorageDomainExternalStatus must be set.
const ( StorageDomainStatusActivating StorageDomainStatus = "activating" StorageDomainStatusActive StorageDomainStatus = "active" StorageDomainStatusDetaching StorageDomainStatus = "detaching" StorageDomainStatusInactive StorageDomainStatus = "inactive" StorageDomainStatusLocked StorageDomainStatus = "locked" StorageDomainStatusMaintenance StorageDomainStatus = "maintenance" StorageDomainStatusMixed StorageDomainStatus = "mixed" StorageDomainStatusPreparingForMaintenance StorageDomainStatus = "preparing_for_maintenance" StorageDomainStatusUnattached StorageDomainStatus = "unattached" StorageDomainStatusUnknown StorageDomainStatus = "unknown" StorageDomainStatusNA StorageDomainStatus = "" )
type Template ¶
type Template interface {
// ID returns the identifier of the template. This is typically a UUID.
ID() string
// Name is the human-readable name for the template.
Name() string
// Description is a longer description for the template.
Description() string
}
Template is a set of prepared configurations for VMs.
type TemplateClient ¶
type TemplateClient interface {
ListTemplates(retries ...RetryStrategy) ([]Template, error)
GetTemplate(id string, retries ...RetryStrategy) (Template, error)
}
TemplateClient represents the portion of the client that deals with VM templates.
type TestConnectionClient ¶ added in v0.5.0
type TestConnectionClient interface {
// Test tests if the connection is alive or not.
Test() error
}
TestConnectionClient defines the functions related to testing the connection.
type TestHelper ¶
type TestHelper interface {
// GetClient returns the goVirt client.
GetClient() Client
// GetClusterID returns the ID for the cluster.
GetClusterID() string
// GetBlankTemplateID returns the ID of the blank template that can be used for creating dummy VMs.
GetBlankTemplateID() string
// GetStorageDomainID returns the ID of the storage domain to create the images on.
GetStorageDomainID() string
// GenerateRandomID generates a random ID for testing.
GenerateRandomID(length uint) string
}
TestHelper is a helper to run tests against an oVirt engine. When created it scans the oVirt Engine and tries to find working resources (hosts, clusters, etc) for running tests against. Tests should clean up after themselves.
func MustNewTestHelper ¶
type UploadImageProgress ¶
type UploadImageProgress interface {
// Disk returns the disk created as part of the upload process once the upload is complete. Before the upload
// is complete it will return nil.
Disk() Disk
// CorrelationID returns the correlation ID for the upload.
CorrelationID() string
// UploadedBytes returns the number of bytes already uploaded.
UploadedBytes() uint64
// TotalBytes returns the total number of bytes to be uploaded.
TotalBytes() uint64
// Err returns the error of the upload once the upload is complete or errored.
Err() error
// Done returns a channel that will be closed when the upload is complete.
Done() <-chan struct{}
}
UploadImageProgress is a tracker for the upload progress happening in the background.
type UploadImageResult ¶
type UploadImageResult interface {
// Disk returns the disk that has been created as the result of the image upload.
Disk() Disk
// CorrelationID returns the opaque correlation ID for the upload.
CorrelationID() string
}
UploadImageResult represents the completed image upload.
type VMBlockDevice ¶
type VMCPUTopo ¶
func MustNewVMCPUTopo ¶
MustNewVMCPUTopo is identical to NewVMCPUTopo, but panics instead of returning an error if cores, threads, or sockets is zero.
func NewVMCPUTopo ¶
NewVMCPUTopo creates a new CPU topology with the given parameters. It returns an error if cores, threads, or sockets is 0. If the parameters are guaranteed to be non-zero MustNewVMCPUTopo should be used.
Source Files
¶
- client.go
- client_cluster.go
- client_cluster_get.go
- client_cluster_list.go
- client_disk.go
- client_disk_downloadimage.go
- client_disk_get.go
- client_disk_helper_imagetransfer.go
- client_disk_list.go
- client_disk_remove.go
- client_disk_uploadimage.go
- client_host.go
- client_host_get.go
- client_host_list.go
- client_storagedomain.go
- client_storagedomain_get.go
- client_storagedomain_list.go
- client_template.go
- client_template_get.go
- client_template_list.go
- client_testconnection.go
- client_util.go
- client_vm.go
- client_vm_create.go
- const.go
- consts.go
- errors.go
- logger.go
- mock.go
- mock_cluster_get.go
- mock_cluster_list.go
- mock_disk.go
- mock_disk_downloadimage.go
- mock_disk_get.go
- mock_disk_list.go
- mock_disk_remove.go
- mock_disk_uploadimage.go
- mock_host_get.go
- mock_host_list.go
- mock_storagedomain_get.go
- mock_storagedomain_list.go
- mock_template_get.go
- mock_template_list.go
- mock_vm_create.go
- new.go
- newmock.go
- retry.go
- test_helper.go
- util_qcow.go