Writing a Provider¶
This page is aligned to VirtRigaud v0.4.2 and describes how to build a provider against the public SDK in sdk/provider/. External providers are first-class — they implement the same gRPC contract as the in-tree vSphere/Libvirt/Proxmox providers and the manager dials them identically.
For the high-level "what is a provider" overview, see Provider Tutorial. For day-2 operator concerns, see Operations.
Two paths¶
| Path | When to use |
|---|---|
In-tree (internal/providers/<name>/) | You want your provider in the canonical repo; you're comfortable with the project's release cadence and contribution rules. Used by vSphere, Libvirt, Proxmox, Mock. Has direct access to the manager's internal helpers but lives inside the main Go module. A new in-tree provider needs a cmd/provider-<name>/ binary, every RPC implemented (or answered Unimplemented and declared through its capabilities), and an entry in the spec.type enum. |
Out-of-tree, SDK-based (sdk/provider/) | You want to ship your own gRPC server and container image without forking the manager. The SDK is a separate Go module (sdk/go.mod) with a stable API surface. This is the path this page documents. |
spec.type is a closed enum
Provider.spec.type accepts vsphere, libvirt, firecracker, qemu or proxmox (the ProviderType enum in api/infra.virtrigaud.io/v1beta1/provider_types.go) and is immutable. An out-of-tree provider runs under one of those values (it also selects the provider_type metric label); adding a new value is an API change in the main repository.
The vrtg-provider scaffolder¶
vrtg-provider init|generate|verify|publish scaffolds and checks a provider project (see the CLI Tools Reference):
vrtg-provider init myprovider --type libvirt
cd providers/myprovider
go mod tidy
make build
make test
vrtg-provider verify
initwrites a project whose provider answersValidateandGetCapabilitiesand returnsUnimplementedfor the VM operations, with a test, aMakefile, aDockerfileand a CI workflow.--typeacceptsgeneric,vsphere,libvirt,proxmox,firecrackerandqemu(proxmoxis new in v0.4.1: the core profile,raw/qcow2disks andbridge/vlannetworks, nothing optional advertised); it selects the scaffold's template and is separate from the closedProvider.spec.typeenum above.- Since v0.4.1 the SDK and proto modules are published under their own tags (see Go modules).
initfrom a release binary writes ago.modthat requires the three modules at the binary's own version, with noreplacedirectives, and aDockerfilethat builds from the project directory alone. Pass--virtrigaud-path <checkout>(or use a development build inside a checkout) to resolve them from a checkout throughreplacedirectives instead; the image of such a project must be built from a context that contains both. verifybuilds the project, runs its unit tests and reportsgofmt,go vetandgolangci-lintfindings. It does not run the conformance suite, which needs the provider deployed in a cluster: deploy it, then runvcts run --provider <name> --set IMAGE=<vmimage>(see the CLI Tools Reference).publishwrites a catalog entry and records conformance as not run (core: skip); it never claims a pass.
cmd/provider-mock/main.go together with internal/providers/mock/ is a fuller reference implementation.
Go modules: the SDK and proto¶
The repository holds three Go modules. Since v0.4.1 every release publishes all three under their own tags on the same commit, so a provider written outside this repository requires them like any other Go dependency, without a local checkout or replace directives:
| Module | Release tag | Contents |
|---|---|---|
github.com/projectbeskar/virtrigaud | vX.Y.Z | The operator, the providers and the CLIs |
github.com/projectbeskar/virtrigaud/sdk | sdk/vX.Y.Z | The provider SDK: gRPC server, middleware, capabilities, errors, client |
github.com/projectbeskar/virtrigaud/proto | proto/vX.Y.Z | The provider gRPC contract (provider.proto) and its generated Go bindings |
go get github.com/projectbeskar/virtrigaud/sdk@v0.4.2 github.com/projectbeskar/virtrigaud/proto@v0.4.2
- Use the same version for both. The SDK requires the root module and the proto module at its own version, so
go getof the SDK alone selects all three at that version unless your module requires a newer one. The modules need the Go version of the release'sgo.mod(go 1.26.10for v0.4.2); with the defaultGOTOOLCHAIN=autothegocommand downloads it. - Before v0.4.1 there are no tags. Releases up to and including v0.4.0 have no
sdk/orproto/tags:go get github.com/projectbeskar/virtrigaud/sdk@v0.4.0fails withmodule github.com/projectbeskar/virtrigaud@v0.4.0 found, but does not contain package github.com/projectbeskar/virtrigaud/sdk. If you wrote a provider against v0.4.0 or earlier withreplacedirectives or pinned commits, drop them and require the three modules at one release. - Release candidates are tagged too (
sdk/v0.4.1-rc1). Thegocommand never selects a prerelease for@latestonce a release of that module exists. - Only release tags are supported versions of the SDK and proto modules. A pseudo-version of an arbitrary commit (
go get .../sdk@<commit>) resolves the root and proto modules at whatever release that commit'ssdk/go.modnames, not at the same commit. go installof a CLI does not work.go install github.com/projectbeskar/virtrigaud/cmd/<tool>@vX.Y.Zis refused because the rootgo.modhasreplacedirectives; download the CLI binaries from the GitHub release.- Tags are never moved. The Go checksum database records a module version the first time anyone fetches it. A broken version is fixed with a new release, never by re-tagging.
Root and SDK require each other (Go allows a cycle between modules; there is none between packages): the SDK may import the root module's internal/ packages because Go decides internal/ visibility by import path. Inside the repository, replace directives resolve the other modules from the working tree; a consumer ignores them. The lockstep rule and the release procedure are in docs/go-modules.md. The generated Go bindings are imported from github.com/projectbeskar/virtrigaud/proto/rpc/provider/v1.
Contract surface (v0.4.2)¶
The gRPC contract lives in proto/provider/v1/provider.proto (service provider.v1.Provider) and is a separate Go module. The RPCs your provider must implement (or explicitly answer with Unimplemented) are:
# Core lifecycle (all providers must implement)
rpc Validate(ValidateRequest) returns (ValidateResponse);
rpc Create(CreateRequest) returns (CreateResponse);
rpc Delete(DeleteRequest) returns (TaskResponse);
rpc Power(PowerRequest) returns (TaskResponse);
rpc Reconfigure(ReconfigureRequest) returns (TaskResponse);
rpc HardwareUpgrade(HardwareUpgradeRequest) returns (TaskResponse); // vSphere-specific in practice
rpc Describe(DescribeRequest) returns (DescribeResponse);
rpc TaskStatus(TaskStatusRequest) returns (TaskStatusResponse);
# Snapshots (optional via capabilities)
rpc SnapshotCreate(SnapshotCreateRequest) returns (SnapshotCreateResponse);
rpc SnapshotDelete(SnapshotDeleteRequest) returns (TaskResponse);
rpc SnapshotRevert(SnapshotRevertRequest) returns (TaskResponse);
# Clones (optional via capabilities)
rpc Clone(CloneRequest) returns (CloneResponse);
# Image management (optional via capabilities)
rpc ImagePrepare(ImagePrepareRequest) returns (ImagePrepareResponse);
# Capabilities + migration support
rpc GetCapabilities(GetCapabilitiesRequest) returns (GetCapabilitiesResponse);
rpc ExportDisk(ExportDiskRequest) returns (ExportDiskResponse);
rpc ImportDisk(ImportDiskRequest) returns (ImportDiskResponse);
rpc GetDiskInfo(GetDiskInfoRequest) returns (GetDiskInfoResponse);
rpc DeleteStagedDisk(DeleteStagedDiskRequest) returns (DeleteStagedDiskResponse); // nfs / s3 staging cleanup
rpc DeleteLandedDisk(DeleteLandedDiskRequest) returns (DeleteLandedDiskResponse); // unused imported disk cleanup
# Inventory and ownership
rpc ListVMs(ListVMsRequest) returns (ListVMsResponse);
rpc TransferOwner(TransferOwnerRequest) returns (TransferOwnerResponse);
# Host inventory (clustered providers only)
rpc ListHosts(ListHostsRequest) returns (ListHostsResponse);
rpc GetHostInfo(GetHostInfoRequest) returns (HostInfo);
Returning codes.Unimplemented from an RPC is acceptable only if your provider also advertises the absence via the capabilities mechanism — otherwise the manager will try to call it and treat the Unimplemented as a hard failure for migration / snapshot / clone flows. For the optional RPCs added since v0.3.11 the matching declarations are:
| RPC | Declare the absence by |
|---|---|
ListHosts, GetHostInfo | Answering Unimplemented and reporting supports_clustering = false (every non-clustered provider). |
DeleteStagedDisk | Leaving a backend out of supported_staged_disk_delete_backends (empty means the manager never sends it and records the staged object as left behind). |
DeleteLandedDisk | supports_landed_disk_delete = false. |
TransferOwner | supports_owner_transfer = false (single-host) and supports_routed_adoption = false (clustered). |
Ownership and clustered providers¶
Two contracts matter to every provider author, because the manager sends the fields to every provider and keys safety decisions on what the provider reports:
- Owner stamps.
CreateRequest.owner(anObjectIdentitywithuid,namespace,name) identifies theVirtualMachinea create is for. A provider whose hypervisor-side names are not unique across namespaces stamps the owner onto the VM it creates, treats a create for a VM that already exists as an idempotent success only when the stamp carries the sameuid, and otherwise fails closed withALREADY_EXISTS.ListVMsreports each VM'sowner_namespace/owner_name(andowner_uidinprovider_raw), honours the optionalListVMsRequest.owner_namespace/owner_namefilter, andTransferOwnerre-stamps a VM compare-and-swap when the manager adopts it. Advertise what you implement withsupports_owner_rebind(Create and Clone re-bind to the VM an earlier attempt made, never a second one),supports_owner_transfer,supports_list_owner_filterandsupports_routed_adoption. - Clustered providers. A Provider with
spec.topology: clusterfronts several hosts. The manager decides placement and sends the chosen host astarget_host_idon the per-VM requests (andsource_host_idonClone); single-host providers never receive it. A clustered provider must route by it, must not default to some host when it is empty, implementsListHosts/GetHostInfo(returningHostInfowith allocatable CPU, memory and storage, health, labels and CPU/emulator details), tags everyVMInfowithhost_idand names the hosts it could not list inListVMsResponse.unreachable_host_ids, and reportssupports_clustering(plussupports_routed_clone,supports_routed_importand the flags above). See the Libvirt provider guide for the operator-side behaviour.
Both are additive in the proto: a provider that predates them keeps working and the manager falls back to the earlier behaviour (for example, it never re-sends an uncertain Create to a provider that does not report supports_owner_rebind).
SDK packages¶
The SDK is laid out as five packages under sdk/provider/:
| Package | What it gives you | Source |
|---|---|---|
server | gRPC + HTTP health server bootstrap, TLS config (including certificate hot-reload and ResolveTLSAndAuth), keep-alive defaults, optional /metrics handler, graceful shutdown. | sdk/provider/server/server.go, sdk/provider/server/tlsconfig.go |
middleware | Unary + stream interceptors: recovery, logging, timeout, metrics, rate limiting, and Auth.RequireTLS / Auth.BearerTokenAuth. | sdk/provider/middleware/middleware.go |
capabilities | Builder for GetCapabilitiesResponse. Encodes flags like SupportsSnapshots, SupportsLinkedClones. | sdk/provider/capabilities/capabilities.go |
errors | Typed errors (NewNotFound, NewInvalidSpec, etc.) that map cleanly to gRPC status codes via .GRPCStatus(). | sdk/provider/errors/errors.go |
client | High-level gRPC client (mostly useful for testing your provider end-to-end from another Go program). | sdk/provider/client/client.go |
The sdk/provider/doc.go is the canonical entry point; it includes a working server example.
Compatibility commitment¶
sdk/ is a separate Go module from internal/. Per sdk/provider/doc.go:
The SDK abstracts the underlying gRPC protocol and provides stable interfaces that will not change in minor releases, even if the internal RPC protocol evolves.
Breaking changes ship in major SDK releases only. The proto module (proto/) is also separate; new RPCs and fields land additively, and a generated server that embeds UnimplementedProviderServer keeps compiling.
Minimal SDK-based provider¶
package main
import (
"context"
"log"
"log/slog"
"github.com/projectbeskar/virtrigaud/sdk/provider/capabilities"
"github.com/projectbeskar/virtrigaud/sdk/provider/errors"
"github.com/projectbeskar/virtrigaud/sdk/provider/middleware"
"github.com/projectbeskar/virtrigaud/sdk/provider/server"
providerv1 "github.com/projectbeskar/virtrigaud/proto/rpc/provider/v1"
)
// MyProvider is your provider implementation. It must satisfy the
// providerv1.ProviderServer interface (the embedded
// UnimplementedProviderServer lets the compiler accept partial impls
// during development).
type MyProvider struct {
providerv1.UnimplementedProviderServer
caps *capabilities.Manager
}
func (p *MyProvider) Validate(ctx context.Context, req *providerv1.ValidateRequest) (*providerv1.ValidateResponse, error) {
// Your hypervisor reachability check goes here.
return &providerv1.ValidateResponse{Ok: true}, nil
}
func (p *MyProvider) Describe(ctx context.Context, req *providerv1.DescribeRequest) (*providerv1.DescribeResponse, error) {
vm, ok := p.lookupVM(req.Id)
if !ok {
// Typed error → gRPC codes.NotFound automatically.
return nil, errors.NewNotFound("VirtualMachine", req.Id)
}
return p.describeVM(vm), nil
}
func (p *MyProvider) GetCapabilities(ctx context.Context, req *providerv1.GetCapabilitiesRequest) (*providerv1.GetCapabilitiesResponse, error) {
return p.caps.GetCapabilities(ctx, req)
}
// ... implement the rest of the contract, returning
// errors.NewUnimplemented(...) for RPCs you do not support and reflecting
// that in p.caps so the manager knows not to call them.
func main() {
caps := capabilities.NewBuilder().
Core(). // Validate/Create/Delete/Power/Describe/GetCapabilities
Snapshots(). // We support snapshots
DiskTypes("qcow2", "raw").
NetworkTypes("bridge", "nat").
Build()
cfg := server.DefaultConfig()
cfg.ServiceName = "my-provider"
cfg.Port = 9443
cfg.HealthPort = 8080
cfg.Middleware = &middleware.Config{
Recovery: &middleware.RecoveryConfig{Enabled: true},
Logging: &middleware.LoggingConfig{Enabled: true, Logger: slog.Default()},
}
// TLS: see "mTLS" below. In a pod run by the manager, resolve it from
// the standard mount instead of hard-coding paths:
// res, err := server.ResolveTLSAndAuth()
// cfg.TLS = res.TLS
// cfg.Middleware.Auth = res.Auth
srv, err := server.New(cfg)
if err != nil {
log.Fatalf("server.New: %v", err)
}
srv.RegisterProvider(&MyProvider{caps: caps})
if err := srv.Serve(context.Background()); err != nil {
log.Fatalf("Serve: %v", err)
}
}
lookupVM and describeVM stand for your own hypervisor code. The skeleton above (minus those two helpers) compiles against the v0.4.2 SDK.
Why the Unimplemented embedding matters¶
The generated gRPC code uses the forward-compatible service registration pattern: embedding providerv1.UnimplementedProviderServer in your struct means proto evolution that adds new RPCs does not break your provider's build — the unimplemented embeddings supply default Unimplemented responses for the new RPCs until you fill them in. Always embed it, and keep your method signatures identical to the generated interface (a method with the same name but a different signature, such as an old ImagePrepare that returns *TaskResponse, hides the embedded one and the type no longer satisfies ProviderServer).
Capabilities — the contract for "what works"¶
The manager fetches GetCapabilities on its Provider reconcile, once the Provider is healthy and its runtime is Running, and writes the result to the Provider's status. It surfaces what a provider reported under Provider.status.reportedCapabilities, and an opt-in --enforce-provider-capabilities manager flag (default off) makes the manager refuse snapshot and migration operations a provider does not advertise. Intrinsic correctness gates — such as the VMClone linked-clone pre-check — run regardless of that flag, so advertising a capability you do not implement will still surface as a failure.
Capabilities the manager reads from GetCapabilitiesResponse (proto/provider/v1/provider.proto), and the SDK builder method that sets each:
| Capability flag | Set via builder | Meaning |
|---|---|---|
supports_reconfigure_online | .OnlineReconfigure() | CPU/memory changes while powered on. |
supports_disk_expansion_online | .OnlineDiskExpansion() | Disk expansion while powered on. |
supports_snapshots | .Snapshots() | SnapshotCreate/Delete/Revert work. |
supports_memory_snapshots | .MemorySnapshots() | Snapshots include memory state. |
supports_linked_clones | .LinkedClones() | Clone produces a linked (CoW) clone. |
supports_image_import | .ImageImport() | ImagePrepare is meaningful. |
supports_image_artifact_identity | .ImageArtifactIdentity() | ImagePrepare names and stamps prepared artifacts from the image/source-digest/provider identity and never reuses one by bare name (identity-safe image preparation). The manager holds import-style prepares through a provider that supports image import but does not advertise this. |
supports_honest_reconfigure | .HonestReconfigure() | Reconfigure applies every requested change (to the running VM and its definition), or reports restart_required, or fails; it never reports success for a change it did not apply. |
supports_disk_export / supports_disk_import | .DiskExport(formats...) / .DiskImport(formats...) | Disk export / import for migration, with the formats; also .ExportCompression(). |
supported_export_backends[] / supported_import_backends[] / supported_transfer_modes[] | .ExportBackends(...) / .ImportBackends(...) / .TransferModes(...) | Migration staging backends (pvc, nfs, s3) and transfer modes (relay, direct); empty means PVC and relay only. |
supports_clustering | .Clustering() | Fronts several hosts and implements ListHosts / GetHostInfo. |
supports_owner_transfer, supports_owner_rebind, supports_import_size_limit, supports_landed_disk_delete, supports_routed_import | .OwnerTransfer(), .OwnerRebind(), .ImportSizeLimit(), .LandedDiskDelete(), .RoutedImport() | Ownership and migration-safety contracts described above and in the proto comments. |
supported_staged_disk_delete_backends[], resend_safe_export_backends[], resend_safe_import_backends[] | .StagedDiskDeleteBackends(...), .ResendSafeExportBackends(...), .ResendSafeImportBackends(...) | Backends on which staging cleanup and re-sent export/import are safe. |
supports_routed_adoption, supports_list_owner_filter | Manager.AddCapability(capabilities.CapabilityRoutedAdoption) / CapabilityListOwnerFilter | Clustered-provider ListVMs/TransferOwner contracts (no dedicated builder method). supports_routed_clone is also not set by the SDK's GetCapabilities. |
supported_disk_types[] | .DiskTypes(...) | E.g. "qcow2", "raw", "vmdk". |
supported_network_types[] | .NetworkTypes(...) | E.g. "bridge", "nat", "vlan". |
Be honest. Returning supports_linked_clones: true while having Clone return a non-linked synthetic response is the kind of drift that caused real audit findings against the in-tree libvirt provider (see Libvirt Host Prep). In v0.4.2 the in-tree libvirt provider implements full clones and advertises supports_linked_clones: false (it refuses a linked clone because the source disk is not frozen), so a VMClone that asks for a linked clone against a libvirt source is refused cleanly rather than silently producing a broken VM. Reflect the real shape of your implementation; the operator's Provider Capabilities Matrix page is the source of truth they consult.
Error handling¶
Use the typed constructors in sdk/provider/errors. They wrap a gRPC status.Status with a structured error type and automatically map to the right codes.Code:
import "github.com/projectbeskar/virtrigaud/sdk/provider/errors"
// codes.NotFound
return nil, errors.NewNotFound("VirtualMachine", id)
// codes.InvalidArgument
return nil, errors.NewInvalidSpec("CPU count must be > 0, got %d", req.Cpu)
// codes.PermissionDenied
return nil, errors.NewPermissionDenied("describe VM")
// codes.Unavailable — typically used for hypervisor outages.
// The manager's CircuitBreaker counts these toward the failure threshold
// (FailureThreshold=10 by default, see internal/transport/grpc/client.go:isInfraFailure).
return nil, errors.NewUnavailable("vCenter", cause)
The full constructor list (NewInvalidSpec, NewNotFound, NewAlreadyExists, NewPermissionDenied, NewUnavailable, NewInternal, NewUnimplemented, NewTimeout, NewRateLimit, NewCanceled) is in sdk/provider/errors/errors.go.
What the manager's CircuitBreaker counts¶
Per internal/transport/grpc/client.go:isInfraFailure, the manager's per-Provider CircuitBreaker counts these gRPC codes as infra failures toward the threshold:
UnavailableDeadlineExceededInternalUnknown
These are not counted (operational failures, not provider-health issues):
NotFound,AlreadyExists,InvalidArgument,PermissionDenied,Unauthenticated,FailedPrecondition,ResourceExhausted,Aborted,OutOfRange,Unimplemented,Canceled.
Some answers never count whatever their code, because the provider answered and is healthy: a clustered provider's host-scoped Unavailable (HOST_UNAVAILABLE), a per-VM operation that failed on its host (VM_OPERATION_FAILED), a refused disk dependency check (VM_DISK_CHECK_FAILED), a VM_OUTCOME_UNKNOWN_RETRY outcome, and, on ImagePrepare, IMAGE_ARTIFACT_IN_PROGRESS / IMAGE_SOURCE_UNAVAILABLE and manager-side DeadlineExceeded / Canceled. Using these reasons is how a clustered provider keeps one dead host or one tenant's failing request from opening the breaker for every VM of the Provider.
Returning Unavailable for a transient SSH blip is exactly correct — the breaker will Open after enough such failures, and your provider's operator will see it via virtrigaud_circuit_breaker_state{provider=…}. Returning Internal for a business error (a bad request) would count against the provider's health; use InvalidArgument, NotFound or FailedPrecondition for those.
See Resilience for the full classification.
mTLS and bearer-token auth¶
The SDK supports both. The in-tree manager negotiates mTLS with providers; it does not send bearer tokens.
Server side (your provider)¶
For a provider the manager deploys (spec.runtime), the manager mounts the TLS material at /etc/virtrigaud/tls/{tls.crt,tls.key,ca.crt} and sets VIRTRIGAUD_PROVIDER_INSECURE=true only when the Provider disables TLS. Resolve that contract with one call, exactly as the in-tree providers do:
res, err := server.ResolveTLSAndAuth()
switch {
case err == nil:
// TLS material present: mTLS (RequireClientCert), leaf-certificate hot reload.
case errors.Is(err, server.ErrInsecureModeOptedIn):
// No TLS files and VIRTRIGAUD_PROVIDER_INSECURE=true: plaintext (log a loud warning).
default:
log.Fatalf("TLS: %v", err) // no material and no explicit opt-out: refuse to start
}
cfg.TLS = res.TLS
cfg.Middleware.Auth = res.Auth
(errors here is the standard library package; import the SDK's errors package under another name if you use both.) VIRTRIGAUD_PROVIDER_ALLOWED_SANS (comma-separated) restricts which SANs of the manager's client certificate are accepted; empty accepts any certificate signed by the configured CA.
To configure TLS by hand instead:
cfg.TLS = &server.TLSConfig{
CertFile: "/etc/certs/tls.crt",
KeyFile: "/etc/certs/tls.key",
CAFile: "/etc/certs/ca.crt",
RequireClientCert: true, // mTLS: require + verify client cert
AutoReload: true, // hot-reload the leaf cert (the CA still needs a restart)
}
cfg.Middleware.Auth = &middleware.AuthConfig{
RequireTLS: true,
AllowedSANs: []string{"virtrigaud-manager.example.com"},
}
Manager side¶
- mTLS. The manager builds a TLS 1.3 client configuration from the Secret named by
Provider.spec.runtime.service.tls.secretRef(keystls.crt,tls.key,ca.crt) and verifies the provider's certificate against the Service namevirtrigaud-provider-<namespace>-<name>.<namespace>.svc.cluster.local(internal/runtime/remote/resolver.go,buildTLSConfig). Thetlsblock must be set explicitly: an unset block is reported asTLSConfigured=False(TLSBlockMissing) rather than silently falling back to plaintext;tls.enabled: falseis the explicit plaintext opt-out. - Bearer tokens.
internal/transport/grpcdoes not attach anAuthorization: Bearer …header to outbound RPCs. If you enableBearerTokenAuthon a provider the in-tree manager dials, the manager's RPCs will fail withUnauthenticated. Use mTLS (RequireTLS) for manager-to-provider authentication.
See mTLS and Bearer Token for the operator-facing configuration.
proto + SDK regeneration¶
The protobuf bindings are owned by the proto/ module and regenerated with buf:
# In the virtrigaud repo root
make proto # regen all Go bindings (proto/rpc/provider/v1/)
make proto-lint # buf lint
make proto-breaking # check for breaking changes vs the main branch
The generated files are committed, and CI's Verify Generated Files job fails if they are out of date. A new RPC in provider.proto must be implemented, or stubbed with Unimplemented and declared through the capabilities, in all four in-tree providers (vsphere, libvirt, proxmox, mock). To pick up a new contract in an external provider, update the required SDK and proto versions (see Go modules) and regenerate nothing — the bindings are consumed as a Go package.
Building and publishing¶
There is no opinionated build harness for external providers. The in-tree providers use the build/Dockerfile.manager pattern (parameterised on BUILDER_IMAGE/BASE_IMAGE/GOPROXY); you can adopt that pattern or your own.
Minimal Dockerfile sketch for an SDK-based provider:
# syntax=docker/dockerfile:1
ARG BUILDER_IMAGE=docker.io/golang:1.26.10
ARG BASE_IMAGE=gcr.io/distroless/static:nonroot
FROM ${BUILDER_IMAGE} AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/provider .
FROM ${BASE_IMAGE}
COPY --from=build /out/provider /provider
ENTRYPOINT ["/provider"]
EXPOSE 9443 8080
USER 65532:65532
Then wire the image into a Provider CR. The manager runs it as a Deployment (spec.runtime), passes the Provider's settings in environment variables (PROVIDER_TYPE, PROVIDER_ENDPOINT, PROVIDER_NAMESPACE, PROVIDER_NAME, TLS_ENABLED, TLS_INSECURE_SKIP_VERIFY, LOG_LEVEL, LOG_FORMAT), mounts the credentials Secret at /etc/virtrigaud/credentials and the TLS Secret at /etc/virtrigaud/tls:
apiVersion: infra.virtrigaud.io/v1beta1
kind: Provider
metadata:
name: my-provider
namespace: default
spec:
type: qemu # must be one of the ProviderType enum values
endpoint: qemu+ssh://hypervisor.example.com/system # passed to your provider as PROVIDER_ENDPOINT
credentialSecretRef:
name: my-provider-creds
runtime:
mode: Remote
image: ghcr.io/my-org/my-provider:v0.1.0
service:
port: 9443
tls:
enabled: true
secretRef:
name: my-provider-tls # tls.crt, tls.key, ca.crt
Reference implementations¶
The in-tree providers are the best examples; reading them is the fastest way to understand the contract:
| Provider | File | Notes |
|---|---|---|
| vSphere | internal/providers/vsphere/server.go | Pure-Go, uses govmomi. The most feature-complete in-tree provider; supports linked clones and online reconfigure. |
| Libvirt | internal/providers/libvirt/server.go and the other files in that package | Pure Go (CGO_ENABLED=0): in-process SSH transport, virsh on the host for most operations, and an opt-in go-libvirt shadow-compare read path. Full clones only. Implements the clustered-provider contract (topology: cluster), owner stamps and routed per-host lifecycle. |
| Proxmox | internal/providers/proxmox/server.go | Uses the Proxmox REST API with API-token auth (the recommended Proxmox posture). |
| Mock | internal/providers/mock/ + cmd/provider-mock/main.go | The smallest complete provider; useful as a starting skeleton. |
A useful exercise when starting a new provider: read cmd/provider-mock/main.go end-to-end; it's the SDK in production, minus a real hypervisor.
See also¶
- SDK doc.go — canonical usage example.
- proto/provider/v1/provider.proto — the contract.
- Provider gRPC API — the generated reference for the contract.
- Provider Tutorial — operator-facing walkthrough.
- Provider Capabilities Matrix — what each in-tree provider can and cannot do; useful as a comparison for declaring your own capabilities.
- Resilience — failure classification and CircuitBreaker behavior; informs your error-code choices.
- mTLS, Bearer Token, Network Policies — the manager-to-provider security controls.