config

package
v1.27.1 Latest Latest
Warning

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

 Go to latest Published: Mar 19, 2026 License: MIT Imports: 21 Imported by: 0

README

Configuration Package

This package handles loading and parsing Caproni configuration files.

Configuration Versioning Policy

Caproni should never support more than 2 versions of the configuration schema at any time:

  • The current version (e.g., v2)
  • The previous version (e.g., v1) for automatic in-memory conversion

Versions more than 1 behind the current version should be removed.

Rationale

Supporting only 2 versions keeps the codebase maintainable:

  • Minimizes complexity in configuration loading logic
  • Reduces the testing matrix (fewer version combinations to validate)
  • Encourages users to stay current with configuration formats
  • Prevents accumulation of technical debt from old schema support
Upgrade Path

When introducing a new version (e.g., v3):

  1. Add the new version:

    • Create internal/config/v3/caproni.go with v3 structures
    • Add schema/config.v3.schema.json for validation
    • Implement ConvertV2ToV3() in internal/config/convert.go
    • Add compileSchemaV3() and update LoadCaproniConfig() in internal/config/caproni.go
    • Create caproni config migrate-v3 command

  2. Update documentation:

    • Update migration guide to mention v1 removal
    • Add deprecation notice for v1 in release notes

  3. Remove the oldest version (v1):

    • Delete internal/config/v1/ directory
    • Remove v1 schema compilation and loading logic
    • Remove v1-to-v2 conversion code
    • Remove caproni config migrate command (replace with v2-to-v3)
    • Update tests

  4. Communicate the change:

    • Document that v1 configs are no longer supported
    • Provide clear migration instructions from v1 → v2 → v3
    • Consider providing a "check version" command to help users identify what they need
Version Detection

Configuration version is detected from the version field in the YAML:

version: 2  # v2 config

If no version field exists, the config is assumed to be v1 (for backward compatibility with the initial version).

Current Versions
  • v1 (legacy): Original format where repositories contained type, helm, mirror, and skaffold fields
  • v2 (current): Separated concerns format with distinct repositories, deployers, and reloaders sections
Automatic Conversion

V1 configs are automatically converted to v2 in-memory when loaded by any Caproni command. This allows users to continue using v1 configs without immediate migration, but the caproni config migrate command is recommended for better performance and clarity.

Directory Structure

internal/config/
├── README.md              # This file
├── caproni.go            # Main config loading logic
├── convert.go            # Version conversion functions
├── migration.go          # Migration command logic
├── version.go            # Version detection
├── types/                # Shared types across versions
│   └── cluster.go
├── v1/                   # V1 configuration structures
│   └── caproni.go
└── v2/                   # V2 configuration structures (current)
    └── caproni.go

Adding a New Configuration Field

When adding a new field to the current version:

  1. Add the field to the appropriate struct in v2/caproni.go
  2. Update schema/config.v2.schema.json with the new field definition
  3. Add tests for the new field in caproni_test.go
  4. Update documentation in docs/

Note: New fields should be optional (with omitempty tag) to maintain backward compatibility within the same major version.

Documentation

Overview

Package config provides global configuration management via context propagation.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrConfigFileNotFound is returned when the configuration file is not found.
	ErrConfigFileNotFound = errors.New("configuration file not found")
	// ErrNoConfigFileFound is returned when no config file is found in the directory tree.
	ErrNoConfigFileFound = errors.New("no caproni.yaml found in current directory or any parent directory up to home directory")
	// ErrInvalidYAML is returned when the YAML syntax is invalid.
	ErrInvalidYAML = errors.New("invalid YAML syntax")

	// ErrSchemaValidation is returned when schema validation fails.
	ErrSchemaValidation = errors.New("configuration does not match schema")
	// ErrSemanticValidation is returned when semantic validation fails.
	ErrSemanticValidation = errors.New("configuration semantic validation failed")
	// ErrReferenceNotFound is returned when a referenced item is not found.
	ErrReferenceNotFound = errors.New("referenced item not found")
	// ErrPathNotFound is returned when a referenced file path does not exist.
	ErrPathNotFound = errors.New("referenced file path not found")
	// ErrDeprecatedVersion is returned when a deprecated configuration version is used.
	ErrDeprecatedVersion = errors.New("deprecated configuration version")

	// ErrInvalidClusterDriver is returned when the cluster driver is invalid.
	ErrInvalidClusterDriver = errors.New("invalid cluster driver")
	// ErrInvalidMemoryFormat is returned when the memory format is invalid.
	ErrInvalidMemoryFormat = errors.New("invalid memory format")
	// ErrInvalidNamespace is returned when the namespace format is invalid.
	ErrInvalidNamespace = errors.New("invalid namespace format")
	// ErrInvalidRepoType is returned when the repository type is invalid.
	ErrInvalidRepoType = errors.New("invalid repository type")
	// ErrInvalidKubeType is returned when the kubernetes type is invalid.
	ErrInvalidKubeType = errors.New("invalid kubernetes type")
)
View Source 
var (
	// ErrLegacyConfig is returned when a v1 config is detected and migration is required.
	ErrLegacyConfig = errors.New("legacy configuration format detected")

	// ErrUnsupportedVersion is returned when the config version is not supported.
	ErrUnsupportedVersion = errors.New("unsupported config version")
)
View Source 
var (
	// ErrAlreadyMigrated is returned when attempting to migrate a config that's already v2.
	ErrAlreadyMigrated = errors.New("config is already migrated, no migration needed")
)
View Source 
var ErrConfigNotFound = errors.New("GlobalConfig not found in context")

ErrConfigNotFound is returned when GlobalConfig is not found in context.

View Source 
var (
	// ErrUnknownRepositoryType is returned when a v1 repository has an unknown type.
	ErrUnknownRepositoryType = errors.New("unknown repository type")
)

Functions

func AnalyzeMigration 

func AnalyzeMigration(path string) (string, error)

AnalyzeMigration analyzes a v1 config and returns a human-readable summary of what would be migrated.

func ConvertV1ToV2 

func ConvertV1ToV2(v1Cfg *v1.CaproniConfig) (*v2.CaproniConfig, error)

ConvertV1ToV2 converts a v1 CaproniConfig to v2 format. This is used during migration and when loading v1 configs. Returns error if the conversion encounters issues (e.g., conflicting repository definitions).

func FindConfigFile 

func FindConfigFile() (string, error)

FindConfigFile searches for a caproni.yaml file starting from the current directory and walking up the directory tree until it reaches either the root directory or the user's home directory. Returns the absolute path to the first caproni.yaml found, or an error if none is found.

func LoadCaproniConfig 

func LoadCaproniConfig(gc *GlobalConfig) (*v2.CaproniConfig, error)

LoadCaproniConfig loads and parses the caproni.yaml configuration file. Returns a v2 CaproniConfig regardless of input version. V1 configs are automatically converted to v2 format. The config file path and version defaults (such as CopySleepImage) are read from gc.

func PreviewMigration 

func PreviewMigration(path string) (string, error)

PreviewMigration generates a preview of what the migrated config would look like.

func RequireV2OrMigrate 

func RequireV2OrMigrate(path string) error

RequireV2OrMigrate checks if a config file is v2, and if not, returns an error with migration instructions.

func ValidateSemantics 

func ValidateSemantics(cfg *v2.CaproniConfig) error

ValidateSemantics performs semantic validation on a v2 configuration. This checks referential integrity, file paths, and other semantic constraints beyond what the JSON schema enforces.

func WithContext 

func WithContext(ctx context.Context, cfg *GlobalConfig) context.Context

WithContext returns a new context with the GlobalConfig stored in it.

Types

type ConfigVersion 

type ConfigVersion int

ConfigVersion represents a configuration version. 

const (
	// VersionUnknown indicates the version could not be determined.
	VersionUnknown ConfigVersion = 0
	// Version1 indicates v1 configuration format (repositories with type field).
	Version1 ConfigVersion = 1
	// Version2 indicates v2 configuration format (separate deployers/reloaders).
	Version2 ConfigVersion = 2
)

func DetectVersionFromBytes 

func DetectVersionFromBytes(data []byte) (ConfigVersion, error)

DetectVersionFromBytes detects the configuration version from raw YAML bytes.

func DetectVersionFromFile 

func DetectVersionFromFile(path string) (ConfigVersion, error)

DetectVersionFromFile detects the configuration version from a file path.

func (ConfigVersion) String 

func (v ConfigVersion) String() string

String returns a string representation of the version.

type GlobalConfig 

type GlobalConfig struct {
	// ConfigFile is the path to the caproni.yaml configuration file
	ConfigFile string

	// ProfileName is the name of the cluster profile to use.
	// This allows multiple isolated cluster instances.
	ProfileName string
	// contains filtered or unexported fields
}

GlobalConfig holds all global configuration options that can be set via persistent flags on the root command.

func FromContext 

func FromContext(ctx context.Context) *GlobalConfig

FromContext retrieves the GlobalConfig from the context. Returns nil if no config is found.

func MustFromContext 

func MustFromContext(ctx context.Context) *GlobalConfig

MustFromContext retrieves the GlobalConfig from the context. Panics if no config is found. This should only be used in command RunE functions where we're guaranteed the config exists.

func NewGlobalConfig 

func NewGlobalConfig(embeddedVersions map[string]string) *GlobalConfig

NewGlobalConfig creates a new GlobalConfig with sensible defaults.

func (*GlobalConfig) GetToolVersion 

func (gc *GlobalConfig) GetToolVersion(key string) (string, bool)

GetToolVersion retrieves a tool version from the embedded CI version files. It lazy-loads and parses the YAML files on first call, then caches the results. Returns the version string and true if found, or empty string and false if not found. Panics if YAML parsing fails, as this indicates a build-time issue with embedded files.

type MigrationOptions 

type MigrationOptions struct {
	// DryRun performs the migration without writing files.
	DryRun bool
	// BackupSuffix is the suffix to append to the backup file (default: .bak).
	BackupSuffix string
	// SkipBackup skips creating a backup file (use with caution).
	SkipBackup bool
}

MigrationOptions contains options for the migration.

func DefaultMigrationOptions 

func DefaultMigrationOptions() *MigrationOptions

DefaultMigrationOptions returns default migration options.

type MigrationResult 

type MigrationResult struct {
	OriginalFile string
	BackupFile   string
	Version      ConfigVersion
	Repositories int
	Deployers    int
	Reloaders    int
}

MigrationResult contains the results of a migration operation.

func MigrateConfig 

func MigrateConfig(path string, opts *MigrationOptions) (*MigrationResult, error)

MigrateConfig migrates a v1 configuration file to v2 format. Returns the migration result and any error encountered.

type ValidationError 

type ValidationError struct {
	Errors []error
}

ValidationError aggregates multiple validation errors.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Error implements the error interface.

Source Files

View all Source files

Directories

Path Synopsis
Package types contains shared configuration types used across config versions.
 Package types contains shared configuration types used across config versions.
Package v1 provides configuration structures for Caproni v1 format.
 Package v1 provides configuration structures for Caproni v1 format.
Package v2 provides configuration structures for Caproni v2 format.
 Package v2 provides configuration structures for Caproni v2 format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.