Skip to content

Resource: awsAcmCertificate

The ACM certificate resource allows requesting and management of certificates from the Amazon Certificate Manager.

ACM certificates can be created in three ways: Amazon-issued, where AWS provides the certificate authority and automatically manages renewal; imported certificates, issued by another certificate authority; and private certificates, issued using an ACM Private Certificate Authority.

Amazon-Issued Certificates

For Amazon-issued certificates, this resource deals with requesting certificates and managing their attributes and life-cycle. This resource does not deal with validation of a certificate but can provide inputs for other resources implementing the validation. It does not wait for a certificate to be issued. Use a awsAcmCertificateValidation resource for this.

Most commonly, this resource is used together with awsRoute53Record and awsAcmCertificateValidation to request a DNS validated certificate, deploy the required validation records and wait for validation to complete.

Domain validation through email is also supported but should be avoided as it requires a manual step outside of Terraform.

It's recommended to specify createBeforeDestroy =True in a lifecycle block to replace a certificate which is currently in use (eg, by awsLbListener).

Certificates Imported from Other Certificate Authority

Imported certificates can be used to make certificates created with an external certificate authority available for AWS services.

As they are not managed by AWS, imported certificates are not eligible for automatic renewal. New certificate materials can be supplied to an existing imported certificate to update it in place.

Private Certificates

Private certificates are issued by an ACM Private Cerificate Authority, which can be created using the resource type awsAcmpcaCertificateAuthority.

Private certificates created using this resource are eligible for managed renewal if they have been exported or associated with another AWS service. See managed renewal documentation for more information. By default, a certificate is valid for 395 days and the managed renewal process will start 60 days before expiration. To renew the certificate earlier than 60 days before expiration, configure earlyRenewalDuration.

Example Usage

Create Certificate

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsAcmCertificateCert = new aws.acmCertificate.AcmCertificate(
  this,
  "cert",
  {
    domainName: "example.com",
    tags: {
      Environment: "test",
    },
    validationMethod: "DNS",
  }
);
awsAcmCertificateCert.addOverride("lifecycle", [
  {
    create_before_destroy: true,
  },
]);

Custom Domain Validation Options

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.acmCertificate.AcmCertificate(this, "cert", {
  domainName: "testing.example.com",
  validationMethod: "EMAIL",
  validationOption: [
    {
      domainName: "testing.example.com",
      validationDomain: "example.com",
    },
  ],
});

Existing Certificate Body Import

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
import * as tls from "./.gen/providers/tls";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: tls.
For a more precise conversion please use the --provider flag in convert.*/
const tlsPrivateKeyExample = new tls.privateKey.PrivateKey(this, "example", {
  algorithm: "RSA",
});
const tlsSelfSignedCertExample = new tls.selfSignedCert.SelfSignedCert(
  this,
  "example_1",
  {
    allowed_uses: ["key_encipherment", "digital_signature", "server_auth"],
    key_algorithm: "RSA",
    private_key_pem: tlsPrivateKeyExample.privateKeyPem,
    subject: [
      {
        common_name: "example.com",
        organization: "ACME Examples, Inc",
      },
    ],
    validity_period_hours: 12,
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
tlsSelfSignedCertExample.overrideLogicalId("example");
new aws.acmCertificate.AcmCertificate(this, "cert", {
  certificateBody: tlsSelfSignedCertExample.certPem,
  privateKey: tlsPrivateKeyExample.privateKeyPem,
});

Referencing domain_validation_options With for_each Based Resources

See the awsAcmCertificateValidation resource for a full example of performing DNS validation.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsRoute53RecordExample = new aws.route53Record.Route53Record(
  this,
  "example",
  {
    allowOverwrite: true,
    name: "${each.value.name}",
    records: ["${each.value.record}"],
    ttl: 60,
    type: "${each.value.type}",
    zoneId: "${aws_route53_zone.example.zone_id}",
  }
);
/*In most cases loops should be handled in the programming language context and 
not inside of the Terraform context. If you are looping over something external, e.g. a variable or a file input
you should consider using a for loop. If you are looping over something only known to Terraform, e.g. a result of a data source
you need to keep this like it is.*/
awsRoute53RecordExample.addOverride(
  "for_each",
  "${{\n    for dvo in aws_acm_certificate.example.domain_validation_options : dvo.domain_name => {\n      name   = dvo.resource_record_name\n      record = dvo.resource_record_value\n      type   = dvo.resource_record_type\n    }\n  }}"
);

Argument Reference

The following arguments are supported:

  • Creating an Amazon issued certificate
  • domainName - (Required) Domain name for which the certificate should be issued
  • subjectAlternativeNames - (Optional) Set of domains that should be SANs in the issued certificate. To remove all elements of a previously configured list, set this value equal to an empty list ([]) or use the terraformTaint command to trigger recreation.
  • validationMethod - (Required) Which method to use for validation. dns or email are valid, none can be used for certificates that were imported into ACM and then into Terraform.
  • keyAlgorithm - (Optional) Specifies the algorithm of the public and private key pair that your Amazon issued certificate uses to encrypt data. See ACM Certificate characteristics for more details.
  • options - (Optional) Configuration block used to set certificate options. Detailed below.
  • validationOption - (Optional) Configuration block used to specify information about the initial validation of each domain name. Detailed below.
  • Importing an existing certificate
  • privateKey - (Required) Certificate's PEM-formatted private key
  • certificateBody - (Required) Certificate's PEM-formatted public key
  • certificateChain - (Optional) Certificate's PEM-formatted chain
  • Creating a private CA issued certificate
  • certificateAuthorityArn - (Required) ARN of an ACM PCA
  • domainName - (Required) Domain name for which the certificate should be issued.
  • earlyRenewalDuration - (Optional) Amount of time to start automatic renewal process before expiration. Has no effect if less than 60 days. Represented by either a subset of RFC 3339 duration supporting years, months, and days (e.g., p90D), or a string such as 2160H.
  • subjectAlternativeNames - (Optional) Set of domains that should be SANs in the issued certificate. To remove all elements of a previously configured list, set this value equal to an empty list ([]) or use the terraformTaint command to trigger recreation.
  • tags - (Optional) Map of tags to assign to the resource. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.

options Configuration Block

Supported nested arguments for the options configuration block:

  • certificateTransparencyLoggingPreference - (Optional) Whether certificate details should be added to a certificate transparency log. Valid values are enabled or disabled. See https://docs.aws.amazon.com/acm/latest/userguide/acm-concepts.html#concept-transparency for more details.

validation_option Configuration Block

Supported nested arguments for the validationOption configuration block:

  • domainName - (Required) Fully qualified domain name (FQDN) in the certificate.
  • validationDomain - (Required) Domain name that you want ACM to use to send you validation emails. This domain name is the suffix of the email addresses that you want ACM to use. This must be the same as the domainName value or a superdomain of the domainName value. For example, if you request a certificate for "testingExampleCom", you can specify "exampleCom" for this value.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • id - ARN of the certificate
  • arn - ARN of the certificate
  • domainName - Domain name for which the certificate is issued
  • domainValidationOptions - Set of domain validation objects which can be used to complete certificate validation. Can have more than one element, e.g., if SANs are defined. Only set if dns-validation was used.
  • notAfter - Expiration date and time of the certificate.
  • notBefore - Start of the validity period of the certificate.
  • pendingRenewal - true if a Private certificate eligible for managed renewal is within the earlyRenewalDuration period.
  • renewalEligibility - Whether the certificate is eligible for managed renewal.
  • renewalSummary - Contains information about the status of ACM's managed renewal for the certificate.
  • status - Status of the certificate.
  • type - Source of the certificate.
  • tagsAll - Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.
  • validationEmails - List of addresses that received a validation email. Only set if email validation was used.

Domain validation objects export the following attributes:

  • domainName - Domain to be validated
  • resourceRecordName - The name of the DNS record to create to validate the certificate
  • resourceRecordType - The type of DNS record to create
  • resourceRecordValue - The value the DNS record needs to have

Renewal summary objects export the following attributes:

  • renewalStatus - The status of ACM's managed renewal of the certificate
  • renewalStatusReason - The reason that a renewal request was unsuccessful or is pending

Import

Certificates can be imported using their ARN, e.g.,

$ terraform import aws_acm_certificate.cert arn:aws:acm:eu-central-1:123456789012:certificate/7e7a28d2-163f-4b8f-b9cd-822f96c08d6a