geoengineer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +13 -0
  3. data/README.md +476 -0
  4. data/bin/geo +7 -0
  5. data/lib/geoengineer.rb +29 -0
  6. data/lib/geoengineer/cli/geo_cli.rb +208 -0
  7. data/lib/geoengineer/cli/status_command.rb +101 -0
  8. data/lib/geoengineer/cli/terraform_commands.rb +59 -0
  9. data/lib/geoengineer/environment.rb +186 -0
  10. data/lib/geoengineer/output.rb +27 -0
  11. data/lib/geoengineer/project.rb +79 -0
  12. data/lib/geoengineer/resource.rb +200 -0
  13. data/lib/geoengineer/resources/aws_db_instance.rb +46 -0
  14. data/lib/geoengineer/resources/aws_db_parameter_group.rb +25 -0
  15. data/lib/geoengineer/resources/aws_elasticache_cluster.rb +50 -0
  16. data/lib/geoengineer/resources/aws_elasticache_parameter_group.rb +30 -0
  17. data/lib/geoengineer/resources/aws_elasticache_replication_group.rb +44 -0
  18. data/lib/geoengineer/resources/aws_elasticache_subnet_group.rb +25 -0
  19. data/lib/geoengineer/resources/aws_elasticsearch_domain.rb +35 -0
  20. data/lib/geoengineer/resources/aws_elb.rb +57 -0
  21. data/lib/geoengineer/resources/aws_iam_policy.rb +53 -0
  22. data/lib/geoengineer/resources/aws_iam_user.rb +42 -0
  23. data/lib/geoengineer/resources/aws_instance.rb +24 -0
  24. data/lib/geoengineer/resources/aws_proxy_protocol_policy.rb +39 -0
  25. data/lib/geoengineer/resources/aws_redshift_cluster.rb +23 -0
  26. data/lib/geoengineer/resources/aws_route53_record.rb +32 -0
  27. data/lib/geoengineer/resources/aws_route53_zone.rb +21 -0
  28. data/lib/geoengineer/resources/aws_s3_bucket.rb +54 -0
  29. data/lib/geoengineer/resources/aws_security_group.rb +53 -0
  30. data/lib/geoengineer/resources/aws_ses_receipt_rule.rb +38 -0
  31. data/lib/geoengineer/resources/aws_ses_receipt_rule_set.rb +28 -0
  32. data/lib/geoengineer/resources/aws_sns_topic.rb +28 -0
  33. data/lib/geoengineer/resources/aws_sns_topic_subscription.rb +42 -0
  34. data/lib/geoengineer/resources/aws_sqs_queue.rb +37 -0
  35. data/lib/geoengineer/resources/iam/statement.rb +43 -0
  36. data/lib/geoengineer/sub_resource.rb +35 -0
  37. data/lib/geoengineer/template.rb +28 -0
  38. data/lib/geoengineer/utils/aws_clients.rb +63 -0
  39. data/lib/geoengineer/utils/has_attributes.rb +97 -0
  40. data/lib/geoengineer/utils/has_lifecycle.rb +54 -0
  41. data/lib/geoengineer/utils/has_resources.rb +63 -0
  42. data/lib/geoengineer/utils/has_sub_resources.rb +43 -0
  43. data/lib/geoengineer/utils/has_validations.rb +57 -0
  44. data/lib/geoengineer/utils/null_object.rb +17 -0
  45. data/lib/geoengineer/version.rb +3 -0
  46. data/spec/environment_spec.rb +140 -0
  47. data/spec/output_spec.rb +3 -0
  48. data/spec/project_spec.rb +79 -0
  49. data/spec/resource_spec.rb +169 -0
  50. data/spec/resources/aws_db_instance_spec.rb +23 -0
  51. data/spec/resources/aws_db_parameter_group_spec.rb +23 -0
  52. data/spec/resources/aws_elasticache_replication_group_spec.rb +29 -0
  53. data/spec/resources/aws_elasticache_subnet_group_spec.rb +31 -0
  54. data/spec/resources/aws_elasticcache_cluster_spec.rb +23 -0
  55. data/spec/resources/aws_elasticcache_parameter_group_spec.rb +26 -0
  56. data/spec/resources/aws_elasticsearch_domain_spec.rb +22 -0
  57. data/spec/resources/aws_elb_spec.rb +65 -0
  58. data/spec/resources/aws_iam_policy.rb +35 -0
  59. data/spec/resources/aws_iam_user.rb +35 -0
  60. data/spec/resources/aws_instance_spec.rb +26 -0
  61. data/spec/resources/aws_proxy_protocol_policy_spec.rb +5 -0
  62. data/spec/resources/aws_redshift_cluster_spec.rb +25 -0
  63. data/spec/resources/aws_route53_record_spec.rb +41 -0
  64. data/spec/resources/aws_route53_zone_spec.rb +34 -0
  65. data/spec/resources/aws_s3_bucket_spec.rb +39 -0
  66. data/spec/resources/aws_security_group_spec.rb +80 -0
  67. data/spec/resources/aws_ses_receipt_rule.rb +33 -0
  68. data/spec/resources/aws_ses_receipt_rule_set.rb +25 -0
  69. data/spec/resources/aws_sns_topic_spec.rb +23 -0
  70. data/spec/resources/aws_sns_topic_subscription.rb +35 -0
  71. data/spec/resources/aws_sqs_queue_spec.rb +20 -0
  72. data/spec/rubocop_spec.rb +13 -0
  73. data/spec/spec_helper.rb +71 -0
  74. data/spec/sub_resource_spec.rb +20 -0
  75. data/spec/template_spec.rb +39 -0
  76. data/spec/utils/has_attributes_spec.rb +118 -0
  77. data/spec/utils/has_lifecycle_spec.rb +24 -0
  78. data/spec/utils/has_resources_spec.rb +68 -0
  79. data/spec/utils/has_subresources_spec.rb +29 -0
  80. data/spec/utils/has_validations_spec.rb +35 -0
  81. data/spec/utils/null_object_spec.rb +18 -0
  82. metadata +303 -0
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: d7ba4efcd817f80f7f9f1cd14b0605e3b71cfc9c
4
+ data.tar.gz: 596d587ef7bbede66b50e5b72570bed3305e43a2
5
+ SHA512:
6
+ metadata.gz: c7bf1e7081f46e7b6d2468a37c5fcca8fb29a783f3802d2d5f74e19dafb9120f64abcc5f61ecb5f9af8df67cdfa39aa9dd60b6aab96bf158c95393067641a812
7
+ data.tar.gz: 2566e1bf5352d9aa9b54d0d69bf86afec722685d1856a04566ee14ba77ef7cc73394260e5742672f218338796b23038deb20bf99cf817ba9da9fefcb3b208be7
data/LICENSE ADDED
@@ -0,0 +1,13 @@
1
+ Copyright 2016 Coinbase, Inc.
2
+
3
+ Licensed under the Apache License, Version 2.0 (the "License");
4
+ you may not use this file except in compliance with the License.
5
+ You may obtain a copy of the License at
6
+
7
+ http://www.apache.org/licenses/LICENSE-2.0
8
+
9
+ Unless required by applicable law or agreed to in writing, software
10
+ distributed under the License is distributed on an "AS IS" BASIS,
11
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ See the License for the specific language governing permissions and
13
+ limitations under the License.
@@ -0,0 +1,476 @@
1
+ # GeoEngineer
2
+
3
+ <a href="https://commons.wikimedia.org/wiki/File:Mantle_of_Responsibility.png"><img src="./assets/mantle.png" align="right" alt="Mantle_of_Responsibility" /></a>
4
+
5
+ *[🚀 Coinbase is looking for DevOps and Software Engineers](http://grnh.se/gri162)*
6
+
7
+ GeoEngineer provides a Ruby DSL and command line tool (`geo`) to *codeify* then plan and execute changes to cloud resources.
8
+
9
+ GeoEngineer's goals/requirements/features are:
10
+
11
+ 0. **DSL based on Terraform**: GeoEngineer uses [Terraform](https://github.com/hashicorp/terraform) to plan and execute changes, so the DSL to describe resources is similar to Terraform's. GeoEngineer's DSL also provides programming and object oriented features like inheritance, abstraction, branching and looping.
12
+ 1. **Development Workflow**: GeoEngineer is built to be used within existing development workflows, e.g. branching, creating pull requests, code reviewing and merging. To simplify these workflows, GeoEngineer dynamically generates Terraform state files using cloud APIs and opinionated tagging.
13
+ 2. **Extensible Validation**: Every team has their own standards when managing cloud resources e.g. naming patterns, tagging requirements, security rules. GeoEngineer resources can have custom validations added to ensure the resources conform to required standards.
14
+ 3. **Reusable Templates**: copy and pasting codified resources makes it difficult to understand and maintain infrastructure. By abstracting recommended patterns of reuse into **templates**, GeoEngineer aims to increase code reuse and decrease code copy/paste.
15
+ 4. **Describe Existing Resources**: Existing resources can be described with GeoEngineer without having to destroy and recreate them.
16
+ 5. **Principle of Least Astonishment**: show the exact plan before execution; do nothing without confirmation; do not allow a plan to be executed with failing validations; by default do not allow deletions; show warnings and hints to make code better.
17
+ 6. **One File per Project**: Managing dozens of projects with hundreds of files is difficult and error-prone, especially if a single project's resources are described across many files. Projects are easier to manage when they are each described in one file.
18
+ 7. **Dependencies**: resources have dependencies on other resources, projects have dependencies on other projects. Using Ruby's `require` file that describe resources can be included and referenced without having to hard-code any values.
19
+
20
+ ## Getting Started
21
+
22
+ ### Install Terraform
23
+
24
+ Instructions to install Terraform can be found [here](https://www.terraform.io/downloads.html).
25
+
26
+ ### Install Ruby
27
+
28
+ Instruction to install Ruby can be found [here](https://www.ruby-lang.org/en/documentation/installation/).
29
+
30
+ ### Install GeoEngineer
31
+
32
+ ```
33
+ gem build geoengineer.gempsec
34
+ gem install geoengineer
35
+ ```
36
+
37
+ Test it is installed correctly with:
38
+
39
+ ```
40
+ geo --help
41
+ ```
42
+
43
+ ### First GeoEngineer Project
44
+
45
+ GeoEngineer can use the folder structure where projects and environments are in the `projects` and `environments` directories respectively, however everything can also be defined in a single file, e.g. `first_project.rb`:
46
+
47
+ ```ruby
48
+ # First define the environment which is available with the variable `env`
49
+ # This is where project invariants are stored, e.g. subnets, vpc ...
50
+ environment("staging") {
51
+ account_id "1"
52
+ subnet "1"
53
+ vpc_id "1"
54
+ }
55
+
56
+ # Create the first_project to be in the `staging` environment
57
+ project = project('org', 'first_project') {
58
+ environments 'staging'
59
+ }
60
+
61
+ # Define the security group for the ELB to allow HTTP
62
+ elb_sg = project.resource("aws_security_group", "allow_http") {
63
+ name "allow_http"
64
+ description "Allow All HTTP"
65
+ vpc_id env.vpc_id
66
+ ingress {
67
+ from_port 80
68
+ to_port 80
69
+ protocol "tcp"
70
+ cidr_blocks ["0.0.0.0/0"]
71
+ }
72
+ tags {
73
+ Name "allow_http"
74
+ }
75
+ }
76
+
77
+ # Define the security group for EC2 to allow ingress from the ELB
78
+ ec2_sg = project.resource("aws_security_group", "allow_elb") {
79
+ name "allow_elb"
80
+ description "Allow ELB to 80"
81
+ vpc_id env.vpc_id
82
+ ingress {
83
+ from_port 8000
84
+ to_port 8000
85
+ protocol "tcp"
86
+ security_groups [elb_sg]
87
+ }
88
+ tags {
89
+ Name "allow_elb"
90
+ }
91
+ }
92
+
93
+ # cloud_config to run webserver
94
+ user_data = %{
95
+ #cloud-config
96
+ runcmd:
97
+ - docker run -d --name nginx -p 8000:80 nginx
98
+ }
99
+
100
+ # Create an EC2 instance to run nginx server
101
+ instance = project.resource("aws_instance", "web") {
102
+ ami "ami-1c94e10b" # COREOS AMI
103
+ instance_type "t1.micro"
104
+ subnet_id env.subnet
105
+ user_data user_data
106
+ tags {
107
+ Name "ec2_instance"
108
+ }
109
+ }
110
+
111
+ # Create the ELB connected to the instance
112
+ project.resource("aws_elb", "main-web-app") {
113
+ name "main-app-elb"
114
+ security_groups [elb_sg]
115
+ subnets [env.subnet]
116
+ instances [instance]
117
+ listener {
118
+ instance_port 8000
119
+ instance_protocol "http"
120
+ lb_port 80
121
+ lb_protocol "http"
122
+ }
123
+ }
124
+ ```
125
+
126
+ GeoEngineer command line tool `geo` can:
127
+
128
+ 1. **Create a plan** with `geo plan -e staging first_project.rb`
129
+ 2. **Execute the plan** with `geo apply -e staging first_project.rb`
130
+ 3. **Create a graph** with `geo graph -e staging --quiet first_project.rb | dot -Tpng > graph.png && open graph.png`
131
+ 4. **Status of Codeified Resources** with `geo status first_project.rb -e staging`
132
+
133
+ *There are more examples in the `examples` folder.*
134
+
135
+ ## Customizations
136
+
137
+ A core benefit of GeoEngineer is the ability to customize the DSL to your needs using custom validations, templates and reusable methods on resources.
138
+
139
+ ### Validations
140
+
141
+ Below is an example which will add the validation to ensure that all listeners on all ELB's must be HTTPS, for security reasons.
142
+
143
+ ```ruby
144
+ class GeoEngineer::Resources::AwsElb < GeoEngineer::Resource
145
+ validate :validate_listeners_must_be_https
146
+
147
+ def validate_listeners_must_be_https
148
+ errors = []
149
+ all_listener.select{ |i| i.lb_protocol != 'https' }.each do
150
+ errors << "ELB must use https protocol #{for_resource}"
151
+ end
152
+ return errors
153
+ end
154
+ end
155
+ ```
156
+
157
+ ### Templates
158
+
159
+ Below is an example template that builds a Elastic Load Balancer and a security group for an array of listeners:
160
+
161
+ ```ruby
162
+ class LoadBalancedInstance < Template
163
+ attr_reader :elb, :elb_sg
164
+
165
+ def initialize(name, project, parameters)
166
+ super(name, project, parameters)
167
+ # { listeners: [{ in: out: }]}
168
+ listeners = parameters[:listeners] || []
169
+
170
+ # Create the Security Groups
171
+ elb_sg = resource("aws_security_group", "#{name}_allow_http") {
172
+ name "#{name}_elb_sg"
173
+ description ""
174
+ vpc_id env.vpc_id
175
+ for l in listeners
176
+ ingress {
177
+ from_port l[:in]
178
+ to_port l[:in]
179
+ protocol "tcp"
180
+ cidr_blocks ["0.0.0.0/0"]
181
+ }
182
+ end
183
+ tags { Name "#{name}_elb_sg" }
184
+ }
185
+
186
+ # ELB
187
+ elb = resource("aws_elb", "main-web-app") {
188
+ name "#{name}_elb"
189
+ security_groups [elb_sg]
190
+ subnets [env.subnet]
191
+ for l in listeners
192
+ listener {
193
+ instance_port l[:out]
194
+ instance_protocol "http"
195
+ lb_port l[:in]
196
+ lb_protocol "http"
197
+ }
198
+ end
199
+ }
200
+
201
+ @elb = elb
202
+ @elb_sg = elb_sg
203
+ end
204
+
205
+ def template_resources
206
+ [@elb, @elb_sg]
207
+ end
208
+ end
209
+
210
+ # Instantiate the template for this project to forward two ports 80 and 8080
211
+ project.from_template("load_balanced_instance", "main_app", {
212
+ listeners: [{in: 80, out: 3000 }, {in: 8080, out: 4000 }]
213
+ })
214
+ ```
215
+
216
+ ### Methods
217
+
218
+ Define methods to be used in your own resources, e.g. a custom method to security group to add a rule:
219
+
220
+ ```ruby
221
+ class GeoEngineer::Resources::AwsSecurityGroup < GeoEngineer::Resource
222
+ # ...
223
+ def all_egress_everywhere
224
+ egress {
225
+ from_port 0
226
+ to_port 0
227
+ protocol "-1"
228
+ cidr_blocks ["0.0.0.0/0"]
229
+ }
230
+ end
231
+ # ...
232
+ end
233
+
234
+ project.resource('aws_security_group', 'all_egress') {
235
+ all_egress_everywhere # use the method to add egress
236
+ }
237
+ ```
238
+
239
+ ## Adding New Resources
240
+
241
+ The best way to contribute is to add resources that exist in Terraform but are not yet described in GeoEngineer.
242
+
243
+ To define a resource:
244
+
245
+ 0. checkout and fork/branch GeoEngineer
246
+ 1. create a file `./lib/geoengineer/resources/<resource_type>.rb`
247
+ 2. define a class `class GeoEngineer::Resources::<ResourceType> < GeoEngineer::Resource`
248
+ 3. define `_terraform_id`, and potentially `_geo_id` and `self._fetch_remote_resources` method (more below).
249
+ 4. write a test file for the resource that follows the style of other similar resources
250
+
251
+ ### Codeified to Remote Resources
252
+
253
+ A fundamental problem with codifying resources is matching the in code resource to the real remote resource. Terraform does this by maintaining an `id` in a state file which is matched to a remote resources attribute. This attribute is different per resource, e.g. for ELB's it is their `name`, for security groups it is their `group_name` that is generated so cannot be codified.
254
+
255
+ Without a state file GeoEngineer uses API's to match resources, this makes generated `id`'s likes security groups difficult. For these generated ids GeoEngineer uses tags e.g. for ELB's the GeoEngineer id is its `name` (just like Terraform) and for security groups it is their `Name` tag.
256
+
257
+ In a GeoEngineer resource the `_terraform_id` is the id used by Terraform and the `_geo_id` is GeoEngineer ID. By default a resources `_geo_id` is the same as the `_terraform_id`, so for most resources only the `_terraform_id` is required.
258
+
259
+ If `_terraform_id` is generated then the remote resource needed to be fetched via API and matched to the codified resource with `_geo_id`. This is done by implementing the `self._fetch_remote_resources` method to use the API and return a list of resources with both `_terraform_id` and `_geo_id`, then GeoEngineer can match them.
260
+
261
+ For example, in `aws_security_group`'s the resource is matched based on the `Name` tag, implements as:
262
+
263
+ ```ruby
264
+ class GeoEngineer::Resources::AwsSecurityGroup < GeoEngineer::Resource
265
+ after :initialize, -> { _terraform_id -> { NullObject.maybe(remote_resource)._terraform_id } }
266
+ after :initialize, -> { _geo_id -> { NullObject.maybe(tags)[:Name] } }
267
+
268
+ def self._fetch_remote_resources
269
+ AwsClients.ec2.describe_security_groups['security_groups'].map(&:to_h).map do |sg|
270
+ sg[:name] = sg[:group_name]
271
+ sg[:_terraform_id] = sg[:group_id]
272
+ sg[:_geo_id] = sg[:tags] ? sg[:tags].select { |x| x[:key] == "Name" }.first[:value] : nil
273
+ sg
274
+ end
275
+ end
276
+ end
277
+ ```
278
+
279
+ ### Validations
280
+
281
+ Terraform does not validate a lot of attributes before they are sent to the cloud. This means that often plans will fail for reasons that could have been initially validated. When creating a resource think about what validations could be done to ensure a plan is successful.
282
+
283
+ For example, a security groups needs a `Name` tag, requires a `name` and `description`, and a more complicated example is that its `cidr_blocks` should be valid:
284
+
285
+ ```ruby
286
+ class GeoEngineer::Resources::AwsSecurityGroup < GeoEngineer::Resource
287
+ # ...
288
+ validate :validate_correct_cidr_blocks
289
+ validate -> { validate_required_attributes([:name, :description]) }
290
+ validate -> { validate_has_tag(:Name) }
291
+
292
+ def validate_correct_cidr_blocks
293
+ errors = []
294
+ (self.all_ingress + self.all_egress).each do |in_eg|
295
+ next unless in_eg.cidr_blocks
296
+ in_eg.cidr_blocks.each do |cidr|
297
+ begin
298
+ NetAddr::CIDR.create(cidr)
299
+ rescue NetAddr::ValidationError
300
+ errors << "Bad cidr block \"#{cidr}\" #{for_resource}"
301
+ end
302
+ end
303
+ end
304
+ errors
305
+ end
306
+ # ...
307
+ end
308
+ ```
309
+
310
+ ### Terraform State
311
+
312
+ Terraform by default will attempt to sync its resources with the API so that its state file is up to date with the real world. Given that GeoEngineer uses Terraform in a different way this sometimes causes plans to list changes that have already happened.
313
+
314
+ To fix this issue a resource can override `to_terraform_state` method, e.g. `aws_db_instance` has issues with `final_snapshot_identifier` updating:
315
+
316
+
317
+ ```ruby
318
+ class GeoEngineer::Resources::AwsDbInstance < GeoEngineer::Resource
319
+ # ...
320
+ def to_terraform_state
321
+ tfstate = super
322
+ tfstate[:primary][:attributes] = {
323
+ 'final_snapshot_identifier' => final_snapshot_identifier,
324
+ }
325
+ tfstate
326
+ end
327
+ # ...
328
+ end
329
+ ```
330
+
331
+ ## GeoEngineer Reference
332
+
333
+ The core models in GeoEngineer are:
334
+
335
+ ```
336
+ +-------------+ 1
337
+ | Environment +-----------+
338
+ +-------------+ |
339
+ | 1 |
340
+ | |
341
+ v * v *
342
+ +-----+-------+ 1 * +-------------+ 1 * +-------------+
343
+ | Project +----->+ Resource +------>+ SubResource |
344
+ +-------------+ +-------------+ +-------------+
345
+ | 1 ^ *
346
+ | |
347
+ v * |
348
+ +-------------+ |
349
+ | Template +-----------+
350
+ +-------------+ 1
351
+ ```
352
+
353
+
354
+ 1. `Environment` contains many resources that may exist outside of a project, like VPCs or routing tables. Also every project defined to be in the environment, for example the `test_www` project is in `staging` but `monorail` is in `staging` and `production` environments.
355
+ 2. `Project` contains many resources and services grouped together into a name.
356
+ 3. `Template` has a `type` and `name`, and a group of resources that are defined in a pattern, e.g. every Load Balancer requires a unique security group that allows traffic in. It is an simple abstraction that can dramatically simplify and standardize cloud resources.
357
+ 4. `Resource` and `SubResource` are based off of how terraform models cloud resources. A `Resource` instance can have many `SubResource` instances, but a `SubResource` instance belongs to only one `Resource` instance, e.g. a load balancer resource may have a `health_check` sub-resource to only allow specific incoming ports.
358
+
359
+ All these models can have arbitrary attributes assigned to them either by directly assigning on the instance, or through passing a block to the constructor. For example:
360
+
361
+ ```ruby
362
+ resource = Resource.new('type','id') { |res|
363
+ # CORRECT
364
+ res.hello = 'hey'
365
+ puts res.hello # 'hey'
366
+ hello 'hey again' #
367
+ puts res.hello # 'hey again'
368
+
369
+ # INCORRECT way of assigning variables
370
+ goodbye = 'nooo' # This assigns a local variable, not an attribute on the resource
371
+ puts res.goodbye # nil
372
+ }
373
+
374
+ puts resource.hello # 'hey again'
375
+
376
+ resource.goodbye = 'see ya'
377
+ puts resource.goodbye # 'see ya'
378
+ ```
379
+
380
+ Additionally, if the value is expensive to calculate or requires other attributes not yet assigned, an attribute can be assigned a `Proc` or `lambda` which will be calculated lazily:
381
+
382
+ ```ruby
383
+ resource = Resource.new('type','id')
384
+ resource.lazy_attr = -> { puts "CALCULATING THE VALUE"; 'value' }
385
+ # ...
386
+ puts resource.lazy_attr
387
+ #$ "CALCULATING THE VALUE"
388
+ #$ "value"
389
+ ```
390
+
391
+ ### Environment
392
+
393
+ The top level class in GeoEngineer is the `environment`, it contains all projects, resources and services, there should only ever be one initialized at a time.
394
+
395
+ An environment can mean many things to different people, e.g. an AWS account, an AWS region, or a specific AWS VPC. The only real constraint is that a resource has one instance per environment, e.g. a load balancer that is defined to be in `staging` and `production` environments, will have an instance in each.
396
+
397
+ The function `environment` is provided as a factory to build an environment:
398
+
399
+ ```ruby
400
+ environment = environment("environment_name") { |e|
401
+ e.attr_1 = [1,2,3]
402
+ attr_2 'value'
403
+ }
404
+ environment.attr_3 = "another value"
405
+ ```
406
+
407
+ ### Project
408
+
409
+ A project is a group of resources typically provisioned to deploy one code base. A project has an `organization` and `name`, to mimic the github `username`/`organiztion` and `repository` structure.
410
+
411
+ A project is defined like:
412
+
413
+ ```ruby
414
+ project = project('org', 'project_name') {
415
+ environments 'staging', 'production'
416
+ }
417
+ ```
418
+
419
+ This projects organization is `org`, its name `project_name` and will be provisioned in the `staging` and `production` environments. The `org` and `name` must be unique across all other projects.
420
+
421
+ The method `project` will automatically add the project to the instantiated environment object **only if** that environments name is in the list of environments, otherwise it is ignored.
422
+
423
+ ### Templates
424
+
425
+ A template is used to create a group of resources in a recommended pattern. For example, an HTTP service could create a load balancer, a load balancer security group, and a ec2 security group.
426
+
427
+ ```ruby
428
+ template_instance = project.from_template('template_type', 'name', { parameter: 'helloworld') { |resource, resource_sg|
429
+
430
+ # set attribute
431
+ attribute "custom attribute"
432
+
433
+ # Customize the values
434
+ resource.cutomize_value = "Customize"
435
+ resource.override_value = "Override"
436
+
437
+ # Overrider a subresource value
438
+ resource.subresource.override_sr_value = "first value"
439
+ resource.all_subresource[1].override_sr_value = "new value"
440
+ }
441
+
442
+ template_instance.resource_sg # access the created resources outside the block
443
+ ```
444
+
445
+ This template will create a resource `resource` and a resource security group `resource_sg` with the option `hello` set to value `'world'`. The resources can then be customized and have their values overridden.
446
+
447
+ Each template should be documented with the created resources and how to modify them.
448
+
449
+ ### Resources and SubResources
450
+
451
+ Resources are defined to be similar to the [terraform resource](https://www.terraform.io/docs/configuration/resources.html) configuration. The main difference is to not use `=` as this will create a local ruby variable and not assign the value.
452
+
453
+ A `Resource` can be created with and `environment`, `project` or `template` object (this will add that resource to that object):
454
+
455
+ ```ruby
456
+ environment.resource('type', 'identifier') {
457
+ name "resource_name"
458
+ subresource {
459
+ attribute "attribute"
460
+ }
461
+ }
462
+
463
+ project.resource('type', 'identifier') {
464
+ # ...
465
+ }
466
+
467
+ template.resource('type', 'identifier') {
468
+ # ...
469
+ }
470
+ ```
471
+
472
+ The `type` of a resource must be a valid terraform type, where AWS types are listed [here](https://www.terraform.io/docs/providers/aws/index.html). Some resources are not supported yet by GeoEngineer.
473
+
474
+ `identifier` is used by GeoEngineer and terraform to reference this resource so must be unique, however it is not stored in the cloud so can be changed without affecting a plan.
475
+
476
+ A resource also has a ruby block sent to it that contains parameters and sub-resources. These values are defined by terraform so for reference to what values are required please refer to the [terraform docs](https://www.terraform.io/docs/providers/aws/index.html).