Skip to content

Commit 98866e9

Browse files
vadim-gleifvadim-gleif
authored
Migrate readme yaml (#2)
1 parent a7bc774 commit 98866e9

File tree

7 files changed

+443
-99
lines changed

7 files changed

+443
-99
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,6 @@
77
**/terraform.tfvars
88
**/*.pem
99
**/*.pub
10+
11+
.build-harness
12+
build-harness

‎.travis.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
addons:
2+
apt:
3+
packages:
4+
- git
5+
- make
6+
- curl
7+
8+
install:
9+
- make init
10+
11+
script:
12+
- make terraform/install
13+
- make terraform/get-plugins
14+
- make terraform/get-modules
15+
- make terraform/lint
16+
- make terraform/validate

‎Makefile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
SHELL := /bin/bash
2+
3+
# List of targets the `readme` target should call before generating the readme
4+
export README_DEPS ?= docs/targets.md docs/terraform.md
5+
6+
-include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
7+
8+
## Lint terraform code
9+
lint:
10+
$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate

‎README.md‎

Lines changed: 191 additions & 99 deletions
Large diffs are not rendered by default.

‎README.yaml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
#
3+
# This is the canonical configuration for the `README.md`
4+
# Run `make readme` to rebuild the `README.md`
5+
#
6+
7+
# Name of this project
8+
name: terraform-aws-ec2-instance-group
9+
10+
# Logo for this project
11+
#logo: docs/logo.png
12+
13+
# License of this project
14+
license: "APACHE2"
15+
16+
# Canonical GitHub repo
17+
github_repo: cloudposse/terraform-aws-ec2-instance-group
18+
19+
# Badges to display
20+
badges:
21+
- name: "Build Status"
22+
image: "https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group.svg?branch=master"
23+
url: "https://travis-ci.org/cloudposse/terraform-aws-ec2-instance-group"
24+
- name: "Latest Release"
25+
image: "https://img.shields.io/github/release/cloudposse/terraform-aws-ec2-instance-group.svg"
26+
url: "https://github.com/cloudposse/terraform-aws-ec2-instance-group/releases/latest"
27+
- name: "Slack Community"
28+
image: "https://slack.cloudposse.com/badge.svg"
29+
url: "https://slack.cloudposse.com"
30+
31+
related:
32+
- name: "terraform-aws-ec2-instance"
33+
description: "Terraform Module for providing a general EC2 instance provisioned by Ansible"
34+
url: "https://github.com/cloudposse/terraform-aws-ec2-instance"
35+
- name: "terraform-aws-ec2-bastion-server"
36+
description: "Terraform Module to define a generic Bastion host with parameterized user_data"
37+
url: "https://github.com/cloudposse/terraform-aws-ec2-bastion-server"
38+
- name: "https://github.com/cloudposse/terraform-aws-rds-cluster"
39+
description: "Terraform module to provision an RDS Aurora cluster for MySQL or Postgres"
40+
url: "https://github.com/cloudposse/terraform-aws-rds-cluster"
41+
42+
# Short description of this project
43+
description: |-
44+
Terraform Module for providing N general purpose EC2 hosts.
45+
46+
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.
47+
48+
**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).
49+
50+
51+
Included features:
52+
* Automatically create a Security Group
53+
* Option to switch EIP attachment
54+
* CloudWatch monitoring and automatic reboot if instance hangs
55+
* Assume Role capability
56+
57+
# How to use this project
58+
usage: |-
59+
Note: add `${var.ssh_key_pair}` private key to the `ssh agent`.
60+
61+
Include this repository as a module in your existing terraform code.
62+
63+
64+
### Simple example:
65+
66+
```hcl
67+
module "instance" {
68+
source = "git::https://github.com/cloudposse/terraform-aws-ec2-instance-group.git?ref=master"
69+
namespace = "cp"
70+
stage = "prod"
71+
name = "app"
72+
ami = "ami-a4dc46db"
73+
ssh_key_pair = "${var.ssh_key_pair}"
74+
instance_type = "${var.instance_type}"
75+
vpc_id = "${var.vpc_id}"
76+
security_groups = ["${var.security_groups}"]
77+
subnet = "${var.subnet}"
78+
79+
instance_count = "3"
80+
}
81+
```
82+
83+
### Example with additional volumes and EIP
84+
85+
```hcl
86+
module "kafka_instance" {
87+
source = "git::https://github.com/cloudposse/terraform-aws-ec2-instance-group.git?ref=master"
88+
namespace = "cp"
89+
stage = "prod"
90+
name = "app"
91+
ami = "ami-a4dc46db"
92+
ssh_key_pair = "${var.ssh_key_pair}"
93+
vpc_id = "${var.vpc_id}"
94+
security_groups = ["${var.security_groups}"]
95+
subnet = "${var.subnet}"
96+
associate_public_ip_address = "true"
97+
additional_ips_count = "1"
98+
ebs_volume_count = "2"
99+
allowed_ports = ["22", "80", "443"]
100+
101+
instance_count = "3"
102+
}
103+
```
104+
105+
### Additional complete working example with variations of how to use the module
106+
In /examples directory
107+
108+
This module depends on these modules:
109+
110+
* [terraform-terraform-label](https://github.com/cloudposse/terraform-terraform-label)
111+
112+
It is necessary to run `terraform get` or `terraform init` to download this module.
113+
114+
Now reference the label when creating an instance (for example):
115+
```hcl
116+
resource "aws_ami_from_instance" "example" {
117+
count = "${length(module.instance.*.id)}"
118+
name = "terraform-example"
119+
source_instance_id = "${element(module.instance.*.id, count.index)}"
120+
}
121+
```
122+
123+
references:
124+
- name: "terraform-aws-ec2-bastion-server"
125+
description: "Terraform module to define a generic Bastion host with parameterized user_data"
126+
url: "https://github.com/cloudposse/terraform-aws-ec2-bastion-server"
127+
128+
include:
129+
- "docs/targets.md"
130+
- "docs/terraform.md"
131+
132+
# Contributors to this project
133+
contributors:
134+
- name: "Erik Osterman"
135+
github: "osterman"
136+
- name: "Jamie Nelson"
137+
github: "Jamie-BitFlight"

‎docs/targets.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Makefile Targets
2+
```
3+
Available targets:
4+
5+
help This help screen
6+
help/all Display help for all targets
7+
lint Lint terraform code
8+
9+
```

‎docs/terraform.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
2+
## Inputs
3+
4+
| Name | Description | Type | Default | Required |
5+
|------|-------------|:----:|:-----:|:-----:|
6+
| additional_ips_count | Count of additional EIPs | string | `0` | no |
7+
| allowed_ports | List of allowed ingress ports | list | `<list>` | no |
8+
| ami | The AMI to use for the instance. | string | - | yes |
9+
| applying_period | The period in seconds over which the specified statistic is applied | string | `60` | no |
10+
| assign_eip_address | Assign an Elastic IP address to the instance | string | `true` | no |
11+
| associate_public_ip_address | Associate a public IP address with the instance | string | `true` | no |
12+
| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
13+
| availability_zone | Availability Zone the instance is launched in. If not set, will be launched in the first AZ of the region | string | `` | no |
14+
| comparison_operator | The arithmetic operation to use when comparing the specified Statistic and Threshold. Possible values are: GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, LessThanOrEqualToThreshold. | string | `GreaterThanOrEqualToThreshold` | no |
15+
| create_default_security_group | Create default Security Group with only Egress traffic allowed | string | `true` | no |
16+
| default_alarm_action | | string | `action/actions/AWS_EC2.InstanceId.Reboot/1.0` | no |
17+
| delete_on_termination | Whether the volume should be destroyed on instance termination | string | `true` | no |
18+
| delimiter | | string | `-` | no |
19+
| disable_api_termination | Enable EC2 Instance Termination Protection | string | `false` | no |
20+
| ebs_device_names | Name of the EBS device to mount | list | `<list>` | no |
21+
| ebs_iops | Amount of provisioned IOPS. This must be set with a volume_type of io1 | string | `0` | no |
22+
| ebs_optimized | Launched EC2 instance will be EBS-optimized | string | `false` | no |
23+
| ebs_volume_count | Count of EBS volumes that will be attached to the instance | string | `0` | no |
24+
| ebs_volume_size | Size of the EBS volume in gigabytes | string | `10` | no |
25+
| ebs_volume_type | The type of EBS volume. Can be standard, gp2 or io1 | string | `gp2` | no |
26+
| evaluation_periods | The number of periods over which data is compared to the specified threshold. | string | `5` | no |
27+
| 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 |
28+
| instance_count | Count of ec2 instances to create | string | `1` | no |
29+
| instance_enabled | Flag to control the instance creation. Set to false if it is necessary to skip instance creation | string | `true` | no |
30+
| instance_type | The type of the instance | string | `t2.micro` | no |
31+
| 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 |
32+
| ipv6_addresses | List of IPv6 addresses from the range of the subnet to associate with the primary network interface | list | `<list>` | no |
33+
| 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 |
34+
| 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 |
35+
| metric_threshold | The value against which the specified statistic is compared | string | `1` | no |
36+
| monitoring | Launched EC2 instance will have detailed monitoring enabled | string | `true` | no |
37+
| name | Name (e.g. `bastion` or `db`) - required for `terraform-terraform-label` module | string | - | yes |
38+
| namespace | Namespace (e.g. `cp` or `cloudposse`) - required for `terraform-terraform-label` module | string | - | yes |
39+
| private_ips | Private IP address to associate with the instances in the VPC | list | `<list>` | no |
40+
| region | AWS Region the instance is launched in | string | - | yes |
41+
| root_iops | Amount of provisioned IOPS. This must be set if root_volume_type is set to `io1` | string | `0` | no |
42+
| root_volume_size | Size of the root volume in gigabytes | string | `10` | no |
43+
| root_volume_type | Type of root volume. Can be standard, gp2 or io1 | string | `gp2` | no |
44+
| security_groups | List of Security Group IDs allowed to connect to the instance | list | `<list>` | no |
45+
| 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 |
46+
| ssh_key_pair | SSH key pair to be provisioned on the instance | string | `` | no |
47+
| ssh_key_pair_path | Path to where the generated key pairs will be created. Defaults to $${path.cwd} | string | `` | no |
48+
| stage | Stage (e.g. `prod`, `dev`, `staging` - required for `terraform-terraform-label` module | string | - | yes |
49+
| statistic_level | The statistic to apply to the alarm's associated metric. Allowed values are: SampleCount, Average, Sum, Minimum, Maximum | string | `Maximum` | no |
50+
| subnet | VPC Subnet ID the instance is launched in | string | - | yes |
51+
| tags | Additional tags | map | `<map>` | no |
52+
| user_data | Instance user data. Do not pass gzip-compressed data via this argument | string | `` | no |
53+
| vpc_id | The ID of the VPC that the instance security group belongs to | string | - | yes |
54+
| welcome_message | | string | `` | no |
55+
56+
## Outputs
57+
58+
| Name | Description |
59+
|------|-------------|
60+
| alarm_ids | CloudWatch Alarm IDs |
61+
| aws_key_pair_name | Name of AWS key pair |
62+
| ebs_ids | IDs of EBSs |
63+
| eip_per_instance_count | Number of EIPs per instance. |
64+
| eni_to_eip_map | Map of ENI with EIP |
65+
| ids | Disambiguated IDs list |
66+
| instance_count | Total number of instances created. |
67+
| network_interface_ids | IDs of the network interface that was created with the instance |
68+
| new_ssh_keypair_generated | Was a new ssh_key_pair generated |
69+
| primary_network_interface_ids | IDs of the instance's primary network interface |
70+
| private_dns | Private DNS records of instances |
71+
| private_ips | Private IPs of instances |
72+
| public_dns | All public DNS records for the public interfaces and ENIs |
73+
| public_ips | List of Public IPs of instances (or EIP) |
74+
| role_names | Names of AWS IAM Roles associated with creating instance |
75+
| security_group_ids | ID on the new AWS Security Group associated with creating instance |
76+
| ssh_key_pem_path | Path where SSH key pair was created (if applicable) |
77+

0 commit comments

Comments
 (0)