cloudformation

package
v0.0.1-alpha.30 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package cloudformation provides emulation of AWS CloudFormation.

Implemented operations:

  • CreateStack, UpdateStack, DeleteStack
  • DescribeStacks, ListStacks
  • GetTemplate
  • CreateChangeSet, DescribeChangeSet, ExecuteChangeSet, DeleteChangeSet, ListChangeSets
  • DescribeStackResources, ListStackResources
  • DescribeStackEvents
  • GetTemplateSummary
  • ValidateTemplate

Stack operations are asynchronous: CreateStack returns CREATE_IN_PROGRESS, and a background goroutine provisions resources by dispatching internal HTTP requests through the emulator's router. DescribeStacks is the polling mechanism.

Index

Constants

View Source 
const (
	StatusCreateInProgress   = "CREATE_IN_PROGRESS"
	StatusCreateComplete     = "CREATE_COMPLETE"
	StatusCreateFailed       = "CREATE_FAILED"
	StatusUpdateInProgress   = "UPDATE_IN_PROGRESS"
	StatusUpdateComplete     = "UPDATE_COMPLETE"
	StatusUpdateFailed       = "UPDATE_FAILED"
	StatusDeleteInProgress   = "DELETE_IN_PROGRESS"
	StatusDeleteComplete     = "DELETE_COMPLETE"
	StatusDeleteFailed       = "DELETE_FAILED"
	StatusRollbackInProgress = "ROLLBACK_IN_PROGRESS"
	StatusRollbackComplete   = "ROLLBACK_COMPLETE"
	StatusRollbackFailed     = "ROLLBACK_FAILED"

	StatusUpdateRollbackInProgress = "UPDATE_ROLLBACK_IN_PROGRESS"
	StatusUpdateRollbackComplete   = "UPDATE_ROLLBACK_COMPLETE"
	StatusUpdateRollbackFailed     = "UPDATE_ROLLBACK_FAILED"

	// Cleanup states. An update does not finish the moment every resource has
	// been updated: CloudFormation then removes what the update superseded —
	// resources dropped from the template, and the originals that replacements
	// replaced — and reports that phase separately. Both are transient states
	// on the way to their COMPLETE counterpart, and both are observable, which
	// is why a stack can sit visibly in one when a leftover resource will not
	// delete.
	StatusUpdateCompleteCleanupInProgress         = "UPDATE_COMPLETE_CLEANUP_IN_PROGRESS"
	StatusUpdateRollbackCompleteCleanupInProgress = "UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS"

	ChangeSetStatusCreateComplete = "CREATE_COMPLETE"
	ChangeSetStatusFailed         = "FAILED"

	ExecStatusAvailable         = "AVAILABLE"
	ExecStatusUnavailable       = "UNAVAILABLE"
	ExecStatusExecuteComplete   = "EXECUTE_COMPLETE"
	ExecStatusExecuteFailed     = "EXECUTE_FAILED"
	ExecStatusExecuteInProgress = "EXECUTE_IN_PROGRESS"

	ResourceCreateInProgress = "CREATE_IN_PROGRESS"
	ResourceCreateComplete   = "CREATE_COMPLETE"
	ResourceCreateFailed     = "CREATE_FAILED"
	ResourceUpdateInProgress = "UPDATE_IN_PROGRESS"
	ResourceUpdateComplete   = "UPDATE_COMPLETE"
	ResourceUpdateFailed     = "UPDATE_FAILED"
	ResourceDeleteInProgress = "DELETE_IN_PROGRESS"
	ResourceDeleteComplete   = "DELETE_COMPLETE"
	ResourceDeleteFailed     = "DELETE_FAILED"
	ResourceDeleteSkipped    = "DELETE_SKIPPED"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Change 

type Change struct {
	Type           string         `json:"Type"` // always "Resource"
	ResourceChange ResourceChange `json:"ResourceChange"`
}

Change describes a single resource change in a change set.

type ChangeSet 

type ChangeSet struct {
	ChangeSetName   string      `json:"ChangeSetName"`
	ChangeSetID     string      `json:"ChangeSetId"`
	StackID         string      `json:"StackId"`
	StackName       string      `json:"StackName"`
	TemplateBody    string      `json:"TemplateBody"`
	Parameters      []Parameter `json:"Parameters,omitempty"`
	Tags            []Tag       `json:"Tags,omitempty"`
	TagsSet         bool        `json:"TagsSet,omitempty"`
	Capabilities    []string    `json:"Capabilities,omitempty"`
	Status          string      `json:"Status"`
	StatusReason    string      `json:"StatusReason,omitempty"`
	ChangeSetType   string      `json:"ChangeSetType"` // CREATE or UPDATE
	Changes         []Change    `json:"Changes,omitempty"`
	CreatedAt       time.Time   `json:"CreationTime"`
	ExecutionStatus string      `json:"ExecutionStatus"`
}

ChangeSet represents a CloudFormation change set.

type Export 

type Export struct {
	ExportingStackId string
	Name             string
	Value            string
}

Export represents a stack output that is exported for cross-stack references.

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler holds CloudFormation handler dependencies.

func (*Handler) CreateChangeSet 

func (h *Handler) CreateChangeSet(w http.ResponseWriter, r *http.Request)

func (*Handler) CreateStack 

func (h *Handler) CreateStack(w http.ResponseWriter, r *http.Request)

func (*Handler) DeleteChangeSet 

func (h *Handler) DeleteChangeSet(w http.ResponseWriter, r *http.Request)

func (*Handler) DeleteStack 

func (h *Handler) DeleteStack(w http.ResponseWriter, r *http.Request)

func (*Handler) DescribeChangeSet 

func (h *Handler) DescribeChangeSet(w http.ResponseWriter, r *http.Request)

func (*Handler) DescribeStackEvents 

func (h *Handler) DescribeStackEvents(w http.ResponseWriter, r *http.Request)

func (*Handler) DescribeStackResources 

func (h *Handler) DescribeStackResources(w http.ResponseWriter, r *http.Request)

func (*Handler) DescribeStacks 

func (h *Handler) DescribeStacks(w http.ResponseWriter, r *http.Request)

func (*Handler) ExecuteChangeSet 

func (h *Handler) ExecuteChangeSet(w http.ResponseWriter, r *http.Request)

func (*Handler) GetTemplate 

func (h *Handler) GetTemplate(w http.ResponseWriter, r *http.Request)

func (*Handler) GetTemplateSummary 

func (h *Handler) GetTemplateSummary(w http.ResponseWriter, r *http.Request)

func (*Handler) ListChangeSets 

func (h *Handler) ListChangeSets(w http.ResponseWriter, r *http.Request)

func (*Handler) ListExports 

func (h *Handler) ListExports(w http.ResponseWriter, r *http.Request)

func (*Handler) ListImports 

func (h *Handler) ListImports(w http.ResponseWriter, r *http.Request)

func (*Handler) ListStackResources 

func (h *Handler) ListStackResources(w http.ResponseWriter, r *http.Request)

func (*Handler) ListStacks 

func (h *Handler) ListStacks(w http.ResponseWriter, r *http.Request)

func (*Handler) RollbackStack 

func (h *Handler) RollbackStack(w http.ResponseWriter, r *http.Request)

RollbackStack rolls a failed stack back to its last known stable state. This is what `cdk rollback` calls to recover a stack stuck in UPDATE_FAILED, which otherwise blocks every subsequent deploy.

func (*Handler) UpdateStack 

func (h *Handler) UpdateStack(w http.ResponseWriter, r *http.Request)

func (*Handler) ValidateTemplate 

func (h *Handler) ValidateTemplate(w http.ResponseWriter, r *http.Request)

type Output 

type Output struct {
	Key         string `json:"OutputKey"`
	Value       string `json:"OutputValue"`
	Description string `json:"Description,omitempty"`
	ExportName  string `json:"ExportName,omitempty"`
}

Output is a stack output value.

type Parameter 

type Parameter struct {
	Key   string `json:"ParameterKey"`
	Value string `json:"ParameterValue"`
}

Parameter is a key-value pair for a stack parameter.

type ResourceChange 

type ResourceChange struct {
	Action             string `json:"Action"` // Add, Modify, Remove
	LogicalResourceID  string `json:"LogicalResourceId"`
	PhysicalResourceID string `json:"PhysicalResourceId,omitempty"`
	ResourceType       string `json:"ResourceType"`
	Replacement        string `json:"Replacement,omitempty"` // True, False, Conditional
}

ResourceChange describes how a resource will be modified.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service implements router.Service and router.QueryDispatcher for CloudFormation. Uses the AWS Query protocol (form-encoded POST, XML responses) and identifies itself by individual action names.

func New 

func New(cfg *config.Config, store state.Store, logger *zap.Logger, clk clock.Clock) *Service

New returns a configured CloudFormation Service.

func (*Service) DispatchQuery 

func (s *Service) DispatchQuery(w http.ResponseWriter, r *http.Request)

DispatchQuery satisfies router.QueryDispatcher.

func (*Service) InitBus 

func (s *Service) InitBus(bus *events.Bus)

InitBus wires the event bus for stack lifecycle events.

func (*Service) InitRouter 

func (s *Service) InitRouter(router http.Handler)

InitRouter sets the HTTP handler for internal resource provisioning dispatch. Must be called after the router is fully constructed.

func (*Service) Name 

func (s *Service) Name() string

Name satisfies router.Service.

func (*Service) Operations 

func (s *Service) Operations() []op.Operation

Operations implements router.ProtocolService.

func (*Service) OwnsVersion 

func (s *Service) OwnsVersion(version string) bool

OwnsVersion satisfies router.QueryVersionOwner. CloudFormation's API version (2010-05-15) uniquely identifies requests to this service — the same way LocalStack and real AWS route Query-protocol requests before inspecting the action name.

func (*Service) RegisterRoutes 

func (s *Service) RegisterRoutes(_ chi.Router)

RegisterRoutes satisfies router.Service. CloudFormation has no path-routed endpoints.

func (*Service) Stop 

func (s *Service) Stop(ctx context.Context)

Stop drains in-flight provisioning goroutines.

func (*Service) SupportedProtocols 

func (s *Service) SupportedProtocols() []codec.Codec

SupportedProtocols implements router.ProtocolService.

type Stack 

type Stack struct {
	StackName       string            `json:"StackName"`
	StackID         string            `json:"StackId"`
	Region          string            `json:"Region,omitempty"`
	ParentStackID   string            `json:"ParentId,omitempty"`
	RootID          string            `json:"RootId,omitempty"`
	TemplateBody    string            `json:"TemplateBody"`
	Parameters      []Parameter       `json:"Parameters,omitempty"`
	Tags            []Tag             `json:"Tags,omitempty"`
	Outputs         []Output          `json:"Outputs,omitempty"`
	Resources       []StackResource   `json:"Resources,omitempty"`
	Status          string            `json:"StackStatus"`
	StatusReason    string            `json:"StackStatusReason,omitempty"`
	Capabilities    []string          `json:"Capabilities,omitempty"`
	RoleARN         string            `json:"RoleARN,omitempty"`
	DisableRollback bool              `json:"DisableRollback,omitempty"`
	CreatedAt       time.Time         `json:"CreationTime"`
	UpdatedAt       *time.Time        `json:"LastUpdatedTimestamp,omitempty"`
	DeletedAt       *time.Time        `json:"DeletionTime,omitempty"`
	Metadata        map[string]string `json:"Metadata,omitempty"`
}

Stack represents a CloudFormation stack. Events are stored separately (see cfnStore.appendStackEvent / getStackEvents) so that stack metadata reads never load the full event history.

type StackEvent 

type StackEvent struct {
	EventID              string    `json:"EventId"`
	StackID              string    `json:"StackId"`
	StackName            string    `json:"StackName"`
	LogicalResourceID    string    `json:"LogicalResourceId"`
	PhysicalResourceID   string    `json:"PhysicalResourceId,omitempty"`
	ResourceType         string    `json:"ResourceType"`
	ResourceStatus       string    `json:"ResourceStatus"`
	ResourceStatusReason string    `json:"ResourceStatusReason,omitempty"`
	Timestamp            time.Time `json:"Timestamp"`
}

StackEvent is an immutable record of a lifecycle state transition. Events are appended as provisioning progresses and are never mutated. The order in which events are appended matches the order AWS emits them; DescribeStackEvents returns them newest-first.

type StackResource 

type StackResource struct {
	LogicalID    string            `json:"LogicalResourceId"`
	PhysicalID   string            `json:"PhysicalResourceId,omitempty"`
	Type         string            `json:"ResourceType"`
	Status       string            `json:"ResourceStatus"`
	StatusReason string            `json:"ResourceStatusReason,omitempty"`
	Timestamp    time.Time         `json:"Timestamp"`
	Attributes   map[string]string `json:"Attributes,omitempty"`
	// PropertiesHash is a sha256 of the resolved Properties at provisioning
	// time. UpdateStack uses it to detect property drift and re-provision
	// only resources whose properties actually changed (e.g. Lambda code).
	PropertiesHash string `json:"PropertiesHash,omitempty"`
	// Properties are the resolved properties this resource was provisioned
	// with. They must persist: an update reads them back as the "old" side of
	// the comparison every Update handler makes to decide whether a changed
	// property can be applied in place or forces replacement, and to diff which
	// fields to patch. Marked `json:"-"` they came back nil on every update, so
	// each of those comparisons quietly concluded "nothing changed" — an
	// AWS::RDS::DBInstance kept its old master username, an API Gateway stage
	// patched nothing, and a custom resource's Lambda was handed a null
	// OldResourceProperties, which the custom-resource contract does not allow.
	//
	// Records written before this was persisted decode to nil, which every
	// caller already treats as "no prior state known" and skips.
	Properties map[string]any `json:"Properties,omitempty"`
	// DeletionPolicy / UpdateReplacePolicy are copied from the template at
	// provisioning time so DeleteStack and UpdateStack can honour Retain /
	// Snapshot semantics without re-parsing the template.
	DeletionPolicy      string `json:"DeletionPolicy,omitempty"`
	UpdateReplacePolicy string `json:"UpdateReplacePolicy,omitempty"`
}

StackResource tracks a single provisioned resource within a stack.

type Tag 

type Tag struct {
	Key   string `json:"Key"`
	Value string `json:"Value"`
}

Tag is a key-value pair for tagging.

type Template 

type Template struct {
	AWSTemplateFormatVersion string                       `json:"AWSTemplateFormatVersion"`
	Description              string                       `json:"Description"`
	Parameters               map[string]TemplateParameter `json:"Parameters"`
	Resources                map[string]TemplateResource  `json:"Resources"`
	Outputs                  map[string]TemplateOutput    `json:"Outputs"`
	Conditions               map[string]any               `json:"Conditions"`
	Mappings                 map[string]any               `json:"Mappings"`
}

Template is a parsed CloudFormation template.

type TemplateOutput 

type TemplateOutput struct {
	Value       any    `json:"Value"`
	Description string `json:"Description"`
	Export      *struct {
		Name any `json:"Name"`
	} `json:"Export"`
	Condition string `json:"Condition"`
}

TemplateOutput describes a declared output.

type TemplateParameter 

type TemplateParameter struct {
	Type          string                   `json:"Type"`
	Default       templateParameterValue   `json:"Default"`
	Description   string                   `json:"Description"`
	AllowedValues []templateParameterValue `json:"AllowedValues"`
}

TemplateParameter describes a declared parameter.

type TemplateResource 

type TemplateResource struct {
	Type       string         `json:"Type"`
	Properties map[string]any `json:"Properties"`
	DependsOn  any            `json:"DependsOn"` // string or []string
	Condition  string         `json:"Condition"`
	// DeletionPolicy controls what happens on stack delete: "Delete" (default),
	// "Retain" (leave the resource in place), or "Snapshot" (treated as Retain
	// in Overcast — we don't snapshot).
	DeletionPolicy string `json:"DeletionPolicy,omitempty"`
	// UpdateReplacePolicy controls what happens when an UpdateStack requires
	// the resource to be replaced (delete + create). "Delete" (default),
	// "Retain" (orphan the old resource), or "Snapshot" (treated as Retain).
	UpdateReplacePolicy string `json:"UpdateReplacePolicy,omitempty"`
}

TemplateResource describes a declared resource.

Source Files

View all Source 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.