ccdeploy

README

ccdeploy

The rain ccdeploy command provisions resources using the AWS Cloud Control API (CCAPI). It does not submit templates to CloudFormation, so there will be no managed stack to interact with after running this command. API calls are made directly from the client to CCAPI, and the state for the resources is stored by Rain in the same S3 bucket that is used for assets.

This is a highly experimental feature that exists mainly as a prototype for what a client-side provisioning engine might look like. Do not use this for production workloads. (Seriously)

Only resources that have been fully migrated to the CloudFormation registry can be provisioned with this command. It is important to note that resource provisioning is still done by the same back-end resource providers that CloudFormation uses. Those are available on GitHub under the aws-cloudformation organization, for example RDS. The ccdeploy command makes client-side calls to CCAPI endpoints like CreateResource, but then CCAPI itself is the one making SDK calls into specific services.

The following is an excerpt from a blog post: The history and future roadmap of the AWS CloudFormation Registry

If you want to see if a given CloudFormation resource is on the new registry model or not, check if the provisioning type is either Fully Mutable or Immutable by invoking the DescribeType API and inspecting the ProvisioningType response element.

Here is a sample CLI command that gets a description for the AWS::Lambda::Function resource, which is on the new registry model.

sh $ aws cloudformation describe-type --type RESOURCE \ --type-name AWS::Lambda::Function | grep ProvisioningType

   "ProvisioningType": "FULLY_MUTABLE", 

The difference between FULLY_MUTABLE and IMMUTABLE is the presence of the Update handler. FULLY_MUTABLE types includes an update handler to process updates to the type during stack update operations. Whereas, IMMUTABLE types do not include an update handler, so the type can’t be updated and must instead be replaced during stack update operations. Legacy resource types will be NON_PROVISIONABLE.

Why would I want to use this?

Again, for production workloads, you shouldn't. But the one big benefit is that you have access to the resource state, which is described in detail below. You could, in theory, modify the state to deal with unexpected deployment failures, or to remediate complex drift situations. Template deployment might be slightly faster, since you won't wait for the CloudFormation backend to push your stack through the workflow, but since CloudFormation uses the same resource providers, the difference will not be huge.

Another good reason is that you are curious about how CCAPI works, and you are interested in learning about all the really hard things a template provisioning engine has to do. Let us know if you want to dive in and contribute. The best way to learn is by doing!

State management

State cannot be managed based on the template alone, due to the fact that primary identifiers are not always required (and often disouraged). For example, the following template deploys an S3 bucket:

Resources: 
    MyBucket: 
        Type: AWS::S3::Bucket 

The physical name of the bucket was not specified, and since two different templates could both have an S3 bucket with the logical ID "MyBucket", there is no way to tell from looking at the template alone what bucket it corresponds to in your account.

It is obviously very important to store the state in a way that it cannot be lost or associated with the wrong AWS environment. It is also important to make sure two processes don't try to deploy the same template at the same time.

The state file for rain ccdeploy is stored as a YAML file that has the same format as the source CloudFormation template. Extra sections are added to the file to associate state with the deployed resources.

State: 
  LastWriteTime: ...
  ResourceModels:
    MyResource:
      Identifier:
      Model:
        ...

Each deployment has its own state file in the rain artifacts bucket in the region where you are deploying. If a user tries a deploymemnt while there is a locked state file, the command gives an error message with instructions on how to remediate the issue. Often times, this will result from a deployment that failed halfway through.

rain-artifacts-0123456789012-us-east-1/ 
    deployments/ 
        name1.yaml
        name2.yaml

Drift detection can be run on the state file to inspect the actual resource properties and compare them to the stored state.

Usage

To use this command, supply the same arguments that you would supply to the deploy command:

$ rain ccdeploy my-template.yaml my-deployment-name

To remove resources deployed with ccdeploy, use the ccrm command:

$ rain ccrm my-deployment-name

Unsupported features

Since this is a prototype, some features are not yet supported:

• Instrinsic functions (Fn::*, GetAtt, Sub)
• Parameters
• Tags
• Retention policies
• Probably more stuff that is totally necessary for production use

Documentation

Index

• Constants
• Variables
• func PackageTemplate(fn string, yes bool) cft.Template
• type DeploymentResults
  • func DeployTemplate(template cft.Template) (*DeploymentResults, error)
• type Resource
  • func NewResource(name string, resourceType string, state ResourceState, node *yaml.Node) *Resource
  • func (r Resource) String() string
• type ResourceState
• type StateResult

Constants

const FILE_PATH string = "FilePath"

const STATE_DIR string = "deployments"

Variables

var Cmd = &cobra.Command{
	Use:   "ccdeploy <template> <name>",
	Short: "Deploy a local template directly using the Cloud Control API (Experimental!)",
	Long: `Creates or updates resources directly using Cloud Control API from the template file <template>.
You must pass the --experimental (-x) flag to use this command, to acknowledge that it is experimental and likely to be unstable!
`,
	Args:                  cobra.ExactArgs(2),
	DisableFlagsInUseLine: true,
	Run:                   run,
}

var Experimental bool

Functions

func PackageTemplate

func PackageTemplate(fn string, yes bool) cft.Template

PackageTemplate reads the template and performs any necessary packaging on it before deployment. The rain bucket will be created if it does not already exist.

Types

type DeploymentResults

type DeploymentResults struct {
	Succeeded bool
	State     cft.Template
	Resources map[string]*Resource
}

DeploymentResults captures everything that happened as a result of deployment

func DeployTemplate

func DeployTemplate(template cft.Template) (*DeploymentResults, error)

deployTemplate deloys the CloudFormation template using the Cloud Control API. A failed deployment will result in DeploymentResults.Succeeded = false. A non-nil error is returned when something unexpected caused a failure not related to actually deploying resources, like an invalid template.

type Resource

type Resource struct {
	Name       string
	Type       string
	Node       *yaml.Node
	State      ResourceState
	Message    string
	Identifier string
	Model      string
	Action     diff.ActionType
	PriorJson  string
}

func NewResource

func NewResource(name string,
	resourceType string, state ResourceState, node *yaml.Node) *Resource

NewResource creates a new Resource and adds it to the map

func (Resource) String

func (r Resource) String() string

type ResourceState

type ResourceState int

const (
	Waiting ResourceState = iota
	Deploying
	Failed
	Deployed
	Canceled
)

type StateResult

type StateResult struct {
	StateFile cft.Template
	Lock      string
	IsUpdate  bool
}