This folder contains an example of how to create an EC2 instance with two EBS volumes that are persisted between
redeploys. This is useful for servers that persist data to the local hard disk and need that data to still be available
after a redeploy, such as a database like MySQL, CI server like Jenkins, or CMS like WordPress. Although it should be
possible to do this with native Terraform using the aws_ebs_volume and aws_volume_attachment resources, due to a
bug, the aws_volume_attachment resource
does not work correctly and cannot be used. Therefore, this example includes a Packer template that installs the
persistent-ebs-volume scripts and uses those scripts to attach and mount the volume
when the instance is booting.
Note, an EBS volume can only be associated with a single EC2 Instance, so if you need the data on the disk to be shared
amongst multiple servers, check out the Amazon Elastic File System, which provides a
service built on top of NFS.
How do you run this example?
To run this example, you need to do the following:
Build an AMI using Packer
Deploy the AMI using Terraform
These steps are described in detail next.
Build an AMI using Packer
The code that runs the EC2 instance in this example is an Amazon Machine Image
(AMI) that has been defined in a Packer
template under packer/build.json. To build an AMI from this template:
Open up vars.tf and set secrets at the top of the file as environment variables and fill in any other variables in
the file that don't have defaults. This includes the ami variable which you should fill in with the ID of the
AMI you just built with Packer.
terraform get.
terraform plan.
If the plan looks good, run terraform apply.
When the templates are applied, Terraform will output the IP address of the EC2 instance. If you SSH to the instance,
it should have a /data folder. This is the EBS volume. It should persist whatever data you put into it in between
restarts of this EC2 instance.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"5223424303d075508d70cdc44e04ede09845d7a9"}]},{"name":".gitignore","path":".gitignore","sha":"1b77db107bd9abb565bd5adafce570dd59adf016"},{"name":".pre-commit-config.yaml","path":".pre-commit-config.yaml","sha":"d32719967fe548aec5b26866a86b40273421ddc5"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"555c0c6e23a7502acbef94fb0b77bfa759ba11e8"},{"name":"LICENSE.txt","path":"LICENSE.txt","sha":"f4e3d9bd4717a044ed31ad847a300eee74371a78"},{"name":"README.adoc","path":"README.adoc","sha":"123e02e79535b1cef11e5190b6d962143f74ff79"},{"name":"_docs","children":[{"name":"aws-ec2.png","path":"_docs/aws-ec2.png","sha":"861e17a7d1df585b37d10e3211f71f6a6e182115"},{"name":"single-ec2-instance-architecture.png","path":"_docs/single-ec2-instance-architecture.png","sha":"c44f7efdb936c53fc4988f286ddcf31be8a6fdc9"}]},{"name":"core-concepts.md","path":"core-concepts.md","sha":"74ee29b0f03ed842c70a271d1a58be0c61b1c358"},{"name":"examples","children":[{"name":"attach-eni","children":[{"name":"README.md","path":"examples/attach-eni/README.md","sha":"86ce148cc900ce48f3debc490ce771ff5cd9fded"},{"name":"main.tf","path":"examples/attach-eni/main.tf","sha":"3c8bd421bcdc81d044a365c521f16fc363ba9744"},{"name":"outputs.tf","path":"examples/attach-eni/outputs.tf","sha":"cf9472109a00b477ec4eb950e5b4e5ce9d21f4d1"},{"name":"packer","children":[{"name":"build.json","path":"examples/attach-eni/packer/build.json","sha":"5457202e3df0aecefc61d7f624792ef96cb45fe4"}]},{"name":"user-data","children":[{"name":"user-data-1.sh","path":"examples/attach-eni/user-data/user-data-1.sh","sha":"978ca952d47f3dcd84881deb3723614339edbd6f"},{"name":"user-data-2.sh","path":"examples/attach-eni/user-data/user-data-2.sh","sha":"898fd7a3c7179cc0c6d595b6ccbb4b92b1b2cedb"}]},{"name":"vars.tf","path":"examples/attach-eni/vars.tf","sha":"c8bd5aa7b155cf011bd03e3c6bf76a79fd1be4d5"}]},{"name":"bastion-host","children":[{"name":"README.md","path":"examples/bastion-host/README.md","sha":"0326f3c2c0707a3e2a67ffb6e002aec3eb30e1fa"},{"name":"main.tf","path":"examples/bastion-host/main.tf","sha":"6449b057f0eaeea679d658b3f2449c661f9551db"},{"name":"outputs.tf","path":"examples/bastion-host/outputs.tf","sha":"5f0c2d739b9646c39e19bfd05cacb852c6080c0c"},{"name":"user-data.sh","path":"examples/bastion-host/user-data.sh","sha":"1f5d58de29f4b834fd43db38f2ad8723fa84ec5f"},{"name":"vars.tf","path":"examples/bastion-host/vars.tf","sha":"3864d03b7a4035b0c6e41d35f8829b886790f282"}]},{"name":"ec2-backup","children":[{"name":"README.md","path":"examples/ec2-backup/README.md","sha":"782667373dc4d7cf602fea0e05d6b78ed47d2c42"},{"name":"main.tf","path":"examples/ec2-backup/main.tf","sha":"65641a0c500586e5fba5df4a894577f6bdfdc4ce"},{"name":"outputs.tf","path":"examples/ec2-backup/outputs.tf","sha":"6023311f87f6757e60e5d47600095cbc6dce324a"},{"name":"variables.tf","path":"examples/ec2-backup/variables.tf","sha":"e6e9fa9520608ef0a5cc0aadc70d118775543b03"}]},{"name":"persistent-ebs-volume","children":[{"name":"README.md","path":"examples/persistent-ebs-volume/README.md","sha":"7acf321a8a3183bfe4d7187be94208ed281bcd66","toggled":true},{"name":"main.tf","path":"examples/persistent-ebs-volume/main.tf","sha":"a4646f40d7546b63bc5529b7144c41dd512fd924"},{"name":"outputs.tf","path":"examples/persistent-ebs-volume/outputs.tf","sha":"54f33c96b796373b12b9702f46d30a1c85043f65"},{"name":"packer","children":[{"name":"build.json","path":"examples/persistent-ebs-volume/packer/build.json","sha":"b45f3c0ba6da9f5d9ec473cbaa75025fbd4c9541"},{"name":"nvme_build.json","path":"examples/persistent-ebs-volume/packer/nvme_build.json","sha":"d99f1c211eac42d01e2b9b47f26442b92881ff2c"}]},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/persistent-ebs-volume/user-data/user-data.sh","sha":"6793c2066296ff24917f6a86c43ad9674dd53624"}]},{"name":"vars.tf","path":"examples/persistent-ebs-volume/vars.tf","sha":"6f26667744846a28777af25bb3b311b1bf34a1bf"}],"toggled":true},{"name":"route53-helpers","children":[{"name":"README.md","path":"examples/route53-helpers/README.md","sha":"e302ef0f18f85a3a191105dea785005685b9522f"},{"name":"main.tf","path":"examples/route53-helpers/main.tf","sha":"91409439a4887ee192453255c5b0d3a5f345ec79"},{"name":"outputs.tf","path":"examples/route53-helpers/outputs.tf","sha":"4c3c3ccccf964155ffbce7546fcbc9ef6e886de6"},{"name":"packer","children":[{"name":"build.json","path":"examples/route53-helpers/packer/build.json","sha":"e372902627f36cbafe2170ba6f43c8cf951ff505"}]},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/route53-helpers/user-data/user-data.sh","sha":"7f4de426ead32d966fe46d7091a1d293cb3ca099"}]},{"name":"vars.tf","path":"examples/route53-helpers/vars.tf","sha":"3c990b1e4ae4da54aac558cf24124e29cd362931"}]}],"toggled":true},{"name":"modules","children":[{"name":"attach-eni","children":[{"name":"README.md","path":"modules/attach-eni/README.md","sha":"5c32557105967e1b0e82f50fe693c12370e905cc"},{"name":"bin","children":[{"name":"attach-eni","path":"modules/attach-eni/bin/attach-eni","sha":"71b4beffba2e93cbc1547445dc723d4d768f89d7"}]},{"name":"install.sh","path":"modules/attach-eni/install.sh","sha":"542cbd93ca08fd9cbe6f121f4d8fea2b1d76ca8b"}]},{"name":"ec2-backup","children":[{"name":"README.md","path":"modules/ec2-backup/README.md","sha":"e5f22ab6bdd9f34dacf71428bc04fef1d5415bad"},{"name":"main.tf","path":"modules/ec2-backup/main.tf","sha":"809439e9be3fa565e6480aaa857276669a706bc9"},{"name":"outputs.tf","path":"modules/ec2-backup/outputs.tf","sha":"19b7bd464c3c0916e03bff6f4f2cf69b671041ed"},{"name":"variables.tf","path":"modules/ec2-backup/variables.tf","sha":"d590cf90b9a1060c9f003f64d82085d183c5e8f2"}]},{"name":"persistent-ebs-volume","children":[{"name":"README.md","path":"modules/persistent-ebs-volume/README.md","sha":"6d8c0c80d3e674fcda15a9a95a7fc2f4de7d6e9d"},{"name":"bin","children":[{"name":"mount-ebs-volume","path":"modules/persistent-ebs-volume/bin/mount-ebs-volume","sha":"46cc65171354b261affdccde92f846d43b39268a"},{"name":"unmount-ebs-volume","path":"modules/persistent-ebs-volume/bin/unmount-ebs-volume","sha":"2eddbccd97812577f68964e3903a46953611a270"}]},{"name":"install.sh","path":"modules/persistent-ebs-volume/install.sh","sha":"e0ce5862cd6975992dc011a6dfe94fdf14a9b607"}]},{"name":"route53-helpers","children":[{"name":"README.md","path":"modules/route53-helpers/README.md","sha":"52d0b942bba658065589567e9c9d78c98b4ca028"},{"name":"bin","children":[{"name":"add-dns-a-record","path":"modules/route53-helpers/bin/add-dns-a-record","sha":"7195a02479864ec79071cfae429bd545bf7d8d32"}]},{"name":"install.sh","path":"modules/route53-helpers/install.sh","sha":"535ed35d64611c5f12e9924b3cb8df0a77180ab8"}]},{"name":"single-server","children":[{"name":"README.md","path":"modules/single-server/README.md","sha":"afcb5405b0aca7dd4438538ddfa3d87b79846b4a"},{"name":"main.tf","path":"modules/single-server/main.tf","sha":"ec2f5a21f9c9fb38077a336732e15b322467d8ec"},{"name":"outputs.tf","path":"modules/single-server/outputs.tf","sha":"1e59900af7a55bca5f7d00415f66fb79d5b739c8"},{"name":"vars.tf","path":"modules/single-server/vars.tf","sha":"a26ea719e615de3880826b6222c3efb7dac5df46"}]}]},{"name":"terraform-cloud-enterprise-private-module-registry-placeholder.tf","path":"terraform-cloud-enterprise-private-module-registry-placeholder.tf","sha":"ae586c0fe830819580e1009d41a9074f16e65bed"},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"ef26d3851db2fff0b36dfa61379724c0db9ff281"},{"name":"attach_eni_test.go","path":"test/attach_eni_test.go","sha":"65117277872ad1bed9f54c09825a668071882d70"},{"name":"bastion_host_test.go","path":"test/bastion_host_test.go","sha":"0001a84a6a1a5081175de46d8ec13b0057754976"},{"name":"ec2_backup_test.go","path":"test/ec2_backup_test.go","sha":"73ae620eb4bbec7771bfc614e676935956134e9d"},{"name":"go.mod","path":"test/go.mod","sha":"5c844ea883d065bc849982ebeca7b5b782116762"},{"name":"go.sum","path":"test/go.sum","sha":"b697d9d9b65472616812e2927a687ed9ecebf66c"},{"name":"persistent_ebs_volume_test.go","path":"test/persistent_ebs_volume_test.go","sha":"a8827cb209dcbb48af4e71dfe2304222170f956f"},{"name":"route53_helpers_test.go","path":"test/route53_helpers_test.go","sha":"9317cf471fc541e77f387cad08c13c56dc3d06f9"},{"name":"test_helpers.go","path":"test/test_helpers.go","sha":"88a0a959547631589f956f6ae8304429a51a6ea2"}]}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"persistent-ebs-volume-example\">Persistent EBS Volume Example</h1><div class=\"preview__body--border\"></div><p>This folder contains an example of how to create an EC2 instance with two EBS volumes that are persisted between\nredeploys. This is useful for servers that persist data to the local hard disk and need that data to still be available\nafter a redeploy, such as a database like MySQL, CI server like Jenkins, or CMS like WordPress. Although it should be\npossible to do this with native Terraform using the <code>aws_ebs_volume</code> and <code>aws_volume_attachment</code> resources, <a href=\"https://github.com/hashicorp/terraform/issues/2957#issuecomment-150613677\" class=\"preview__body--description--blue\" target=\"_blank\">due to a\nbug</a>, the <code>aws_volume_attachment</code> resource\ndoes not work correctly and cannot be used. Therefore, this example includes a Packer template that installs the\n<a href=\"/repos/v0.9.0/module-server/modules/persistent-ebs-volume\" class=\"preview__body--description--blue\">persistent-ebs-volume scripts</a> and uses those scripts to attach and mount the volume\nwhen the instance is booting.</p>\n<p>Note, an EBS volume can only be associated with a single EC2 Instance, so if you need the data on the disk to be shared\namongst multiple servers, check out the <a href=\"https://aws.amazon.com/efs/\" class=\"preview__body--description--blue\" target=\"_blank\">Amazon Elastic File System</a>, which provides a\nservice built on top of NFS.</p>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-you-run-this-example\">How do you run this example?</h2>\n<p>To run this example, you need to do the following:</p>\n<ol>\n<li>Build an AMI using Packer</li>\n<li>Deploy the AMI using Terraform</li>\n</ol>\n<p>These steps are described in detail next.</p>\n<h3 class=\"preview__body--subtitle\" id=\"build-an-ami-using-packer\">Build an AMI using Packer</h3>\n<p>The code that runs the EC2 instance in this example is an <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html\" class=\"preview__body--description--blue\" target=\"_blank\">Amazon Machine Image\n(AMI)</a> that has been defined in a <a href=\"https://www.packer.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Packer\ntemplate</a> under <code>packer/build.json</code>. To build an AMI from this template:</p>\n<ol>\n<li>Install <a href=\"https://www.packer.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Packer</a>.</li>\n<li>Set up your <a href=\"https://www.packer.io/docs/builders/amazon.html\" class=\"preview__body--description--blue\" target=\"_blank\">AWS credentials as environment variables</a>.</li>\n<li>Run <code>packer build build.json</code> to create the AMI in your AWS account. Note down the ID of this new AMI.</li>\n</ol>\n<p><strong>NOTE</strong>: If you wish to try the example on <a href=\"https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances\" class=\"preview__body--description--blue\" target=\"_blank\">a Nitro based EC2\ninstance</a>, use\n<code>nvme_build.json</code> instead of <code>build.json</code>.</p>\n<h3 class=\"preview__body--subtitle\" id=\"deploy-the-ami-using-terraform\">Deploy the AMI using Terraform</h3>\n<p>Now that you have an AMI, use Terraform to deploy it:</p>\n<ol>\n<li>Install <a href=\"https://www.terraform.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Terraform</a>.</li>\n<li>Open up <code>vars.tf</code> and set secrets at the top of the file as environment variables and fill in any other variables in\nthe file that don't have defaults. This includes the <code>ami</code> variable which you should fill in with the ID of the\nAMI you just built with Packer.</li>\n<li><code>terraform get</code>.</li>\n<li><code>terraform plan</code>.</li>\n<li>If the plan looks good, run <code>terraform apply</code>.</li>\n</ol>\n<p>When the templates are applied, Terraform will output the IP address of the EC2 instance. If you SSH to the instance,\nit should have a <code>/data</code> folder. This is the EBS volume. It should persist whatever data you put into it in between\nrestarts of this EC2 instance.</p>\n","repoName":"module-server","repoRef":"v0.12.1","serviceDescriptor":{"serviceName":"Single EC2 Instance","serviceRepoName":"module-server","serviceRepoOrg":"gruntwork-io","cloudProviders":["aws"],"description":"Run a single EC2 instance for stateless or stateful apps. Supports IAM roles, EBS volumes, ENIs, and EIPs.","imageUrl":"single-service.png","licenseType":"subscriber","technologies":["Terraform","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"Server orchestration","fileName":"README.md","filePath":"/examples/persistent-ebs-volume","title":"Repo Browser: Single EC2 Instance","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
main.tf
