https://github.com/andreswebs/terraform-aws-ec2-userdata-ad-join
Generates a user-data script for dynamically joining and un-joining Windows EC2 instances to an Active Directory domain
https://github.com/andreswebs/terraform-aws-ec2-userdata-ad-join
aws ec2 terraform-module
Last synced: about 1 year ago
JSON representation
Generates a user-data script for dynamically joining and un-joining Windows EC2 instances to an Active Directory domain
- Host: GitHub
- URL: https://github.com/andreswebs/terraform-aws-ec2-userdata-ad-join
- Owner: andreswebs
- License: unlicense
- Created: 2022-01-25T15:13:47.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-17T11:14:25.000Z (about 2 years ago)
- Last Synced: 2025-03-27T20:40:27.996Z (over 1 year ago)
- Topics: aws, ec2, terraform-module
- Language: HCL
- Homepage: https://registry.terraform.io/modules/andreswebs/ec2-userdata-ad-join/aws/latest
- Size: 20.5 KB
- Stars: 3
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# terraform-aws-ec2-userdata-ad-join
Generates a user-data script for dynamically joining and un-joining Windows EC2 instances to an Active Directory domain.
## Configuration
The user-data script will fetch configuration values from SSM parameters. These parameters are assumed to already exist in the environment.
Default parameter names used by the module are:
- `/ad-join/domain`
- `/ad-join/username`
- `/ad-join/password`
- `/ad-join/dns-servers`
The parameter names are configured from Terraform variables. (See the input values below.)
The "username" and "password" parameters must contain credentials from an AD user with enough permissions to join machines to the domain.
## IAM permissions
The user-data script assumes that the EC2 instance role has the proper permissions to access these parameters.
The following IAM policy is an example that can be adapted and added to the instance role to accomplish that.
Replace `${AWS_REGION}` and `${AWS_ACCOUNT_ID}` with the correct values for the environment.
This example assumes that the parameter prefix for AD configurations is `/ad`:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetParameter",
"ssm:GetParameters",
"ssm:GetParametersByPath",
"ssm:GetParameterHistory"
],
"Resource": "arn:aws:ssm:${AWS_REGION}:${AWS_ACCOUNT_ID}:parameter/ad/*"
}
]
}
```
[//]: # (BEGIN_TF_DOCS)
## Usage
Example:
```hcl
data "aws_ami" "windows" {
most_recent = true
filter {
name = "name"
values = ["Windows_Server-2019-English-Full-Base-*"]
}
filter {
name = "virtualization-type"
values = ["hvm"]
}
owners = ["801119661308"]
}
module "ec2_role" {
source = "andreswebs/ec2-role/aws"
version = "1.0.0"
role_name = var.name
profile_name = var.name
policies = [
"arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore",
"arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy",
"arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess"
]
}
module "params_access" {
source = "andreswebs/ssm-parameters-access-policy-document/aws"
version = "1.0.0"
parameter_names = [var.ad_ssm_prefix]
}
resource "aws_iam_role_policy" "params_access" {
name = "params-access"
role = module.ec2_role.role.name
policy = module.params_access.json
}
#############################
## Use the module like this:
#############################
module "user_data" {
source = "github.com/andreswebs/terraform-aws-ec2-userdata-ad-join"
ad_ssm_prefix = var.ad_ssm_prefix
}
resource "aws_instance" "windows" {
ami = data.aws_ami.windows.id
iam_instance_profile = module.ec2_role.instance_profile.name ## <-- Make sure the instance has proper permissions
instance_type = "t3a.xlarge"
user_data_base64 = module.user_data.b64 ## <-- Use the module
tags = {
Name = "example-windows-server"
}
lifecycle {
ignore_changes = [ami, tags]
}
}
```
## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| [ad\_ssm\_parameter\_name\_dns\_servers](#input\_ad\_ssm\_parameter\_name\_dns\_servers) | Name suffix of the SSM parameter containing the AD domain controller IPs (DNS servers) | `string` | `"/dns-servers"` | no |
| [ad\_ssm\_parameter\_name\_domain](#input\_ad\_ssm\_parameter\_name\_domain) | Name suffix of the SSM parameter containing the AD domain name | `string` | `"/domain"` | no |
| [ad\_ssm\_parameter\_name\_password](#input\_ad\_ssm\_parameter\_name\_password) | Name suffix of the SSM parameter containing the AD password | `string` | `"/password"` | no |
| [ad\_ssm\_parameter\_name\_username](#input\_ad\_ssm\_parameter\_name\_username) | Name suffix of the SSM parameter containing the AD username | `string` | `"/username"` | no |
| [ad\_ssm\_prefix](#input\_ad\_ssm\_prefix) | SSM parameter prefix for AD configurations | `string` | `"/ad-join"` | no |
| [log\_group](#input\_log\_group) | Name of the log group to log user-data output | `string` | `"/windows"` | no |
| [log\_retention\_in\_days](#input\_log\_retention\_in\_days) | Log retention in days | `number` | `30` | no |
## Modules
No modules.
## Outputs
| Name | Description |
|------|-------------|
| [b64](#output\_b64) | Base64-encoded user-data script |
| [script](#output\_script) | The user-data script |
## Providers
No providers.
## Requirements
| Name | Version |
|------|---------|
| [terraform](#requirement\_terraform) | >= 1.0.0 |
| [aws](#requirement\_aws) | >= 3.50.0 |
## Resources
No resources.
[//]: # (END_TF_DOCS)
## Authors
**Andre Silva** - [@andreswebs](https://github.com/andreswebs)
## License
This project is licensed under the [Unlicense](UNLICENSE.md).
## References