_:warning: This community-supported open source project has reached its END-OF-LIFE and will receive only security related updates and critical bug fixes going forward. All functionality of this project (and more) is available in the Ansible Collection for Venafi which is under active development. Switching over is easy, simply install the venafi.machine_identity
collection using Ansible Galaxy and replace role: venafi.ansible_role_venafi
with role: venafi.machine_identity.certificate
in your playbooks. Please transition at your earliest convienence._
This solution adds certificate enrollment capabilities to Red Hat Ansible by seamlessly integrating with the Venafi Trust Protection Platform or Venafi as a Service in a manner that ensures compliance with corporate security policy and provides visibility into certificate issuance enterprise wide.
:red_car: Test drive our integration examples today
Let us show you step-by-step how to add certificates to your Infrastucture as Code automation with Ansible.
NOTE If you don't see an example for a product you use, check back later. We're working hard to add more integration examples.
Review the Venafi
prerequisites, then install Ansible and VCert-Python (v0.10.0 or higher) using pip
:
pip install ansible vcert --upgrade
For more information about Ansible Galaxy, go to https://galaxy.ansible.com/docs/using/installing.html
Install the Venafi Role for Ansible from Ansible Galaxy:
ansible-galaxy install venafi.ansible_role_venafi
Create the credentials.yml
and populate it with connection parameters:
Trust Protection Platform:
cat <<EOF >>credentials.yml
access_token: 'p0WTt3sDPbzm2BDIkoJROQ=='
url: 'https://tpp.venafi.example'
zone: "DevOps\\Ansible"
trust_bundle: "/path/to/bundle.pem"
EOF
Venafi as a Service:
cat <<EOF >>credentials.yml
token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
zone: 'Business App\\Enterprise CIT'
EOF
The Venafi Role for Ansible supports the following connection and credential settings:
Variable Name | Description |
---|---|
access_token |
Trust Protection Platform access token for the "ansible-by-venafi" API Application |
password |
[DEPRECATED] Trust Protection Platform WebSDK password, use access_token if possible |
test_mode |
When "true", the role operates without connecting to Trust Protection Platform or Venafi as a Service |
token |
Venafi as a Service API key |
trust_bundle |
Text file containing trust anchor certificates in PEM (text) format, generally required for Trust Protection Platform |
url |
Venafi service URL (e.g. "https://tpp.venafi.example"), generally only applicable to Trust Protection Platform |
user |
[DEPRECATED] Trust Protection Platform WebSDK username, use access_token if possible |
zone |
Policy folder for TPP or Application name and Issuing Template API Alias for VaaS (e.g. "Business App\Enterprise CIT") |
Use ansible-vault
to encrypt the credentials.yml
file using a password. This is optional but highly recommended.
As long as you know the password you can always decrypt the file to make changes and then re-encrypt it.
Go to https://docs.ansible.com/ansible/latest/user_guide/vault.html for more information.
ansible-vault encrypt credentials.yml
Write a simple playbook called, for example, sample.yml
.
- hosts: localhost
roles:
- role: venafi.ansible_role_venafi
certificate_cert_dir: "/tmp/etc/ssl/{{ certificate_common_name }}"
Run the playbook.
ansible-playbook sample.yml --ask-vault-pass
Running the playbook will generate a certificate and place it into folder in /tmp/etc/ssl/ directory.
The --ask-vault-pass
parameter is needed if you encrypted the credentials.yml
file. Additional
playbook variables can be added to specify properties of the certificate and key pair, file locations,
and to override default behaviors.
Variable Name | Description | |
---|---|---|
credentials_file |
Name of the file containing Venafi credentials and connection settings Default: credentials.yml |
|
certificate_common_name |
Common Name to request for the certificate. Default: "{{ ansible_fqdn }}" |
|
certificate_alt_name |
Comma separated list of Subject Alternative Names to request for the certificate. Prefix each value with the SAN type. Example: "DNS:host.example.com,IP:10.20.30.40,email:me@example.com" |
|
certificate_privatekey_type |
Key algorithm, "RSA" or "ECDSA" Default: "RSA" (from VCert) |
|
certificate_privatekey_size |
Key size in bits for RSA keys Default: "2048" (from VCert) |
|
certificate_privatekey_curve |
Elliptic Curve for ECDSA keys Default: "P251" (from VCert) |
|
certificate_privatekey_passphrase |
Password to use for encrypting the private key | |
certificate_chain_option |
Specifies whether the root CA certificate appears "last" (default) or "first" in the chain file |
|
certificate_cert_dir |
Local parent directory where the cryptographic assets will be stored Default: "/etc/ssl/{{ certificate_common_name }}" |
|
certificate_cert_path |
Local directory where certificate files will be stored Default: {{ certificate_cert_dir }}/{{ certificate_common_name }}.pem" |
|
certificate_chain_path |
Local directory where certificate chain files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem" |
|
certificate_privatekey_path |
Local directory where private key files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.key" |
|
certificate_csr_path |
Local directory where certificate signing request files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.csr" |
|
certificate_remote_execution |
Specifies whether cryptographic assets will be generated remotely, or locally and then provisioned to the remote host Default: false |
|
certificate_remote_cert_path |
Directory on remote host where certificate files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.pem" |
|
certificate_remote_chain_path |
Directory on remote host where certificate chain files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem" |
|
certificate_remote_privatekey_path |
Directory on remote host where private key files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.key" |
|
certificate_copy_private_key_to_remote |
Specifies whether to copy the private key file to the remote host Default: true |
|
certificate_before_expired_hours |
Number of hours prior to the expiration of the certificate before it can be renewed Default: 72 |
|
certificate_renew |
Specifies whether to renew the certificate if it is within the "before_expired_hours" window when the playbook is run Default: true |
|
certificate_force |
Specifies whether to request a new certificate every time the playbook is run Default: false |
Defaults are defined in the defaults/main.yml file.
(Optional) Prepare the demo environment. If you want to use your own inventory, update the tests/inventory file.
To run our test/demo playbook you'll need the Docker provisioning role.
Download it into the tests/roles/provision_docker
directory:
git clone https://github.com/chrismeyersfsu/provision_docker.git tests/roles/provision_docker
Then build the Docker images needed for the demo playbook:
docker build ./tests --tag local-ansible-test
Demo certificates will be placed in the /tmp/ansible/etc/ssl
directory on the Ansible host.
From there they will be distributed to the /etc/ssl/
directory of remote hosts.
Generate a credentials file for either Trust Protection Platform or Venafi as a Service as described in the above section.
Run the Ansible playbook (remove docker_demo=true
if you want to use your own inventory).
The contents of credentials.yml
will be used to decide whether Trust Protection Platform or Venafi as a Service is used.
If you set the token
parameter, the playbook assumes you are using Venafi as a Service. If you set the access_token
or
password
parameters, the playbook assumes you are using Trust Protection Platform.
ansible-playbook -i tests/inventory \
tests/venafi-playbook-example.yml \
--extra-vars "credentials_file=credentials.yml docker_demo=true" \
--ask-vault-pass
You will be prompted for the password for decrypting the credentials.yml
as before. The source file for the
credentials can be overridden using the credentials_file variable and this can be specified on the command line
using the --extra-vars
parameter as shown.
- hosts: servers
roles:
- role: "ansible-role-venafi"
certificate_common_name: "{{ ansible_fqdn }}.venafi.example.com"
certificate_cert_dir: "/tmp/ansible/etc/ssl/{{ certificate_common_name }}"
certificate_cert_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.pem"
certificate_chain_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem"
certificate_privatekey_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.key"
certificate_csr_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.csr"
# Where to execute venafi_certificate module. If set to false, certificate will be
# created on ansible master host and then copied to the remote server.
certificate_remote_execution: false
# Remote location where to place the certificate.
certificate_remote_cert_dir: "/etc/ssl"
certificate_remote_cert_path: "{{ certificate_remote_cert_dir }}/{{ certificate_common_name }}.pem"
certificate_remote_chain_path: "{{ certificate_remote_cert_dir }}/{{ certificate_common_name }}.chain.pem"
certificate_remote_privatekey_path: "{{ certificate_remote_cert_dir }}/{{ certificate_common_name }}.key"
# Set to false if you don't want to copy private key to remote location.
certificate_copy_private_key_to_remote: true
For playbook examples look into venafi-playbook-example.yml file. For role examples look into venafi-role-playbook-example.yml file
For more information about using roles go to https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html
Copyright © Venafi, Inc. All rights reserved.
This solution is licensed under the Apache License, Version 2.0. See LICENSE
for the full license text.
Please direct questions/comments to opensource@venafi.com.