Documentation
¶
Overview ¶
Package syncwindow implements sync windows: operator-defined, timezone-aware allow and deny windows that decide whether a deployment may change a stack at a given time.
A window is active from each occurrence of its cron schedule for its duration. Only windows whose selectors match a deployment target are considered:
- an active matching deny window blocks the deployment,
- matching allow windows that are all inactive block the deployment,
- otherwise the deployment is allowed.
Deny windows win over allow windows. Manual (API/MCP) deployments bypass a block only if every blocking window has manual_sync enabled, and reconciliation of an already deployed revision is never blocked.
Index ¶
Constants ¶
const MinDuration = time.Minute
MinDuration is the shortest allowed window duration.
Variables ¶
var ( // ErrInvalidConfig is returned for any invalid window definition. ErrInvalidConfig = errors.New("invalid sync window configuration") // ErrBothConfigSet is returned when both SYNC_WINDOWS and SYNC_WINDOWS_FILE are set. ErrBothConfigSet = errors.New("both SYNC_WINDOWS and SYNC_WINDOWS_FILE are set, please use one or the other") )
Functions ¶
This section is empty.
Types ¶
type Decision ¶
type Decision struct {
Allowed bool `json:"allowed"`
// ManualOverride is true when a manual deployment is allowed only
// because every blocking window has manual_sync enabled.
ManualOverride bool `json:"manual_override"`
// Windows lists the names of the windows that block (or, with
// ManualOverride, would block) the deployment.
Windows []string `json:"windows"`
// NextOpen is the earliest time the target may deploy again. It is zero
// when unknown or when the deployment is allowed.
NextOpen time.Time `json:"next_open,omitzero"`
}
Decision is the result of evaluating a target against the policy.
type Origin ¶
type Origin string
Origin identifies what started a deployment, which decides how windows apply to it.
const ( // OriginAutomatic covers webhooks, polls and the local repository watcher. OriginAutomatic Origin = "automatic" // OriginManual covers deployments requested through the REST API or MCP. OriginManual Origin = "manual" // OriginReconciliation covers restoring the already deployed revision // after drift, for example when a container died. It is never blocked; // a reconciliation that would deploy another revision must be evaluated // as OriginAutomatic instead. OriginReconciliation Origin = "reconciliation" )
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy is a validated, immutable set of windows. A nil Policy allows everything.
func Parse ¶
Parse parses and validates a YAML (or JSON) list of windows. Empty input returns an empty policy.
func (*Policy) Evaluate ¶
Evaluate decides whether a deployment of target started by origin may change the target at now.
func (*Policy) Report ¶
Report returns the state of every window at now and, if target is not nil, the decision for deploying target with origin at now.
type Report ¶
type Report struct {
Time time.Time `json:"time"`
Windows []Status `json:"windows"`
// Decision is the decision for the requested target, if any.
Decision *Decision `json:"decision,omitempty"`
}
Report is the state of a policy at a point in time.
type Status ¶
type Status struct {
Name string `json:"name"`
Kind Kind `json:"kind"`
Schedule string `json:"schedule"`
Duration string `json:"duration"`
Timezone string `json:"timezone"`
Repositories []string `json:"repositories"`
Deployments []string `json:"deployments"`
Contexts []string `json:"contexts"`
ManualSync bool `json:"manual_sync"`
Active bool `json:"active"`
ActiveSince *time.Time `json:"active_since,omitempty"`
ActiveUntil *time.Time `json:"active_until,omitempty"`
NextStart *time.Time `json:"next_start,omitempty"`
}
Status describes a window at a point in time.
type Target ¶
type Target struct {
Repository string // Repository is the repository/artifact name the stack is deployed from, e.g. "github.com/acme/app".
// ConfigRepository is the repository containing the deploy config, if it
// differs from Repository (deploy configs with repository_url). Repository
// selectors match if either name matches.
ConfigRepository string
Deployment string // Deployment is the deployment (stack/project) name.
Context string // Context is the Docker context name. Empty means "default".
}
Target identifies the stack a deployment would change.
type Window ¶
type Window struct {
Name string // Name identifies the window in logs, metrics and the API. Defaults to "<kind>-<index>".
Kind Kind // Kind is either allow or deny.
Schedule string // Schedule is the 5-field cron expression or descriptor at which the window opens.
Duration time.Duration // Duration is how long the window stays active after each occurrence.
Timezone string // Timezone is the IANA timezone the schedule is evaluated in. Empty means the doco-cd timezone (TZ).
Repositories []string // Repositories are glob patterns matched against the repository/artifact name. Empty matches all.
Deployments []string // Deployments are glob patterns matched against the deployment (stack/project) name. Empty matches all.
Contexts []string // Contexts are glob patterns matched against the Docker context name ("default" for the default context). Empty matches all.
ManualSync bool // ManualSync lets manual (API/MCP) deployments bypass this window.
// contains filtered or unexported fields
}
Window is a single sync window definition.
Source Files