This solution implements an Ansible Role that uses the VCert-Python library to simplify certificate enrollment and ensure compliance with enterprise security policy.
Install VCert-Python using pip:
pip install vcert
-
Install Ansible and VCert via pip
sudo pip install ansible vcert --upgrade
-
Prepare demo environment (if you want to use your own environment you can skip this step. Change tests/inventory file to use your own inventory.)
-
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
-
Build 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 Venafi Platform or Venafi Cloud.
- For Venafi Platform create a
credentials.yml
similar to the following:user: 'admin' password: 'myStrongTPP-Password' url: 'https://tpp.venafi.example/vedsdk/' zone: "example\\policy" trust_bundle: "/path-to/tpp-trust-bundle.pem"
- For Venafi Cloud set the token to your API key in the credentials.yml and the Zone ID
of the Venafi Cloud zone that you want to request certificates from:
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" zone: "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
- Encrypt the credentials file using ansible-vault; you will be asked to enter a password:
ansible-vault encrypt credentials.yml
- For Venafi Platform create a
-
Run Ansible playbook (remove docker_demo=true if you want to use your own inventory). Choice between Cloud and Platform depends on credentials provided. If you set a token, the playbook runs using Venafi Cloud. If you set a password, the playbook runs using Venafi Platform. You will be asked for the vault password you entered before.
ansible-playbook -i tests/inventory \ tests/venafi-playbook-example.yml \ --extra-vars "credentials_file=credentials.yml docker_demo=true" \ --ask-vault-pass
-
Install role with Ansible Galaxy command:
ansible-galaxy install venafi.ansible_role_venafi
-
Generate credentials.yml as described in Quickstart
-
Write a simple playbook:
- hosts: localhost roles: - role: venafi.ansible_role_venafi certificate_cert_dir: "/tmp/etc/ssl/{{ certificate_common_name }}"
-
Run the playbook:
ansible-playbook vcert.yml --ask-vault-pass
It will generate a certificate and place it into folder in /tmp/etc/ssl/ directory. You can change other parameters by changin more variables described bellow. Also look into variables in defaults/main.yml file.
For more information about Ansible Galaxy, please refer to official documentation: https://galaxy.ansible.com/docs/using/installing.html
For default variables values, please look into defaults/main.yml file.
# Credentials.
venafi:
# Venafi Platform connection parameters
user: 'admin'
password: 'myTPPpassword'
url: 'https://tpp.venafi.example/vedsdk'
zone: "devops\\vcert"
# Path to the trust bundle for Venafi Platform server
trust_bundle: "/opt/venafi/bundle.pem"
# Venafi Cloud connection parameters
#token: 'enter-cloud-api-token-here'
#zone: 'enter Zone ID obtained from Venafi Cloud Web UI'
#Test mode parameter
#test_mode: true
# All variables from venafi section should be in credentials file.
credentials_file: credentials.yml
# Certificate parameters. These are examples.
certificate_common_name: "{{ ansible_fqdn }}"
certificate_alt_name: "IP:192.168.1.1,DNS:www.venafi.example.com,DNS:m.venafi.example.com,email:e@venafi.com,email:e2@venafi.com,IP Address:192.168.2.2"
certificate_privatekey_type: "RSA"
certificate_privatekey_size: "2048"
certificate_privatekey_curve: "P251"
certificate_privatekey_passphrase: "password"
certificate_chain_option: "last"
certificate_cert_dir: "/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_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.pem"
certificate_remote_chain_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem"
certificate_remote_privatekey_path: "{{ certificate_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
vcert, ansible
sudo pip install ansible vcert --upgrade
Playbook file example:
- 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
Credential file examples:
for Venafi Platform:
user: 'admin'
password: 'secret'
url: 'https://tpp.venafi.example/vedsdk/'
zone: "some\\policy"
for Venafi Cloud:
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
zone: "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
By default credentials are read from file credentials.yml but can be overridden using the credentials_file variable, for example:
ansible-playbook playbook.yml --extra-vars "credentials_file=other_credentials.yml"
Look in the /tests directory and Makefile for additional examples. For playbook examples look into venafi-playbook-example.yml file. For role examples look into venafi-role-playbook-example.yml file
For official documentation about using roles see https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html
We strongly recommend that you use ansible-vault for the credentials file. To do so you can use the following steps:
-
Create the
credentials.yml
and populate it with connection parameters:cat <<EOF >>credentials.yml user: 'admin' password: 'secret' url: 'https://tpp.venafi.example/vedsdk/' zone: "some\\policy" EOF
-
Encrypt it using ansible-vault:
ansible-vault encrypt credentials.yml
-
Add option "--vault-id @prompt" to your ansible-playbook command to prompt for vault password:
ansible-playbook --vault-id @prompt playbook.yml
For other Vault use cases see https://docs.ansible.com/ansible/latest/user_guide/vault.html
Please refer to this section:
https://github.com/Venafi/vcert-python#prerequisites-for-using-with-trust-protection-platform
Apache License Version 2.0
Venafi Inc.