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:

./src

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

./test

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

./roles

Configuration for stack roles (tbc)

./environments

Configuration for stack instances

./pipeline

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

./monitoring

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

./smoke

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

./stack-instance-defaults.yaml

Default parameters for stack instances and roles

./Rakefile

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

./Gemfile

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

./Gemfile.lock

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:

./stack-instance-local.yaml

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

./work

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.

./state

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:

stack:
  name: example1
  version: 0.0.1
Option Description

stack:name

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.

stack:version

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 ""