SparkleFormation CLI
SparkleFormation command line interface for interacting with orchestration APIs.
API Compatibility
- AWS
- Rackspace
- OpenStack
Configuration
Configuration is defined within a .sfn
file. The
sfn
command will start from the current working
directory and work up to the root of the file system
to discover this file.
Configuration formats
The configuration file can be provided in a variety of formats:
JSON
{
"credentials": {
AWS_CREDENTIALS
},
"options": {
"disable_rollback": true
}
}
YAML
---
:credentials:
:fubar: true
:options:
:disable_rollback: true
XML
<configuration>
<credentials>
AWS_CREDENTIALS
</credentials>
<options>
<disable_rollback>
true
</disable_rollback>
</options>
</configuration>
Ruby
Configuration.new do
credentials do
AWS_CREDENTIALS
end
.disable_rollback true
end
Commands
sfn list
sfn create
sfn update
sfn destroy
sfn events
sfn describe
sfn inspect
sfn validate
sfn list
Provides listing of current stacks and state of each stack.
Supported options
--attribute ATTR
stack attribute to display--status STATUS
match stacks with given status
sfn validate
Validates template with API
Supported options
--[no-]processing
enable template processing--file PATH
path to stack template file--translate PROVIDER
translate template to provider--[no-]apply-nesting
apply template nesting logic--nesting-bucket BUCKET
asset store bucket to place nested stack templates
sfn create NAME
Creates a new stack with the provided name (NAME
).
Supported options
--timeout MINUTES
stack creation timeout limit--[no-]rollback
disable rollback on failure--capability CAPABILITY
enable capability within API--notifications ARN
add notification ARN--print-only
print stack template JSON and exit--apply-stack NAME
apply existing stack outputs--[no-]processing
enable template processing--file PATH
path to stack template file--translate PROVIDER
translate template to provider--[no-]apply-nesting
apply template nesting logic--nesting-bucket BUCKET
asset store bucket to place nested stack templates
Apply Stacks
The --apply-stack
option allows providing the name of an existing
stack when creating or updating. Applying stacks is simply fetching
the outputs from the applied stacks and automatically defaulting the
set parameter of the new or updated stack. Outputs are matched
by name to the parameters of the target stack. This allows an easy
way to use values from existing stacks when building new stacks.
Example:
StackA:
...
"Outputs": {
"LoadBalancerAddress": {
"Description": "Address of Load Balancer",
"Value": {
"Fn::GetAtt": [
"LoadBalancerResource",
"DNSName"
]
}
}
}
...
StackB:
...
"Parameters": {
"LoadBalancerAddress": {
"Type": "String",
"Default": "unset"
}
}
...
When creating StackB, if we use the --apply-stack
option:
$ sfn create StackB --apply-stack StackA
when prompted for the stack parameters, we will find the parameter
value for LoadBalancerAddress
to be filled in with the output
provided from StackA.
Processing
The default behavior of this plugin assumes templates will be
in JSON format. The --processing
flag will allow providing Ruby
files to dynamically generate templates using the SparkleFormation
library.
NOTE: (SparkleFormation Usage Documentation)[].
This plugin supports the advanced stack nesting feature provided by the SparkleFormation library.
Translations
Translations are currently an alpha
feature and only a subset of
resources are supported.
sfn update STACK
Update an existing stack.
Supported options
--print-only
print stack template JSON and exit--apply-stack NAME
apply existing stack outputs--[no-]processing
enable template processing--file PATH
path to stack template file--translate PROVIDER
translate template to provider--[no-]apply-nesting
apply template nesting logic--nesting-bucket BUCKET
asset store bucket to place nested stack templates
sfn destroy STACK
Destroy an existing stack.
Name globs
The destroy command supports globbing for performing multiple destructions based on glob match. For example, given existing stacks:
- TestStack1
- TestStack2
- Production
running the following command:
$ sfn destroy Test*
will destroy the TestStack1
and TestStack2
sfn events STACK
Display the event listing of given stack. If the state of the stack is "in progress", the polling option will result in polling and displaying new events until the stack reaches a completed state.
Supported options
--[no-]poll
poll for new events until completed state reached
sfn describe STACK
Display resources and outputs of give stack.
Supported options
--resources
display resources--outputs
display outputs
sfn inspect STACK
The stack inspection command simply provides a proxy to the underlying resource modeling objects provided via the miasma library. It also provides extra helpers for running common inspection commands.
Supported options
--nodes
list node addresses within stack--instance-failure [LOG_FILE]
print log file from failed instance--attribute ATTR
print stack attribute
--nodes
This option will return a list of compute instance IDs and their addresses. The result will be a complete list including direct compute resources within the stack as well as compute resources that are part of auto scaling group resouces.
--instance-failure [LOG_FILE]
If the stack create or update failed due to a compute instance,
this option will attempt to locate the instance, connect to
it and download the defined log file. The default log file
is set to: /var/log/chef/client.log
--attribute ATTR
The attribute option is what provides the proxy to the underlying
miasma resource modeling. The value of ATTR
is what should be
called on the Miasma::Models::Orchestration::Stack
instance.
For example, to display the JSON template of a stack:
$ sfn inspect STACK -a template
To display the resource collection of the stack:
$ sfn inspect STACK -a resources
This will provide a list of resources. Now, to make this more useful, we can start inspect specific resources. Lets assume that the 3rd resource in the collection is an auto scaling group resource. We can isolate that resource for display:
$ sfn inspect STACK -a "resources.all.at(2)"
Note that the resources are an array, and we are using a zero based index. Now, this simply provides us with the information we already have seen. One of the handy features within the miasma library is the ability to expand supported resources. So, we can expand this resource:
$ sfn inspect STACK -a "resources.all.at(2).expand"
This will expand the resource instance and return the actual
auto scaling group resource. The result will provide more detailed
information about the scaling group. But, perhaps we are looking
for the instances in this scaling group. The model instance we
now have (Miasma::Orchestration::Models::AutoScale::Group
)
contains a servers
attribute. The output lists the IDs of the
instances, but we can expand those as well:
$ sfn inspect STACK -a "resources.all.at(2).expand.servers.map(&:expand)"
The attribute string will be minimally processed when proxying calls to the underlying models, which is why we are able to do ruby-ish style things.
Chef Knife Integration
This library will also provide cloudformation
subcommands
to knife.
Configuration
The easiest way to configure the plugin is via the
knife.rb
file. Credentials are the only configuration
requirement, and the Hash
provided is proxied to
Miasma. All configuration options provided
via the sfn
command are allowed within the
knife[:cloudformation]
namespace:
AWS
# .chef/knife.rb
knife[:cloudformation][:credentials] = {
:provider => :aws,
:aws_access_key_id => ENV['AWS_ACCESS_KEY_ID'],
:aws_secret_access_key => ENV['AWS_SECRET_ACCESS_KEY'],
:aws_region => ENV['AWS_REGION']
}
Rackspace
# .chef/knife.rb
knife[:cloudformation][:credentials] = {
:provider => :rackspace,
:rackspace_username => ENV['RACKSPACE_USERNAME'],
:rackspace_api_key => ENV['RACKSPACE_API_KEY'],
:rackspace_region => ENV['RACKSPACE_REGION']
}
OpenStack
# .chef/knife.rb
knife[:cloudformation][:credentials] = {
:provider => :open_stack,
:open_stack_username => ENV['OPENSTACK_USERNAME'],
:open_stack_password => ENV['OPENSTACK_PASSWORD'],
:open_stack_identity_url => ENV['OPENSTACK_IDENTITY_URL'],
:open_stack_tenant_name => ENV['OPENSTACK_TENANT']
}
Usage
All commands available via the sfn
command are available as
knife subcommands under cloudformation
and sparkleformation
$ knife cloudformation --help
or
$ knife sparkleformation --help
Info
- Repository: https://github.com/sparkleformation/sfn
- IRC: Freenode @ #sparkleformation