From 9e09815bce0fea61f4a17968d2902e8d58601632 Mon Sep 17 00:00:00 2001 From: vadim-hleif Date: Thu, 12 Jul 2018 18:18:11 +0300 Subject: [PATCH] Migrate readme yaml --- .gitignore | 3 + .travis.yml | 16 +++ Makefile | 10 ++ README.md | 290 ++++++++++++++++++++++++++++++---------------- README.yaml | 137 ++++++++++++++++++++++ docs/targets.md | 9 ++ docs/terraform.md | 77 ++++++++++++ 7 files changed, 443 insertions(+), 99 deletions(-) create mode 100644 .travis.yml create mode 100644 Makefile create mode 100644 README.yaml create mode 100644 docs/targets.md create mode 100644 docs/terraform.md diff --git a/.gitignore b/.gitignore index 5bc52d0..a507c7b 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,6 @@ **/terraform.tfvars **/*.pem **/*.pub + +.build-harness +build-harness \ No newline at end of file diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..b7cf901 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,16 @@ +addons: + apt: + packages: + - git + - make + - curl + +install: + - make init + +script: + - make terraform/install + - make terraform/get-plugins + - make terraform/get-modules + - make terraform/lint + - make terraform/validate \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..655f630 --- /dev/null +++ b/Makefile @@ -0,0 +1,10 @@ +SHELL := /bin/bash + +# List of targets the `readme` target should call before generating the readme +export README_DEPS ?= docs/targets.md docs/terraform.md + +-include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness) + +## Lint terraform code +lint: + $(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate \ No newline at end of file diff --git a/README.md b/README.md index 230edf9..948ec3d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ -# terraform-aws-ec2-instance-group [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group) + + +[![Cloud Posse](https://cloudposse.com/logo-300x69.svg)](https://cloudposse.com) + +# terraform-aws-ec2-instance-group [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group) [![Latest Release](https://img.shields.io/github/release/cloudposse/terraform-aws-ec2-instance-group.svg)](https://github.com/cloudposse/terraform-aws-ec2-instance-group/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com) + Terraform Module for providing N general purpose EC2 hosts. @@ -13,6 +18,18 @@ Included features: * CloudWatch monitoring and automatic reboot if instance hangs * Assume Role capability + +--- + +This project is part of our comprehensive ["SweetOps"](https://docs.cloudposse.com) approach towards DevOps. + + +It's 100% Open Source and licensed under the [APACHE2](LICENSE). + + + + + ## Usage Note: add `${var.ssh_key_pair}` private key to the `ssh agent`. @@ -79,108 +96,177 @@ resource "aws_ami_from_instance" "example" { } ``` -## Variables - -| Name | Default | Description | Required | -|:--------------------------------|:----------------------------------------------:|:-------------------------------------------------------------------------------------------------------|:--------:| -| `region` | `` | AWS Region the instance is launched in. Optional. If not provided, the current region will be used | No | -| `namespace` | `` | Namespace (e.g. `cp` or `cloudposse`) | Yes | -| `stage` | `` | Stage (e.g. `prod`, `dev`, `staging` | Yes | -| `name` | `` | Name (e.g. `bastion` or `db`) | Yes | -| `attributes` | `[]` | Additional attributes (e.g. `policy` or `role`) | No | -| `tags` | `{}` | Additional tags (e.g. `map("BusinessUnit","XYZ")` | No | -| `ami` | `` | The AMI id | Yes | -| `instance_enabled` | `true` | Flag to control the instance creation. Set to false if it is necessary to skip instance creation | No | -| `create_default_security_group` | `true` | Create default Security Group with only Egress traffic allowed | No | -| `ssh_key_pair` | `` | SSH key pair to be provisioned on the instance. If none provided, and `generate_ssh_key_pair` is true a new keypair is generated | No | -| `generate_ssh_key_pair` | `false` | Should a new SSH key pair be generated. | No | -| `ssh_key_pair_path` | `` | Path to where SSH key pair should be generated. Defaults to ${path.cwd} | No | -| `instance_type` | `t2.micro` | The type of the instance (e.g. `t2.micro`) | No | -| `vpc_id` | `` | The ID of the VPC that the instance security group belongs to | Yes | -| `security_groups` | `[]` | List of Security Group IDs allowed to connect to the instance | Yes | -| `allowed_ports` | `[]` | List of allowed ingress ports, _e.g._ ["22", "80", "443"] | No | -| `subnet` | `` | VPC Subnet ID the instance is launched in | Yes | -| `associate_public_ip_address` | `true` | Associate a public IP address with the instance | No | -| `assign_eip_address` | `true` | Assign an Elastic IP address to the instance | No | -| `additional_ips_count` | `0` | Count of additional EIPs | No | -| `private_ip` | `` | Private IP address to associate with the instance in the VPC | No | -| `source_dest_check` | `true` | Controls if traffic is routed to the instance when the destination address does not match the instance | No | -| `ipv6_address_count` | `0` | Number of IPv6 addresses to associate with the primary network interface | No | -| `ipv6_addresses` | `[]` | List of IPv6 addresses from the range of the subnet to associate with the primary network interface | No | -| `root_volume_type` | `gp2` | Type of the root volume. Can be `standard`, `gp2` or `io1` | No | -| `root_volume_size` | `10` | Size of the root volume in gigabytes | No | -| `root_iops` | `0` | Amount of provisioned IOPS. This must be set with a `root_volume_type` of `io1` | No | -| `ebs_device_name` | `[/dev/xvdb]` | Name of the EBS device to mount | No | -| `ebs_volume_type` | `gp2` | Type of EBS volume. Can be `standard`, `gp2` or `io1` | No | -| `ebs_volume_size` | `10` | Size of the EBS volume in gigabytes | No | -| `ebs_iops` | `0` | Amount of provisioned IOPS. This must be set if `ebs_volume_type` is set to `io1` | No | -| `ebs_volume_count` | `0` | Count of EBS volumes that will be attached to the instance | No | -| `delete_on_termination` | `true` | Whether the volume should be destroyed on instance termination | No | -| `comparison_operator` | `GreaterThanOrEqualToThreshold` | Arithmetic operation to use when comparing the specified Statistic and Threshold | No | -| `metric_name` | `StatusCheckFailed_Instance` | Name for the alarm's associated metric | No | -| `evaluation_periods` | `5` | Number of periods over which data is compared to the specified threshold | No | -| `metric_namespace` | `AWS/EC2` | Namespace for the alarm's associated metric | No | -| `applying_period` | `60` | Period in seconds over which the specified statistic is applied | No | -| `statistic_level` | `Maximum` | Statistic to apply to the alarm's associated metric | No | -| `metric_threshold` | `1` | Value against which the specified statistic is compared | No | -| `default_alarm_action` | `action/actions/AWS_EC2.InstanceId.Reboot/1.0` | String of action to execute when this alarm transitions into an ALARM state | No | -| `instance_count` | `1` | Number of EC2 instances to create - each will have the same settings | No | + + + +## Makefile Targets +``` +Available targets: + + help This help screen + help/all Display help for all targets + lint Lint terraform code + +``` + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|:----:|:-----:|:-----:| +| additional_ips_count | Count of additional EIPs | string | `0` | no | +| allowed_ports | List of allowed ingress ports | list | `` | no | +| ami | The AMI to use for the instance. | string | - | yes | +| applying_period | The period in seconds over which the specified statistic is applied | string | `60` | no | +| assign_eip_address | Assign an Elastic IP address to the instance | string | `true` | no | +| associate_public_ip_address | Associate a public IP address with the instance | string | `true` | no | +| attributes | Additional attributes (e.g. `policy` or `role`) | list | `` | no | +| availability_zone | Availability Zone the instance is launched in. If not set, will be launched in the first AZ of the region | string | `` | no | +| comparison_operator | The arithmetic operation to use when comparing the specified Statistic and Threshold. Possible values are: GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, LessThanOrEqualToThreshold. | string | `GreaterThanOrEqualToThreshold` | no | +| create_default_security_group | Create default Security Group with only Egress traffic allowed | string | `true` | no | +| default_alarm_action | | string | `action/actions/AWS_EC2.InstanceId.Reboot/1.0` | no | +| delete_on_termination | Whether the volume should be destroyed on instance termination | string | `true` | no | +| delimiter | | string | `-` | no | +| disable_api_termination | Enable EC2 Instance Termination Protection | string | `false` | no | +| ebs_device_names | Name of the EBS device to mount | list | `` | no | +| ebs_iops | Amount of provisioned IOPS. This must be set with a volume_type of io1 | string | `0` | no | +| ebs_optimized | Launched EC2 instance will be EBS-optimized | string | `false` | no | +| ebs_volume_count | Count of EBS volumes that will be attached to the instance | string | `0` | no | +| ebs_volume_size | Size of the EBS volume in gigabytes | string | `10` | no | +| ebs_volume_type | The type of EBS volume. Can be standard, gp2 or io1 | string | `gp2` | no | +| evaluation_periods | The number of periods over which data is compared to the specified threshold. | string | `5` | no | +| generate_ssh_key_pair | If true, create a new key pair and save the pem for it to the current working directory | string | `false` | no | +| instance_count | Count of ec2 instances to create | string | `1` | no | +| instance_enabled | Flag to control the instance creation. Set to false if it is necessary to skip instance creation | string | `true` | no | +| instance_type | The type of the instance | string | `t2.micro` | no | +| ipv6_address_count | Number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet | string | `0` | no | +| ipv6_addresses | List of IPv6 addresses from the range of the subnet to associate with the primary network interface | list | `` | no | +| metric_name | The name for the alarm's associated metric. Allowed values can be found in https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ec2-metricscollected.html | string | `StatusCheckFailed_Instance` | no | +| metric_namespace | The namespace for the alarm's associated metric. Allowed values can be found in https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-namespaces.html | string | `AWS/EC2` | no | +| metric_threshold | The value against which the specified statistic is compared | string | `1` | no | +| monitoring | Launched EC2 instance will have detailed monitoring enabled | string | `true` | no | +| name | Name (e.g. `bastion` or `db`) - required for `terraform-terraform-label` module | string | - | yes | +| namespace | Namespace (e.g. `cp` or `cloudposse`) - required for `terraform-terraform-label` module | string | - | yes | +| private_ips | Private IP address to associate with the instances in the VPC | list | `` | no | +| region | AWS Region the instance is launched in | string | - | yes | +| root_iops | Amount of provisioned IOPS. This must be set if root_volume_type is set to `io1` | string | `0` | no | +| root_volume_size | Size of the root volume in gigabytes | string | `10` | no | +| root_volume_type | Type of root volume. Can be standard, gp2 or io1 | string | `gp2` | no | +| security_groups | List of Security Group IDs allowed to connect to the instance | list | `` | no | +| source_dest_check | Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs | string | `true` | no | +| ssh_key_pair | SSH key pair to be provisioned on the instance | string | `` | no | +| ssh_key_pair_path | Path to where the generated key pairs will be created. Defaults to $${path.cwd} | string | `` | no | +| stage | Stage (e.g. `prod`, `dev`, `staging` - required for `terraform-terraform-label` module | string | - | yes | +| statistic_level | The statistic to apply to the alarm's associated metric. Allowed values are: SampleCount, Average, Sum, Minimum, Maximum | string | `Maximum` | no | +| subnet | VPC Subnet ID the instance is launched in | string | - | yes | +| tags | Additional tags | map | `` | no | +| user_data | Instance user data. Do not pass gzip-compressed data via this argument | string | `` | no | +| vpc_id | The ID of the VPC that the instance security group belongs to | string | - | yes | +| welcome_message | | string | `` | no | + ## Outputs -| Name | Type | Description | -|:-------------------------------:|:------:|:-------------------------------------------------------------------:| -| `ids` | list | Disambiguated IDs | -| `private_dns` | list | Private DNS records of the instances | -| `private_ips` | list | Private IPs of the instances | -| `public_ips` | list | Public IPs of the instance (or EIP ) | -| `aws_key_pair` | string | Name of AWS key | -| `ssh_key_pem_path` | string | Local path to SSH pem key | -| `security_group_id` | string | ID of the AWS Security Group associated with the instance | -| `role_names` | list | Name of the AWS IAM Roles associated with the instance | -| `alarm_ids` | list | CloudWatch Alarm IDs | -| `eni_to_eip_map` | map | ENI to EIP | -| `ebs_ids` | list | IDs of EBSs | -| `primary_network_interface_ids` | list | IDs of the instances primary network interfaces | -| `network_interface_id` | list | IDs of the network interface that was created with the instance | -| `public_dns` | list | Public DNS of the instances (or DNS of EIP) | -| `eip_per_instance_count` | string | Number of EIP's per instance | - - -## License +| Name | Description | +|------|-------------| +| alarm_ids | CloudWatch Alarm IDs | +| aws_key_pair_name | Name of AWS key pair | +| ebs_ids | IDs of EBSs | +| eip_per_instance_count | Number of EIPs per instance. | +| eni_to_eip_map | Map of ENI with EIP | +| ids | Disambiguated IDs list | +| instance_count | Total number of instances created. | +| network_interface_ids | IDs of the network interface that was created with the instance | +| new_ssh_keypair_generated | Was a new ssh_key_pair generated | +| primary_network_interface_ids | IDs of the instance's primary network interface | +| private_dns | Private DNS records of instances | +| private_ips | Private IPs of instances | +| public_dns | All public DNS records for the public interfaces and ENIs | +| public_ips | List of Public IPs of instances (or EIP) | +| role_names | Names of AWS IAM Roles associated with creating instance | +| security_group_ids | ID on the new AWS Security Group associated with creating instance | +| ssh_key_pem_path | Path where SSH key pair was created (if applicable) | + + + + +## Related Projects + +Check out these related projects. + +- [terraform-aws-ec2-instance](https://github.com/cloudposse/terraform-aws-ec2-instance) - Terraform Module for providing a general EC2 instance provisioned by Ansible +- [terraform-aws-ec2-bastion-server](https://github.com/cloudposse/terraform-aws-ec2-bastion-server) - Terraform Module to define a generic Bastion host with parameterized user_data +- [https://github.com/cloudposse/terraform-aws-rds-cluster](https://github.com/cloudposse/terraform-aws-rds-cluster) - Terraform module to provision an RDS Aurora cluster for MySQL or Postgres + + + ## References -* https://github.com/cloudposse/terraform-aws-ec2-bastion-server + +For additional context, refer to some of these links. + +- [terraform-aws-ec2-bastion-server](https://github.com/cloudposse/terraform-aws-ec2-bastion-server) - Terraform module to define a generic Bastion host with parameterized user_data + ## Help **Got a question?** -Review the [docs](docs/), file a GitHub [issue](https://github.com/cloudposse/terraform-aws-ec2-instance/issues), send us an [email](mailto:hello@cloudposse.com) or reach out to us on [Gitter](https://gitter.im/cloudposse/). +File a GitHub [issue](https://github.com/cloudposse/terraform-aws-ec2-instance-group/issues), send us an [email][email] or join our [Slack Community][slack]. + +## Commerical Support + +Work directly with our team of DevOps experts via email, slack, and video conferencing. +We provide *commercial support* for all of our [Open Source][github] projects. As a *Dedicated Support* customer, you have access to our team of subject matter experts at a fraction of the cost of a fulltime engineer. + +[![E-Mail](https://img.shields.io/badge/email-hello@cloudposse.com-blue.svg)](mailto:hello@cloudposse.com) + +- **Questions.** We'll use a Shared Slack channel between your team and ours. +- **Troubleshooting.** We'll help you triage why things aren't working. +- **Code Reviews.** We'll review your Pull Requests and provide constructive feedback. +- **Bug Fixes.** We'll rapidly work to fix any bugs in our projects. +- **Build New Terraform Modules.** We'll develop original modules to provision infrastructure. +- **Cloud Architecture.** We'll assist with your cloud strategy and design. +- **Implementation.** We'll provide hands on support to implement our reference architectures. + + +## Community Forum + +Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build *sweet* infrastructure. ## Contributing ### Bug Reports & Feature Requests -Please use the [issue tracker](https://github.com/cloudposse/terraform-aws-ec2-instance/issues) to report any bugs or file feature requests. +Please use the [issue tracker](https://github.com/cloudposse/terraform-aws-ec2-instance-group/issues) to report any bugs or file feature requests. ### Developing +If you are interested in being a contributor and want to get involved in developing this project or [help out](https://github.com/orgs/cloudposse/projects/3) with our other projects, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com). + In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. 1. **Fork** the repo on GitHub 2. **Clone** the project to your own machine 3. **Commit** changes to your own branch 4. **Push** your work back up to your fork - 5. Submit a **Pull request** so that we can review your changes + 5. Submit a **Pull Request** so that we can review your changes + +**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request! -**NOTE:** Be sure to merge the latest from "upstream" before making a pull request! -## License +## Copyright -[APACHE 2.0](LICENSE) © 2016-2018 [Cloud Posse, LLC](https://cloudposse.com) +Copyright © 2017-2018 [Cloud Posse, LLC](https://cloudposse.com) + + + +## License + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) + +See [LICENSE](LICENSE) for full details. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -190,7 +276,7 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an @@ -200,35 +286,41 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. under the License. +## Trademarks + +All other trademarks referenced herein are the property of their respective owners. + ## About -This module is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at +This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at -We love [Open Source Software](https://github.com/cloudposse/)! +[![Cloud Posse](https://cloudposse.com/logo-300x69.svg)](https://cloudposse.com) -See [our other projects][community] -or [hire us][hire] to help build your next cloud-platform. +We're a [DevOps Professional Services][hire] company based in Los Angeles, CA. We love [Open Source Software](https://github.com/cloudposse/)! + +We offer paid support on all of our projects. + +Check out [our other projects][github], [apply for a job][jobs], or [hire us][hire] to help with your cloud strategy and implementation. + + [docs]: https://docs.cloudposse.com/ + [website]: https://cloudposse.com/ + [github]: https://github.com/cloudposse/ + [jobs]: https://cloudposse.com/jobs/ + [hire]: https://cloudposse.com/contact/ + [slack]: https://slack.cloudposse.com/ + [linkedin]: https://www.linkedin.com/company/cloudposse + [twitter]: https://twitter.com/cloudposse/ + [email]: mailto:hello@cloudposse.com - [website]: http://cloudposse.com/ - [community]: https://github.com/cloudposse/ - [hire]: http://cloudposse.com/contact/ ### Contributors -| [![Erik Osterman][erik_img]][erik_web]
[Erik Osterman][erik_web] | [![Igor Rodionov][igor_img]][igor_web]
[Igor Rodionov][igor_web] | [![Andriy Knysh][andriy_img]][andriy_web]
[Andriy Knysh][andriy_web] | [![Sergey Vasilyev][sergey_img]][sergey_web]
[Sergey Vasilyev][sergey_web] | [![Konstantin B][konstantin_img]][konstantin_web]
[Konstantin B][konstantin_web] | [![Valeriy][valeriy_img]][valeriy_web]
[Valeriy][valeriy_web] | [![Vladimir][vladimir_img]][vladimir_web]
[Vladimir][vladimir_web] | -|---------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | -----------------------------------------------------------------------| - - [erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144 - [erik_web]: https://github.com/osterman/ - [igor_img]: http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144 - [igor_web]: https://github.com/goruha/ - [andriy_img]: https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 - [andriy_web]: https://github.com/aknysh/ - [sergey_img]: https://avatars1.githubusercontent.com/u/1134449?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 - [sergey_web]: https://github.com/s2504s/ - [konstantin_img]: https://avatars1.githubusercontent.com/u/11299538?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 - [konstantin_web]: https://github.com/comeanother/ - [valeriy_img]: https://avatars1.githubusercontent.com/u/10601658?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 - [valeriy_web]: https://github.com/drama17/ - [vladimir_img]: https://avatars1.githubusercontent.com/u/26582191?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 - [vladimir_web]: https://github.com/SweetOps/ +| [![Erik Osterman][osterman_avatar]][osterman_homepage]
[Erik Osterman][osterman_homepage] | [![Jamie Nelson][Jamie-BitFlight_avatar]][Jamie-BitFlight_homepage]
[Jamie Nelson][Jamie-BitFlight_homepage] | +|---|---| + + [osterman_homepage]: https://github.com/osterman + [osterman_avatar]: https://github.com/osterman.png?size=150 + [Jamie-BitFlight_homepage]: https://github.com/Jamie-BitFlight + [Jamie-BitFlight_avatar]: https://github.com/Jamie-BitFlight.png?size=150 + + diff --git a/README.yaml b/README.yaml new file mode 100644 index 0000000..86b3543 --- /dev/null +++ b/README.yaml @@ -0,0 +1,137 @@ +--- +# +# This is the canonical configuration for the `README.md` +# Run `make readme` to rebuild the `README.md` +# + +# Name of this project +name: terraform-aws-ec2-instance-group + +# Logo for this project +#logo: docs/logo.png + +# License of this project +license: "APACHE2" + +# Canonical GitHub repo +github_repo: cloudposse/terraform-aws-ec2-instance-group + +# Badges to display +badges: + - name: "Build Status" + image: "https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group.svg?branch=master" + url: "https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group" + - name: "Latest Release" + image: "https://img.shields.io/github/release/cloudposse/terraform-aws-ec2-instance-group.svg" + url: "https://github.com/cloudposse/terraform-aws-ec2-instance-group/releases/latest" + - name: "Slack Community" + image: "https://slack.cloudposse.com/badge.svg" + url: "https://slack.cloudposse.com" + +related: + - name: "terraform-aws-ec2-instance" + description: "Terraform Module for providing a general EC2 instance provisioned by Ansible" + url: "https://github.com/cloudposse/terraform-aws-ec2-instance" + - name: "terraform-aws-ec2-bastion-server" + description: "Terraform Module to define a generic Bastion host with parameterized user_data" + url: "https://github.com/cloudposse/terraform-aws-ec2-bastion-server" + - name: "https://github.com/cloudposse/terraform-aws-rds-cluster" + description: "Terraform module to provision an RDS Aurora cluster for MySQL or Postgres" + url: "https://github.com/cloudposse/terraform-aws-rds-cluster" + +# Short description of this project +description: |- + Terraform Module for providing N general purpose EC2 hosts. + + If you only need to provision a single EC2 instance, consider using the [terraform-aws-ec2-instance](https://github.com/cloudposse/terraform-aws-ec2-instance) module instead. + + **IMPORTANT** This module by-design does not provision an AutoScaling group. It was designed to provision a discrete number of instances suitable for running stateful services such as databases (E.g. Kafka, Redis, etc). + + + Included features: + * Automatically create a Security Group + * Option to switch EIP attachment + * CloudWatch monitoring and automatic reboot if instance hangs + * Assume Role capability + +# How to use this project +usage: |- + Note: add `${var.ssh_key_pair}` private key to the `ssh agent`. + + Include this repository as a module in your existing terraform code. + + + ### Simple example: + + ```hcl + module "instance" { + source = "git::https://github.com/cloudposse/terraform-aws-ec2-instance-group.git?ref=master" + namespace = "cp" + stage = "prod" + name = "app" + ami = "ami-a4dc46db" + ssh_key_pair = "${var.ssh_key_pair}" + instance_type = "${var.instance_type}" + vpc_id = "${var.vpc_id}" + security_groups = ["${var.security_groups}"] + subnet = "${var.subnet}" + + instance_count = "3" + } + ``` + + ### Example with additional volumes and EIP + + ```hcl + module "kafka_instance" { + source = "git::https://github.com/cloudposse/terraform-aws-ec2-instance-group.git?ref=master" + namespace = "cp" + stage = "prod" + name = "app" + ami = "ami-a4dc46db" + ssh_key_pair = "${var.ssh_key_pair}" + vpc_id = "${var.vpc_id}" + security_groups = ["${var.security_groups}"] + subnet = "${var.subnet}" + associate_public_ip_address = "true" + additional_ips_count = "1" + ebs_volume_count = "2" + allowed_ports = ["22", "80", "443"] + + instance_count = "3" + } + ``` + + ### Additional complete working example with variations of how to use the module + In /examples directory + + This module depends on these modules: + + * [terraform-terraform-label](https://github.com/cloudposse/terraform-terraform-label) + + It is necessary to run `terraform get` or `terraform init` to download this module. + + Now reference the label when creating an instance (for example): + ```hcl + resource "aws_ami_from_instance" "example" { + count = "${length(module.instance.*.id)}" + name = "terraform-example" + source_instance_id = "${element(module.instance.*.id, count.index)}" + } + ``` + +references: + - name: "terraform-aws-ec2-bastion-server" + description: "Terraform module to define a generic Bastion host with parameterized user_data" + url: "https://github.com/cloudposse/terraform-aws-ec2-bastion-server" + +include: + - "docs/targets.md" + - "docs/terraform.md" + +# Contributors to this project +contributors: + - name: "Erik Osterman" + github: "osterman" + - name: "Jamie Nelson" + github: "Jamie-BitFlight" \ No newline at end of file diff --git a/docs/targets.md b/docs/targets.md new file mode 100644 index 0000000..09c39cd --- /dev/null +++ b/docs/targets.md @@ -0,0 +1,9 @@ +## Makefile Targets +``` +Available targets: + + help This help screen + help/all Display help for all targets + lint Lint terraform code + +``` diff --git a/docs/terraform.md b/docs/terraform.md new file mode 100644 index 0000000..c4b99ba --- /dev/null +++ b/docs/terraform.md @@ -0,0 +1,77 @@ + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|:----:|:-----:|:-----:| +| additional_ips_count | Count of additional EIPs | string | `0` | no | +| allowed_ports | List of allowed ingress ports | list | `` | no | +| ami | The AMI to use for the instance. | string | - | yes | +| applying_period | The period in seconds over which the specified statistic is applied | string | `60` | no | +| assign_eip_address | Assign an Elastic IP address to the instance | string | `true` | no | +| associate_public_ip_address | Associate a public IP address with the instance | string | `true` | no | +| attributes | Additional attributes (e.g. `policy` or `role`) | list | `` | no | +| availability_zone | Availability Zone the instance is launched in. If not set, will be launched in the first AZ of the region | string | `` | no | +| comparison_operator | The arithmetic operation to use when comparing the specified Statistic and Threshold. Possible values are: GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, LessThanOrEqualToThreshold. | string | `GreaterThanOrEqualToThreshold` | no | +| create_default_security_group | Create default Security Group with only Egress traffic allowed | string | `true` | no | +| default_alarm_action | | string | `action/actions/AWS_EC2.InstanceId.Reboot/1.0` | no | +| delete_on_termination | Whether the volume should be destroyed on instance termination | string | `true` | no | +| delimiter | | string | `-` | no | +| disable_api_termination | Enable EC2 Instance Termination Protection | string | `false` | no | +| ebs_device_names | Name of the EBS device to mount | list | `` | no | +| ebs_iops | Amount of provisioned IOPS. This must be set with a volume_type of io1 | string | `0` | no | +| ebs_optimized | Launched EC2 instance will be EBS-optimized | string | `false` | no | +| ebs_volume_count | Count of EBS volumes that will be attached to the instance | string | `0` | no | +| ebs_volume_size | Size of the EBS volume in gigabytes | string | `10` | no | +| ebs_volume_type | The type of EBS volume. Can be standard, gp2 or io1 | string | `gp2` | no | +| evaluation_periods | The number of periods over which data is compared to the specified threshold. | string | `5` | no | +| generate_ssh_key_pair | If true, create a new key pair and save the pem for it to the current working directory | string | `false` | no | +| instance_count | Count of ec2 instances to create | string | `1` | no | +| instance_enabled | Flag to control the instance creation. Set to false if it is necessary to skip instance creation | string | `true` | no | +| instance_type | The type of the instance | string | `t2.micro` | no | +| ipv6_address_count | Number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet | string | `0` | no | +| ipv6_addresses | List of IPv6 addresses from the range of the subnet to associate with the primary network interface | list | `` | no | +| metric_name | The name for the alarm's associated metric. Allowed values can be found in https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ec2-metricscollected.html | string | `StatusCheckFailed_Instance` | no | +| metric_namespace | The namespace for the alarm's associated metric. Allowed values can be found in https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-namespaces.html | string | `AWS/EC2` | no | +| metric_threshold | The value against which the specified statistic is compared | string | `1` | no | +| monitoring | Launched EC2 instance will have detailed monitoring enabled | string | `true` | no | +| name | Name (e.g. `bastion` or `db`) - required for `terraform-terraform-label` module | string | - | yes | +| namespace | Namespace (e.g. `cp` or `cloudposse`) - required for `terraform-terraform-label` module | string | - | yes | +| private_ips | Private IP address to associate with the instances in the VPC | list | `` | no | +| region | AWS Region the instance is launched in | string | - | yes | +| root_iops | Amount of provisioned IOPS. This must be set if root_volume_type is set to `io1` | string | `0` | no | +| root_volume_size | Size of the root volume in gigabytes | string | `10` | no | +| root_volume_type | Type of root volume. Can be standard, gp2 or io1 | string | `gp2` | no | +| security_groups | List of Security Group IDs allowed to connect to the instance | list | `` | no | +| source_dest_check | Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs | string | `true` | no | +| ssh_key_pair | SSH key pair to be provisioned on the instance | string | `` | no | +| ssh_key_pair_path | Path to where the generated key pairs will be created. Defaults to $${path.cwd} | string | `` | no | +| stage | Stage (e.g. `prod`, `dev`, `staging` - required for `terraform-terraform-label` module | string | - | yes | +| statistic_level | The statistic to apply to the alarm's associated metric. Allowed values are: SampleCount, Average, Sum, Minimum, Maximum | string | `Maximum` | no | +| subnet | VPC Subnet ID the instance is launched in | string | - | yes | +| tags | Additional tags | map | `` | no | +| user_data | Instance user data. Do not pass gzip-compressed data via this argument | string | `` | no | +| vpc_id | The ID of the VPC that the instance security group belongs to | string | - | yes | +| welcome_message | | string | `` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| alarm_ids | CloudWatch Alarm IDs | +| aws_key_pair_name | Name of AWS key pair | +| ebs_ids | IDs of EBSs | +| eip_per_instance_count | Number of EIPs per instance. | +| eni_to_eip_map | Map of ENI with EIP | +| ids | Disambiguated IDs list | +| instance_count | Total number of instances created. | +| network_interface_ids | IDs of the network interface that was created with the instance | +| new_ssh_keypair_generated | Was a new ssh_key_pair generated | +| primary_network_interface_ids | IDs of the instance's primary network interface | +| private_dns | Private DNS records of instances | +| private_ips | Private IPs of instances | +| public_dns | All public DNS records for the public interfaces and ENIs | +| public_ips | List of Public IPs of instances (or EIP) | +| role_names | Names of AWS IAM Roles associated with creating instance | +| security_group_ids | ID on the new AWS Security Group associated with creating instance | +| ssh_key_pem_path | Path where SSH key pair was created (if applicable) | +