Using the Venafi Terraform provider¶

To create the Venafi Terraform provider¶

To use the Terraform provider, create a venafi.tf file. In it you must first create the provider. Do this by creating a provider block.

For Venafi as a Service:

    provider "venafi" {
    url = “<ALT_VENAFI_CLOUD_URL>”  // optional, defaults to production URL
    api_key = "<API_KEY>"
    zone = "<ZONE>"  // optional, defaults to 'default'
    }

To create a certificate signing request (CSR)

Important

Currently, the Venafi Terraform provider does not encrypt private key material that is generated by Terraform plans. Be sure to configure the Terraform host to restrict unauthorized access.

By default, the Venafi as a Service service issues certificates intended for test and development purposes. In the default configuration, certificates that are issued will be valid for only the following test domains:

[subdomain].example.com
[subdomain].example.org
[subdomain].example.net
[subdomain].invalid
[subdomain].local
[subdomain].localhost
[subdomain].test

Where [subdomain] is the subdomain of the registered Venafi Cloud user’s email address. For example, if the user registers with email address jdoe@mydemocorp.com, certificate requests submitted to the Venafi Cloud service must match one of the following patterns:

*.mydemocorp.example.com
*.mydemocorp.example.org
*.mydemocorp.example.net
*.mydemocorp.invalid
*.mydemocorp.local
*.mydemocorp.localhost
*.mydemocorp.test

Certificate signing requests can be created using the venafi_csr resource. This resource has only one required field.

common_name (string)

The following optional fields can also be set:

Field	Type
organizational_unit	string array
organization_name	string
country	string
state	string
locality	string
key_password	string
san_dns	string array
san_email	string array
san_ip	string array

After creation, this resource exposes two more fields:

Field	Type
private_key_pem	string
csr_pem	string

Example

The following code outputs the created private key and CSR:

provider "venafi" {
api_key = "XXXX"
zone = "Default"
}
resource "venafi_csr" "webserver" {
common_name = "web.organization.localhost"
san_dns = ["blog.organization.localhost", "contact.organization.localhost"]
organizational_unit = ["appdev", "webdev"]
state = "London"
country = "UK"
}
output "csr" {
value = "${venafi_csr.webserver.csr_pem}"
}
output "csr_private_key" {
value = "${venafi_csr.webserver.private_key_pem}"
}

To create a certificate/private key pair

Certificates can be created using the venafi_certificate resource. This resource has only one required field.

common_name (string)

The following optional fields can also be set:

Field	Type
algorithm	string (RSA or ECDSA)
rsa_bits	integer (used when algorithm = RSA)
ecdsa_curve	string (used when algorithm = ECDSA
san_dns	string array
san_email	string array
san_ip	string array
key_password	string

After creation, this resource exposes two more fields:

Field	Type
private_key_pem	string
csr_pem	string

Example

The following code outputs the created private key and CSR:

provider "venafi" {
api_key = "XXXX" // your Venafi Cloud API key
zone = "Default" //optional. Defaults to 'Default'
}
resource "venafi_certificate" "webserver" {
common_name = "web.organization.localhost"
algorithm = "RSA"
rsa_bits = "2048"
san_dns = [
"web01.organization.localhost",
"web02.organization.localhost"
]
key_password = "secretpassword"
}
output "cert_certificate" {
value = "${venafi_certificate.webserver.certificate}"
}
output "cert_chain" {
value = "${venafi_certificate.webserver.chain}"
}
output "cert_private_key" {
value = "${venafi_certificate.webserver.private_key_pem}"
}

Troubleshooting Terraform integration

If the ‘terraform apply’ command fails with an exit code 1, the error is most likely due to incorrect authentication parameters (using an incorrect API key for Venafi Cloud, or incorrect username, password, or URL for Venafi Trust Protection Platform). Verify your authentication parameters are correct, then try again.

Known Issues

The current version of the Terraform provider does not output the request ID for submitted certificates. As a result, if there is an issue with the certificate request, the Terraform plan will not display an obvious error to the user. The easiest resolution to this is to output all certificate requests submitted to Venafi Cloud using another REST client and locate the certificate request that was submitted (based on the subject name supplied in the Terraform plan). The certificate request response will contain information that can be used to help troubleshoot the error.

    curl -H 'Content-Type: application/json' -H 'tppl-api-key: XXXXX
    https://api.staging.venafi.io/v1/certificaterequest