Class: AwsCftTools::Runbook Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/aws_cft_tools/runbook.rb,
lib/aws_cft_tools/runbook/report.rb

Overview

This class is abstract.

Subclass and override default_options, #options, and #run to implement a custom Runbook class.

This is the base class for runbooks.

A runbook is a command that can be accessed via the ‘aws-cft` script. A runbook is implemented as a subclass of this class.

Callbacks

The AwsCftTools::CLI uses callbacks to manage runbook-specific options and behaviors.

Helpers

The various helpers make managing logic flow much easier. Rather than having to be aware of how the different modes (verbose, change, noop) interplay and are configured, you can use the methods in this section to annotate the flow with your intent.

Defined Under Namespace

Classes: Report

Instance Attribute Summary collapse

Callbacks collapse

Helpers collapse

Instance Method Summary collapse

Constructor Details

#initialize(configuration = {}) ⇒ Object

Recognized configuration options depend on the runbook but include any options valid for AwsCftTools::Client.

Modes are selected by various configuration options:

:verbose

provide more narrative as the runbook executes

:noop

do nothing that could modify state

:change

do nothing that could permanently modify state, though some modifications are permitted

in order to examine what might change if permanent changes were made

Parameters:

  • configuration (Hash) (defaults to: {}) —

    Various options passed to the AwsCftTools::Client.



48
49
50
51
52
 
# File 'lib/aws_cft_tools/runbook.rb', line 48

def initialize(configuration = {})
  @options = configuration
  @client = AwsCftTools::Client.new(options)
  @stdout = $stdout
end

Instance Attribute Details

#client ⇒ Object (readonly)

The AwsCftTools::Client instance used by the runbook.



27
28
29
 
# File 'lib/aws_cft_tools/runbook.rb', line 27

def client
  @client
end

#options ⇒ Object (readonly)

The configuration options passed in to the runbook.



32
33
34
 
# File 'lib/aws_cft_tools/runbook.rb', line 32

def options
  @options
end

Instance Method Details

#_run ⇒ Object

An internal wrapper around #run to catch credential errors and print a useful message.



66
67
68
69
70
71
 
# File 'lib/aws_cft_tools/runbook.rb', line 66

def _run
  run
rescue Aws::Errors::MissingCredentialsError
  puts 'Unable to access AWS without valid credentials. Either define a default credential' \
  ' profile or use the -p option to specify an AWS credential profile.'
end

#checking(description = nil) { ... } ⇒ Object

Runs the given block when in check mode and not in noop mode. Outputs the description if the block is run.

Examples:

operation("considering the change" ) do
  checking("seeing what changes") { check_what_changes }
  doing("committing the change") { make_the_change }
end

Parameters:

  • description (String) (defaults to: nil) —

    an optional description of the check

Yields:

  • runs the block if in check mode and not in noop mode

Returns:

  • void



105
106
107
108
109
 
# File 'lib/aws_cft_tools/runbook.rb', line 105

def checking(description = nil)
  return if options[:noop] || !options[:check]
  output(description)
  yield if block_given?
end

#debug(note = nil) ⇒ Object

Prints the given content to stdout if running in debug mode. Debug statements are output without any capture when running multiple threads.

Parameters:

  • note (String) (defaults to: nil) —

    a debug note



147
148
149
150
 
# File 'lib/aws_cft_tools/runbook.rb', line 147

def debug(note = nil)
  return unless note && options[:debug]
  @stdout.puts "DEBUG\nDEBUG  " + note.split(/\n/).join("\nDEBUG  ") + "\nDEBUG"
end

#detail(description = nil) { ... } ⇒ Object

Prints out the given description and runs the block if in verbose mode. This is useful if the verbose narrative might be computationally expensive.

Examples:

detail do
  ... run some extensive processing to summarize stuff
  puts "The results are #{interesting}."
end

Parameters:

  • description (String) (defaults to: nil) —

    an optional verbose description

Yields:

  • runs the block if in verbose mode

Returns:

  • void



166
167
168
169
170
 
# File 'lib/aws_cft_tools/runbook.rb', line 166

def detail(description = nil)
  return unless options[:verbose]
  output(description)
  yield if block_given?
end

#doing(description = nil) { ... } ⇒ Object

Runs the given block when not in check or noop mode. Outputs the description if the block is run.

Examples:

operation("considering the change" ) do
  checking("seeing what changes") { check_what_changes }
  doing("committing the change") { make_the_change }
end

Parameters:

  • description (String) (defaults to: nil) —

    an optional description of the action

Yields:

  • runs the block if not in check or noop mode

Returns:

  • void



120
121
122
123
124
 
# File 'lib/aws_cft_tools/runbook.rb', line 120

def doing(description = nil)
  return if options[:noop] || options[:check]
  output(description)
  yield if block_given?
end

#narrative(description = nil) ⇒ Object

Prints out the given description to stdout. If in noop mode, “ (noop)” is appended.

Parameters:

  • description (String) (defaults to: nil) —

    an optional narrative string

Returns:

  • void



132
133
134
135
136
137
138
139
 
# File 'lib/aws_cft_tools/runbook.rb', line 132

def narrative(description = nil)
  return unless description
  if options[:noop]
    puts "#{description} (noop)"
  else
    puts description
  end
end

#operation(description = nil) { ... } ⇒ Object

Defines an operation that may or may not be narrated and that should not be run if in noop mode.

Examples:

operation("considering the change" ) do
  checking("seeing what changes") { check_what_changes }
  doing("committing the change") { make_the_change }
end

Parameters:

  • description (String) (defaults to: nil) —

    an optional description of the operation

Yields:

  • runs the block if not in noop mode

Returns:

  • void



88
89
90
91
92
93
 
# File 'lib/aws_cft_tools/runbook.rb', line 88

def operation(description = nil)
  narrative(description)
  return if options[:noop]

  yield if block_given?
end

#run ⇒ Object

A callback to implement the runbook actions. Nothing is passed in or returned.

Returns:

  • void



61
 
# File 'lib/aws_cft_tools/runbook.rb', line 61

def run; end