cmd

Documentation

Overview

Copyright © 2022 Ed Howard exfhoward@protonmail.com

Index

• Constants
• func Execute()
• func ExitCodeForOutcome(outcome ApplyOutcome) int
• type ApplyMode
• type ApplyOutcome
  • func DetermineApplyOutcome(results []ApplyResult) ApplyOutcome
• type ApplyResult
• type Drift
• type FieldChange
• type GroupApplyResult
• type GroupDiffConfig
• type RemediationGuidance
  • func BuildEncryptionGuidance(resourceName, origin string) RemediationGuidance
  • func BuildJobGuidance(resourceName, origin string) RemediationGuidance
  • func BuildKmsGuidance(resourceName, origin string) RemediationGuidance
  • func BuildRepoGuidance(resourceName, origin string) RemediationGuidance
  • func BuildSobrGuidance(resourceName, origin string) RemediationGuidance
• type ResourceApplyConfig
• type ResourceExportConfig
• type ResourceListItem
• type Severity
• type SeverityMap
  • func (sm SeverityMap) GetSeverity(path string) Severity
• type SkippedField

Constants

const (
	// ExitSuccess indicates the command completed successfully.
	// For diff: no drift detected. For apply: all changes accepted.
	ExitSuccess = 0

	// ExitError indicates a general error occurred.
	// Examples: API failure, invalid spec file, network error.
	ExitError = 1

	// ExitDriftWarning indicates drift was detected at INFO or WARNING severity.
	// Used by diff commands when non-critical changes are found.
	ExitDriftWarning = 3

	// ExitDriftCritical indicates drift was detected at CRITICAL severity.
	// Used by diff commands when security-relevant changes are found.
	ExitDriftCritical = 4

	// ExitPartialApply indicates partial success in batch apply operations.
	// Some resources were applied successfully, but others failed.
	// This exit code is used when applying multiple spec files and some succeed
	// while others fail. It is not used for single-resource operations.
	// Note: VBR API uses all-or-nothing semantics per resource, so field-level
	// partial success is not possible within a single resource.
	ExitPartialApply = 5

	// ExitResourceNotFound indicates the target resource does not exist in VBR.
	// Used when applying to update-only resources (repos, SOBRs, KMS)
	// that must be created via VBR console first.
	ExitResourceNotFound = 6
)

Exit codes for owlctl commands. These codes are used for CI/CD integration to distinguish between different outcomes.

Functions

func Execute

func Execute()

func ExitCodeForOutcome

func ExitCodeForOutcome(outcome ApplyOutcome) int

ExitCodeForOutcome returns the appropriate exit code for an apply outcome

Types

type ApplyMode

type ApplyMode int

ApplyMode determines how apply handles missing resources

const (
	// ApplyUpdateOnly only allows updating existing resources (PUT only).
	// Returns an error if the resource doesn't exist.
	// Used for repos, SOBRs, KMS servers which are created via VBR console.
	ApplyUpdateOnly ApplyMode = iota

	// ApplyCreateOrUpdate creates new resources or updates existing ones (POST or PUT).
	// Used for jobs which can be created via API.
	ApplyCreateOrUpdate
)

type ApplyOutcome

type ApplyOutcome int

ApplyOutcome represents the overall outcome of an apply operation

const (
	// OutcomeSuccess means all resources applied successfully
	OutcomeSuccess ApplyOutcome = iota
	// OutcomePartial means some resources succeeded, some failed
	OutcomePartial
	// OutcomeAllFailed means all resources failed
	OutcomeAllFailed
	// OutcomeNotFound means resource not found (update-only mode)
	OutcomeNotFound
)

func DetermineApplyOutcome

func DetermineApplyOutcome(results []ApplyResult) ApplyOutcome

DetermineApplyOutcome analyzes a slice of ApplyResults and returns the overall outcome. An empty results slice returns OutcomeAllFailed as it likely indicates a programming error.

type ApplyResult

type ApplyResult struct {
	ResourceName string
	ResourceID   string
	Action       string         // "created", "updated", "would-create", "would-update"
	NotFound     bool           // True if resource not found in update-only mode
	Changes      []FieldChange  // Fields that were changed
	Skipped      []SkippedField // Fields that were skipped due to policy/known immutability
	DryRun       bool           // True if this was a dry-run (no changes made)
	Error        error
}

ApplyResult contains the result of an apply operation

type Drift

type Drift struct {
	Path     string
	Action   string // "modified", "added", "removed"
	State    interface{}
	VBR      interface{}
	Severity Severity
}

Drift represents a single configuration drift between state and live VBR

type FieldChange

type FieldChange struct {
	Path     string      // Dotted path like "storage.retentionPolicy.quantity"
	OldValue interface{} // Value before apply (from VBR)
	NewValue interface{} // Value after apply (from spec)
}

FieldChange represents a single field that changed during apply

type GroupApplyResult

type GroupApplyResult struct {
	SpecPath     string
	ResourceName string
	Action       string // "created", "updated", "would-create", "would-update"
	Error        error
}

GroupApplyResult tracks the outcome of applying a single spec within a group

type GroupDiffConfig

type GroupDiffConfig struct {
	// Kind is the expected resource kind string used in YAML specs (e.g., "VBRRepository")
	Kind string
	// DisplayName is the human-readable singular name for output (e.g., "repository")
	DisplayName string
	// PluralName is the human-readable plural name (e.g., "repositories"). If empty, DisplayName+"s" is used.
	PluralName string
	// FetchCurrent retrieves the current resource from VBR by name.
	// Returns (rawJSON, resourceID, error). If not found, returns (nil, "", nil).
	FetchCurrent func(name string, profile models.Profile) (json.RawMessage, string, error)
	// IgnoreFields are fields to exclude from drift detection
	IgnoreFields map[string]bool
	// SeverityMap classifies drift fields by severity
	SeverityMap SeverityMap
	// RemediateCmd is the remediation command template shown in summary (e.g., "owlctl repo apply --group %s")
	RemediateCmd string
}

GroupDiffConfig defines resource-specific parameters for group diff operations

type RemediationGuidance

type RemediationGuidance struct {
	Origin       string // "applied" or "observed"
	ResourceType string // e.g., "repository", "job"
	ResourceName string
	ApplyCmd     string // Command to remediate (for applied resources)
	ExportCmd    string // Command to export (for observed resources)
	AdoptCmd     string // Command to adopt (for observed resources)
}

RemediationGuidance contains the guidance to show after diff based on origin

func BuildEncryptionGuidance

func BuildEncryptionGuidance(resourceName, origin string) RemediationGuidance

BuildEncryptionGuidance creates guidance for encryption password diff

func BuildJobGuidance

func BuildJobGuidance(resourceName, origin string) RemediationGuidance

BuildJobGuidance creates guidance for job diff

func BuildKmsGuidance

func BuildKmsGuidance(resourceName, origin string) RemediationGuidance

BuildKmsGuidance creates guidance for KMS server diff

func BuildRepoGuidance

func BuildRepoGuidance(resourceName, origin string) RemediationGuidance

BuildRepoGuidance creates guidance for repository diff

func BuildSobrGuidance

func BuildSobrGuidance(resourceName, origin string) RemediationGuidance

BuildSobrGuidance creates guidance for SOBR diff

type ResourceApplyConfig

type ResourceApplyConfig struct {
	// Kind is the expected resource kind (e.g., "VBRJob", "VBRRepository")
	Kind string

	// Endpoint is the API endpoint (e.g., "jobs", "backupInfrastructure/repositories")
	Endpoint string

	// IgnoreFields are fields to exclude from the PUT payload (read-only fields)
	IgnoreFields map[string]bool

	// Mode determines whether POST is allowed for new resources
	Mode ApplyMode

	// FetchCurrent retrieves the current resource from VBR by name.
	// Returns (rawJSON, resourceID, error).
	// If not found, returns (nil, "", nil) - not an error.
	FetchCurrent func(name string, profile models.Profile) (json.RawMessage, string, error)

	// PreparePayload optionally transforms the merged spec before sending.
	// If nil, the merged spec is sent as-is.
	PreparePayload func(spec, existing map[string]interface{}) (map[string]interface{}, error)

	// PostCreate is called after creating a new resource (ApplyCreateOrUpdate mode only).
	// Returns the resource ID from the API response.
	// If nil, a default implementation extracts "id" from the response.
	PostCreate func(spec map[string]interface{}, profile models.Profile, endpoint string) (string, error)
}

ResourceApplyConfig defines how to apply a specific resource type

type ResourceExportConfig

type ResourceExportConfig struct {
	// Kind is the resource kind (e.g., "VBRRepository")
	Kind string

	// DisplayName is the human-readable singular name (e.g., "repository", "SOBR")
	DisplayName string

	// PluralName is the human-readable plural name (e.g., "repositories", "SOBRs")
	PluralName string

	// IgnoreFields are fields to strip from the exported spec (id, uniqueId, etc.)
	IgnoreFields map[string]bool

	// FetchSingle retrieves a single resource by name (used for single-resource export).
	// Returns (rawJSON, resourceID, error). If not found, returns (nil, "", nil).
	FetchSingle func(name string, profile models.Profile) (json.RawMessage, string, error)

	// FetchByID retrieves a single resource by ID (used for bulk export).
	// If nil, bulk export falls back to FetchSingle(item.Name).
	// Returns (rawJSON, error). If not found, returns (nil, nil).
	FetchByID func(id string, profile models.Profile) (json.RawMessage, error)

	// ListAll lists all resources of this type.
	ListAll func(profile models.Profile) ([]ResourceListItem, error)

	// SanitizeSpec optionally strips sensitive fields from the spec before export.
	// If nil, no sanitization is performed.
	SanitizeSpec func(spec map[string]interface{})

	// SupportsOverlay indicates whether --as-overlay is allowed for this resource type.
	SupportsOverlay bool
}

ResourceExportConfig defines how to export a specific resource type

type ResourceListItem

type ResourceListItem struct {
	ID   string
	Name string
}

ResourceListItem represents a single item in a resource listing

type Severity

type Severity string

Severity represents the security severity level of a drift

const (
	SeverityCritical Severity = "CRITICAL"
	SeverityWarning  Severity = "WARNING"
	SeverityInfo     Severity = "INFO"
)

type SeverityMap

type SeverityMap map[string]Severity

SeverityMap maps field path segments to severity levels. Fields not listed default to INFO.

func (SeverityMap) GetSeverity

func (sm SeverityMap) GetSeverity(path string) Severity

GetSeverity returns the severity for a drift path. Checks full path first, then last segment. Defaults to INFO.

type SkippedField

type SkippedField struct {
	Path   string
	Reason string
}

SkippedField represents a field that was skipped during apply