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 Cloud:
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 Cloud 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