cloudspin-stack 0.1.10 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a77954b28811b4e70c3b68e38ec4aa222da97576
-  data.tar.gz: 7d2e8ff6082d11293d69bf87890701c0da1b02c6
+  metadata.gz: 0e7bef5adc2239f0f03b92de64f81790bbfaf2b7
+  data.tar.gz: e7d0aeb6042c40c76412f944c8742f5960a4b023
 SHA512:
-  metadata.gz: 0d21bea647d8da42838070efa33d2ff2462f386c71b3d554e22485accc48ddc943436e1a615eab549e27a1244120340542b470d8c1b3f3d9720626aad154e062
-  data.tar.gz: d794ab498fcdb482ad0013ae5f0a0730a27e5828117c161a8f9bfc8771720124096fbece73d4fe15cc26ece1eb69fd9c1543b520059e91ffff07a0d2ca5556f9
+  metadata.gz: ce1a12b0f4fcf245340c9b64fcde15450e2239a045904c61a0c157e60faa2e246b3c7b693212ced3784f1b4125bc5ead74bf879e1b357721bf687632dfabb2b9
+  data.tar.gz: 2800664544aad1ae5980e0413d5cfaea31fe581f697aab9fe2ab1fbe9e7f6e5e6a00646e1b72f0fcd886e79c7dcc5e518470cdeb79cdb603710dceb3fbf91b48

data/README.md

@@ -1,8 +1,55 @@
 # Cloudspin::Stack
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/cloudspin/stack`. To experiment with that code, run `bin/console` for an interactive prompt.
+This Ruby library is a prototype for an infrastructure project delivery framework. It is intended as a basis for exploring project structures, conventions, and functionality, but is not currently in a stable state.
 
-TODO: Delete this and the text above, and describe your gem
+Feel free to copy and use this, but be prepared to extend and modify it in order to make it useful for your own project. There isn't likely to be a clean path to upgrade your projects as this thing evolves - my assumption is that nobody else is directly depending on this code or the gems I've published from it.
+
+
+## What's here
+
+This project creates a ruby gem, which has some classes that can be used to manage instances of infrastructure stacks. These classes can be called used in rspec-based tests. There is also a command line tool included in the gem (`stack`), which can be used to manage stack instances.
+
+A separate gem, [cloudspin-stack-rake](https://github.com/cloudspinners/cloudspin-stack-rake), can be used to create rake tasks that use the classes here to manage stacks.
+
+The classes and tools in this gem are meant to be primitives. They shouldn't dictate details of how to organise and configure infrastructure and environments, although I've designed them to support patterns that I have in mind, so it's possible some of this has leaked into them.
+
+
+## Examples
+
+I'm using [spin-stack-network](https://github.com/cloudspinners/spin-stack-network) as an example of an infrastructure stack project to make use of this framework. I may add other projects in the future as the tool is developed.
+
+
+# Concepts
+
+## What's the point of this?
+
+Currently, most people and teams managing infrastructure with tools such as Terraform, CloudFormation, etc. define their own project structures, and write their own wrapper scripts to run that tool and associated tasks. Essentially, each project is a unique snowflake.
+
+The goal for cloudspin is to evolve a common structure and build tooling for infrastructure projects, focused on the lifecycle of "[stacks](http://infrastructure-as-code.com/patterns/2018/03/28/defining-stacks.html)" - infrastructure elements provisioned on dynamic infrastructure such as IaaS clouds.
+
+Our hypothesis is that, with a common project structure and tooling:
+
+- Teams will spend less time building and maintaining snowflake build systems,
+- New team members can more quickly get up to speed when joining an infrastructure project,
+- People can create and share tools and scripts that work with the common structure, creating an ecosystem,
+- People can create and share infrastructure code for running various software and services, creating a community library.
+
+
+## Philosophy
+
+- [Convention over configuration](https://en.wikipedia.org/wiki/Convention_over_configuration).
+-- The tool should discover elements of the project based on folder structure
+-- A given configuration value should be set in a single place
+-- Implies a highly "[opinionated](https://medium.com/@stueccles/the-rise-of-opinionated-software-ca1ba0140d5b)" approach
+- Encourage good agile engineering practices for the infrastructure code
+-- Writing and running tests should be a natural thing
+-- Building and using [infrastructure pipelines](http://infrastructure-as-code.com/book/2017/08/02/environment-pipeline.html) should be a natural thing
+- Support evolutionary architecture
+-- Loose coupling of infrastructure elements
+- Empower developers / users of infrastructure
+
+
+# Instructions
 
 ## Installation
 
@@ -20,11 +67,64 @@ Or install it yourself as:
 
     $ gem install cloudspin-stack
 
-## Usage
 
-TODO: Write usage instructions here
+## Documentation
+
+
+### Stack Definition
+
+A *stack definition* is a single infrastructure code project, i.e. a Terraform project (but could be implemented for CloudFormation, ARM, or other tools in the future).
+
+### Stack Instance
+
+A *stack instance* is an instance of the stack running on your infrastructure platform (I have used it for AWS so far, but it should work for other cloud platforms without much modification).
+
+Operations on the stack include:
+
+- up: create or update an instance of the stack, from a defintion
+- down: destroy an instance of the stack
 
-## Development
+Each of these operations can be *planned*, which prints the changes that will be applied, without actually applying them.
+
+
+## Usage: Ruby API
+
+TODO: Write stuff.
+
+
+## Usage: Command line tool
+
+Create or update an instance of the stack defined in `TERRAFORM_FOLDER`, using the identifier `STACKNAME` to distinguish it from other instances of the stack:
+
+```bash
+stack up STACKNAME -t TERRAFORM_FOLDER
+```
+
+Destroy the stack instance:
+
+```bash
+stack down STACKNAME -t TERRAFORM_FOLDER
+```
+
+Each of these commands can take the `--dry` and/or `--plan` argument. 
+
+`--dry` prints out the terraform command to be run, but doesn't do anything. So this doesn't even need AWS credentials to work.
+
+`--plan` prints out the changes that will be made to the existing stack instance, if any. This does need AWS credentials.
+
+
+## Configuration
+
+The classes don't many assumptions about how to configure your stack projects. The classes themselves are very primitive: you'll pass in whatever parameters and resources you need, and then use those in your project files, generally as terraform variables.
+
+The stack command line tool, and rake tasks, tests, and your own stuff will tend to put more conventions around parameters and resources.
+
+Resources are essentially the same as parameters, but are assumed to relate to other infrastructure, e.g. things you'll need to integrate with, cloud provider credentials, etc.
+
+All this needs more documentation and elaboration. For now, you can peruse the code, especially for the example project(s) mentioned above, and hopefully figure stuff out.
+
+
+# Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
@@ -33,3 +133,9 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cloudspin-stack.
+
+
+# Credits
+
+This project makes extensive use of ideas and code from Toby Clemson and Jimmy Thompson, particularly [infrablocks](https://github.com/infrablocks). I've also benefited from feedback on implementation concepts from Vincenzo Fabrizi, and other [ThoughtWorkers](https://thoughtworks.com).
+

data/lib/cloudspin/stack.rb

@@ -1,8 +1,3 @@
 require 'cloudspin/stack/version'
 require 'cloudspin/stack/definition'
 require 'cloudspin/stack/instance'
-
-module Cloudspin
-  module Stack
-  end
-end

data/lib/cloudspin/stack/definition.rb

@@ -4,14 +4,21 @@ module Cloudspin
   module Stack
     class Definition
 
-      attr_reader :parameter_names, :resource_names, :terraform_source_path
+      attr_reader :name
+      attr_reader :version
+      attr_reader :parameter_names
+      attr_reader :resource_names
+      attr_reader :terraform_source_path
 
       def initialize(terraform_source_path: '',
                      parameter_names: [],
-                     resource_names: [])
+                     resource_names: [],
+                     stack: {})
         @terraform_source_path = terraform_source_path
         @parameter_names = parameter_names
         @resource_names = resource_names
+        @name = stack[:name] || 'NO_NAME'
+        @version = stack[:version] || '0'
       end
 
       def self.from_file(specfile)

data/lib/cloudspin/stack/version.rb

@@ -1,5 +1,5 @@
 module Cloudspin
   module Stack
-    VERSION = '0.1.10'
+    VERSION = '0.1.11'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudspin-stack
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.11
 platform: ruby
 authors:
 - 'kief '