Rezept

A tool to manage EC2 Systems Manager (SSM) Documents with programmable DSL.

Installation

Add this line to your application's Gemfile:

gem 'rezept'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rezept

Usage

General

$ rezept
Commands:
  rezept apply                                    # Apply the documents
  rezept convert -n, --name=NAME -t, --type=TYPE  # Convert the documents to the other format
  rezept export                                   # Export the documents
  rezept help [COMMAND]                           # Describe available commands or one specific command

Options:
  -f, [--file=FILE]                        # Configuration file
                                           # Default: Docfile
      [--color], [--no-color]              # Disable colorize
                                           # Default: true
      [--amazon-docs], [--no-amazon-docs]  # Include Amazon owned documents
      [--dsl-content], [--no-dsl-content]  # Convert JSON contents to DSL
                                           # Default: true

apply

Apply the documents

$ rezept help apply
Usage:
  rezept apply

Options:
      [--prefix=PREFIX]                    # The prefix of the documents (All documents are targeted by default)
      [--dry-run], [--no-dry-run]          # Dry run (Only output the difference)
  -f, [--file=FILE]                        # Configuration file
                                           # Default: Docfile
      [--color], [--no-color]              # Disable colorize
                                           # Default: true
      [--amazon-docs], [--no-amazon-docs]  # Include Amazon owned documents
      [--dsl-content], [--no-dsl-content]  # Convert JSON contents to DSL
                                           # Default: true

convert

Convert the documents to the other format

$ rezept help convert
Usage:
  rezept convert -n, --name=NAME -t, --type=TYPE

Options:
  -n, --name=NAME                          # Name of document
  -t, --type=TYPE                          # Type of document (Command|Automation)
      [--format=FORMAT]                    # Output format (json|ruby)
  -o, [--output=OUTPUT]                    # Output filename (path)
  -f, [--file=FILE]                        # Configuration file
                                           # Default: Docfile
      [--color], [--no-color]              # Disable colorize
                                           # Default: true
      [--amazon-docs], [--no-amazon-docs]  # Include Amazon owned documents
      [--dsl-content], [--no-dsl-content]  # Convert JSON contents to DSL
                                           # Default: true

export

Export the documents

$ rezept help export
Usage:
  rezept export

Options:
      [--write], [--no-write]              # Write the documents to the file
      [--split], [--no-split]              # Split file by the documents
  -f, [--file=FILE]                        # Configuration file
                                           # Default: Docfile
      [--color], [--no-color]              # Disable colorize
                                           # Default: true
      [--amazon-docs], [--no-amazon-docs]  # Include Amazon owned documents
      [--dsl-content], [--no-dsl-content]  # Convert JSON contents to DSL
                                           # Default: true

run_command

Run the commands

$ rezept help run_command
Usage:
  rezept run_command -d, --document=DOCUMENT

Options:
  -d, --document=DOCUMENT                    # The name of the document
  -i, [--instance-ids=one two three]         # EC2 Instance IDs
  -t, [--tags=key:value]                     # EC2 Instance tags
  -I, [--inventory=INVENTORY]                # The name of the inventory type
  -C, [--conditions=one two three]           # The conditions to search inventories (ex. "Foo = Bar", "Buz > 1.0")
  -p, [--parameters=key:value]               # Parameters for the document
      [--dry-run], [--no-dry-run]            # Dry run (Only output the targets)
      [--wait-entries], [--no-wait-entries]  # Wait for entries of managed instances
      [--wait-results], [--no-wait-results]  # Wait and check for all results
  -f, [--file=FILE]                          # Configuration file
                                             # Default: Docfile
      [--color], [--no-color]                # Disable colorize
                                             # Default: true
      [--amazon-docs], [--no-amazon-docs]    # Include Amazon owned documents
      [--dsl-content], [--no-dsl-content]    # Convert JSON contents to DSL
                                             # Default: true

• If you specify multiple values to tags and parameters, separate them with commas(,).
• When you use the wait option, the exit code will be 0 if the commands succeed on the all instances, else it will be 1.

put_inventory

Put the inventory

$ rezept help put_inventory
Usage:
  rezept put_inventory -c, --content=key:value -i, --instance-id=INSTANCE_ID -n, --name=NAME

Options:
  -n, --name=NAME                          # The name of the inventory type
  -i, --instance-id=INSTANCE_ID            # EC2 Instance ID
  -c, --content=key:value                  # Parameters for the document
      [--schema-version=SCHEMA_VERSION]    # The schema version for the inventory item
                                           # Default: 1.0
  -f, [--file=FILE]                        # Configuration file
                                           # Default: Docfile
      [--color], [--no-color]              # Disable colorize
                                           # Default: true
      [--amazon-docs], [--no-amazon-docs]  # Include Amazon owned documents
      [--dsl-content], [--no-dsl-content]  # Convert JSON contents to DSL
                                           # Default: true

Advanced methods

Script styled commands (__script)

• Docfile

Command "My-RunShellScript" do
  account_ids []
  content do
    __dsl do
      schemaVersion "2.0"
      description "Run a shell script."
      mainSteps do |*|
        action "aws:runShellScript"
        name "runShellScript"
        inputs do
          runCommand __script(<<-'EOS')
#! /bin/bash
echo 1
echo 2
echo 3
EOS
        end
      end
    end
  end
end

• Result

$ rezept convert -n My-RunShellScript -t Command --format json
Document: 'My-RunShellScript'
Document Type: 'Command'
{
  "schemaVersion": "2.0",
  "description": "Run a shell script",
  "mainSteps": [
    {
      "action": "aws:runShellScript",
      "name": "runShellScript",
      "inputs": {
        "runCommand": [
          "#! /bin/bash",
          "echo 1",
          "echo 2",
          "echo 3"
        ]
      }
    }
  ]
}

Commands from the other script file (__script_file)

• Docfile

Command "My-RunShellScript" do
  account_ids []
  content do
    __dsl do
      schemaVersion "2.0"
      description "my Run a shell script or specify the path to a script to run."
      mainSteps do |*|
        action "aws:runShellScript"
        name "runShellScript"
        inputs do
          runCommand __script_file("script.sh")
        end
      end
    end
  end
end

• script.sh

#! /bin/bash
echo 1
echo 2
echo 3

• Result

$ rezept convert -n My-RunShellScript -t Command --format json
Document: 'My-RunShellScript'
Document Type: 'Command'
{
  "schemaVersion": "2.0",
  "description": "Run a shell script",
  "mainSteps": [
    {
      "action": "aws:runShellScript",
      "name": "runShellScript",
      "inputs": {
        "runCommand": [
          "#! /bin/bash",
          "echo 1",
          "echo 2",
          "echo 3"
        ]
      }
    }
  ]
}

Templating

• Docfile

template "runShellScriptTemplate" do
  content do
    __dsl do
      schemaVersion "2.0"
      description "Run a shell script"
      mainSteps do |*|
        action "aws:runShellScript"
        name "runShellScript"
        inputs do
          runCommand __script(context.commands)
        end
      end
    end
  end
end

Command "My-RunShellScript" do
  account_ids []
  include_template "runShellScriptTemplate", commands: "echo 1"
end

• Result

$ rezept convert -n My-RunShellScript -t Command --format json
Document: 'My-RunShellScript'
Document Type: 'Command'
{
  "schemaVersion": "2.0",
  "description": "Run a shell script",
  "mainSteps": [
    {
      "action": "aws:runShellScript",
      "name": "runShellScript",
      "inputs": {
        "runCommand": [
          "echo 1"
        ]
      }
    }
  ]
}

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.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/serverworks/rezept. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.