Using the Terraform package

This page describes how to issue and manage certificates using the Terraform package.

Running the Terraform commands

Once the terraform.auto.tfvars file is configured with customer specific values, you may interact with the Sectigo Terraform plugin by using the following commands:

terraform init: This command is used to initialize terraform-provider-sectigo provider. This command must be executed once after making the terraform-provider-sectigo file executable.
terraform plan: This command is used to create an execution plan. This command is a convenient way to check whether the execution plan for a set of changes matches your expectations without making any changes to the real resources or to the state. This command should be executed after any changes to configurable files (main.tf, output.tf, variable.tf, and terraform.auto.tfvars).
terraform apply: This command is used to apply the changes shown after running the terraform plan command.

If you add the -auto-approve option, this command will not ask for further approval.

After successfully executing this command, you should have a valid certificate inside the declared path location and file name in the terraform.auto.tvars file.
terraform destroy: This command is used to destroy the certificate. This will revoke the certificate from SCM, and the certificate will no longer be active. Execute this command only if you don’t want the certificate anymore.

If you add the option -auto-approve, then this command will not ask for user approval. For example, terraform destroy -auto-approve.

Certificate issuance

To issue a new certificate, run the terraform apply command. A certificate will be generated based on the parameters in the main.tf and terraform.auto.tfvars files.

To force issuance of a new certificate, change the values for the sectigo_*_cert_file_name and sectigo_*_cert_file_path parameters.

Certificate auto-renewal

If you run the terraform apply command, sectigo_auto_renew is true, and the existing certificate is about to expire within the specified sectigo_expiry_window, the package will discard the existing certificate and issue a new one.

When issuing a new certificate, the plugin will make use of user provided CSR (.csr) or the existing private key (.key) files if these are available. If there are no existing private key and CSR files, they will be generated by the plugin before issuing the certificate.

Certificate revocation

If you want to revoke the certificate, run the terraform destroy command. It will revoke the certificate from SCM.

Certificate auto replacement

Automatic certificate replacement is initiated when one of the following conditions are met:

A CSR value is provided by the user with the sectigo_csr parameter.
A value modification for any individual CSR, domain, or SANs parameters has taken place.

If either of the two conditions above are satisfied, run the terraform apply command to replace your certificate. The certificate replacement behavior is shown in the following diagram.

Logs

You can enable the Terraform logs by passing the TF_LOGS flag. The script also creates a sectigo_*_file_name.log file in the sectigo_*_cert_file_path corresponding to the certificate type.

Scenarios

Passing existing private key and CSR for creating first time certificate

If the .key and .csr files are provided, the package will use them instead of creating new ones. The certificate enrollment and download will proceed using the content from the provided .key and .csr files. The .key and .csr files must be present in the sectigo_*_cert_file_path location and the names should match the sectigo_*_cert_file_name parameter. The .crt file will be downloaded to the same location.

Terraform state file

The terraform.tfstate file is created after the first terraform apply command. This file contains all the information about the resources that are created and is the source of truth. This file must not be lost or deleted. All resource data will be lost if this file is unavailable.

This version only supports one set of resources per instance of the terraform.tfstate. This means that the one terraform.tfstate file will only contain details of one certificate instance. For example, the keyname, csrname, sslId, and status of one certificate.

In order to generate a new certificate, you need to provide a different path to the terraform.tfstate file.

terraform apply -state=<path_to_state_file>/terraform.tfstate

Single resource vs. multi-resource

The following sections provide a brief example of how the main.tf and output.tf files may look in a single resource or multi-resource context.

Single resource

The following are examples of the main.tf and output.tf files in a single resource context. Complete examples of the main.tf and output.tf files are provided as part of the package.

Sample single resource for main.tf

provider "sectigo" {
    username     = var.SECTIGO_CM_LOGIN
    password     = var.SECTIGO_CM_PWD
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
}
resource "sectigo_certificate" "ssl_certificate" {
    base_url       = var.sectigo_ssl_cert_cm_base_url
    orgid          = var.sectigo_cm_org_id

    cert_file_path = var.sectigo_ssl_cert_file_path
    cert_file_name = var.sectigo_ssl_cert_file_name
    cert_type      = var.sectigo_ssl_cert_type

# ...and so on.
}

Sample single resource for output.tf

output "ssl_domain" {
    value = "${sectigo_config.ssl_certificate.id}"
}
output "sectigo_ssl_cert_id" {
    value = "${sectigo_certificate.ssl_certificate.sectigo_ssl_cert_id}"
}
# ...and so on.

Multi-resource

This version supports multi-resource. The following are examples of the main.tf and output.tf files as a multi-resource context. Complete examples of the main.tf and output.tf files are provided as part of the package.

Sample multi-resource for main.tf

provider "sectigo" {
    username     = var.SECTIGO_CM_LOGIN
    password     = var.SECTIGO_CM_PWD
    customer_uri = var.SECTIGO_CM_CUSTOMERURI
}

resource "sectigo_certificate" "ssl_certificate" {
    base_url = var.sectigo_ssl_cert_cm_base_url
    orgid    = var.sectigo_cm_org_id

    cert_file_path = var.sectigo_ssl_cert_file_path
    cert_file_name = var.sectigo_ssl_cert_file_name
    cert_type      = var.sectigo_ssl_cert_type

# ...and so on.
}

resource "sectigo_certificate" "client_certificate" {
    base_url = var.sectigo_client_cert_cm_base_url
    orgid    = var.sectigo_cm_org_id

    client_file_path = var.sectigo_client_cert_file_path
    client_file_name = var.sectigo_client_cert_file_name
    cert_type        = var.sectigo_client_cert_type

# ...and so on.
}

Sample multi-resource for output.tf

output "ssl_domain" {
    value = "${sectigo_certificate.ssl_certificate.id}"
}

output "ssl-sectigo_ssl_id" {
    value = "${sectigo_certificate.ssl_certificate.sectigo_ssl_id}"
}
# ...and so on.

output "client_domain" {
    value = "${sectigo_certificate.client_certificate.id}"
}

output "client_sectigo_ssl_id" {
    value = "${sectigo_certificate.client_certificate.sectigo_ssl_id}"
}
# ... and so on.

Using the generated files

Once the execution is complete, the package will store the private key (.key), generated CSR (.csr) and certificate (.crt) files in the sectigo_*_cert_file_path folder that you provided. You can then make use of these files and configure the server manually.

The configuration of the server with these files is handled outside the scope of this package.

If the terraform apply command is run on the same server where the configuration needs to happen, you can specify the appropriate sectigo_*_cert_file_path that is mentioned in the server .config file to automate the process.

Using the generated files in NGINX

To demonstrate how the generated files can be used on a live server, a sample configuration for a basic NGINX server is provided. If you have a fresh installation of NGINX in a Linux environment, in order to make use of the generated certificate files using the provided NGINX sample code, you need to do the following:

Copy the server.conf file and place it in the /etc/nginx/conf.d/ directory.
1. The current configuration in server.conf assumes that the certificate and private key files from the Terraform Sectigo provider are located at /etc/ssl/sectigo_ssl.crt and /etc/ssl/sectigo_ssl.key, respectively. If you used a different sectigo_ssl_cert_file_path or sectigo_ssl_cert_file_name, please update the paths in the server.conf file accordingly.
2. By default, the server_name variable in server.conf points to <sectigo_csr_domain>. You must change this value to point to your server’s hostname (for example, localhost).
Copy the index.html file and place it in /usr/share/nginx/html/.
Reload and restart your NGINX server.
Connect to your NGINX server in the browser over HTTPS.
Verify that the certificate being used is the one that you just generated.