Reference: Cloudspin project structure

This defines a standard project structure for an infrastructure stack. The goals of having this standardized include:

  • Make it easy for people who’ve worked with this structure before to understand and work with new infrastructure stack code.

  • (Hopefully) make it easy for people who haven’t worked with this structure to learn it.

  • Avoid wasting time haggling with people on your team about how to structure your project. Just use ours. ;-)

  • Write scripts, tools, etc. that can work across all your infrastructure projects

  • Use scripts, tools, etc. that were written by other people using this same structure

Top level stack project structure

Each stack definition can include the following top level folders and files, which should be checked into source control:


Stack definition code, i.e. Terraform source code (*.tf files)


Code used to test stack definitions. Not run against production environments, as it may be destructive.


Configuration for stack roles (tbc)


Configuration for stack instances


Delivery pipeline definition code. Typically run to add pipeline stages to a CI or CD service.


Code used to monitor stack instances. Typically run to add monitoring checks to a monitoring service. (tbc)


Code to run after provisioning or updating a stack instance, to validate it (tbc)


Default parameters for stack instances and roles


Optional rakefile for stack management and test tasks. See Cloudspin Rake tasks for more information.


Optional, needed if you’re using rake to make sure the required gems are available


Optional, useful if you’re using rake to ensure consistent versions of gems are used

Some of these are "(tbc)", meaning it’s an aspirational thing that hasn’t been worked on yet.

There is also at least one file that can be added to local instances of your project, but which should not added to source control:


Override parameter values when you work with stack instances from your local machine. Often used for user-specific information such as AWS profiles to use. Avoid putting secrets in this file, in case it is accidentally committed to a public repository (easier than you think!)

And, there are a few folders that may be created by cloudspin tools for various purposes, which should normally not be committed to version control:

Folder What is it When is it destroyed


Various files are copied or created under here as a part of stack instance management, and testing. This includes logfiles, temporary files, and a copy of the stack definition code.

This folder is deleted on nearly every run of the stack or rake commands. rake clean removes it.


Terraform local statefiles are stored in this folder.

Only destroyed when rake clobber is run. Losing these files while you have an instance running means you can’t use cloudspin tools to destroy or change your instance - it becomes orphaned, and so must be deleted manually.

Stack definition configuration

As mentioned, the ./src folder holds the stack definition, i.e. the terraform code. It also normally has a file ./src/stack-definition.yaml, which includes some configuration information used by the cloudspin tools.

At the moment this is fairly minimal:

  name: example1
  version: 0.0.1
Option Description


The name of the stack definition. This is used as the base name for the stack definition artefact package file. It is also used, by default, as the base name for stack instances.


The version of the stack definition. This is appended to the stack:name to name the artefact package file.

In the future, things could be added to this file to define integration points and dependencies between stacks.

results matching ""

    No results matching ""