stackup 1.4.5 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d963de325ab9c50ad23fb0962aa34704dd002b48e9379d4437246d4298b763aa
-  data.tar.gz: da6d00022a700f509867f655ef64c1787f84c2091159f8cf9dc552d2682698eb
+  metadata.gz: 60e50e255335b7924e71a6fed889c946c3b182c2b95277056f88e2e420915f79
+  data.tar.gz: 816b9a71283680668fe9d3cf35c54a3a1a2516a68f0251a1771e4bba17e2cce2
 SHA512:
-  metadata.gz: 619cfb540220d6b16477cb99ef8f04b71fd9470de38a6b55a2ed5d9ff25a0feaeb4f3a5491df3800bf32b8399aedb9a972576c995c2760cf22c1362358e1dfd0
-  data.tar.gz: ad748effec9ed41253d99b1789ceddd6841c948d32658186c99fd6871e2814e320d493a465a2ba0122b012f013dec117019fb994a7c2c667f741b2e822f1075d
+  metadata.gz: be56a2ae96045ace217de36cd7f82592eb2588178b314f8d68d51e6b6d16a1e66c60557e78fa5f524cb710aa42f0d64372629fe4d6b9aad65c3ddec11fe051f4
+  data.tar.gz: 79974fadb7ac89a76a92fa424c4cc2ef63deeec8cfd55b6eda352e965ecd84e832322eddafaaf9eb57fd3640c3744646a484954664f15cfa9bbfeda4b0eb03c8

data/CHANGES.md

@@ -1,5 +1,25 @@
 # CHANGES
 
+## 1.7.0 (2020-11-25)
+
+* Feature: --no-fail-on-empty-change-set
+
+## 1.6.0 (2020-11-19)
+
+* Feature: Support --service-role-arn on "change-set create"
+
+## 1.5.1 (2020-11-16)
+
+* Fix: Recognise that template is in S3 when URL is formatted like `s3.REGION.amazonaws.com`
+
+## 1.5.0 (2020-04-21)
+
+* Feature: --preserve-template-formatting
+
+## 1.4.6 (2019-12-09)
+
+* Fix: Don't error out when receiving tags in AWS style (array of hashes) from YAML or JSON file
+
 ## 1.4.5 (2019-10-03)
 
 * Fix: Tags in RakeTasks

data/README.md

@@ -78,10 +78,12 @@ For more details on usage, see
 
 ### Specifying parameters
 
-Stack parameters can be be read from a file, e.g.
+Stack parameters can be read from a file, e.g.
 
     $ stackup myapp-test up -t template.json -p parameters.json
 
+These files can be either JSON or YAML format, see [YAML support](#yaml-support) for more information.
+
 Parameters can be specified as simple key-value pairs:
 
 ```json
@@ -116,6 +118,22 @@ Or, you can specify one or more override parameters on the command-line, using `
       -o IndexDoc=index-override.html
       -o ContentDoc=content-override.html
 
+### Specifying tags
+
+Stack tags can be read from a file, e.g.
+
+    $ stackup myapp-test up -t template.json --tags tags.json
+
+These files can be either JSON or YAML format, see [YAML support](#yaml-support) for more information.
+
+Tags are specified as simple key-value pairs:
+
+```json
+{
+  "environment": "dev"
+}
+```
+
 ### Acknowledging Capabilities
 
 CloudFormation requires that some stacks explicitly acknowledge certain capabilities before creation. This helps to prevent the creation of stacks with unintended privileges.
@@ -137,7 +155,11 @@ This is to provide backwards compatibility with previously deployed stacks and m
 
 `stackup` supports input files (template, parameters, tags) in YAML format, as well as JSON.
 
-It also supports the [abbreviated YAML syntax for Cloudformation functions](https://aws.amazon.com/blogs/aws/aws-cloudformation-update-yaml-cross-stack-references-simplified-substitution/), though unlike the [AWS CLI](https://aws.amazon.com/cli/), Stackup normalises YAML input to JSON before invoking CloudFormation APIs.
+It also supports the [abbreviated YAML syntax for Cloudformation functions](https://aws.amazon.com/blogs/aws/aws-cloudformation-update-yaml-cross-stack-references-simplified-substitution/), though unlike the [AWS CLI](https://aws.amazon.com/cli/), Stackup (by default) normalises YAML input to JSON before invoking CloudFormation APIs.
+
+If you don't want normalisation of the YAML input to JSON, then use the `--preserve-template-formatting` flag to the `up` or `change-set create` commands.
+
+Note: normalisation of S3 / HTTP URL stored templates is never done, as Cloudformation collects these directly.
 
 ### AWS credentials
 
@@ -194,6 +216,10 @@ You can also create, list, inspect, apply and delete [change sets](http://docs.a
 
 The change-set name defaults to "pending", but can be overridden using `--name`.
 
+The `change-set create` subcommand, like the `up` command, supports `--service-role-arn` to specify a service role.
+
+It is impossible to create a change set with no changes. By default, stackup will only return successfully if a change set was actually created, and will otherwise fail. If the `--no-fail-on-empty-change-set` option is provided, stackup will return successfully if a change set was created _or_ if no change set was created because no changes were needed.
+
 ## Programmatic usage
 
 Get a handle to a `Stack` object as follows:
@@ -278,18 +304,24 @@ This policy grants the principal all actions required by `stackup up` for any cl
 }
 ```
 
-## Releasing
+## Development
+
+### Running tests
+
+`auto/test` will run the tests in a Docker container.
+
+### Releasing
 
-The release process will push tags to GitHub, push the gem to rubygems and push the docker image to DockerHub.
+Releasing is done manually, not by CI. The release process will push tags to GitHub, push the gem to rubygems and push the docker image to DockerHub.
 
 Prerequisites:
 
-* logged into dockerhub via `docker login`. Your user must have permission to push to `realestate/stackup`
-* logged into rubygems via `gem push`. Your user must have permission to push to the `stackup` gem.
+* You must be logged into docker hub via `docker login`. Your user must have permission to push to `realestate/stackup`
+* You must have a rubygems account with permission to push to the `stackup` gem. (`auto/release` will ask for your username and password)
+* You must have cloned this repo via HTTPS and have a github account with permission to push. (`auto/release` will ask for your username and a GitHub personal access token)
 
 To release:
 
 ```
-bundle install
 auto/release
 ```

data/bin/stackup

@@ -2,542 +2,9 @@
 
 $LOAD_PATH << File.expand_path("../lib", __dir__)
 
-require "clamp"
-require "console_logger"
-require "multi_json"
-require "securerandom"
-require "stackup"
-require "stackup/differ"
-require "stackup/source"
-require "stackup/version"
-require "stackup/yaml"
+require "stackup/main_command"
 
 $stdout.sync = true
 $stderr.sync = true
 
-Clamp do
-
-  option ["-L", "--list"], :flag, "list stacks" do
-    list_stacks
-    exit 0
-  end
-
-  option ["-Y", "--yaml"], :flag, "output data in YAML format"
-
-  option ["--region"], "REGION", "set region" do |arg|
-    raise ArgumentError, "#{arg.inspect} doesn't look like a region" unless arg =~ /^[a-z]{2}-[a-z]+-\d$/
-
-    arg
-  end
-
-  option ["--with-role"], "ROLE_ARN", "assume this role",
-         :attribute_name => :role_arn
-
-  option ["--retry-limit"], "N", "maximum number of retries for API calls",
-         :environment_variable => "AWS_API_RETRY_LIMIT" do |arg|
-    Integer(arg)
-  end
-
-  option ["--[no-]wait"], :flag, "wait for stack updates to complete",
-         :default => true
-
-  option ["--wait-poll-interval"], "N", "polling interval while waiting for updates",
-         :default => 5, &method(:Integer)
-
-  option "--debug", :flag, "enable debugging"
-
-  option ["--version"], :flag, "display version" do
-    puts "stackup v#{Stackup::VERSION}"
-    exit 0
-  end
-
-  parameter "NAME", "Name of stack", :attribute_name => :stack_name
-
-  def run(arguments)
-    super(arguments)
-  rescue Stackup::Source::ReadError => e
-    signal_error e.message
-  rescue Stackup::ServiceError => e
-    signal_error e.message
-  rescue Aws::Errors::MissingCredentialsError
-    signal_error "no credentials provided"
-  rescue Aws::Errors::ServiceError => e
-    signal_error e.message
-  end
-
-  private
-
-  def logger
-    @logger ||= ConsoleLogger.new($stdout, debug?)
-  end
-
-  def format_data(data)
-    if yaml?
-      YAML.dump(data)
-    else
-      MultiJson.dump(data, :pretty => true)
-    end
-  end
-
-  def display_data(data)
-    puts format_data(data)
-  end
-
-  def role_arn=(arg)
-    raise ArgumentError, "#{arg.inspect} doesn't look like a role ARN" unless arg =~ %r{^arn:aws:iam::\d+:role/}
-
-    @role_arn = arg
-  end
-
-  def stackup
-    Stackup(aws_config)
-  end
-
-  def base_aws_config
-    {
-      :log_level => :debug,
-      :logger => logger,
-      :region => region,
-      :retry_limit => retry_limit
-    }.reject { |_k, v| v.nil? }
-  end
-
-  def aws_config
-    return base_aws_config unless role_arn
-
-    assumed_credentials = Aws::AssumeRoleCredentials.new(
-      :client => Aws::STS::Client.new(base_aws_config),
-      :role_arn => role_arn,
-      :role_session_name => "stackup-#{SecureRandom.hex(8)}"
-    )
-    base_aws_config.merge(:credentials => assumed_credentials)
-  end
-
-  def stack
-    stackup.stack(stack_name, :wait => wait?, :wait_poll_interval => wait_poll_interval)
-  end
-
-  def list_stacks
-    stackup.stack_names.each do |name|
-      puts name
-    end
-  end
-
-  def report_change
-    final_status = yield
-    puts final_status unless final_status.nil?
-  end
-
-  subcommand "status", "Print stack status." do
-
-    def execute
-      puts stack.status
-    end
-
-  end
-
-  module HasParameters
-
-    extend Clamp::Option::Declaration
-
-    option ["-p", "--parameters"], "FILE", "parameters file (last wins)",
-           :multivalued => true,
-           :attribute_name => :parameter_sources,
-           &Stackup::Source.method(:new)
-
-    option ["-o", "--override"], "PARAM=VALUE", "parameter overrides",
-           :multivalued => true,
-           :attribute_name => :override_list
-
-    private
-
-    def parameters
-      parameters_from_files.merge(parameter_overrides)
-    end
-
-    def parameters_from_files
-      parameter_sources.map do |src|
-        Stackup::Parameters.new(src.data).to_hash
-      end.inject({}, :merge)
-    end
-
-    def parameter_overrides
-      {}.tap do |result|
-        override_list.each do |override|
-          key, value = override.split("=", 2)
-          result[key] = value
-        end
-      end
-    end
-
-  end
-
-  subcommand "up", "Create/update the stack." do
-
-    option ["-t", "--template"], "FILE", "template source",
-           :attribute_name => :template_source,
-           &Stackup::Source.method(:new)
-
-    option ["-T", "--use-previous-template"], :flag,
-           "reuse the existing template"
-
-    include HasParameters
-
-    option "--tags", "FILE", "stack tags file",
-           :attribute_name => :tag_source,
-           &Stackup::Source.method(:new)
-
-    option "--policy", "FILE", "stack policy file",
-           :attribute_name => :policy_source,
-           &Stackup::Source.method(:new)
-
-    option "--service-role-arn", "SERVICE_ROLE_ARN", "cloudformation service role ARN" do |arg|
-      raise ArgumentError, "#{arg.inspect} doesn't look like a role ARN" unless arg =~ %r{^arn:aws:iam::\d+:role/}
-
-      arg
-    end
-
-    option "--on-failure", "ACTION",
-           "when stack creation fails: DO_NOTHING, ROLLBACK, or DELETE",
-           :default => "ROLLBACK"
-
-    option "--capability", "CAPABILITY", "cloudformation capability",
-           :multivalued => true, :default => ["CAPABILITY_NAMED_IAM"]
-
-    def execute
-      unless template_source || use_previous_template?
-        signal_usage_error "Specify either --template or --use-previous-template"
-      end
-      options = {}
-      if template_source
-        if template_source.s3?
-          options[:template_url] = template_source.location
-        else
-          options[:template] = template_source.data
-        end
-      end
-      options[:on_failure] = on_failure
-      options[:parameters] = parameters
-      options[:tags] = tag_source.data if tag_source
-      if policy_source
-        if policy_source.s3?
-          options[:stack_policy_url] = policy_source.location
-        else
-          options[:stack_policy] = policy_source.data
-        end
-      end
-      options[:role_arn] = service_role_arn if service_role_arn
-      options[:use_previous_template] = use_previous_template?
-      options[:capabilities] = capability_list
-      report_change do
-        stack.create_or_update(options)
-      end
-    end
-
-  end
-
-  subcommand ["change-sets"], "List change-sets." do
-
-    def execute
-      stack.change_set_summaries.each do |change_set|
-        puts [
-          pad(change_set.change_set_name, 36),
-          pad(change_set.status, 20),
-          pad(change_set.execution_status, 24)
-        ].join("  ")
-      end
-    end
-
-    private
-
-    def pad(s, width)
-      (s || "").ljust(width)
-    end
-
-  end
-
-  subcommand ["change-set"], "Change-set operations." do
-
-    option "--name", "NAME", "Name of change-set",
-           :attribute_name => :change_set_name,
-           :default => "pending"
-
-    subcommand "create", "Create a change-set." do
-
-      option ["-d", "--description"], "DESC",
-             "Change-set description"
-
-      option ["-t", "--template"], "FILE", "template source",
-             :attribute_name => :template_source,
-             &Stackup::Source.method(:new)
-
-      option ["-T", "--use-previous-template"], :flag,
-             "reuse the existing template"
-
-      option ["--force"], :flag,
-             "replace existing change-set of the same name"
-
-      include HasParameters
-
-      option "--tags", "FILE", "stack tags file",
-             :attribute_name => :tag_source,
-             &Stackup::Source.method(:new)
-
-      option "--capability", "CAPABILITY", "cloudformation capability",
-             :multivalued => true, :default => ["CAPABILITY_NAMED_IAM"]
-
-      def execute
-        unless template_source || use_previous_template?
-          signal_usage_error "Specify either --template or --use-previous-template"
-        end
-        options = {}
-        if template_source
-          if template_source.s3?
-            options[:template_url] = template_source.location
-          else
-            options[:template] = template_source.data
-          end
-        end
-        options[:parameters] = parameters
-        options[:description] = description if description
-        options[:tags] = tag_source.data if tag_source
-        options[:use_previous_template] = use_previous_template?
-        options[:force] = force?
-        options[:capabilities] = capability_list
-        report_change do
-          change_set.create(options)
-        end
-      end
-
-    end
-
-    subcommand "changes", "Describe the change-set." do
-
-      def execute
-        display_data(change_set.describe.changes.map(&:to_h))
-      end
-
-    end
-
-    subcommand "inspect", "Show full change-set details." do
-
-      def execute
-        display_data(change_set.describe.to_h)
-      end
-
-    end
-
-    subcommand ["apply", "execute"], "Apply the change-set." do
-
-      def execute
-        report_change do
-          change_set.execute
-        end
-      end
-
-    end
-
-    subcommand "delete", "Delete the change-set." do
-
-      def execute
-        report_change do
-          change_set.delete
-        end
-      end
-
-    end
-
-    private
-
-    def change_set
-      stack.change_set(change_set_name)
-    end
-
-  end
-
-  subcommand "diff", "Compare template/params to current stack." do
-
-    option "--diff-format", "FORMAT", "'text', 'color', or 'html'", :default => "color"
-
-    option ["-C", "--context-lines"], "LINES", "number of lines of context to show", :default => 10_000
-
-    option ["-t", "--template"], "FILE", "template source",
-           :attribute_name => :template_source,
-           &Stackup::Source.method(:new)
-
-    include HasParameters
-
-    option "--tags", "FILE", "stack tags file",
-           :attribute_name => :tag_source,
-           &Stackup::Source.method(:new)
-
-    def execute
-      current = {}
-      planned = {}
-      if template_source
-        current["Template"] = stack.template
-        planned["Template"] = template_source.data
-      end
-      unless parameter_sources.empty?
-        current["Parameters"] = existing_parameters.sort.to_h
-        planned["Parameters"] = new_parameters.sort.to_h
-      end
-      if tag_source
-        current["Tags"] = stack.tags.sort.to_h
-        planned["Tags"] = tag_source.data.sort.to_h
-      end
-      signal_usage_error "specify '--template' or '--parameters'" if planned.empty?
-      puts differ.diff(current, planned, context_lines)
-    end
-
-    private
-
-    def differ
-      Stackup::Differ.new(diff_format, &method(:format_data))
-    end
-
-    def existing_parameters
-      @existing_parameters ||= stack.parameters
-    end
-
-    def new_parameters
-      existing_parameters.merge(parameters)
-    end
-
-  end
-
-  subcommand ["down", "delete"], "Remove the stack." do
-
-    def execute
-      report_change do
-        stack.delete
-      end
-    end
-
-  end
-
-  subcommand "cancel-update", "Cancel the update in-progress." do
-
-    def execute
-      report_change do
-        stack.cancel_update
-      end
-    end
-
-  end
-
-  subcommand "wait", "Wait until stack is stable." do
-
-    def execute
-      puts stack.wait
-    end
-
-  end
-
-  subcommand "events", "List stack events." do
-
-    option ["-f", "--follow"], :flag, "follow new events"
-    option ["--data"], :flag, "display events as data"
-
-    def execute
-      stack.watch(false) do |watcher|
-        loop do
-          watcher.each_new_event do |event|
-            display_event(event)
-          end
-          break unless follow?
-
-          sleep 5
-        end
-      end
-    end
-
-    private
-
-    def display_event(e)
-      if data?
-        display_data(event_data(e))
-      else
-        puts event_summary(e)
-      end
-    end
-
-    def event_data(e)
-      {
-        "timestamp" => e.timestamp.localtime,
-        "logical_resource_id" => e.logical_resource_id,
-        "physical_resource_id" => e.physical_resource_id,
-        "resource_status" => e.resource_status,
-        "resource_status_reason" => e.resource_status_reason
-      }.reject { |_k, v| blank?(v) }
-    end
-
-    def blank?(v)
-      v.nil? || v.respond_to?(:empty?) && v.empty?
-    end
-
-    def event_summary(e)
-      summary = "[#{e.timestamp.localtime.iso8601}] #{e.logical_resource_id}"
-      summary += " - #{e.resource_status}"
-      summary += " - #{e.resource_status_reason}" if e.resource_status_reason
-      summary
-    end
-
-  end
-
-  subcommand "template", "Display stack template." do
-
-    def execute
-      display_data(stack.template)
-    end
-
-  end
-
-  subcommand ["parameters", "params"], "Display stack parameters." do
-
-    def execute
-      display_data(stack.parameters)
-    end
-
-  end
-
-  subcommand "tags", "Display stack tags." do
-
-    def execute
-      display_data(stack.tags)
-    end
-
-  end
-
-  subcommand "resources", "Display stack resources." do
-
-    def execute
-      display_data(stack.resources)
-    end
-
-  end
-
-  subcommand "outputs", "Display stack outputs." do
-
-    def execute
-      display_data(stack.outputs)
-    end
-
-  end
-
-  subcommand "inspect", "Display stack particulars." do
-
-    def execute
-      data = {
-        "Status" => stack.status,
-        "Parameters" => stack.parameters,
-        "Tags" => stack.tags,
-        "Resources" => stack.resources,
-        "Outputs" => stack.outputs
-      }
-      display_data(data)
-    end
-
-  end
-
-end
+Stackup::MainCommand.run