config

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source
const (
	StepSSMSync    = "ssm-sync"
	StepBuild      = "build"
	StepCDK        = "cdk"
	StepDeploy     = "deploy"
	StepConfigSync = "config-sync"
	StepWait       = "wait"
	StepRollback   = "rollback"
)

Built-in step names (used as `uses: citadel/<name>`) and the reserved name the executor uses for an automatic rollback step.

View Source
const CacheEndpointEnvVar = "VALKEY_ENDPOINT"

CacheEndpointEnvVar is the plain environment variable the cache: block injects into the container, holding the cache's "host:port" endpoint.

View Source
const CacheEngineValkey = "valkey"

CacheEngineValkey is the only cache engine citadel provisions.

View Source
const DefaultFileName = "citadel.yml"

DefaultFileName is the config file citadel reads by default and the file `citadel init` writes.

Variables

View Source
var PipelineVars = []string{"env", "name", "image", "sha", "region", "account"}

PipelineVars are the ${…} variables pipeline steps may use.

Functions

func ExpandEnv added in v0.5.0

func ExpandEnv(s, env string) string

ExpandEnv substitutes the environment name for every {env} in s.

func ExpandVars added in v0.4.0

func ExpandVars(s string, vals map[string]string) (string, error)

ExpandVars replaces citadel ${var} references using vals. A lowercase ${word} that is not a known variable is an error; ${UPPER} and $VAR are left untouched for the shell.

func ResolveDefaultPath added in v0.3.0

func ResolveDefaultPath(dir string) string

ResolveDefaultPath returns the config path to use in dir when --config was not passed: citadel.yml if it exists, else citadel.yaml if it exists, else citadel.yml (so "not found" errors and `citadel init` name the canonical file).

Types

type CacheConfig added in v0.5.0

type CacheConfig struct {
	Engine     string `yaml:"engine"`
	Serverless bool   `yaml:"serverless"`
}

CacheConfig asks citadel to create an ElastiCache Serverless cache in the service's VPC (optional). Only the task's security group may reach it, and its endpoint is injected as VALKEY_ENDPOINT. Serverless caches always require TLS.

type CloudFrontConfig

type CloudFrontConfig struct {
	Enabled bool   `yaml:"enabled"`
	Comment string `yaml:"comment,omitempty"`
}

CloudFrontConfig defines CloudFront distribution settings (optional)

type ContainerConfig

type ContainerConfig struct {
	Port                   int    `yaml:"port"`
	CPU                    int    `yaml:"cpu"`
	Memory                 int    `yaml:"memory"`
	HealthCheckPath        string `yaml:"health_check_path"`
	HealthCheckGracePeriod int    `yaml:"health_check_grace_period"`
}

ContainerConfig defines container runtime settings

type DeployConfig

type DeployConfig struct {
	Name         string               `yaml:"name"`
	Region       string               `yaml:"region"`
	Runtime      Runtime              `yaml:"runtime,omitempty"`
	Lambda       *LambdaConfig        `yaml:"lambda,omitempty"`
	Container    ContainerConfig      `yaml:"container"`
	Environments map[string]EnvConfig `yaml:"environments"`
	Secrets      []string             `yaml:"secrets"`
	Env          map[string]string    `yaml:"env,omitempty"`
	Queues       *QueuesConfig        `yaml:"queues,omitempty"`
	ECS          *ECSConfig           `yaml:"ecs,omitempty"`
	VPC          *VPCConfig           `yaml:"vpc,omitempty"`
	CloudFront   *CloudFrontConfig    `yaml:"cloudfront,omitempty"`
	IAM          *IAMConfig           `yaml:"iam,omitempty"`
	Cache        *CacheConfig         `yaml:"cache,omitempty"`
	Pipeline     PipelineSteps        `yaml:"pipeline,omitempty"`
}

DeployConfig represents the citadel.yml schema

func Load

func Load(path string) (*DeployConfig, error)

Load reads and parses a citadel.yml file

func Parse added in v0.3.0

func Parse(data []byte) (*DeployConfig, error)

Parse decodes and validates citadel.yml content. Load and `citadel init` (which checks rendered templates before writing them) share it.

func (*DeployConfig) CacheName added in v0.5.0

func (c *DeployConfig) CacheName(env string) string

CacheName is the ElastiCache Serverless cache name for env: "<name>-<env>", like every other per-environment resource.

func (*DeployConfig) GetEnv

func (c *DeployConfig) GetEnv(name string) (*EnvConfig, error)

GetEnv returns the config for a specific environment

func (*DeployConfig) ResolveFunctionName

func (c *DeployConfig) ResolveFunctionName(env string) string

ResolveFunctionName returns the Lambda function name for env. When lambda.functionName is set it is used verbatim with "{env}" substituted; otherwise the "<name>-<env>" convention is used (e.g. smaug-dev), matching the ECS resource naming convention (see ResolvedName). env must be non-empty.

func (*DeployConfig) ResolvedName

func (c *DeployConfig) ResolvedName(env string) string

ResolvedName returns the env-namespaced base name for a deployment ("<name>-<env>", e.g. legolas-dev). All per-environment ECS resources (ECR repo, cluster, service, log group, SSM prefix) are derived from this so that dev and prod stay isolated even when they share one AWS account. env must be non-empty.

func (*DeployConfig) ResolvedPipeline added in v0.4.0

func (c *DeployConfig) ResolvedPipeline() []PipelineStep

ResolvedPipeline returns the declared pipeline, or the default one.

func (*DeployConfig) ResolvedRuntime

func (c *DeployConfig) ResolvedRuntime() Runtime

ResolvedRuntime returns the runtime with the implicit default (ecs) applied.

func (*DeployConfig) SSMReadResources added in v0.5.0

func (c *DeployConfig) SSMReadResources(env string) []string

SSMReadResources returns the SSM parameter ARNs the task role may read in env: one "<prefix>/*" ARN per iam.ssm_read entry, with {env} expanded. Nil when the block is absent.

func (*DeployConfig) Validate

func (c *DeployConfig) Validate() error

Validate checks if the config is valid for the citadel deploy pipeline. Lambda-runtime configs skip ECS-only field requirements; functionName is optional (ResolveFunctionName applies the "<name>-<env>" convention when unset).

type ECSConfig

type ECSConfig struct {
	Cluster string `yaml:"cluster,omitempty"`
	Service string `yaml:"service,omitempty"`
}

ECSConfig overrides how Citadel locates an existing ECS service. When unset, Citadel falls back to the "<name>-cluster" / "<name>-service" convention. Useful for projects whose ECS resources were not created by Citadel.

type EnvConfig

type EnvConfig struct {
	Account     string `yaml:"account"`
	MinCapacity int    `yaml:"min_capacity"`
	MaxCapacity int    `yaml:"max_capacity"`
	FargateSpot bool   `yaml:"fargate_spot,omitempty"`
}

EnvConfig defines per-environment settings

type IAMConfig added in v0.5.0

type IAMConfig struct {
	// SSMRead lists SSM parameter path prefixes the application reads at
	// runtime, e.g. "/smaug/{env}/psp". Each grants ssm:GetParameter and
	// ssm:GetParameters on every parameter under the prefix.
	SSMRead []string `yaml:"ssm_read,omitempty"`
}

IAMConfig declares extra runtime permissions for the ECS task role (optional). Boot-time secrets never need it: the execution role already reads /<name>-<env>/*.

type LambdaConfig

type LambdaConfig struct {
	FunctionName string `yaml:"functionName"`
}

LambdaConfig declares Lambda-specific metadata. functionName is optional; when absent ResolveFunctionName applies the "<name>-<env>" convention.

type PipelineStep added in v0.4.0

type PipelineStep struct {
	Name string      `yaml:"name,omitempty"`
	Uses string      `yaml:"uses,omitempty"`
	Run  string      `yaml:"run,omitempty"`
	Task TaskCommand `yaml:"task,omitempty"`
	HTTP string      `yaml:"http,omitempty"`

	Shell            []string          `yaml:"shell,omitempty"`
	WorkingDirectory string            `yaml:"working_directory,omitempty"`
	Env              map[string]string `yaml:"env,omitempty"`

	Container string `yaml:"container,omitempty"`

	ExpectStatus      *int   `yaml:"expect_status,omitempty"` // nil = default; 0 is invalid
	Retries           *int   `yaml:"retries,omitempty"`       // nil = default; 0 is invalid
	Interval          string `yaml:"interval,omitempty"`
	RequestTimeout    string `yaml:"request_timeout,omitempty"`
	RollbackOnFailure bool   `yaml:"rollback_on_failure,omitempty"`

	Envs            []string `yaml:"envs,omitempty"`
	ContinueOnError bool     `yaml:"continue_on_error,omitempty"`
	Timeout         string   `yaml:"timeout,omitempty"`
}

PipelineStep is one entry of citadel.yml's pipeline: list. Exactly one of Uses, Run, Task, HTTP is set (enforced by Validate).

func DefaultPipeline added in v0.4.0

func DefaultPipeline(rt Runtime) []PipelineStep

DefaultPipeline is today's fixed sequence, used when citadel.yml has no pipeline: block.

func (PipelineStep) Builtin added in v0.4.0

func (s PipelineStep) Builtin() string

Builtin returns "build" for `uses: citadel/build` ("" for custom steps).

func (PipelineStep) ExpectStatusOrDefault added in v0.4.0

func (s PipelineStep) ExpectStatusOrDefault() int

ExpectStatusOrDefault is the http status that means healthy (default 200).

func (PipelineStep) IntervalOrDefault added in v0.4.0

func (s PipelineStep) IntervalOrDefault() time.Duration

IntervalOrDefault is the http retry interval (default 6s).

func (PipelineStep) Kind added in v0.4.0

func (s PipelineStep) Kind() StepKind

Kind returns the step's kind. Valid only for a validated step.

func (PipelineStep) RequestTimeoutOrDefault added in v0.4.0

func (s PipelineStep) RequestTimeoutOrDefault() time.Duration

RequestTimeoutOrDefault is the per-attempt http timeout (default 5s).

func (PipelineStep) RetriesOrDefault added in v0.4.0

func (s PipelineStep) RetriesOrDefault() int

RetriesOrDefault is the number of http attempts (default 10).

func (PipelineStep) ShellOrDefault added in v0.4.0

func (s PipelineStep) ShellOrDefault() []string

ShellOrDefault is the interpreter for run steps; the command is appended.

func (PipelineStep) StepName added in v0.4.0

func (s PipelineStep) StepName() string

StepName is the name used for logs and run.json: Name, or the built-in name.

func (PipelineStep) TimeoutOrDefault added in v0.4.0

func (s PipelineStep) TimeoutOrDefault() time.Duration

TimeoutOrDefault is the run/task timeout (default 30m).

func (*PipelineStep) UnmarshalYAML added in v0.4.0

func (s *PipelineStep) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML rejects unknown keys (a misspelled `environment:` or `rollback-on-failure:` would otherwise be silently ignored).

type PipelineSteps added in v0.4.0

type PipelineSteps []PipelineStep

PipelineSteps is citadel.yml's pipeline: list. Decoding errors name the step as pipeline[<i>] "<name>", like validation errors.

func (*PipelineSteps) UnmarshalYAML added in v0.4.0

func (p *PipelineSteps) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML decodes each step, labelling its errors with its position.

type QueuesConfig

type QueuesConfig struct {
	Consume []string `yaml:"consume,omitempty"`
	Produce []string `yaml:"produce,omitempty"`
}

QueuesConfig declares the SQS queues a service may access, split by intent. Consume queues receive read/delete permissions; produce queues receive send permissions. A queue ARN may appear in both lists. An ARN may contain {env}, so each environment is granted only its own queue.

func (*QueuesConfig) ConsumeARNs added in v0.5.0

func (q *QueuesConfig) ConsumeARNs(env string) []string

ConsumeARNs returns queues.consume for env with {env} expanded.

func (*QueuesConfig) ProduceARNs added in v0.5.0

func (q *QueuesConfig) ProduceARNs(env string) []string

ProduceARNs returns queues.produce for env with {env} expanded.

type Runtime

type Runtime string

Runtime identifies which AWS compute primitive a service runs on. The citadel deploy CLI only handles RuntimeECS; RuntimeLambda exists so the citadel-logs daemon can ingest logs from Lambda-backed services like smaug using the same citadel.yml registry mechanism.

const (
	RuntimeECS    Runtime = "ecs"
	RuntimeLambda Runtime = "lambda"
)

type StepKind added in v0.4.0

type StepKind string

StepKind is the kind of a pipeline step.

const (
	KindBuiltin StepKind = "builtin"
	KindRun     StepKind = "run"
	KindTask    StepKind = "task"
	KindHTTP    StepKind = "http"
)

type TaskCommand added in v0.4.0

type TaskCommand struct {
	Script string
	Args   []string
}

TaskCommand is a task: value — a string (run as `sh -c`) or a list (the container command as-is, for images without a shell).

func (TaskCommand) Command added in v0.4.0

func (t TaskCommand) Command() []string

Command returns the container command for the task.

func (TaskCommand) IsZero added in v0.4.0

func (t TaskCommand) IsZero() bool

IsZero reports whether no task command is set (used by yaml omitempty).

func (TaskCommand) String added in v0.4.0

func (t TaskCommand) String() string

String returns the command as written, for logs and dry runs.

func (*TaskCommand) UnmarshalYAML added in v0.4.0

func (t *TaskCommand) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML accepts a scalar or a sequence of strings.

type VPCConfig

type VPCConfig struct {
	MaxAZs      int  `yaml:"max_azs"`
	NATGateways *int `yaml:"nat_gateways,omitempty"`
}

VPCConfig defines custom VPC settings (optional)

Jump to

Keyboard shortcuts

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