Why Go
- Case Studies
  
  Common problems companies solve with Go
- Use Cases
  
  Stories about how and why companies use Go
- Security
  
  How Go can help keep you secure by default
Learn
Docs
- Effective Go
  
  Tips for writing clear, performant, and idiomatic Go code
- Go User Manual
  
  A complete introduction to building software with Go
- Standard library
  
  Reference documentation for Go's standard library
- Release Notes
  
  Learn what's new in each Go release
- API
  
  Reference documentation for the pkg.go.dev API
Packages
Community
- Recorded Talks
  
  Videos from prior events
- Meetups
  
  Meet other local Go developers
- Conferences
  
  Learn and network with Go developers from around the world
- Go blog
  
  The Go project's official blog.
- Go project
  
  Get help and stay informed from Go
- Get connected

retainedprovider

package

Go to main page

Versions in this module

v1

v1.0.34

Oct 3, 2026

v1.0.33

Oct 3, 2026

v1.0.32

Jul 15, 2026

Changes in this version

+ const ActiveStateProtocolVersion

+ const ConfigProtocolVersion

+ const GitHubPluginID

+ const LifecycleJournalProtocolVersion

+ const MaxProviderProbeLabels

+ const MaxStateFileBytes

+ const StatusProtocolVersion

+ const TransactionJournalProtocolVersion

+ var ErrInstallLocked = errors.New("retained provider install is already locked")

+ func AtomicWriteJSON(path string, value any) (returnErr error)

+ func CloneRegularTree(source, destination string, limits CloneLimits) (returnErr error)

+ func IsCanonicalSafeAbsolutePath(value string) bool

+ func ReadStrictJSONFile(path string, target any) error

+ func ValidateUserPath(home, path string, requireExisting bool) error

+ func WriteInstallMaterial(paths LifecyclePaths, material InstallMaterial) error

+ func WriteStatus(writer io.Writer, status Status) error

+ type ActiveState struct

+ Current ImageSelection

+ Previous *ImageSelection

+ ProtocolVersion string

+ UpdatedAt time.Time

+ func RecoverActiveState(journal TransactionJournal) (ActiveState, error)

+ func (state ActiveState) Validate() error

+ func (state ActiveState) ValidateForConfig(config Config) error

+ type CloneLimits struct

+ MaxBytes int64

+ MaxFiles int

+ type Command struct

+ Args []string

+ Dir string

+ Env []string

+ Path string

+ Stdin []byte

+ type CommandRunner interface

+ Exec func(Command) error

+ Run func(context.Context, Command) ([]byte, error)

+ type Config struct

+ AgentUnit string

+ CandidateContainer string

+ ComponentID string

+ ComputeAgentPath string

+ ContainerNetwork string

+ InstallRoot string

+ Labels []string

+ LocalStatusPath string

+ LoginctlPath string

+ Organization string

+ PluginID string

+ PodmanPath string

+ ProfileID string

+ ProtocolVersion string

+ ProviderMarkerPath string

+ ProviderURL string

+ Ref string

+ RefreshIntervalSeconds int

+ Repository string

+ RunnerGroup string

+ RunnerName string

+ StableContainer string

+ SupervisorConfigPath string

+ SystemctlPath string

+ SystemdDir string

+ WorkerID string

+ Workflow string

+ func DecodeConfig(reader io.Reader, home string) (Config, error)

+ func ReadConfigFile(path, home string) (Config, error)

+ func (config Config) Validate(home string) error

+ type Credentials struct

+ GitHubToken string

+ ProviderToken string

+ type ImageSelection struct

+ ActivatedAt time.Time

+ ImageID string

+ ImageRef string

+ Update VerifiedUpdate

+ func (selection ImageSelection) Validate() error

+ type InstallLock struct

+ func AcquireInstallLock(path string) (*InstallLock, error)

+ func (lock *InstallLock) Release() error

+ type InstallMaterial struct

+ AgentEnv []byte

+ CACert []byte

+ CAKey []byte

+ ContainersConf []byte

+ ProbeEnv []byte

+ ProviderEnv []byte

+ ServerCert []byte

+ ServerKey []byte

+ func GenerateInstallMaterial(config Config, credentials Credentials, random io.Reader, now time.Time) (InstallMaterial, error)

+ type Installer struct

+ ExecutablePath func() (string, error)

+ Now func() time.Time

+ ProbeActive func(context.Context, Config) error

+ Random io.Reader

+ Refresh func(context.Context, Config) (Status, error)

+ Runner CommandRunner

+ Sleep func(context.Context, time.Duration) error

+ UserID func() (string, error)

+ func (installer Installer) Install(ctx context.Context, home string, config Config, credentials Credentials) (status Status, returnErr error)

+ func (installer Installer) Recover(ctx context.Context, home string, config Config, confirmation string) (status Status, returnErr error)

+ func (installer Installer) Status(ctx context.Context, home string, config Config) (Status, error)

+ func (installer Installer) Uninstall(ctx context.Context, home string, config Config, purge bool) (status Status, returnErr error)

+ type JournalPhase string

+ const JournalActivated

+ const JournalCommitted

+ const JournalPrepared

+ const JournalRollbackCleaned

+ const JournalRollbackRestored

+ const JournalRollbackRestoring

+ const JournalStaging

+ const JournalStateDetached

+ const JournalStatePromoted

+ const JournalStatePromoting

+ type LifecycleAuditEvent struct

+ Count uint64

+ Digest string

+ Disposition string

+ ErrorClass string

+ EventID string

+ FirstSeen time.Time

+ Kind LifecycleAuditKind

+ LastSeen time.Time

+ Offset *int64

+ Operation LifecycleOperation

+ Outcome LifecycleOutcome

+ Phase LifecyclePhase

+ ProviderEffect ProviderEffect

+ Purge *bool

+ Sequence uint64

+ Timestamp time.Time

+ TransactionID string

+ WorkerID string

+ func (event LifecycleAuditEvent) Validate() error

+ type LifecycleAuditKind string

+ const AuditError

+ const AuditOverflow

+ const AuditPhase

+ const AuditRecovery

+ type LifecycleAuditQueue struct

+ Diagnostics []LifecycleAuditEvent

+ NextSequence uint64

+ Safety []LifecycleAuditEvent

+ func (queue *LifecycleAuditQueue) EnqueueDiagnostic(event LifecycleAuditEvent) error

+ func (queue *LifecycleAuditQueue) EnqueueSafety(event LifecycleAuditEvent) error

+ func (queue LifecycleAuditQueue) Validate() error

+ type LifecycleFileAttestation struct

+ Path string

+ SHA256 string

+ func (attestation LifecycleFileAttestation) Validate() error

+ type LifecycleIdentity struct

+ ComponentID string

+ PluginID string

+ ProfileID string

+ WorkerID string

+ func (identity LifecycleIdentity) Validate() error

+ type LifecycleJournal struct

+ Activation systemdActivation

+ AgentUnitIntended *LifecycleSystemdSignature

+ Audit LifecycleAuditQueue

+ Identity LifecycleIdentity

+ Operation LifecycleOperation

+ Outcome LifecycleOutcome

+ Phase LifecyclePhase

+ PreviousUnits map[string]systemdUnitState

+ ProtocolVersion string

+ ProviderEffect ProviderEffect

+ ProviderTransaction *LifecycleProviderTransaction

+ Recovery LifecycleRecoveryAuthority

+ Snapshots []managedFileSnapshot

+ StartedAt time.Time

+ TransactionID string

+ Unchanged *LifecycleUnchangedProvenance

+ Uninstall *LifecycleUninstallPayload

+ UpdatedAt time.Time

+ WiringIntent []LifecycleManagedFileIntent

+ func (journal LifecycleJournal) Validate(home string, paths LifecyclePaths) error

+ type LifecycleManagedFileIntent struct

+ Contents []byte

+ Mode os.FileMode

+ Path string

+ Present bool

+ SHA256 string

+ type LifecycleOperation string

+ const LifecycleInstall

+ const LifecycleRefresh

+ const LifecycleRefreshRecovery

+ const LifecycleUninstall

+ type LifecycleOutcome string

+ const LifecycleCommit

+ const LifecycleRollback

+ type LifecyclePaths struct

+ ActiveState string

+ AgentDropIn string

+ AgentEnv string

+ CAFile string

+ CAKey string

+ CandidatesRoot string

+ ConfigFile string

+ ContainersConf string

+ InstallJournal string

+ InstallLock string

+ Journal string

+ Launcher string

+ LifecycleAudit string

+ LifecycleAuditLock string

+ LifecycleJournal string

+ LifecycleTransactions string

+ PackagesRoot string

+ PathUnit string

+ ProbeEnv string

+ ProviderEnv string

+ ProviderState string

+ ProviderUnit string

+ RefreshUnit string

+ Root string

+ ServerCert string

+ ServerKey string

+ TLSRoot string

+ TimerUnit string

+ func LifecyclePathsFor(config Config) LifecyclePaths

+ func (paths LifecyclePaths) CandidateState(digest string) string

+ func (paths LifecyclePaths) LifecycleTransactionRoot(transactionID string) string

+ func (paths LifecyclePaths) PackageBinary(digest string) string

+ func (paths LifecyclePaths) PackageDir(digest string) string

+ func (paths LifecyclePaths) PreviousState(digest string) string

+ type LifecyclePhase string

+ const LifecycleAdopting

+ const LifecycleCommitted

+ const LifecycleFenced

+ const LifecycleFencing

+ const LifecycleIntent

+ const LifecycleReady

+ const LifecycleReleasing

+ type LifecycleProviderTransaction struct

+ Digest string

+ LegacyJournalSHA256 string

+ ProfileID string

+ TransactionID string

+ func (binding LifecycleProviderTransaction) Validate(identity LifecycleIdentity) error

+ type LifecycleRecoveryAuthority struct

+ AgentUnitBefore LifecycleSystemdSignature

+ ComputeAgent LifecycleFileAttestation

+ Config Config

+ Loginctl LifecycleFileAttestation

+ Podman LifecycleFileAttestation

+ SupervisorConfig LifecycleFileAttestation

+ Systemctl LifecycleFileAttestation

+ func (authority LifecycleRecoveryAuthority) Reattest() error

+ func (authority LifecycleRecoveryAuthority) Validate(home string, identity LifecycleIdentity) error

+ type LifecycleSystemdSignature struct

+ DropIns []LifecycleFileAttestation

+ EnvironmentFiles []LifecycleFileAttestation

+ ExecStart string

+ Fragment LifecycleFileAttestation

+ func (signature LifecycleSystemdSignature) Reattest() error

+ func (signature LifecycleSystemdSignature) Validate(home string) error

+ type LifecycleUnchangedProvenance struct

+ Active ImageSelection

+ Candidate VerifiedUpdate

+ StableProbeAt time.Time

+ func (provenance LifecycleUnchangedProvenance) Validate(identity LifecycleIdentity, requireProbe bool) error

+ type LifecycleUninstallPayload struct

+ Purge bool

+ type OSCommandRunner struct

+ MaxOutputBytes int

+ func (runner OSCommandRunner) Exec(command Command) error

+ func (runner OSCommandRunner) Run(ctx context.Context, command Command) ([]byte, error)

+ type ProviderEffect string

+ const ProviderChanged

+ const ProviderNotApplicable

+ const ProviderUnchanged

+ type Refresher struct

+ ExecutablePath func() (string, error)

+ Now func() time.Time

+ Random io.Reader

+ Runner CommandRunner

+ Sleep func(context.Context, time.Duration) error

+ func (refresher Refresher) Refresh(ctx context.Context, config Config) (status Status, returnErr error)

+ func (refresher Refresher) RestartAndProbeActive(ctx context.Context, config Config) error

+ func (refresher Refresher) ServeActive(ctx context.Context, config Config) error

+ type Status struct

+ CurrentSHA256 string

+ CurrentVersion string

+ Installed bool

+ ObservedAt time.Time

+ ProtocolVersion string

+ ServiceActive bool

+ type SystemdUnits struct

+ AgentDropIn string

+ ProviderService string

+ RefreshPath string

+ RefreshService string

+ RefreshTimer string

+ func RenderSystemdUnits(config Config, paths LifecyclePaths) (SystemdUnits, error)

+ type TransactionJournal struct

+ Candidate ImageSelection

+ DeferredCommit bool

+ ID string

+ OuterTransactionID string

+ Phase JournalPhase

+ Previous *ActiveState

+ ProfileID string

+ ProtocolVersion string

+ RollbackFrom JournalPhase

+ RuntimeRepair bool

+ StartedAt time.Time

+ UpdatedAt time.Time

+ func (journal TransactionJournal) Validate() error

+ func (journal TransactionJournal) ValidateForConfig(config Config) error

+ type VerifiedUpdate struct

+ CampaignID string

+ Component string

+ ComponentID string

+ DirectiveID string

+ Format string

+ Path string

+ PluginID string

+ SHA256 string

+ Version string

+ WorkerID string

+ func VerifyCurrentUpdate(ctx context.Context, config Config, runner CommandRunner) (VerifiedUpdate, error)

+ func (update VerifiedUpdate) Validate() error