manifest

package
v0.2.0 Latest Latest
Warning

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

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

Documentation

Overview

Package manifest parses, validates, and manipulates Deployah manifest files.

It loads YAML manifests, resolves environments and env files, applies schema defaults, substitutes variables, and validates against embedded JSON schemas.

Loading and saving

  • Load: read a manifest, resolve an environment, substitute variables
  • Save: write a manifest to YAML

Validation

Defaults

Index

Constants

View Source 
const (
	// DefaultManifestPath is the default path for the Deployah manifest file
	DefaultManifestPath = "deployah.yaml"

	// DefaultEnvFile is the default environment file name
	DefaultEnvFile = ".env"

	// DefaultConfigFile is the default configuration file name
	DefaultConfigFile = "config.yaml"

	// DeployahConfigDir is the default directory for Deployah-specific files
	DeployahConfigDir = ".deployah"

	// EnvFilePrefix is the prefix for environment-specific files
	EnvFilePrefix = ".env."

	// ConfigFilePrefix is the prefix for environment-specific config files
	ConfigFilePrefix = "config."

	// ConfigFileSuffix is the suffix for configuration files
	ConfigFileSuffix = ".yaml"
)

File and Path Constants

View Source 
const (
	// EnvVarPrefix is the prefix for Deployah-specific environment variables
	EnvVarPrefix = "DPY_VAR_"

	// LogLevelEnvVar is the environment variable for log level override
	LogLevelEnvVar = "DPY_LOG_LEVEL"
)

Environment Variables

View Source 
const (
	// MaxComponentNameLength is the maximum allowed length for component names
	MaxComponentNameLength = 63

	// MaxProjectNameLength is the maximum allowed length for project names
	MaxProjectNameLength = 63

	// MaxEnvironmentNameLength is the maximum allowed length for environment names
	MaxEnvironmentNameLength = 63

	// ComponentNamePattern is the regex pattern for valid component names
	ComponentNamePattern = "^[a-zA-Z0-9_-]+$"

	// ProjectNamePattern is the regex pattern for valid project names
	ProjectNamePattern = "^[a-zA-Z0-9_-]+$"

	// EnvironmentNamePattern is the regex pattern for valid environment names
	EnvironmentNamePattern = "^[a-zA-Z0-9_-]+$"
)

Validation Constants

View Source 
const (
	// PlaceholderName is the placeholder used in templates for name substitution
	PlaceholderName = "{name}"

	// ComponentsPrefix is the prefix for component paths in schemas
	ComponentsPrefix = "components."

	// EnvironmentsPrefix is the prefix for environment paths in schemas
	EnvironmentsPrefix = "environments."

	// ArrayItemIndexTemplate is the template for array item indices in schema paths
	ArrayItemIndexTemplate = "[0]"

	// EnvFileSuffix is the suffix to remove from environment names during cleanup
	EnvFileSuffix = "/*"
)

Manifest Processing

View Source 
const (
	// DefaultResourcePreset is the default resource preset when none is specified
	DefaultResourcePreset = "small"

	// MinCPUMillicores is the minimum CPU allocation in millicores
	MinCPUMillicores = 10

	// MaxCPUMillicores is the maximum CPU allocation in millicores
	MaxCPUMillicores = 16000

	// MinMemoryMB is the minimum memory allocation in megabytes
	MinMemoryMB = 16

	// MaxMemoryMB is the maximum memory allocation in megabytes
	MaxMemoryMB = 32768
)

Resource Management

View Source 
const (
	// LabelPrefix is the prefix for all Deployah-managed labels
	LabelPrefix = "deployah.dev"

	// LabelProject is the label key for project identification
	LabelProject = LabelPrefix + "/project"

	// LabelEnvironment is the label key for environment identification
	LabelEnvironment = LabelPrefix + "/environment"

	// LabelManagedBy is the label key indicating management by Deployah
	LabelManagedBy = LabelPrefix + "/managed-by"

	// LabelVersion is the label key for API version tracking
	LabelVersion = LabelPrefix + "/version"

	// LabelComponent is the label key for component identification
	LabelComponent = LabelPrefix + "/component"

	// ManagedByValue is the value used for the managed-by label
	ManagedByValue = "deployah"
)

Kubernetes Labels

Variables

View Source 
var ResourcePresetMappings = map[ResourcePreset]map[string]Resources{
	ResourcePresetNano: {
		"requests": {
			CPU:              new("100m"),
			Memory:           new("128Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("150m"),
			Memory:           new("192Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
	ResourcePresetMicro: {
		"requests": {
			CPU:              new("250m"),
			Memory:           new("256Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("375m"),
			Memory:           new("384Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
	ResourcePresetSmall: {
		"requests": {
			CPU:              new("500m"),
			Memory:           new("512Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("750m"),
			Memory:           new("768Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
	ResourcePresetMedium: {
		"requests": {
			CPU:              new("500m"),
			Memory:           new("1024Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("750m"),
			Memory:           new("1536Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
	ResourcePresetLarge: {
		"requests": {
			CPU:              new("1000m"),
			Memory:           new("2048Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("1500m"),
			Memory:           new("3072Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
	ResourcePresetXLarge: {
		"requests": {
			CPU:              new("1000m"),
			Memory:           new("3072Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("3000m"),
			Memory:           new("6144Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
	ResourcePreset2XLarge: {
		"requests": {
			CPU:              new("1000m"),
			Memory:           new("3072Mi"),
			EphemeralStorage: new("50Mi"),
		},
		"limits": {
			CPU:              new("6000m"),
			Memory:           new("12288Mi"),
			EphemeralStorage: new("2Gi"),
		},
	},
}

ResourcePresetMappings defines the resource specifications for each preset

Functions

func ClearSchemaCache 

func ClearSchemaCache()

ClearSchemaCache clears all cached schemas and patterns. This function is primarily useful for testing to ensure clean state between test runs and for memory management in long-running applications.

Example usage in tests: 

func TestSchemaDefaults(t *testing.T) {
	defer ClearSchemaCache() // Clean up after test
	// ... test code that modifies schemas
}

func FillManifestWithDefaults 

func FillManifestWithDefaults(manifest *Manifest, version string) error

FillManifestWithDefaults fills a Manifest with defaults from JSON schemas. It applies manifest and environment schema defaults, resolves resource presets, and supports environment-specific placeholder substitution.

The function processes defaults in this order:

  1. Apply manifest schema defaults to components
  2. Resolve resource presets to concrete values
  3. Merge manifest and environment defaults
  4. Apply merged defaults to environments with placeholder substitution

Parameters:

  • manifest: Manifest to fill with defaults (modified in-place)
  • version: Schema version to use for default extraction

Returns:

  • error: If schema loading, default extraction, or application fails

Example: 

manifest := &Manifest{
	APIVersion: "v1-alpha.1",
	Project:    "my-app",
	Components: map[string]Component{
		"web": {Image: "nginx:latest"}, // Only image specified
	},
	Environments: []Environment{
		{Name: "production"}, // Only name specified
	},
}
err := FillManifestWithDefaults(manifest, "v1-alpha.1")
// After filling:
// manifest.Components["web"].Role = "service"
// manifest.Components["web"].Port = 8080
// manifest.Environments[0].EnvFile = ".env.production"

func Save 

func Save(manifest *Manifest, path string) error

Save writes the manifest to a YAML file at the specified path.

func SubstituteVariables 

func SubstituteVariables(data []byte, env *Environment) ([]byte, error)

SubstituteVariables substitutes variables in manifest data using the provided environment variables. The variables are substituted in the following order: 1. Variables from the environment definition (lowest priority) 2. Variables from the env file (medium priority) 3. Variables from the OS environment variables (highest priority) The variables are substituted using the envsubst package.

func ValidateAPIVersion 

func ValidateAPIVersion(manifestObj map[string]any) (string, error)

ValidateAPIVersion checks the manifest apiVersion field for presence, type, and validity. Returns the apiVersion string if valid, or an error otherwise.

func ValidateComponentAutoscaling 

func ValidateComponentAutoscaling(component Component) error

ValidateComponentAutoscaling validates a component's autoscaling configuration.

func ValidateComponentName 

func ValidateComponentName(name string) error

ValidateComponentName validates a component name against the JSON schema pattern

func ValidateComponentResources 

func ValidateComponentResources(component Component) error

ValidateComponentResources validates a component's resource configuration. A component can have either: 1. Explicit resources (resources field with actual values) 2. Resource preset (resourcePreset field) 3. Neither (will use defaults) It cannot have both resources and resourcePreset, or an empty resources object.

func ValidateEnvName 

func ValidateEnvName(name string) error

ValidateEnvName validates an environment name against the JSON schema pattern

func ValidateEnvVarName 

func ValidateEnvVarName(name string) error

ValidateEnvVarName validates an environment variable name against the JSON schema pattern.

func ValidateEnvironments 

func ValidateEnvironments(manifestObj map[string]any, version string) error

ValidateEnvironments validates environments YAML against the provided JSON schema file. version should be the version of the schema (e.g., "v1-alpha.1"). This is a strict validation: unknown fields are not allowed.

func ValidateHostname 

func ValidateHostname(hostname string) error

ValidateHostname validates a hostname against the JSON schema pattern

func ValidateManifest 

func ValidateManifest(manifestObj map[string]any, version string) error

ValidateManifest validates manifest YAML against the provided JSON schema. version should be the version of the schema (e.g., "v1-alpha.1"). This is a strict validation: unknown fields are not allowed.

func ValidateManifestComponents 

func ValidateManifestComponents(manifest *Manifest) error

ValidateManifestComponents validates all components in a manifest.

func ValidatePort 

func ValidatePort(portStr string) error

ValidatePort validates that the port is a number between 1024 and 65535.

func ValidateProjectName 

func ValidateProjectName(name string) error

ValidateProjectName validates a project name against the JSON schema pattern

Types

type Autoscaling 

type Autoscaling struct {
	Enabled     bool     `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	MinReplicas int      `json:"minReplicas,omitempty" yaml:"minReplicas,omitempty"`
	MaxReplicas int      `json:"maxReplicas,omitempty" yaml:"maxReplicas,omitempty"`
	Metrics     []Metric `json:"metrics,omitempty" yaml:"metrics,omitempty"`
}

Autoscaling defines the autoscaling settings for the component.

type Component 

type Component struct {
	Role           ComponentRole     `json:"role,omitempty" yaml:"role,omitempty"`
	EnvFile        string            `json:"envFile,omitempty" yaml:"envFile,omitempty"`
	ConfigFile     string            `json:"configFile,omitempty" yaml:"configFile,omitempty"`
	Environments   []string          `json:"environments,omitempty" yaml:"environments,omitempty"`
	Kind           ComponentKind     `json:"kind,omitempty" yaml:"kind,omitempty"`
	Image          string            `json:"image" yaml:"image"`
	Command        []string          `json:"command,omitempty" yaml:"command,omitempty"`
	Args           []string          `json:"args,omitempty" yaml:"args,omitempty"`
	Port           int               `json:"port,omitempty" yaml:"port,omitempty"`
	Autoscaling    *Autoscaling      `json:"autoscaling,omitempty" yaml:"autoscaling,omitempty"`
	Resources      Resources         `json:"resources" yaml:"resources,omitempty"`
	ResourcePreset ResourcePreset    `json:"resourcePreset,omitempty" yaml:"resourcePreset,omitempty"`
	Ingress        *Ingress          `json:"ingress,omitempty" yaml:"ingress,omitempty"`
	Env            map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
}

Component defines a deployable unit in the project.

type ComponentKind 

type ComponentKind string

ComponentKind specifies the kind of the component. 

const (
	// ComponentKindStateless runs replicas that do not require stable storage.
	ComponentKindStateless ComponentKind = "stateless"
	// ComponentKindStateful runs replicas that require stable storage.
	ComponentKindStateful ComponentKind = "stateful"
)

type ComponentRole 

type ComponentRole string

ComponentRole defines the role of a component and its default deployment strategy. 

const (
	// ComponentRoleService runs a long-lived HTTP or network service.
	ComponentRoleService ComponentRole = "service"
	// ComponentRoleWorker runs background or queue-processing workloads.
	ComponentRoleWorker ComponentRole = "worker"
	// ComponentRoleJob runs a finite batch or one-off task.
	ComponentRoleJob ComponentRole = "job"
)

type DefaultValues 

type DefaultValues map[string]any

DefaultValues represents default values extracted from a JSON schema. Map keys are dot-notation paths to fields; values are defaults to apply.

Examples of keys:

  • "components.[^[a-zA-Z0-9_-]+$].role" -> "service" (pattern-based component default)
  • "components.web.port" -> 8080 (specific component default)
  • "environments.[0].envFile" -> ".env.{name}" (environment template with placeholder)
  • "environments.production.configFile" -> "config.production.yaml" (specific environment)

func GetDefaultValues 

func GetDefaultValues(version string, schemaType schema.SchemaType) (DefaultValues, error)

GetDefaultValues extracts all default values from a JSON schema. This is the main entry point for schema-based defaults for a version and type.

Parameters:

  • version: Schema version identifier (e.g., "v1-alpha.1")
  • schemaType: Type of schema to process (manifest or environments)

Returns:

  • DefaultValues: Map of paths to default values extracted from the schema
  • error: If schema loading or processing fails

Example usage: 

defaults, err := GetDefaultValues("v1-alpha.1", schema.SchemaTypeManifest)
if err != nil {
	return err
}
// defaults now contains:
// "components.[^[a-zA-Z0-9_-]+$].role" -> "service"
// "components.[^[a-zA-Z0-9_-]+$].port" -> 8080
// etc.

type Environment 

type Environment struct {
	Name       string            `json:"name" yaml:"name"`
	EnvFile    string            `json:"envFile,omitempty" yaml:"envFile,omitempty"`
	ConfigFile string            `json:"configFile,omitempty" yaml:"configFile,omitempty"`
	Context    string            `json:"context,omitempty" yaml:"context,omitempty"`
	Variables  map[string]string `json:"variables,omitempty" yaml:"variables,omitempty"`
}

Environment defines the environment definition in the project.

func ResolveEnvironment 

func ResolveEnvironment(environments []Environment, desiredEnvironment string) (*Environment, error)

ResolveEnvironment returns the environment by name, or the default if name is empty. Returns an error if not found or if multiple environments are defined but none specified.

type Ingress 

type Ingress struct {
	Host string `json:"host" yaml:"host"`
	TLS  bool   `json:"tls" yaml:"tls"`
}

Ingress specifies ingress settings for exposing the component via HTTP/HTTPS.

type Manifest 

type Manifest struct {
	// APIVersion is the schema version of the manifest (e.g., "v1-alpha.1").
	APIVersion string `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"`
	// Project is the project name.
	Project string `json:"project" yaml:"project"`
	// Environments is a list of environment definitions.
	Environments []Environment `json:"environments,omitempty" yaml:"environments,omitempty"`
	// Components is a map of component names to their configuration.
	Components map[string]Component `json:"components" yaml:"components"`
}

Manifest defines the structure of the project manifest.

func CreateManifestWithDefaults 

func CreateManifestWithDefaults(projectName, version string) (*Manifest, error)

CreateManifestWithDefaults creates a new Manifest with default values applied. This is a convenience function that creates a minimal manifest structure and then applies all relevant defaults from the specified schema version.

Parameters:

  • projectName: Name of the project
  • version: Schema version to use for defaults

Returns:

  • *Manifest: New manifest with defaults applied
  • error: If creation or default application fails

Example: 

manifest, err := CreateManifestWithDefaults("my-app", "v1-alpha.1")
// Returns:
// &Manifest{
//     APIVersion: "v1-alpha.1",
//     Project:    "my-app",
//     Components: map[string]Component{}, // Empty but initialized
// }

func Load 

func Load(ctx context.Context, path, envName string) (*Manifest, error)

Load reads and parses the manifest YAML file at the given path, resolves the environment (using the provided envName or default resolution rules), and substitutes variables according to precedence (environment definition, env file, then OS environment). Returns the parsed Manifest or an error.

func (*Manifest) EnvironmentNames 

func (m *Manifest) EnvironmentNames() []string

EnvironmentNames returns the list of environment names defined in the manifest. Returns an empty slice if no environments are defined.

type Metric 

type Metric struct {
	Type   MetricType `json:"type" yaml:"type"`
	Target int        `json:"target" yaml:"target"`
}

Metric defines a metric used to trigger autoscaling.

type MetricType 

type MetricType string

MetricType specifies the type of metric to monitor. 

const (
	// MetricTypeCPU scales on CPU utilization.
	MetricTypeCPU MetricType = "cpu"
	// MetricTypeMemory scales on memory utilization.
	MetricTypeMemory MetricType = "memory"
)

type ResourcePreset 

type ResourcePreset string

ResourcePreset specifies the resource preset for the component. 

const (
	// ResourcePresetNano is the smallest resource preset.
	ResourcePresetNano ResourcePreset = "nano"
	// ResourcePresetMicro is a very small resource preset.
	ResourcePresetMicro ResourcePreset = "micro"
	// ResourcePresetSmall is a small resource preset.
	ResourcePresetSmall ResourcePreset = "small"
	// ResourcePresetMedium is a medium resource preset.
	ResourcePresetMedium ResourcePreset = "medium"
	// ResourcePresetLarge is a large resource preset.
	ResourcePresetLarge ResourcePreset = "large"
	// ResourcePresetXLarge is an extra-large resource preset.
	ResourcePresetXLarge ResourcePreset = "xlarge"
	// ResourcePreset2XLarge is a double extra-large resource preset.
	ResourcePreset2XLarge ResourcePreset = "2xlarge"
)

type Resources 

type Resources struct {
	CPU              *string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory           *string `json:"memory,omitempty" yaml:"memory,omitempty"`
	EphemeralStorage *string `json:"ephemeralStorage,omitempty" yaml:"ephemeralStorage,omitempty"`
}

Resources defines the resource requests and limits for the component.

Source Files

View all Source files

Directories

Path Synopsis
Package schema offers utilities for accessing and managing versioned schema files.
 Package schema offers utilities for accessing and managing versioned schema files.

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.