ironfan 4.3.4 → 4.4.0

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# v4.4.0: @nickmarden adds ELB support, broader spec coverage
+* Security groups: removing ensured field (never set, causing bug), making selection use VPC if applicable
+* Spec coverage for full cluster launch process
+* IAMServerCertificate and ElasticLoadBalancer support for EC2
+* Support for cluster-wide resource aggregation
+* Fixes a bug that occurs when you fat-finger a flavor name
+
 # v4.3.4:
 * whoops. actually want attributes, not compact_attributes (#191)
 

data/ELB.md

@@ -0,0 +1,121 @@
+# Managing Elastic Load Balancers with Ironfan
+
+## Example
+
+    Ironfan.cluster "sparky" do
+
+      cloud(:ec2) do
+        # This certificate can be defined at a cluster or facet level.
+        # However, the last call wins if the same attribute is defined
+        # in more than one context.
+        iam_server_certificate "snake-oil" do
+          certificate       IO.read('snakeoil.crt')
+          private_key       IO.read('snakeoil.key')
+          certificate_chain IO.read('snakeoil.crt.bundle') # optional
+        end
+      end
+
+      facet :web do
+        instances 2
+        cloud(:ec2) do
+
+          elastic_load_balancer "sparky-elb" do
+            map_port('HTTP',   80, 'HTTP', 81)
+
+            # This SSL listener uses the certificate defined above
+            map_port('HTTPS', 443, 'HTTP', 81, 'snake-oil')
+
+            # Applies to all HTTPS/SSL listeners
+            disallowed_ciphers(%w[ RC4-SHA ])
+
+            # Health check that is made against ALL running instances
+            health_check do
+              ping_protocol       'HTTP'
+              ping_port           82
+              ping_path           '/healthcheck'
+              timeout             4
+              interval            10
+              unhealthy_threshold 3
+              healthy_threshold   2
+            end
+          end
+
+        end
+      end
+    end
+
+## Uploading your certificate
+
+There are two ways to supply your certificate to Ironfan. The first is to make the certificate, private key, and (optionally) certificate chain data readable by Ruby code in your cluster file.
+
+    iam_server_certificate "snake-oil" do
+      certificate       IO.read('snakeoil.crt')
+      private_key       IO.read('snakeoil.key')
+      certificate_chain IO.read('snakeoil.crt.bundle') # optional
+    end
+
+Having your server certificates persistently available in your ironfan-homebase might not be optimal, so you can simply specify the ARN of the existing IAM server certificate:
+
+    iam_server_certificate "snake-oil" do
+      arn 'arn:aws:iam::782698214375:server-certificate/ironfan-sparky-snake-oil'
+    end
+
+## When are Certificates and ELBs updated?
+
+Your server certificates and ELBs are only relevant when there are server instances present to service them. Therefore, the following logic is applied to decide when to synchronize or update your certificate/ELB configuration:
+
+### bootstrap, kill, launch, start, stop, sync
+
+When one of these `knife cluster` actions finishes, the Ironfan code will examine the up-to-date list of running servers to see if there are any ELBs that are now needed, or which are no longer needed. In support of these feature, any required certificate uploads, health check modifications, SSL policy updates, or listener modifications will be performed as well.
+
+If an ELB is no longer needed, it will be destroyed **but any corresponding certificates will not be destroyed**. This is a convenience for system administrators who want to load their sensitive/precious certificates into AWS just once, and is intended to be used in conjunction with the `iam_server_certificate.arn` attribute.
+
+(To get a list of existing ARNs, try the [IAM Command Line Toolkit](http://aws.amazon.com/developertools/AWS-Identity-and-Access-Management/4143) provided by AWS.)
+
+### kick, list, proxy, pry, show, ssh
+
+These `knife cluster` commands are not associated with updates of the Chef or IAAS configurations of your server instances, so no certificate or ELB modifications occur after these commands complete.
+
+## SSL policy
+
+The SSL policy control in Ironfan is very rudimentary. You may control which ciphers are explicitly disallowed as follows
+
+    elastic_load_balancer "sparky-elb" do
+      ...
+      disallowed_ciphers(%w[ RC4-SHA ])
+      ...
+    end
+
+Note that the default behavior is to disallow ciphers that are hypothetically vulnerable to the [BEAST attack](http://vnhacker.blogspot.com/2011/09/beast.html). You probably don't want or need to change it.
+
+## How do port mappings work?
+
+A port mapping is a mapping between a TCP port on the ELB and a TCP port on your instance. A request arriving at _external_port_number_ on your ELB will be negotiated using the _external_protocol_, and will be forwarded to the _internal_port_ on one of your instances using _internal_protocol_.
+
+If _external_protocol_ is 'HTTPS' and _internal_protocol_ is 'HTTP' (which is referred to as "SSL termination" at the ELB), you'll probably want to know that in your server code. ELBs set the header [X-Forwarded-Proto](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields) to let you know what protocol was used to connect to the ELB. Awareness of that header in your server allows you to aboid redirect loops if, for example, your code insists that clients connect over HTTPS.
+
+The format of the map_port call is as follows:
+
+    map_port(external_protocol, external_port_number, internal_protocol, internal_port_number [, certificate])
+
+You'll need a certificate if the _external\_protocol_ is 'HTTPS' or 'SSL'. It will be ignored otherwise.
+
+Your one-and-only SSL policy (probably the BEAST-defeating default) will be applied to all port mappings with certificates.
+
+## Other policies
+
+The Ironfan ELB code does not support other types of listener policies. Please contact me using the information below if you need other types of policy support.
+
+## VPC support
+
+There is no explicit VPC support in this code. If you need to use Ironfan-based ELBs in a VPC context and find that this code doesn't give you what you need, please submit an issue or, better yet, a pull request.
+
+## Spanning facets
+
+An ELB **can** be declared at the cluster level rather than the facet level, but that's a weird thing to do. But don't let me tell you not to be weird!
+
+Note that since each ELB has only one health check, it would need to be the case that your servers in each facet could respond to the same health check request. If they can, they should probably be members of the same facet.
+
+# Contact me
+
+This feature was initially created by [Nick Marden](https://github.com/nickmarden). I'd love your feedback and suggestions.

data/Gemfile

@@ -29,4 +29,5 @@ group :test do
   gem 'guard-rspec'
   gem 'guard-yard'
   gem 'ruby_gntp'
+  gem 'ruby-debug19'
 end

data/Rakefile

@@ -72,6 +72,10 @@ RSpec::Core::RakeTask.new(:rcov) do |spec|
   spec.rcov_opts = %w[ --exclude .rvm --no-comments --text-summary ]
 end
 
+RSpec::Core::RakeTask.new(:integration) do |spec|
+  spec.pattern = 'spec/integration/**/*_spec.rb'
+end
+
 # ---------------------------------------------------------------------------
 #
 # Yard -- documentation

data/VERSION

@@ -1 +1 @@
-4.3.4
+4.4.0

data/ironfan.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "ironfan"
-  s.version = "4.3.4"
+  s.version = "4.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Infochimps"]
-  s.date = "2012-10-11"
+  s.date = "2012-10-22"
   s.description = "Ironfan allows you to orchestrate not just systems but clusters of machines. It includes a powerful layer on top of knife and a collection of cloud cookbooks."
   s.email = "coders@infochimps.com"
   s.extra_rdoc_files = [
@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
     ".rspec",
     ".yardopts",
     "CHANGELOG.md",
+    "ELB.md",
     "Gemfile",
     "Guardfile",
     "LICENSE.md",
@@ -77,6 +78,8 @@ Gem::Specification.new do |s|
     "lib/ironfan/provider/ec2.rb",
     "lib/ironfan/provider/ec2/ebs_volume.rb",
     "lib/ironfan/provider/ec2/elastic_ip.rb",
+    "lib/ironfan/provider/ec2/elastic_load_balancer.rb",
+    "lib/ironfan/provider/ec2/iam_server_certificate.rb",
     "lib/ironfan/provider/ec2/keypair.rb",
     "lib/ironfan/provider/ec2/machine.rb",
     "lib/ironfan/provider/ec2/placement_group.rb",
@@ -84,11 +87,53 @@ Gem::Specification.new do |s|
     "lib/ironfan/provider/virtualbox.rb",
     "lib/ironfan/provider/virtualbox/machine.rb",
     "lib/ironfan/requirements.rb",
+    "notes/Home.md",
+    "notes/INSTALL-cloud_setup.md",
+    "notes/INSTALL.md",
+    "notes/Ironfan-Roadmap.md",
+    "notes/advanced-superpowers.md",
+    "notes/aws_servers.jpg",
+    "notes/aws_user_key.png",
+    "notes/cookbook-versioning.md",
+    "notes/core_concepts.md",
+    "notes/declaring_volumes.md",
+    "notes/design_notes-aspect_oriented_devops.md",
+    "notes/design_notes-ci_testing.md",
+    "notes/design_notes-cookbook_event_ordering.md",
+    "notes/design_notes-meta_discovery.md",
+    "notes/ec2-pricing_and_capacity.md",
+    "notes/ec2-pricing_and_capacity.numbers",
+    "notes/homebase-layout.txt",
+    "notes/knife-cluster-commands.md",
+    "notes/named-cloud-objects.md",
+    "notes/opscode_org_key.png",
+    "notes/opscode_user_key.png",
+    "notes/philosophy.md",
+    "notes/rake_tasks.md",
+    "notes/renamed-recipes.txt",
+    "notes/silverware.md",
+    "notes/style_guide.md",
+    "notes/tips_and_troubleshooting.md",
+    "notes/version-3_2.md",
+    "notes/walkthrough-hadoop.md",
+    "notes/walkthrough-web.md",
     "spec/chef/cluster_bootstrap_spec.rb",
+    "spec/fixtures/ec2/elb/snakeoil.crt",
+    "spec/fixtures/ec2/elb/snakeoil.key",
     "spec/fixtures/gunbai.rb",
     "spec/fixtures/gunbai_slice.json",
+    "spec/integration/minimal-chef-repo/chefignore",
+    "spec/integration/minimal-chef-repo/environments/_default.json",
+    "spec/integration/minimal-chef-repo/knife/credentials/knife-org.rb",
+    "spec/integration/minimal-chef-repo/knife/credentials/knife-user-ironfantester.rb",
+    "spec/integration/minimal-chef-repo/knife/knife.rb",
+    "spec/integration/minimal-chef-repo/roles/systemwide.rb",
+    "spec/integration/spec/elb_build_spec.rb",
+    "spec/integration/spec_helper.rb",
+    "spec/integration/spec_helper/launch_cluster.rb",
     "spec/ironfan/cluster_spec.rb",
     "spec/ironfan/ec2/cloud_provider_spec.rb",
+    "spec/ironfan/ec2/elb_spec.rb",
     "spec/ironfan/ec2/security_group_spec.rb",
     "spec/spec_helper.rb",
     "spec/spec_helper/dummy_chef.rb",
@@ -100,7 +145,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.24"
   s.summary = "Ironfan allows you to orchestrate not just systems but clusters of machines. It includes a powerful layer on top of knife and a collection of cloud cookbooks."
-  s.test_files = ["spec/spec_helper/dummy_chef.rb", "spec/ironfan/cluster_spec.rb", "spec/ironfan/ec2/cloud_provider_spec.rb", "spec/ironfan/ec2/security_group_spec.rb", "spec/chef/cluster_bootstrap_spec.rb", "spec/fixtures/gunbai_slice.json", "spec/fixtures/gunbai.rb", "spec/spec_helper.rb", "spec/test_config.rb"]
+  s.test_files = ["spec/spec_helper/dummy_chef.rb", "spec/integration/spec_helper/launch_cluster.rb", "spec/integration/minimal-chef-repo/roles/systemwide.rb", "spec/integration/minimal-chef-repo/environments/_default.json", "spec/integration/minimal-chef-repo/chefignore", "spec/integration/minimal-chef-repo/knife/knife.rb", "spec/integration/minimal-chef-repo/knife/credentials/knife-user-ironfantester.rb", "spec/integration/minimal-chef-repo/knife/credentials/knife-org.rb", "spec/integration/spec/elb_build_spec.rb", "spec/integration/spec_helper.rb", "spec/ironfan/cluster_spec.rb", "spec/ironfan/ec2/cloud_provider_spec.rb", "spec/ironfan/ec2/elb_spec.rb", "spec/ironfan/ec2/security_group_spec.rb", "spec/chef/cluster_bootstrap_spec.rb", "spec/fixtures/gunbai_slice.json", "spec/fixtures/ec2/elb/snakeoil.key", "spec/fixtures/ec2/elb/snakeoil.crt", "spec/fixtures/gunbai.rb", "spec/spec_helper.rb", "spec/test_config.rb"]
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

data/lib/chef/knife/cluster_launch.rb

@@ -88,6 +88,11 @@ class Chef
           perform_after_launch_tasks(computer)
         end
 
+        if healthy?
+          ui.info "Applying aggregations:"
+          all_computers(*@name_args).aggregate
+        end
+
         display(target)
       end
 

data/lib/chef/knife/cluster_proxy.rb

@@ -119,9 +119,9 @@ class Chef
 }\n}
       end
 
-
-
-
+      def aggregates?
+        false
+      end
     end
   end
 end

data/lib/chef/knife/cluster_sync.rb

@@ -64,6 +64,10 @@ class Chef
         else Chef::Log.debug("Skipping sync to cloud") ; end
       end
 
+      def aggregates_on_noop?
+        true
+      end
+
     end
   end
 end

data/lib/chef/knife/ironfan_knife_common.rb

@@ -31,12 +31,7 @@ module Ironfan
     #
     # @return [Ironfan::ServerSlice] the requested slice
     def get_slice(slice_string, *args)
-      if not args.empty?
-        slice_string = [slice_string, args].flatten.join("-")
-        ui.info("")
-        ui.warn("Please specify server slices joined by dashes and not separate args:\n\n  knife cluster #{sub_command} #{slice_string}\n\n")
-      end
-      cluster_name, facet_name, slice_indexes = slice_string.split(/[\s\-]/, 3)
+      cluster_name, facet_name, slice_indexes = pick_apart(slice_string, *args)
       desc = predicate_str(cluster_name, facet_name, slice_indexes)
       #
       ui.info("Inventorying servers in #{desc}")
@@ -47,6 +42,22 @@ module Ironfan
       computers.slice(facet_name, slice_indexes)
     end
 
+    def all_computers(slice_string, *args)
+      cluster_name, facet_name, slice_indexes = pick_apart(slice_string, *args)
+      computers = broker.discover! Ironfan.load_cluster(cluster_name)
+      ui.info("Loaded information for #{computers.size} computer(s) in cluster #{cluster_name}")
+      computers
+    end
+
+    def pick_apart(slice_string, *args)
+      if not args.empty?
+        slice_string = [slice_string, args].flatten.join("-")
+        ui.info("")
+        ui.warn("Please specify server slices joined by dashes and not separate args:\n\n  knife cluster #{sub_command} #{slice_string}\n\n")
+      end
+      slice_string.split(/[\s\-]/, 3)
+    end
+
     def predicate_str(cluster_name, facet_name, slice_indexes)
       [ "#{ui.color(cluster_name, :bold)} cluster",
         (facet_name    ? "#{ui.color(facet_name, :bold)} facet"      : "#{ui.color("all", :bold)} facets"),

data/lib/chef/knife/ironfan_script.rb

@@ -44,26 +44,44 @@ module Ironfan
 
       target = get_relevant_slice(* @name_args)
 
-      die("No computers to #{sub_command}, exiting", 1) if target.empty?
+      unless target.empty?
+        ui.info(["\n",
+                 ui.color("Running #{sub_command}", :cyan),
+                 " on #{target.joined_names}..."].join())
+        unless config[:yes]
+          ui.info("")
+          confirm_execution(target)
+        end
+        #
+        perform_execution(target)
+      end
+
+      if healthy? and aggregates? and (aggregates_on_noop? or not target.empty?)
+        ui.info "Applying aggregations:"
+        all_computers(*@name_args).aggregate
+      end
 
-      ui.info(["\n",
-          ui.color("Running #{sub_command}", :cyan),
-          " on #{target.joined_names}..."].join())
-      unless config[:yes]
+      if target.empty?
+        ui.warn("No computers to #{sub_command}")
+      else
         ui.info("")
-        confirm_execution(target)
+        ui.info "Finished! Current state:"
+        display(target)
       end
       #
-      perform_execution(target)
-      ui.info("")
-      ui.info "Finished! Current state:"
-      display(target)
-      #
       exit_if_unhealthy!
     end
 
     def perform_execution(target)
       target.send(sub_command)
     end
+
+    def aggregates?
+      true
+    end
+
+    def aggregates_on_noop?
+      false
+    end
   end
 end

data/lib/ironfan.rb

@@ -148,8 +148,8 @@ module Ironfan
     ui.info("  #{"%-15s" % (name.to_s+":")}\t#{ui.color(desc.to_s, *style)}")
   end
 
-  def self.substep(name, desc)
-    step(name, "  - #{desc}", :gray) if verbosity >= 1
+  def self.substep(name, desc, color = :gray)
+    step(name, "  - #{desc}", color) if (verbosity >= 1 or color != :gray)
   end
 
   def self.verbosity

data/lib/ironfan/broker/computer.rb

@@ -293,11 +293,16 @@ module Ironfan
       end
 
       def validate
-        providers = values.map {|c| c.providers.values}.flatten
         computers = self
-
         values.each{|c|    c.validate }
-        providers.each{|p| p.validate computers }
+        values.map {|c| c.providers.values}.flatten.uniq.each {|p| p.validate computers }
+      end
+
+      def aggregate
+        computers = self
+        provider_keys = values.map {|c| c.chosen_providers({ :providers => :iaas})}.flatten.uniq
+        providers     = provider_keys.map { |pk| values.map { |c| c.providers[pk] } }.flatten.uniq
+        providers.each { |p| p.aggregate! computers }
       end
 
       #

data/lib/ironfan/dsl/ec2.rb

@@ -1,3 +1,5 @@
+require 'digest/md5'
+
 module Ironfan
   class Dsl
 
@@ -12,7 +14,9 @@ module Ironfan
       magic :bootstrap_distro,          String,         :default => ->{ image_info[:bootstrap_distro] }
       magic :chef_client_script,        String
       magic :default_availability_zone, String,         :default => ->{ availability_zones.first }
+      collection :elastic_load_balancers,  Ironfan::Dsl::Ec2::ElasticLoadBalancer, :key_method => :name
       magic :flavor,                    String,         :default => 't1.micro'
+      collection :iam_server_certificates, Ironfan::Dsl::Ec2::IamServerCertificate, :key_method => :name
       magic :image_id,                  String
       magic :image_name,                String
       magic :keypair,                   String
@@ -23,9 +27,9 @@ module Ironfan
       magic :provider,                  Whatever,       :default => Ironfan::Provider::Ec2
       magic :public_ip,                 String
       magic :region,                    String,         :default => ->{ default_region }
+      collection :security_groups,      Ironfan::Dsl::Ec2::SecurityGroup, :key_method => :name
       magic :ssh_user,                  String,         :default => ->{ image_info[:ssh_user] }
       magic :ssh_identity_dir,          String,         :default => ->{ Chef::Config.ec2_key_dir }
-      collection :security_groups,      Ironfan::Dsl::Ec2::SecurityGroup, :key_method => :name
       magic :subnet,                    String
       magic :validation_key,            String,         :default => ->{ IO.read(Chef::Config.validation_key) rescue '' }
       magic :vpc,                       String
@@ -63,7 +67,7 @@ module Ironfan
 
       def flavor_info
         if not Chef::Config[:ec2_flavor_info].has_key?(flavor)
-          ui.warn("Unknown machine image flavor '#{val}'")
+          ui.warn("Unknown machine image flavor '#{flavor}'")
           list_flavors
           return nil
         end
@@ -136,6 +140,133 @@ module Ironfan
         end
       end
 
+      class ElasticLoadBalancer
+
+        class HealthCheck < Ironfan::Dsl
+          magic :ping_protocol,         String,      :default => 'HTTP'
+          magic :ping_port,             Integer,     :default => 80
+          magic :ping_path,             String,      :default => '/'
+          magic :timeout,               Integer,     :default => 5
+          magic :interval,              Integer,     :default => 30
+          magic :unhealthy_threshold,   Integer,     :default => 2
+          magic :healthy_threshold,     Integer,     :default => 10
+
+          def target
+            if %w[ HTTP HTTPS ].include?(self.ping_protocol)
+              "#{self.ping_protocol}:#{self.ping_port}#{self.ping_path}"
+            else
+              "#{self.ping_protocol}:#{self.ping_port}"
+            end
+          end
+
+          def to_fog
+            health_check       = {
+              'HealthyThreshold'   => healthy_threshold,
+              'Timeout'            => timeout,
+              'UnhealthyThreshold' => unhealthy_threshold,
+              'Interval'           => interval,
+              'Target'             => target
+            }
+          end
+
+        end
+
+        # SSL ciphers susceptible to the BEAST attack
+        BEAST_VULNERABLE_CIPHERS = %w[
+          Protocol-SSLv2
+          ADH-AES128-SHA
+          ADH-AES256-SHA
+          ADH-CAMELLIA128-SHA
+          ADH-CAMELLIA256-SHA
+          ADH-DES-CBC-SHA
+          ADH-DES-CBC3-SHA
+          ADH-RC4-MD5
+          ADH-SEED-SHA
+          AES128-SHA
+          AES256-SHA
+          DES-CBC-MD5
+          DES-CBC-SHA
+          DES-CBC3-MD5
+          DES-CBC3-SHA
+          DHE-DSS-AES128-SHA
+          DHE-DSS-AES256-SHA
+          DHE-RSA-AES128-SHA
+          DHE-RSA-AES256-SHA
+          EDH-DSS-DES-CBC-SHA
+          EDH-DSS-DES-CBC3-SHA
+          EDH-RSA-DES-CBC-SHA
+          EDH-RSA-DES-CBC3-SHA
+          EXP-ADH-DES-CBC-SHA
+          EXP-ADH-RC4-MD5
+          EXP-DES-CBC-SHA
+          EXP-EDH-DSS-DES-CBC-SHA
+          EXP-EDH-RSA-DES-CBC-SHA
+          EXP-KRB5-DES-CBC-MD5
+          EXP-KRB5-DES-CBC-SHA
+          EXP-KRB5-RC2-CBC-MD5
+          EXP-KRB5-RC2-CBC-SHA
+          EXP-RC2-CBC-MD5
+          IDEA-CBC-SHA
+          KRB5-DES-CBC-MD5
+          KRB5-DES-CBC-SHA
+          KRB5-DES-CBC3-MD5
+          KRB5-DES-CBC3-SHA
+          PSK-3DES-EDE-CBC-SHA
+          PSK-AES128-CBC-SHA
+          PSK-AES256-CBC-SHA
+          RC2-CBC-MD5
+        ]
+
+        field  :name,               String
+        field  :port_mappings,      Array, :default => []
+        magic  :disallowed_ciphers, Array, :default => BEAST_VULNERABLE_CIPHERS
+        member :health_check,       HealthCheck
+
+        def map_port(load_balancer_protocol = 'HTTP', load_balancer_port = 80, internal_protocol = 'HTTP', internal_port = 80, iam_server_certificate = nil)
+          port_mappings << [ load_balancer_protocol, load_balancer_port, internal_protocol, internal_port, iam_server_certificate ]
+          port_mappings.compact!
+          port_mappings.uniq!
+        end
+
+        def ssl_policy_to_fog
+          result = Hash[ *disallowed_ciphers.collect { |c| [ c, false ] }.flatten ]
+          return {
+            :name       => Digest::MD5.hexdigest("#{disallowed_ciphers.sort.join('')}"),
+            :attributes => result,
+          }
+        end
+
+        def listeners_to_fog(cert_lookup)
+          port_mappings.map do |pm|
+            result = {
+              'Protocol'         => pm[0], # load_balancer_protocl
+              'LoadBalancerPort' => pm[1], # load_balancer_port
+              'InstanceProtocol' => pm[2], # internal_protocol
+              'InstancePort'     => pm[3], # internal_port
+            }
+            result['SSLCertificateId'] = cert_lookup[pm[4]] if pm[4]
+            result
+          end
+        end
+
+      end
+
+      # Although it is unreasonable to talk about an IAM Server Certificate object
+      # without a certificate or private_key field value, we also allow users to
+      # simply specify the arn of an existing IAM Server Certificate so that their
+      # web server certificate is not required to be present in their recipes repo,
+      # for security purposes. In that case the :arn field would be non-nil while
+      # the :certificate and :private_key fields would be nil, which hints to the
+      # EC2 Provider code that it should attempt to validate the existence of the
+      # IAM Server Certificate in the EC2 cloud rather than trying to create it.
+      class IamServerCertificate < Ironfan::Dsl
+        field  :name,                   String
+        magic  :arn,                    String,                         :default => nil
+        magic  :certificate,            String,                         :default => nil # Actually a PEM encoding
+        magic  :private_key,            String,                         :default => nil # Actually a PEM encoding
+        magic  :certificate_chain,      String,                         :default => nil # Actually a PEM encoding
+      end
+
     end
 
   end