Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/launchbynttdata/tf-aws-module_primitive-acmpca_certificate_authority_certificate


https://github.com/launchbynttdata/tf-aws-module_primitive-acmpca_certificate_authority_certificate

Last synced: 15 days ago
JSON representation

Awesome Lists containing this project

README 

          
# tf-aws-module_primitive-acmpca_certificate_authority_certificate



[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![Terraform](https://img.shields.io/badge/terraform-1.5.x-623CE4.svg)](https://www.terraform.io)



## Overview



This Terraform module provides a primitive wrapper around the `aws_acmpca_certificate_authority_certificate` resource, which installs a certificate on an AWS Certificate Manager Private Certificate Authority (ACM PCA).



This resource is used to associate a CA certificate with a Private Certificate Authority. This is typically used after issuing a certificate for the CA using the `aws_acmpca_certificate` resource.



## Features



- **Simple Installation**: Install CA certificates on ACM Private Certificate Authorities

- **Root and Subordinate CA Support**: Works with both root and subordinate Certificate Authorities

- **Certificate Chain Management**: Optional certificate chain for subordinate CAs

- **Full Resource Access**: All resource attributes exposed as outputs

- **Comprehensive Testing**: Validates actual AWS resource state using AWS SDK



## Usage



### Basic Example



```hcl

module "certificate_authority_certificate" {

  source = "launchbynttdata/module_primitive-acmpca_certificate_authority_certificate/aws"



  certificate_authority_arn = aws_acmpca_certificate_authority.example.arn

  certificate               = aws_acmpca_certificate.example.certificate

  certificate_chain         = aws_acmpca_certificate.example.certificate_chain # Optional, for subordinate CAs

}

```



### Complete Example with Root CA



See [examples/simple](examples/simple/) for a complete working example that creates a test Certificate Authority and installs a certificate on it.



## When to Use This Module



Use this module when you need to:



- Install a CA certificate on an ACM Private Certificate Authority

- Complete the setup of a new Certificate Authority after issuing its certificate

- Manage CA certificates separately from CA creation for better modularity



## Prerequisites



- An existing AWS Certificate Manager Private Certificate Authority

- A certificate issued for that Certificate Authority (using `aws_acmpca_certificate`)



---



## What is a Primitive Module?



A **primitive module** is a thin, focused Terraform wrapper around a single AWS resource type. Primitive modules:



- Wrap a **single AWS resource** (in this case, `aws_acmpca_certificate_authority_certificate`)

- Provide sensible defaults while maintaining full configurability

- Follow consistent patterns for inputs, outputs, and validation

- Include automated testing using Terratest

- Serve as building blocks for higher-level composite modules



---



## Getting Started with Development



### 1. Create Your New Module Repository



1. Click the "Use this template" button on GitHub

2. Name your repository following the naming convention: `tf-aws-module_primitive-`

   - Examples: `tf-aws-module_primitive-s3_bucket`, `tf-aws-module_primitive-lambda_function`

3. Clone your new repository locally



### 2. Initialize and Clean Up Template References



After cloning, run the cleanup target to update template references with your actual repository information:



```bash

make init-module

```



This command will:



- Update the `go.mod` file with your repository's GitHub URL

- Update test imports to reference your new module name

- Remove template-specific placeholders



### 3. Configure Your Environment



Install required development dependencies:



```bash

make configure-dependencies

make configure-git-hooks

```



This installs:



- Terraform

- Go

- Pre-commit hooks

- Other development tools specified in `.tool-versions`



---



## HOWTO: Developing a Primitive Module



### Step 1: Define Your Resource



1. **Identify the AWS resource** you're wrapping (e.g., `aws_eks_cluster`)

2. **Review AWS documentation** for the resource to understand all available parameters

3. **Study similar primitive modules** for patterns and best practices



### Step 2: Create the Module Structure



Your primitive module should include these core files:



#### `main.tf`



- Contains the primary resource declaration

- Should be clean and focused on the single resource

- Example:



```hcl

resource "aws_eks_cluster" "this" {

  name     = var.name

  role_arn = var.role_arn

  version  = var.kubernetes_version



  vpc_config {

    subnet_ids              = var.vpc_config.subnet_ids

    security_group_ids      = var.vpc_config.security_group_ids

    endpoint_private_access = var.vpc_config.endpoint_private_access

    endpoint_public_access  = var.vpc_config.endpoint_public_access

    public_access_cidrs     = var.vpc_config.public_access_cidrs

  }



  tags = merge(

    var.tags,

    local.default_tags

  )

}

```



#### `variables.tf`



- Define all configurable parameters

- Include clear descriptions for each variable

- Set sensible defaults where appropriate

- Use validation rules to enforce constraints, but only when the validations can be made precise.

- Alternatively, use [`check`](https://developer.hashicorp.com/terraform/language/block/check) blocks to create more complicated validations. (Requires terraform ~> 1.12)

- Example:



```hcl

variable "name" {

  description = "Name of the EKS cluster"

  type        = string



  validation {

    condition     = length(var.name) <= 100

    error_message = "Cluster name must be 100 characters or less"

  }

}



variable "kubernetes_version" {

  description = "Kubernetes version to use for the EKS cluster"

  type        = string

  default     = null



  validation {

    condition     = var.kubernetes_version == null || can(regex("^1\\.(2[89]|[3-9][0-9])$", var.kubernetes_version))

    error_message = "Kubernetes version must be 1.28 or higher"

  }

}

```



#### `outputs.tf`



- Export all useful attributes of the resource

- Include comprehensive outputs for downstream consumption

- Document what each output provides

- Example:



```hcl

output "id" {

  description = "The ID of the EKS cluster"

  value       = aws_eks_cluster.this.id

}



output "arn" {

  description = "The ARN of the EKS cluster"

  value       = aws_eks_cluster.this.arn

}



output "endpoint" {

  description = "The endpoint for the EKS cluster API server"

  value       = aws_eks_cluster.this.endpoint

}

```



#### `locals.tf`



- Define local values and transformations

- Include standard tags (e.g., `provisioner = "Terraform"`)

- Example:



```hcl

locals {

  default_tags = {

    provisioner = "Terraform"

  }

}

```



#### `versions.tf`



- Specify required Terraform and provider versions

- Example:



```hcl

terraform {

  required_version = "~> 1.5"



  required_providers {

    aws = {

      source  = "hashicorp/aws"

      version = "~> 5.100"

    }

  }

}

```



### Step 3: Create Examples



Create example configurations in the `examples/` directory:



#### `examples/simple/`



- Minimal, working configuration

- Uses only required variables

- Good for quick starts and basic testing



#### `examples/complete/`



- Comprehensive configuration showing all features

- Demonstrates advanced options

- Includes comments explaining choices



Each example should include:



- `main.tf` - The module invocation

- `variables.tf` - Example variables

- `outputs.tf` - Pass-through outputs

- `test.tfvars` - Test values for automated testing

- `README.md` - Documentation for the example



### Step 4: Write Tests



Update the test files in `tests/`:



#### `tests/testimpl/test_impl.go`



Write functional tests that verify:



- The resource is created successfully

- Resource properties match expectations

- Outputs are correct

- Integration with AWS SDK to verify actual state



#### `tests/testimpl/types.go`



Define the configuration structure for your tests:



```go

type ThisTFModuleConfig struct {

    Name              string `json:"name"`

    KubernetesVersion string `json:"kubernetes_version"`

    // ... other fields

}

```



#### `tests/post_deploy_functional/main_test.go`



- Update test names to match your module

- Configure test flags (e.g., idempotency settings)

- Adjust test context as needed



### Step 5: Update Documentation



1. **Update README.md** with:

   - Overview of the module

   - Feature list

   - Usage examples

   - Input/output documentation

   - Validation rules



2. **Document validation rules** clearly so users understand constraints.



### Step 6: Test Your Module



1. **Run local validation**:



```bash

make check

```



This runs:



- Terraform fmt, validate, and plan

- Go tests with Terratest

- Pre-commit hooks

- Security scans



1. **Test with real infrastructure**:



```bash

cd examples/simple

terraform init

terraform plan -var-file=test.tfvars -out=the.tfplan

terraform apply the.tfplan

```



1. **Verify outputs**:



```bash

terraform output

```



1. **Clean up**:



```bash

terraform destroy -var-file=test.tfvars

```



### Step 7: Document and Release



1. **Write a comprehensive README** following the pattern in the example modules

1. **Add files to commit** `git add .`

1. **Run pre-commit hooks manually** `pre-commit run`

1. **Resolve any pre-commit issues**

1. **Push branch to github**



---



## Module Best Practices



### Naming Conventions



- Repository: `tf-aws-module_primitive-`

- Resource identifier: Use `this` for the primary resource.

- Variables: Use snake_case.

- Match AWS resource parameter names where possible.



### Input Variables



- Provide sensible defaults when safe to do so.

- Use `null` as default for optional complex objects.

- Include validation rules with clear error messages.

- Group related parameters using object types.

- Document expected formats and constraints.



### Outputs



- Export all significant resource attributes.

- Use clear, descriptive output names.

- Include descriptions for all outputs.

- Consider downstream module needs.



### Tags



- Always include a `tags` variable, unless the resource does not support tags.

- Merge with `local.default_tags` including `provisioner = "Terraform"`.

- Use provider default tags when appropriate.



### Validation



- Validate input constraints at the variable level.

- Provide helpful error messages.

- Check for common misconfigurations.

- Validate relationships between variables.



### Testing



- Test the minimal example (required parameters only).

- Test the complete example (all features).

- Verify resource creation and properties.

- Test idempotency where applicable.

- Test validation rules by expecting failures.



### Documentation



- Clear overview of the module's purpose.

- Feature list highlighting key capabilities.

- Multiple usage examples (minimal and complete).

- Comprehensive input/output tables.

- Document validation rules and constraints.

- Include links to relevant AWS documentation.



---



## File Structure



After initialization, your module should have this structure:



```text

tf-aws-module_primitive-/

├── .github/

│   └── workflows/          # CI/CD workflows

├── examples/

│   ├── simple/            # Minimal example

│   │   ├── main.tf

│   │   ├── variables.tf

│   │   ├── outputs.tf

│   │   ├── test.tfvars

│   │   └── README.md

│   └── complete/          # Comprehensive example

│       ├── main.tf

│       ├── variables.tf

│       ├── outputs.tf

│       ├── test.tfvars

│       └── README.md

├── tests/

│   ├── post_deploy_functional/

│   │   └── main_test.go

│   ├── testimpl/

│   │   ├── test_impl.go

│   │   └── types.go

├── .gitignore

├── .pre-commit-config.yaml

├── .tool-versions

├── go.mod

├── go.sum

├── LICENSE

├── locals.tf

├── main.tf

├── Makefile

├── outputs.tf

├── README.md

├── variables.tf

└── versions.tf

```



---



## Common Makefile Targets



| Target | Description |

|--------|-------------|

| `make init-module` | Initialize new module from template (run once after creating from template) |

| `make configure-dependencies` | Install required development tools |

| `make configure-git-hooks` | Set up pre-commit hooks |

| `make check` | Run all validation and tests |

| `make configure` | Full setup (dependencies + hooks + repo sync) |

| `make clean` | Remove downloaded components |



---



## Getting Help



- Review example modules: [EKS Cluster](https://github.com/launchbynttdata/tf-aws-module_primitive-eks_cluster), [KMS Key](https://github.com/launchbynttdata/tf-aws-module_primitive-kms_key)

- Check the Launch Common Automation Framework documentation.

- Reach out to the platform team for guidance.



---



## Contributing



Follow the established patterns in existing primitive modules. All modules should:



- Pass `make check` validation.

- Include comprehensive tests.

- Follow naming conventions.

- Include clear documentation.

- Use semantic versioning.



## Requirements



| Name | Version |

|------|---------|

|  [terraform](#requirement\_terraform) | ~> 1.5 |

|  [aws](#requirement\_aws) | ~> 5.100 |



## Modules



No modules.



## Resources



| Name | Type |

|------|------|

| [aws_acmpca_certificate_authority_certificate.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/acmpca_certificate_authority_certificate) | resource |



## Inputs



| Name | Description | Type | Default | Required |

|------|-------------|------|---------|:--------:|

|  [certificate](#input\_certificate) | (Required) PEM-encoded certificate for the Certificate Authority. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/acmpca_certificate_authority_certificate#certificate | `string` | n/a | yes |

|  [certificate\_authority\_arn](#input\_certificate\_authority\_arn) | (Required) ARN of the Certificate Authority. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/acmpca_certificate_authority_certificate#certificate_authority_arn | `string` | n/a | yes |

|  [certificate\_chain](#input\_certificate\_chain) | (Optional) PEM-encoded certificate chain that includes any intermediate certificates and chains up to root CA. Required for subordinate Certificate Authorities. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/acmpca_certificate_authority_certificate#certificate_chain | `string` | `null` | no |



## Outputs



| Name | Description |

|------|-------------|

|  [certificate](#output\_certificate) | PEM-encoded certificate for the Certificate Authority |

|  [certificate\_authority\_arn](#output\_certificate\_authority\_arn) | ARN of the Certificate Authority |

|  [certificate\_chain](#output\_certificate\_chain) | PEM-encoded certificate chain |

|  [id](#output\_id) | Certificate Authority ARN (same as certificate\_authority\_arn) |