Terraform Provider: TLS

The TLS provider provides utilities for working with Transport Layer Security (TLS) keys and certificates (also known as SSL). It allows you to create private keys, certificates, and certificate requests as part of a Terraform deployment.

While the provider is often used in conjunction with other providers (e.g., passing a generated certificate to an AWS IAM resource), it is primarily used to provision the cryptographic material required for TLS services.

The tls_private_key ephemeral resource creates a secure private key encoded in PEM (RFC 1421) and OpenSSH PEM (RFC 4716) formats.

Primary Use Case: Use this ephemeral resource in combination with a write-only argument in a managed resource (a feature introduced in Terraform 1.11). This pattern prevents Terraform from storing the sensitive private key data in your plan or state files, significantly improving security.

Note: If the resource you are interacting with does not support a write-only argument for the private key, you should use the standard managed resource variant of tls_private_key instead.

Resources like tls_private_key are marked as sensitive to prevent accidental leakage in logs. However, the values (including secrets) are stored unencrypted in the Terraform state file.

Recommendations:

• Production Use: Using these resources for production deployments is not recommended due to the unencrypted state storage.
• Mitigation: If you must use them, strongly protect the content of your Terraform state file.
• Best Practice: Generate secrets outside of Terraform and distribute them securely to the systems that require them.

The tls_locally_signed_cert resource supports a mechanism for automatic renewal.

An instance is considered ready for renewal (setting ready_for_renewal to true) when:

1. The validity_period_hours has elapsed (the certificate is expired).
2. The current time is within the early_renewal_hours window before actual expiration.

When ready_for_renewal is true, applying the Terraform configuration will trigger the generation of a new certificate. This is particularly useful in development environments to ensure certificates are rotated automatically before they expire.

Warning: Because this resource does not support certificate revocation, the old certificate remains valid until its true expiration time. Additionally, updating the certificate may cause dependent resources to be replaced depending on their lifecycle rules.

For security-sensitive workflows, you can use the write-only argument private_key_pem_wo (available in Terraform 1.11+). Unlike the standard private_key_pem, the value provided to private_key_pem_wo is never stored in the Terraform state file.

To rotate the key using this method:

1. Set private_key_pem_wo to your new PEM key.
2. Increment the private_key_pem_wo_version number. This version is the only signal the provider uses to detect that the write-only key has changed and triggers a re-issue.

resource "tls_self_signed_cert" "example" {
  # Use write-only version to avoid storing key in state
  private_key_pem_wo        = file("new_private_key.pem")
  private_key_pem_wo_version = 2 

  # ... other required arguments ...
}

The tls_private_key ephemeral resource generates a secure private key in PEM and OpenSSH formats.

Primary Use Case: Use this resource in combination with a write-only argument in a managed resource (a feature introduced in Terraform 1.11). This pattern prevents the private key data from being stored in your Terraform plan or state file, significantly improving security.

If a managed resource does not support a write-only argument for a private key, you must use the standard managed resource variant of tls_private_key instead of this ephemeral version.

# Example of an ephemeral ECDSA key
ephemeral "tls_private_key" "ecdsa-p384-example" {
  algorithm   = "ECDSA"
  ecdsa_curve = "P384"
}

The tls_self_signed_cert resource supports automatic renewal via the readyForRenewal attribute and the earlyRenewalHours configuration.

1. Trigger: The resource becomes readyForRenewal = true when the certificate expires (based on validityPeriodHours) OR when the current time falls within the earlyRenewalHours window before actual expiry.
2. Action: When readyForRenewal is true, applying the Terraform configuration will cause a new certificate to be generated.
3. Usage: This is useful in development environments to automatically provision new certificates before the old ones expire.

Note: This does not support certificate revocation. The old certificate remains valid until its true expiration time. Applying the update only works if the Terraform configuration is applied during the early renewal period.

When using the write-only private key argument private_key_pem_wo (available in Terraform 1.11+), the key value is not stored in the Terraform state. To trigger a re-issuance of the Certificate Signing Request (CSR) when you rotate the key, you must manually increment the private_key_pem_wo_version number. This version acts as the signal to the provider that the key has changed.

resource "tls_cert_request" "example" {
  private_key_pem_wo          = var.new_private_key
  private_key_pem_wo_version  = 2 # Increment this to rotate the key

  subject {
    common_name = "example.com"
  }
}

The tls_self_signed_cert resource supports automatic renewal to facilitate frequent deployments in development environments.

Renewal is triggered when the ready_for_renewal attribute becomes true. This happens under two conditions:

1. The certificate has expired (exceeded validity_period_hours).
2. The certificate has entered the early renewal period (within early_renewal_hours of expiry).

When ready_for_renewal is true, applying the Terraform configuration will generate a new certificate. Note that applying a new certificate may cause dependent resources to be updated or replaced depending on their lifecycle rules.

The tls_certificate data source allows you to retrieve information about the TLS certificates securing a host. You can use it to extract details like the SHA1 fingerprint, serial number, or issuer information.

You can provide the certificate information in one of two ways:

1. Via URL: Provide a url to fetch certificates from a live website. This method supports verify_chain to validate the certificate chain.
2. Via Content: Provide the raw certificate content in PEM (RFC 1421) format using the content argument.

Note: You cannot use both url and content in the same data source block. If using url, you can also set verify_chain (defaults to true).

data "tls_certificate" "example" {
  url = "https://example.com"
}

# OR

data "tls_certificate" "example_content" {
  content = file("example.pem")
}

The LocallySignedCert resource supports automatic renewal via the readyForRenewal attribute.

An instance is considered ready for renewal if:

1. The certificate has expired (exceeded validityPeriodHours).
2. The certificate is within the earlyRenewalHours window before its actual expiration.

When readyForRenewal is true, applying the Terraform configuration will trigger the generation of a new certificate. This is useful in development environments to ensure certificates are rotated before they expire.

Warning: This resource does not support certificate revocation. The old certificate remains valid until its true expiration time.