This is a continuation from part1.
It's time to write our first module. Modules are Terraform solution to reuse code. It's a
great way to keep your infrastructure as code in understandable pieces that can be
then grouped together. You can develop those pieces independently, have different people
working in parallel, test independently as well all of those pieces, and then you
will use them like using lego pieces to build our whole company infrastructure.
In our specific case, since we decided that we will have two environments, production and staging,
the only way for us to not repeat the same code among those two environment is to use modules.
We are in neeed of modules in that case to reuse the code, and it will also force us to
think what bits are environment dependent and what bits are logic that belong to the module.
If you remember from the last post, also because I gave the spoiler, we know that we need two independent modules for our whole
company IaC. We will start with a very easy module just to learn how modules work and on the next
part we will attack directly a more interesting module.
route53 module
Let's start by giving excuses to this sucky name. You might want to think more on
"domain" terms (even though we are just doing infra here!) and call it something like
"NamingDomainModule" or something that might imply we are not totally chained to AWS.
It's all your choice. Sometimes if you don't want to use some grey matter to name
things then the default name should become what that thing actually is, and in this
case that "thing" is a "module that manages route53 resources", so forward with this
name! (and yes, I am totally chained to AWS, I can write a guide if we are using AWS,
I would need to find a guide if we were to use Google Cloud or others).
This module will be very simple:
│ └── route53
│ ├── outputs.tf
│ ├── public.tf
│ └── variables.tf
variables.tf is the place were you define what kind of input this module receives
(and for more things, but mainly that). Public.tf is where we are gonna write the resources
and the outputs.tf are well, yes, the outputs that we want this module to produce.
Let's write the resources in out public.tf. Again, the name of this file, is king of random.
If I have to be honest, I am just walking you through some -not that- old code of mine, and
while I can maybe fix some stuff, I think it's cute to leave some flaws as they were written.
public.tf
resource "aws_route53_zone" "business" {
name = var.domain
tags = local.common_tags
}
Well, that was rather short. Only a zone that we will call it "business" with the required
attribute name that will come from one of those inputs from variables.tf and tags.
So let's define those variables that we will require the programmer - also us- to give us when using our
module:
variables.tf
locals {
common_tags = tomap({
"Environment": title(var.environment),
"Terraform": "True"
})
}
variable "environment" {
description = "The name for the environment, usually staging, production or development."
default = "staging"
}
variable "domain" {
description = "The main domain"
}
The variables block are self-descriptive. The interesting part are the locals. Locals
are used for values computed from variables mainly. In that case, we are creating a
set of tags and using one of the variables, the environment, to create it.
outputs.tf
output "hosted_zone_id" {
value = aws_route53_zone.business.id
}
From the only resource we have created, we get it's id. I am just advancing you that we will
need that.
Tags are kind of very important. It's extremely useful to know which resources are managed
by terraform, (all of them, right?!) and tags is a very human readably way to know that
when you are navigating on the AWS web console.
I said in part1 that there might be a way, on the provider.tf, to add default tags to all the
resources created using terraform apply, but I haven't googled that yet, nor try it, so get
used to see many "tags = var/local.tags" in my code.
EDIT:
The way to add default tags is... no, I haven't googled that yet. But saving the space for
when I do...
About files
To have a file for variables, outputs, and others is some kind of unwritten convention (I think).
I largely stole it from the book. It's useful, you don't really want to jam everything in a
single file, but sometimes I have the feeling it might not be the most useful way to break down
the resources.
A file for variables and for outputs makes a lot of sense. But you might see on other modules
somewhere the division for type of resources, and sometimes that makes for some complicated
understanding, especially when resources depend on each other, and they are located in
different files.
Call our module
Now that we have our first module, let's use it.
Let's begin with the staging environment, we will create some files that will resemble a
module:
└── staging
├── datasources.tf
├── main.tf
├── providers.tf
└── variables.tf
Let's just ignore datasources.tf for now.
If you remember from the last post, on providers.tf we will put some boilerplate code that
we are gonna use terraform:
terraform {
required_version = ">= 1.0.6"
backend "s3" {
}
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 3.0"
}
}
}
provider "aws" {
region = "eu-west-3"
}
The file is basically a copy of the "global" one. (We will add something different here
on the next post).
That might "smell" to some people. Isn't there no way to avoid writing the exact same?
actually there is, with TerraGrunt (explained in the book). For our small infra, though,
we will just accept it. We do need though this file, because we are going to have a main.tf
here, because we gonna have a tf.state that will manage just this part of our Infra.
And the important part about it is that we want this tf.state to manage just this and only
this part of our infra, without ever touching other parts of other infra. We don't want a deploy
to staging to touch any resource that belong to production! That tf state should not even
know that there is an infra for prod. And that's what we are doing by separating our IaC
in this file structure and by "duplicating" this providers.tf (we could actually
change it, but the point of staging is to try things before prod, so you want staging as
similar as possible to prod.)
All right, enough excuses, let's go with the main.tf:
The concept goes like this: on our environment, staging/production, we decide we want
to have a domain called X. So let's try to code that intention.
main.tf:
module "route53" {
source = "../modules/route53"
environment = var.environment
domain = var.domain
}
we add a "resource" which is actually a whole module. Now we pass it what the module input
requires, the environment and the domain. The source has to be there always.
Since we will use this domain and this environment quite often, we made them variables too.
In this case, more than inputs, they are actually that, variables, well, I'd rather call
them "constants" but let's not make it more complicated.
variables.tf
variable "environment" {
description = "The name for the environment, usually staging, production or development."
default = "staging"
}
variable "domain" {
description = "Main DNS Domain"
default = "staging.mycompany.com"
}
you might realize I cope paste descriptions.
Call it from production
Let's mimic the same for production:
├── production
│ ├── datasources.tf
│ ├── main.tf
│ ├── providers.tf
│ └── variables.tf
the providers.tf is the exact same. The main.tf?
main.tf
module "route53" {
source = "../modules/route53"
environment = var.environment
domain = var.domain
}
well for this small module, it's the exact same code, but the variables of course are different:
variables.tf
variable "environment" {
description = "The name for the environment, usually staging, production or development."
default = "production"
}
variable "domain" {
description = "Main DNS Domain"
default = "company.com"
}
So we have our prod and infra base IaC in place!
Trying it out from localhost
As we tried our "global" part, we do a shortcut and use the makefile to be able
to execute our terraform code. This will actually be executed by the pipeline, yet to
be explained.
What I might not have explained properly is that on the makefile, we want to make sure
that we will use the tf.state file that the same pipeline is gonna use.
And that we need to swear on a very cute cat and a dog that we will be responsible when doing
things from our local. We should strive to let the pipeline do the job. We are just
adding this shortcut because our company has only one employee and can do and undo as they
sees fit.
(on a small note, we can avoid dealing with tf state lock logic - which should be easy to add
but I am not explaining it here- if we are sure that all the deploys are done by the pipeline,
single sequential pipelines,
and not by random devs at random, often conflicting, times)
Let's add this new 2 entries in our Makefile:
plan-staging:
cd terraform/staging; export AWS_PROFILE=company-terraform; terraform init \
-backend-config="bucket=company-infra" \
-backend-config="key=infrastructure/staging/terraform.tfstate" \
-backend-config="region=eu-west-3"; \
terraform plan
plan-production:
cd terraform/production; export AWS_PROFILE=company-terraform; terraform init \
-backend-config="bucket=company-infra" \
-backend-config="key=infrastructure/production/terraform.tfstate" \
-backend-config="region=eu-west-3"; \
terraform plan
See that we are using two different state files for prod and staging. We are using the
same bucket we created (manually) for the global infra. No need to create another one.
You can now see what would happen if you execute make plan-staging.
The output should be something like this:
Terraform will perform the following actions:
# module.route53.aws_route53_zone.business will be created
+ resource "aws_route53_zone" "business" {
+ arn = (known after apply)
+ comment = "Managed by Terraform"
+ force_destroy = false
+ id = (known after apply)
+ name = "staging.company.com"
+ name_servers = (known after apply)
+ tags = {
+ "Environment" = "Staging"
+ "Terraform" = "True"
}
+ tags_all = {
+ "Environment" = "Staging"
+ "Terraform" = "True"
}
+ zone_id = (known after apply)
}
Plan: 1 to add, 0 to change, 0 to destroy.
Let's just add two more entries in the Makefile:
deploy-staging:
cd terraform/staging; export AWS_PROFILE=company-terraform; terraform init \
-backend-config="bucket=company-infra" \
-backend-config="key=infrastructure/staging/terraform.tfstate" \
-backend-config="region=eu-west-3"; \
terraform apply
deploy-production:
cd terraform/production; export AWS_PROFILE=company-terraform; terraform init \
-backend-config="bucket=company-infra" \
-backend-config="key=infrastructure/production/terraform.tfstate" \
-backend-config="region=eu-west-3"; \
terraform apply
Just for this once, you may want to execute and say 'yes' at the prompt. I mean, it's just
a resource, not a lot of harm! (you may also want to add an entry with terraform destroy action)
You can go to AWS console, the route53 service, and you will see listed your recently
created hosted zones by terraform. And you didn't even do a single mouse click! (mouse
are for noobs, keyboards for pros!)
All right on the next chapter we will do a module with more consistency. You have the basics
here though to do whatever you want already!
