README.md

⚠️ 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.

Venafi Role for Ansible

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.

🚗 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.

Products	Available integration examples...
	How to configure secure application delivery using F5 BIG-IP and the Venafi Ansible role
	How to configure secure application delivery using Citrix ADC and the Venafi Ansible role

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.

Requirements

Review the Venafi prerequisites, then install Ansible and VCert-Python (v0.10.0 or higher) using pip:

pip install ansible vcert --upgrade

Using with Ansible Galaxy

For more information about Ansible Galaxy, go to https://galaxy.ansible.com/docs/using/installing.html

1. Install the Venafi Role for Ansible from Ansible Galaxy:

   ansible-galaxy install venafi.ansible_role_venafi

2. 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")

3. 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

4. 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 }}"

5. 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.

Preparing a Docker demo environment for running Ansible

1. (Optional) Prepare the demo environment. If you want to use your own inventory, update the tests/inventory file.

   1. 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

   2. 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.

2. Generate a credentials file for either Trust Protection Platform or Venafi as a Service as described in the above section.

3. 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.

Sample Playbook

- 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

License

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.