Note: This public repo contains the documentation for the private GitHub repo https://github.com/gruntwork-io/module-server. We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer. If you're already a Gruntwork customer, the original source for this file is at: https://github.com/gruntwork-io/module-server/blob/master/README.md. If you're not a customer, contact us at [email protected] or http://www.gruntwork.io for info on how to get access!
This repo contains modules that help to deploy, manage, and configure a single server (as opposed to a group of servers in an Auto Scaling Group) in AWS. The modules are:
- single-server: Deploy a single EC2 instance along with the all the resources it typically needs, such as an Elastic IP address, Route 53 DNS entry, IAM Role and IAM instance profile, and security group. This module is useful for deploying standalone servers such as a Bastion Host or Jenkins.
- persistent-ebs-volume: Scripts for mounting and unmounting EBS Volumes on your EC2 Instances for Volumes that need to persist between redeploys of the Instance.
- route53-helpers: Scripts for working with Amazon's DNS Service, Route 53, including a script to add a DNS A record pointing to the instance's IP address.
Click on each module above to see its documentation. Head over to the examples folder for examples.
If you're looking for ways to manage groups of servers, check out the Auto Scaling Group and EC2 Container Service modules.
At Gruntwork, we've taken the thousands of hours we spent building infrastructure on AWS and condensed all that experience and code into pre-built packages or modules. Each module is a battle-tested, best-practices definition of a piece of infrastructure, such as a VPC, ECS cluster, or an Auto Scaling Group. Modules are versioned using Semantic Versioning to allow Gruntwork clients to keep up to date with the latest infrastructure best practices in a systematic way.
Most of our modules contain either:
- Terraform code
- Scripts & binaries
To use a module in your Terraform templates, create a module
resource and set its source
field to the Git URL of
this repo. You should also set the ref
parameter so you're fixed to a specific version of this repo, as the master
branch may have backwards incompatible changes (see module
sources).
For example, to use v1.0.8
of the single-server module, you would add the following:
module "ecs_cluster" {
source = "git::[email protected]:gruntwork-io/module-server.git//modules/single-server?ref=v1.0.8"
// set the parameters for the single-server module
}
Note: the double slash (//
) is intentional and required. It's part of Terraform's Git syntax (see module
sources).
See the module's documentation and vars.tf
file for all the parameters you can set. Run terraform get -update
to
pull the latest version of this module from this repo before runnin gthe standard terraform plan
and
terraform apply
commands.
You can install the scripts and binaries in the modules
folder of any repo using the Gruntwork
Installer. For example, if the scripts you want to install are
in the modules/ecs-scripts
folder of the https://github.com/gruntwork-io/module-ecs repo, you could install them
as follows:
gruntwork-install --module-name "ecs-scripts" --repo "https://github.com/gruntwork-io/module-ecs" --tag "0.0.1"
See the docs for each script & binary for detailed instructions on how to use them.
We are following the principles of Semantic Versioning. During initial development, the major
version is to 0 (e.g., 0.x.y
), which indicates the code does not yet have a stable API. Once we hit 1.0.0
, we will
follow these rules:
- Increment the patch version for backwards-compatible bug fixes (e.g.,
v1.0.8 -> v1.0.9
). - Increment the minor version for new features that are backwards-compatible (e.g.,
v1.0.8 -> 1.1.0
). - Increment the major version for any backwards-incompatible changes (e.g.
1.0.8 -> 2.0.0
).
The version is defined using Git tags. Use GitHub to create a release, which will have the effect of adding a git tag.
See the test folder for details.
Please see LICENSE.txt for details on how the code in this repo is licensed.