Documentation
¶
Index ¶
- Constants
- Variables
- func ExpandEnv(s, env string) string
- func ExpandVars(s string, vals map[string]string) (string, error)
- func ResolveDefaultPath(dir string) string
- type CacheConfig
- type CloudFrontConfig
- type ContainerConfig
- type DeployConfig
- func (c *DeployConfig) CacheName(env string) string
- func (c *DeployConfig) GetEnv(name string) (*EnvConfig, error)
- func (c *DeployConfig) ResolveFunctionName(env string) string
- func (c *DeployConfig) ResolvedName(env string) string
- func (c *DeployConfig) ResolvedPipeline() []PipelineStep
- func (c *DeployConfig) ResolvedRuntime() Runtime
- func (c *DeployConfig) SSMReadResources(env string) []string
- func (c *DeployConfig) Validate() error
- type ECSConfig
- type EnvConfig
- type IAMConfig
- type Ingress
- type LambdaConfig
- type PipelineStep
- func (s PipelineStep) Builtin() string
- func (s PipelineStep) ExpectStatusOrDefault() int
- func (s PipelineStep) IntervalOrDefault() time.Duration
- func (s PipelineStep) Kind() StepKind
- func (s PipelineStep) RequestTimeoutOrDefault() time.Duration
- func (s PipelineStep) RetriesOrDefault() int
- func (s PipelineStep) ShellOrDefault() []string
- func (s PipelineStep) StepName() string
- func (s PipelineStep) TimeoutOrDefault() time.Duration
- func (s *PipelineStep) UnmarshalYAML(n *yaml.Node) error
- type PipelineSteps
- type QueuesConfig
- type Runtime
- type StepKind
- type TaskCommand
- type VPCConfig
Constants ¶
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.
const CacheEndpointEnvVar = "VALKEY_ENDPOINT"
CacheEndpointEnvVar is the plain environment variable the cache: block injects into the container, holding the cache's "host:port" endpoint.
const CacheEngineValkey = "valkey"
CacheEngineValkey is the only cache engine citadel provisions.
const DefaultFileName = "citadel.yml"
DefaultFileName is the config file citadel reads by default and the file `citadel init` writes.
const TunnelTokenSecret = "CLOUDFLARE_TUNNEL_TOKEN"
TunnelTokenSecret is the SSM parameter (under the service's /<name>-<env>/ prefix) holding the Cloudflare tunnel token. Only the cloudflared sidecar receives it, as TUNNEL_TOKEN.
Variables ¶
var PipelineVars = []string{"env", "name", "image", "sha", "region", "account"}
PipelineVars are the ${…} variables pipeline steps may use.
Functions ¶
func ExpandVars ¶ added in v0.4.0
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
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
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 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. In a vpc_id environment it ends with the VPC ID's first 8 hex digits ("<name>-<env>-01f19f79"): a cache moving VPCs is replaced, and CloudFormation creates the replacement before deleting the old one, so the two names must differ.
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"`
Ingress Ingress `yaml:"ingress,omitempty"`
// VPCID runs the environment in an existing VPC (looked up at synth)
// instead of creating one. The VPC needs CDK-tagged public subnets, and
// private-with-egress subnets for prod.
VPCID string `yaml:"vpc_id,omitempty"`
}
EnvConfig defines per-environment settings
func (*EnvConfig) ResolvedIngress ¶ added in v0.6.0
ResolvedIngress returns the ingress with the implicit default (alb) applied.
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 Ingress ¶ added in v0.6.0
type Ingress string
Ingress is how an environment's service is reached from the internet.
const ( // IngressALB fronts the service with an Application Load Balancer (and // CloudFront when cloudfront.enabled). The default. IngressALB Ingress = "alb" // IngressCloudflareTunnel runs a cloudflared sidecar that dials out to // Cloudflare, so the environment needs no load balancer, no CloudFront // and no inbound rule. The tunnel and its public hostname are created in // Cloudflare (origin: http://localhost:<container.port>); its token is // read from SSM at /<name>-<env>/CLOUDFLARE_TUNNEL_TOKEN. IngressCloudflareTunnel Ingress = "cloudflare_tunnel" )
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.
type TaskCommand ¶ added in v0.4.0
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.