From 5b62d534f2a6e7d3ca83e381b6835c4c057c1ba0 Mon Sep 17 00:00:00 2001 From: badra001 Date: Fri, 5 Jan 2024 14:26:47 -0500 Subject: [PATCH] update --- acmpca/README.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 acmpca/README.md diff --git a/acmpca/README.md b/acmpca/README.md new file mode 100644 index 0000000..59902fc --- /dev/null +++ b/acmpca/README.md @@ -0,0 +1,122 @@ + +# About : aws-certificate/acmpca + +This module creates an ACM certificate, using the general purpose (ca1) ACM-PCA or short term (ca2) in the local region. It will automatically +include the DNS name in the SAN. You may add additonal SAN fully qualified domain names, URIs, or +in the SAN for an ACM certificate. The [CLI documentation](https://docs.aws.amazon.com/cli/latest/reference/acm-pca/issue-certificate.html) indicates +you can use any of the standard types for a SAN (DNS, URI, email, DNS, etc.) along with the [API](https://docs.aws.amazon.com/privateca/latest/APIReference/API_IssueCertificate.html) +reference. Other documentation states otherwise (TBD -- find link). + +It expects an SSM parameter `/enterprise/pki/ca1` for general purpose and `/enterprise/pki/ca2` for short term CA to exist in the account (distributed to all OUs from a central account). +If this parameter does not exist, this module will fail. + +It returns: + +# Usage +This shows the module call with how you would use it. + +```hcl +module "cert" { + source = "git@github.e.it.census.gov:terraform-modules/aws-certificates//acm" + + certificate_dns = "test.domain.census.gov" + contact_email = "cio.engineering.alert.list@census.gov" + + ## optional + ## add additional names to SAN + # certificate_san = [ "otherdomain.domain.census.gov" ] +} + +# associating it with the ALB listener +resource "aws_lb_listener" "app_443" { + count = module.cert.certificate_arn != null ? 1 : 0 + load_balancer_arn = aws_lb.app.arn + port = 443 + protocol = "HTTPS" + ssl_policy = "ELBSecurityPolicy-TLS-1-2-2017-01" + certificate_arn = module.cert.certificate_arn + + default_action { + type = "forward" + target_group_arn = aws_lb_target_group.app.arn + } +} +``` + +The output value to look at is `certificate_arn`. This is null if the certificate is incomplete or failed to load into ACM, or +the ARN if completed. You'll use the ARN for an AWS LB Listener. + +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 0.14 | +| [aws](#requirement\_aws) | >= 5.0 | +| [local](#requirement\_local) | >= 2.1.0 | +| [null](#requirement\_null) | >= 3.1.0 | +| [tls](#requirement\_tls) | >= 3.1.0 | + +## Providers + +| Name | Version | +|------|---------| +| [aws](#provider\_aws) | >= 5.0 | +| [local](#provider\_local) | >= 2.1.0 | +| [null](#provider\_null) | >= 3.1.0 | +| [tls](#provider\_tls) | >= 3.1.0 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [aws_acmpca_certificate.certificate](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/acmpca_certificate) | resource | +| [local_sensitive_file.certificate_cert](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/sensitive_file) | resource | +| [local_sensitive_file.certificate_cert_chain](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/sensitive_file) | resource | +| [local_sensitive_file.certificate_csr](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/sensitive_file) | resource | +| [local_sensitive_file.certificate_key](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/sensitive_file) | resource | +| [null_source.output_directory](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/source) | resource | +| [tls_cert_request.certificate](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/cert_request) | resource | +| [tls_private_key.certificate](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/resources/private_key) | resource | +| [aws_arn.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/arn) | data source | +| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source | +| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source | +| [aws_ssm_parameter.ca_longterm](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | data source | +| [aws_ssm_parameter.ca_shortterm](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | data source | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [account\_alias](#input\_account\_alias) | AWS Account Alias | `string` | `""` | no | +| [account\_id](#input\_account\_id) | AWS Account ID (default will pull from current user) | `string` | `""` | no | +| [certificate\_authority\_mode](#input\_certificate\_authority\_mode) | String indicating whether to use the general purpose (general) or short lived (short) CA (general is ca1, short lived is ca2) | `string` | `"general"` | no | +| [certificate\_authority\_template](#input\_certificate\_authority\_template) | String indicating which specific ACMPCA template to use | `string` | `null` | no | +| [certificate\_cn](#input\_certificate\_cn) | CommonName (CN) to use for certificate, defaults in c=US,o=U.S. Census Bureau,ou=Servers. This will typically be the DNS name. Uses certificate\_dns if not provided. | `string` | `null` | no | +| [certificate\_dns](#input\_certificate\_dns) | DNS Name to be used for the certificate. For ACM certificate, the subject and CN may not be customized. | `string` | n/a | yes | +| [certificate\_filename](#input\_certificate\_filename) | Filename for Certificate. Defaults to {certificate\_dns}.crt | `string` | `null` | no | +| [certificate\_san](#input\_certificate\_san) | The Subject Alternate Names (SAN), a list of FQDNs to include in the ACM Certificate. Only DNS names are supported. See docs at https://docs.aws.amazon.com/cli/latest/reference/acm/request-certificate.html | `list(string)` | `[]` | no | +| [certificate\_subject\_overrides](#input\_certificate\_subject\_overrides) | Map of c, o, and ou to override certificate signing request settings. Note that only a single OU is permitted. | `map(string)` | `{}` | no | +| [certificate\_type](#input\_certificate\_type) | Selection of type of certificate, either end-entity or subordinate-ca. Note that the subordinate-ca type is not available for the short lived CA mode | `string` | `"end-entity"` | no | +| [contact\_email](#input\_contact\_email) | Email address in @census.gov of contact for the certificate. This is strongly recommended to be a group email address. | `string` | n/a | yes | +| [create\_files](#input\_create\_files) | Flag controlling the creation of output files for the key, CSR, and certificate and bundle. | `bool` | `false` | no | +| [csr\_filename](#input\_csr\_filename) | Filename for Certificate Signing Request (CSR). Defaults to {certificate\_dns}.csr | `string` | `null` | no | +| [key\_filename](#input\_key\_filename) | Filename for RSA private key. Defaults to {certificate\_dns}.key | `string` | `null` | no | +| [output\_file\_directory](#input\_output\_file\_directory) | File path for resultant files when create\_files is used. Defaults to path.root/certs | `string` | `null` | no | +| [override\_prefixes](#input\_override\_prefixes) | Override built-in prefixes by component. This should be used primarily for common infrastructure things | `map(string)` | `{}` | no | +| [tags](#input\_tags) | AWS Tags to apply to appropriate resources | `map(string)` | `{}` | no | +| [validity\_days](#input\_validity\_days) | Number of days for which the certificate is valid. For the short lived certificate, this must be <= 7 | `number` | `365` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| [certificate](#output\_certificate) | PEM format for signed certificate | +| [certificate\_chain](#output\_certificate\_chain) | PEM format for certificate chain (issuer through root) | +| [certificate\_csr](#output\_certificate\_csr) | PEM format Certificate Signing Request | +| [certificate\_files](#output\_certificate\_files) | Map of certificate file names | +| [certificate\_key](#output\_certificate\_key) | PEM format RSA Key | + \ No newline at end of file