drydock

package
v0.1.20 Latest Latest
Warning

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

Go to latest
Published: Jun 10, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package drydock exposes the drydock orchestrator as an embeddable Go API for rendering Argo CD Applications and calculating local diffs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Application

type Application struct {
	Namespace string
	Name      string
	Project   string
}

Application identifies an Argo CD Application.

type ApplicationSetProviderCluster

type ApplicationSetProviderCluster struct {
	Name        string
	Server      string
	Project     string
	Labels      map[string]string
	Annotations map[string]string
	Values      map[string]string
}

ApplicationSetProviderCluster mirrors one cluster fixture entry.

type ApplicationSetProviderClusterDecision

type ApplicationSetProviderClusterDecision struct {
	ConfigMapRef  string
	ResourceName  string
	Labels        map[string]string
	MatchKey      string
	StatusListKey string
	Decisions     []map[string]any
	Values        map[string]string
}

ApplicationSetProviderClusterDecision mirrors one cluster decision fixture entry.

type ApplicationSetProviderData

type ApplicationSetProviderData struct {
	Clusters         []ApplicationSetProviderCluster
	ClusterDecisions []ApplicationSetProviderClusterDecision
	SCMRepositories  []ApplicationSetProviderSCMRepository
	PullRequests     []ApplicationSetProviderPullRequest
	Plugins          []ApplicationSetProviderPlugin
}

ApplicationSetProviderData supplies explicit offline data for provider-backed ApplicationSet generators.

type ApplicationSetProviderPlugin

type ApplicationSetProviderPlugin struct {
	ConfigMapRef string
	Outputs      []map[string]any
	Values       map[string]string
}

ApplicationSetProviderPlugin mirrors one plugin fixture entry.

type ApplicationSetProviderPullRequest

type ApplicationSetProviderPullRequest struct {
	Provider     string
	Organization string
	Project      string
	Repository   string
	Number       int
	Title        string
	Branch       string
	TargetBranch string
	HeadSHA      string
	Author       string
	State        string
	Labels       []string
	Values       map[string]string
}

ApplicationSetProviderPullRequest mirrors one pull request fixture entry.

type ApplicationSetProviderSCMRepository

type ApplicationSetProviderSCMRepository struct {
	Provider     string
	Organization string
	Project      string
	Region       string
	Repository   string
	RepositoryID string
	Branch       string
	SHA          string
	URL          string
	Tags         map[string]string
	Labels       []string
	Paths        []string
	Values       map[string]string
}

ApplicationSetProviderSCMRepository mirrors one SCM repository fixture entry.

type ApplicationStatus

type ApplicationStatus struct {
	Application Application
	Status      string
	Message     string
}

ApplicationStatus reports whether rendering an Application passed, failed, or was skipped.

type CacheEvent

type CacheEvent struct {
	Source   string
	Action   string
	Target   string
	Revision string
	CacheHit bool
	Offline  bool
	Refresh  bool
	Error    string
}

CacheEvent describes an optional source acquisition cache observation.

type ChartAcquirer

type ChartAcquirer interface {
	Acquire(ctx context.Context, request ChartRequest, opts ChartOptions) (ChartResult, error)
}

ChartAcquirer acquires Helm charts for Application rendering.

type ChartCredentials

type ChartCredentials struct {
	Username       string
	Password       string
	BearerToken    string
	RegistryConfig string
}

ChartCredentials supplies credentials for Helm chart acquisition.

type ChartOptions

type ChartOptions struct {
	CacheDir    string
	Offline     bool
	Refresh     bool
	Credentials ChartCredentials
}

ChartOptions controls Helm chart acquisition.

type ChartRequest

type ChartRequest struct {
	Repository string
	Name       string
	Version    string
	Kind       RepositoryKind
}

ChartRequest identifies a Helm chart to acquire.

type ChartResult

type ChartResult struct {
	ChartDir   string
	Repository string
	Name       string
	Version    string
	Kind       RepositoryKind
	FromCache  bool
}

ChartResult describes an acquired Helm chart.

type Client

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

Client runs drydock operations with a reusable Config and optional injected source acquirers.

func NewClient

func NewClient(config Config) *Client

NewClient creates a Client from config.

If GitAcquirer, ChartAcquirer, or RemoteResourceAcquirer are set, the client uses those implementations instead of the default local fetchers.

func (*Client) DiffApplications

func (client *Client) DiffApplications(ctx context.Context) (DiffApplicationsResult, error)

DiffApplications compares rendered Applications between the client's PathOrig and Path.

func (*Client) DiffImages

func (client *Client) DiffImages(ctx context.Context) (ImageDiffResult, error)

DiffImages compares image references between the client's PathOrig and Path.

func (*Client) ListApplications

func (client *Client) ListApplications(ctx context.Context) (ListApplicationsResult, error)

ListApplications returns Applications discovered under the client's Path.

func (*Client) Render

func (client *Client) Render(ctx context.Context) (RenderResult, error)

Render creates manifests for Applications found under the client's Path.

When an Application fails to render, the returned RenderResult may still contain partial manifests, diagnostics, and per-Application statuses.

type Config

type Config struct {
	// Path is the working tree to inspect for render/list operations and the
	// right side for diff operations.
	Path string
	// PathOrig is the left-side working tree for diff operations when comparing
	// two checked-out trees.
	PathOrig string
	// Repo is a local Git repository used with Ref or RefOrig when drydock should
	// materialize comparison worktrees from Git refs.
	Repo string
	// Ref is the right-side Git ref for diff operations.
	Ref string
	// RefOrig is the left-side Git ref for diff operations.
	RefOrig string
	// DiscoveryMode selects the Application discovery strategy. Empty uses the
	// CLI/default discovery behavior.
	DiscoveryMode string
	// MaxDiscoveryDepth limits recursive rendered Application discovery. Nil uses
	// the default; a pointer to zero disables recursive depth.
	MaxDiscoveryDepth *int
	// DiscoverKustomizePaths adds explicit Kustomize entrypoints to rendered
	// bootstrap discovery.
	DiscoverKustomizePaths []string
	// Strict promotes supported diagnostics that are warnings by default to
	// operation errors.
	Strict bool
	// ProjectDiagnosticsMode controls AppProject-adjacent diagnostics.
	ProjectDiagnosticsMode ProjectDiagnosticsMode
	// Offline disables source-network acquisition and requires local inputs,
	// explicit repo maps, or cache hits.
	Offline bool
	// RefreshCharts refreshes chart cache entries instead of reusing cached
	// charts when network acquisition is allowed.
	RefreshCharts bool
	// ChartCacheDir overrides the Helm chart cache root.
	ChartCacheDir string
	// ChartCredentials supplies credentials for chart repository acquisition.
	ChartCredentials ChartCredentials
	// RepoMaps map declared source repository URLs to local checkout paths.
	RepoMaps []RepoMap
	// Deprecated: Git, chart, and remote resource acquisition are enabled by
	// default. Set Offline to true to disable network acquisition. Offline is
	// authoritative when both fields are set.
	AllowNetwork bool
	// GitCacheDir overrides the Git source cache root.
	GitCacheDir string
	// RefreshGit refreshes Git cache entries instead of reusing cached checkouts
	// when network acquisition is allowed.
	RefreshGit bool
	// GitCredentials supplies credentials for Git source acquisition.
	GitCredentials GitCredentials
	// RefreshRemoteResources refreshes remote Kustomize resource cache entries
	// instead of reusing cached resources when network acquisition is allowed.
	RefreshRemoteResources bool
	// RemoteResourceCacheDir overrides the remote Kustomize resource cache root.
	RemoteResourceCacheDir string
	// RemoteResourceForbiddenRoots rejects remote-resource cache locations under
	// protected roots.
	RemoteResourceForbiddenRoots []string
	// RemoteResourceCredentials supplies credentials for remote Kustomize HTTP
	// resources.
	RemoteResourceCredentials RemoteResourceCredentials
	// EnableAVPCompat forces argocd-vault-plugin placeholder redaction for
	// native-rendered sources. Explicit argocd-vault-plugin sources use native
	// compatibility by default.
	EnableAVPCompat bool
	// EnablePlugins allows trusted PluginPolicy exec or container engines to run
	// when policy provenance matches.
	EnablePlugins bool
	// PluginPolicyPath points to a drydock PluginPolicy file.
	PluginPolicyPath string
	// PluginPolicyPathExplicit records whether PluginPolicyPath was explicitly
	// configured by the caller.
	PluginPolicyPathExplicit bool
	// PluginPolicyRef is the Git ref used to load repository-local plugin policy.
	PluginPolicyRef string
	// PluginPolicyRepo is the repository root used to load repository-local
	// plugin policy.
	PluginPolicyRepo string
	// DisablePluginPolicy disables repository-local plugin policy loading.
	DisablePluginPolicy bool
	// PluginRenderer injects an in-process plugin renderer for embedded callers.
	PluginRenderer PluginRenderer
	// PluginTimeout limits each plugin render request. Zero uses the default.
	PluginTimeout time.Duration
	// Parallelism limits concurrent Application rendering. Zero uses the default.
	Parallelism int
	// SkipKinds omits rendered resources with matching kind names.
	SkipKinds []string
	// SkipCRDs omits rendered CustomResourceDefinition resources.
	SkipCRDs bool
	// SkipSecrets omits rendered Secret resources.
	SkipSecrets bool
	// ApplicationSetProviderFixtures loads provider-backed ApplicationSet fixture
	// data from files.
	ApplicationSetProviderFixtures []string
	// ApplicationSetProviderData supplies provider-backed ApplicationSet fixture
	// data directly.
	ApplicationSetProviderData ApplicationSetProviderData
	// ChangedOnly controls PR-focused changed-only selection. Nil uses the
	// operation default.
	ChangedOnly *bool
	// ChangedOnlyIncludes adds changed-only include globs.
	ChangedOnlyIncludes []string
	// ChangedOnlyIgnores adds changed-only ignore globs.
	ChangedOnlyIgnores []string
	// StrictChangedOnly turns changed-only selection diagnostics into operation
	// errors.
	StrictChangedOnly bool
	// Unified controls unified diff context lines. Zero uses the default.
	Unified int
	// StripAttrs removes matching manifest attributes before diffing.
	StripAttrs []string
	// ShowIgnoredFields includes Argo CD ignored-field differences in diffs.
	ShowIgnoredFields bool
	// GitAcquirer injects Git source acquisition for deterministic embedding.
	GitAcquirer GitAcquirer
	// ChartAcquirer injects Helm chart acquisition for deterministic embedding.
	ChartAcquirer ChartAcquirer
	// RemoteResourceAcquirer injects remote Kustomize resource acquisition for
	// deterministic embedding.
	RemoteResourceAcquirer RemoteResourceAcquirer
	// RecordCacheEvents includes source acquisition cache events in results.
	RecordCacheEvents bool
}

Config controls render, list, and diff operations.

Path is the working tree to inspect for render/list operations and the right side for diff operations. PathOrig is the left side for diff operations. Use keyed struct literals; new fields may be added as drydock gains parity.

type Diagnostic

type Diagnostic struct {
	Code       string
	Severity   string
	Category   string
	Message    string
	Provenance Provenance
}

Diagnostic describes a warning, error, or informational finding.

type DiffApplicationsResult

type DiffApplicationsResult struct {
	Results     []DiffResult
	Diagnostics []Diagnostic
	CacheEvents []CacheEvent
}

DiffApplicationsResult is returned by Application diff operations.

func DiffApplications

func DiffApplications(ctx context.Context, config Config) (DiffApplicationsResult, error)

DiffApplications compares rendered Applications between config.PathOrig and config.Path.

type DiffParent

type DiffParent struct {
	Namespace   string
	Name        string
	SourceIndex int
	SourceName  string
	SourcePath  string
}

DiffParent identifies the Application source that produced a diff.

type DiffResult

type DiffResult struct {
	Parent   DiffParent
	Resource Resource
	Change   string
	Diff     string
}

DiffResult describes one resource-level Application diff.

type GitAcquirer

type GitAcquirer interface {
	Acquire(ctx context.Context, request GitRequest, opts GitOptions) (GitResult, error)
}

GitAcquirer acquires Git sources for Application rendering.

type GitCredentials

type GitCredentials struct {
	Username          string
	Password          string
	BearerToken       string
	SSHPrivateKeyPath string
	SSHPrivateKey     string
	SSHPassphrase     string
	SSHKnownHostsPath string
}

GitCredentials supplies credentials for Git source acquisition.

type GitOptions

type GitOptions struct {
	// AllowNetwork is set by drydock for custom acquirers. Users should set
	// Config.Offline to disable network acquisition.
	AllowNetwork bool
	CacheDir     string
	Refresh      bool
	Credentials  GitCredentials
}

GitOptions controls Git source acquisition.

type GitRequest

type GitRequest struct {
	URL      string
	Revision string
}

GitRequest identifies a Git source to acquire.

type GitResult

type GitResult struct {
	Path      string
	Revision  string
	FromCache bool
	Network   bool
}

GitResult describes an acquired Git source.

type ImageDiffResult

type ImageDiffResult struct {
	Added       []string
	Removed     []string
	Unchanged   []string
	Diagnostics []Diagnostic
	CacheEvents []CacheEvent
}

ImageDiffResult is returned by image diff operations.

func DiffImages

func DiffImages(ctx context.Context, config Config) (ImageDiffResult, error)

DiffImages compares image references between config.PathOrig and config.Path.

type ListApplicationsResult

type ListApplicationsResult struct {
	Applications []Application
	Diagnostics  []Diagnostic
	CacheEvents  []CacheEvent
}

ListApplicationsResult is returned by list operations.

func ListApplications

func ListApplications(ctx context.Context, config Config) (ListApplicationsResult, error)

ListApplications returns Applications discovered under config.Path.

type Manifest

type Manifest struct {
	Application Application
	SourceIndex int
	SourceName  string
	SourcePath  string
	Object      map[string]any
}

Manifest is one rendered Kubernetes object with source provenance.

type PluginArrayParameter

type PluginArrayParameter struct {
	Values []string
}

PluginArrayParameter wraps an array parameter so present-empty arrays are distinct from absent array parameters.

type PluginConfig

type PluginConfig struct {
	Name       string
	Env        []PluginEnvEntry
	Parameters []PluginParameter
}

PluginConfig is the explicit plugin configuration from an Application source.

type PluginEnvEntry

type PluginEnvEntry struct {
	Name  string
	Value string
}

PluginEnvEntry is one explicit plugin environment entry.

type PluginExecution added in v0.1.6

type PluginExecution struct {
	Application Application
	SourceIndex int
	SourceName  string
	SourcePath  string
	PluginName  string
	Engine      string
	Runtime     string
	Image       string
	Phase       string
	Command     string
	Duration    string
}

PluginExecution describes one trusted plugin command that ran.

type PluginManifest

type PluginManifest struct {
	Path   string
	Object map[string]any
}

PluginManifest is one rendered plugin object with optional source path.

type PluginMapParameter

type PluginMapParameter struct {
	Values map[string]string
}

PluginMapParameter wraps a map parameter so present-empty maps are distinct from absent map parameters.

type PluginParameter

type PluginParameter struct {
	Name   string
	String *string
	Map    *PluginMapParameter
	Array  *PluginArrayParameter
}

PluginParameter is one plugin parameter. String, Map, and Array preserve Argo CD's distinct optional value semantics.

type PluginRegistry

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

PluginRegistry dispatches plugin render requests by explicit plugin name. It never discovers plugins or executes plugin commands itself.

func NewPluginRegistry

func NewPluginRegistry(renderers map[string]PluginRenderer) *PluginRegistry

NewPluginRegistry creates a named in-process plugin renderer registry.

Plugin names are trimmed. A source with an empty plugin name only matches an explicitly registered empty-name renderer.

func (*PluginRegistry) RenderPlugin

func (registry *PluginRegistry) RenderPlugin(ctx context.Context, request PluginRequest) (PluginResult, error)

RenderPlugin renders a plugin source with the registered renderer for the requested plugin name.

type PluginRenderer

type PluginRenderer interface {
	RenderPlugin(ctx context.Context, request PluginRequest) (PluginResult, error)
}

PluginRenderer renders Argo CD config management plugin sources for embedded callers. The default CLI and public API paths do not execute plugin commands.

type PluginRequest

type PluginRequest struct {
	Application          Application
	DestinationNamespace string
	Source               PluginSource
	Plugin               PluginConfig
	RefRoots             map[string]string
	RefSources           map[string]PluginSource
	KubeVersion          string
	APIVersions          []string
}

PluginRequest is passed to an injected PluginRenderer.

type PluginResult

type PluginResult struct {
	Manifests   []PluginManifest
	Diagnostics []Diagnostic
}

PluginResult is returned by an injected PluginRenderer.

type PluginSource

type PluginSource struct {
	RepoRoot       string
	Path           string
	RepoURL        string
	TargetRevision string
}

PluginSource describes the resolved source for a plugin render.

type ProjectDiagnosticsMode added in v0.1.18

type ProjectDiagnosticsMode string

ProjectDiagnosticsMode controls which AppProject-adjacent diagnostics are returned and allowed to affect strict render/test/diff outcomes.

const (
	ProjectDiagnosticsModeActionable ProjectDiagnosticsMode = "actionable"
	ProjectDiagnosticsModeAll        ProjectDiagnosticsMode = "all"
	ProjectDiagnosticsModeOff        ProjectDiagnosticsMode = "off"
)

type Provenance

type Provenance struct {
	Path    string
	Pointer string
}

Provenance identifies where a Diagnostic originated.

type RemoteResourceAcquirer

type RemoteResourceAcquirer interface {
	Acquire(ctx context.Context, request RemoteResourceRequest, opts RemoteResourceOptions) (RemoteResourceResult, error)
}

RemoteResourceAcquirer acquires remote Kustomize resources for Application rendering.

type RemoteResourceCredentials

type RemoteResourceCredentials struct {
	Username    string
	Password    string
	BearerToken string
}

RemoteResourceCredentials supplies credentials for remote Kustomize HTTP resources.

type RemoteResourceKind

type RemoteResourceKind string

RemoteResourceKind classifies a remote Kustomize resource acquisition.

const (
	RemoteResourceHTTPFile RemoteResourceKind = "http-file"
	RemoteResourceGitRepo  RemoteResourceKind = "git-repo"
)

type RemoteResourceOptions

type RemoteResourceOptions struct {
	CacheDir       string
	Offline        bool
	Refresh        bool
	ForbiddenRoots []string
	Credentials    RemoteResourceCredentials
	GitCredentials GitCredentials
}

RemoteResourceOptions controls remote Kustomize resource acquisition.

type RemoteResourceRequest

type RemoteResourceRequest struct {
	URL      string
	Kind     RemoteResourceKind
	RepoURL  string
	Revision string
}

RemoteResourceRequest identifies a remote Kustomize resource to acquire. URL is the original Kustomize ref; RepoURL and Revision are structured metadata for Git refs.

type RemoteResourceResult

type RemoteResourceResult struct {
	Path      string
	URL       string
	Revision  string
	FromCache bool
}

RemoteResourceResult describes an acquired remote Kustomize resource.

type RenderResult

type RenderResult struct {
	Applications     []Application
	Manifests        []Manifest
	Diagnostics      []Diagnostic
	Statuses         []ApplicationStatus
	CacheEvents      []CacheEvent
	PluginExecutions []PluginExecution
}

RenderResult is returned by render operations.

func Render

func Render(ctx context.Context, config Config) (RenderResult, error)

Render creates manifests for Applications found under config.Path.

When an Application fails to render, the returned RenderResult may still contain partial manifests, diagnostics, and per-Application statuses.

type RepoMap

type RepoMap struct {
	URL  string
	Path string
}

RepoMap maps a source repository URL to a local checkout path.

type RepositoryKind

type RepositoryKind string

RepositoryKind identifies a Helm repository transport.

const (
	// RepositoryHTTP identifies an HTTP(S) Helm chart repository.
	RepositoryHTTP RepositoryKind = "http"
	// RepositoryOCI identifies an OCI Helm chart repository.
	RepositoryOCI RepositoryKind = "oci"
)

type Resource

type Resource struct {
	Group     string
	Kind      string
	Namespace string
	Name      string
}

Resource identifies a Kubernetes resource.

Jump to

Keyboard shortcuts

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