Skip to content
Ansible Role that uses Venafi to streamline machine identity (certificate and key) acquisition.
Branch: master
Clone or download
arykalin Merge pull request #6 from Venafi/VEN-46715-example-for-check-functio…
…nality

Уxample for check functionality and check improvement
Latest commit dfdc0bf Feb 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
defaults Add some checks to molecule Feb 11, 2019
handlers pep8 and yaml tests Feb 1, 2019
library Add some checks to molecule Feb 11, 2019
meta
molecule/default Add some checks to molecule Feb 11, 2019
tasks Add some checks to molecule Feb 11, 2019
tests Add some checks to molecule Feb 11, 2019
vars
.gitignore python 37 .venv in gitignore Jan 29, 2019
.yamllint
LICENSE fix spelling Jan 30, 2019
Makefile Fixing pep8, adding more checks to molecule Feb 6, 2019
README.md testing change_dump alwaays true, fixing readme Feb 6, 2019
ansible.cfg
requirements.txt fix todos Jan 25, 2019

README.md

Venafi Role for Ansible

This solution implements an Ansible Role that uses the VCert-Python library to simplify certificate enrollment and ensure compliance with enterprise security policy.

Requirements

Install VCert-Python using pip:
pip install vcert

Quickstart

  1. Install Ansible and VCert via pip
    sudo pip install ansible vcert --upgrade

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

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

  3. Generate a credentials file for either Venafi Platform or Venafi Cloud.

    1. 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"
    2. For Venafi Cloud set the token to your API key in the credentials.yml:
      token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
      zone: "Default"
    3. Encrypt the credentials file using ansible-vault; you will be asked to enter a password:
      ansible-vault encrypt credentials.yml
  4. 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

Using with Ansible Galaxy

  1. Install role with Ansible Galaxy command: ansible-galaxy install venafi.ansible_role_venafi

  2. Generate credentials.yml as described in Quickstart

  3. Write a simple playbook:

    - hosts: localhost
      roles:
        - role: venafi.ansible_role_venafi
          certificate_cert_dir: "/tmp/etc/ssl/{{ certificate_common_name }}"
  4. 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

Role Variables

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: 'Default'
  #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

Dependencies

vcert, ansible

sudo pip install ansible vcert --upgrade

Example Playbook

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: "xxxxx-xxxxx-xxxxx-xxxx-xxxxx"
zone: "Default"

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

Security best practices

We strongly recommend that you use ansible-vault for the credentials file. To do so you can use the following steps:

  1. 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
  2. Encrypt it using ansible-vault: ansible-vault encrypt credentials.yml

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

Venafi Platform configuration requirements

Please refer to this section:
https://github.com/Venafi/vcert-python#prerequisites-for-using-with-trust-protection-platform

License

Apache License Version 2.0

Author Information

Venafi Inc.

You can’t perform that action at this time.