README.md in sfn-0.5.0 vs README.md in sfn-1.0.0
- old
+ new
@@ -1,10 +1,16 @@
+
+
# SparkleFormation CLI
SparkleFormation command line interface for interacting
with orchestration APIs.
+## Extra Documentation
+
+* [User Documentation](https://sparkleformation.github.io/sfn/UserDocs)
+
## API Compatibility
* AWS
* Rackspace
* OpenStack
@@ -24,54 +30,123 @@
#### JSON
```json
{
"credentials": {
- AWS_CREDENTIALS
+ MIASMA_CREDENTIALS
},
"options": {
"disable_rollback": true
}
}
```
-### YAML
+#### YAML
```yaml
---
:credentials:
:fubar: true
:options:
:disable_rollback: true
```
-### XML
+#### XML
```xml
<configuration>
<credentials>
- AWS_CREDENTIALS
+ MIASMA_CREDENTIALS
</credentials>
<options>
<disable_rollback>
true
</disable_rollback>
</options>
</configuration>
```
-### Ruby
+#### Ruby
```ruby
Configuration.new do
credentials do
- AWS_CREDENTIALS
+ MIASMA_CREDENTIALS
end
- options.disable_rollback true
+ options.on_failure 'nothing'
end
```
+### Configuration Options
+
+* `processing` - Enable SparkleFormation processing
+ * Valid: Boolean
+ * Default: `true`
+
+* `apply_nesting` - Style of nested stack processing
+ * Valid: `"shallow"`, `"deep"`
+ * Default: `"deep"`
+
+* `options` - API options for target orchestration API (see miasma)
+ * Valid: `Hash`
+ * Default: none
+
+* `ssh_attempt_users` - List of users to attempt SSH connection on node failure
+ * Valid: `Array<String>`
+ * Default: none
+
+* `identity_file` - Custom SSH identity file to use for connection on node failure
+ * Valid: `String`
+ * Default: none
+
+* `nesting_bucket` - Name of bucket to store nested stack templates
+ * Valid: `String`
+ * Default: none
+
+* `credentials` - API credentials for target orchestration API (see [miasma](https://github.com/miasma-rb/miasma))
+ * Valid: `Hash`
+ * Default: none
+
+* `callbacks` - Callbacks to execute around API calls
+ * Valid: `Hash`
+ * Default: none
+ * `before` - Callbacks to execute before _any_ API call
+ * Valid: `Array<String>`
+ * Default: none
+ * `after` - Callbacks to execute after _any_ API call
+ * Valid: `Array<String>`
+ * Default: none
+ * `before_COMMAND` - Callbacks to execute before specific `COMMAND` API call
+ * Valid: `Array<String>`
+ * Default: none
+ * `after_COMMAND` - Callbacks to execute after specific `COMMAND` API call
+ * Valid: `Array<String>`
+ * Default: none
+ * `template` - Callbacks to execute on template
+ * Valid: `Array<String>`
+ * Default: none
+ * `default` - Callbacks to always execute
+ * Valid: `Array<String>`
+ * Default: none
+ * `require` - List of custom libraries to load
+ * Valid: `Array<String>`
+ * Default: none
+
+* `retry` - Configuration of API request retries
+ * Valid: `Hash`
+ * Default: none
+ * `type` - Type of retry
+ * Valid: `"flat"`, `"linear"`, `"exponential"`
+ * Default: `"exponential"`
+ * `interval` - Base wait interval for retry
+ * Valid: `Numeric`
+ * Default: 5
+ * `max_attempts` - Maximum number of attempts allowed
+ * Valid: `Numeric`
+ * Default: 20
+ * _NOTE_: Set to `nil` for infinite retry
+
## Commands
* `sfn list`
* `sfn create`
* `sfn update`
@@ -79,49 +154,24 @@
* `sfn events`
* `sfn describe`
* `sfn inspect`
* `sfn validate`
+_NOTE: All commands respond to `--help` and will provide a full list of valid options._
+
### `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
@@ -191,20 +241,10 @@
### `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
@@ -230,30 +270,22 @@
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][miasma] library. It also provides extra helpers for
running common inspection commands.
-### Supported options
+### Interesting `inspect` options
* `--nodes` list node addresses within stack
* `--instance-failure [LOG_FILE]` print log file from failed instance
* `--attribute ATTR` print stack attribute
\ No newline at end of file