Summary Info: Venafi Cloud DevOps integrations for SaltStack

https://github.com/saltstack/salt/blob/develop/doc/topics/venafi/venafi.rst

Introduction

The SaltStack Venafi module allows Salt users to seamlessly incorporate certificate management into Salt states when configuring applications and services on minions, using certificates issued by Venafi’s ‘Venafi Cloud for DevOps’ service.

Overview

 

The SaltStack Venafi modules consist of a runner module and an external pillar module. The runner module interfaces with the Venafi Cloud REST API for certificate management operations as well as generates key material for certificates. The external pillar module publishes certificate and key material to minions via Salt’s Pillar system. The following diagram outlines the high-level solution architecture.

Configuration and  Usage

As the Venafi Saltstack module is shipped with Salt Open, the latest documentation on basic configuration and usage of the module is documented here:

https://github.com/saltstack/salt/blob/develop/doc/topics/venafi/venafi.rst

Stable versions of the documentation can be found on Salt’s documentation site available here:

https://docs.saltstack.com/en/latest/ref/runners/all/index.html

Using the Venafi Salt Module

The Venafi Salt module is designed to solve basic use cases where applications/services on minions need to consume digital certificates and key material. At a high level, the flow that Salt users will use to obtain certificates is as follows:

1. Create state files referencing pillar data for root, intermediate and end-entity certificates as well as private keys for each minion.
2. Generate a keypair, create a certificate signing request, and submit the request to the Venafi Cloud service.
3. Pickup the issued certificate from the Venafi Cloud service.
4. Apply states to each minion to deploy the certificate/private key material.

For most applications, the file.managed state can be used to deploy certificates and private keys as files that can be referenced in other states. In the following example, a minion will have the nginx webserver installed and configured with HTTPS enabled, using a private key and certificate that was obtained from the Venafi Cloud service.

NOTE: The Venafi runner module does not encrypt private keys stored on the salt master or in pillar data provided to minions. Be certain to secure the salt master file system to restrict unauthorized access to the server.

 

 

Create a Certificate Signing Request

NOTE: The Venafi Cloud service by default issues certificates intended for test and development purposes. In the default configuration, certificates that are issued will be valid only for 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

Contact Venafi at support@venafi.com if support for certificates for use in production environments is required.

 

First, create a certificate request and submit it to the Venafi Cloud service using the venafi.request command. The venafi.request command accepts several parameters; the most important parameter to configure is the ‘zone’ parameter. The Venafi Cloud service provides certificate enrollment services through zones. A zone is configured by a Venafi Cloud administrator with a set of policies that certificate signing requests must conform to in order for the service to issue certificates.

By default, when the Venafi Cloud service is activated for an organization (through the registration process), two zones are created; ‘Default’ and ‘Internet’. Both zones are pre-configured to issue test certificates, using RSA 2048 bit keys.

salt-run venafi.request <minionID> <certificate common name> zone=Default 

The command will output the CSR, private key and request ID. The request ID will be required to pickup the certificate from the Venafi Cloud when it is issued.

Retrieving an issued certificate

The Venafi Cloud service will send an email to the user associated with the API key that is configured on the Salt /etc/salt/master file when the certificate has been issued. The certificate is retrieved using the ‘venafi.pickup’ command:

salt-run venafi.pickup <requestID>

 

The private key, certificate and any intermediate certificates are then stored in pillar data for the minion.

Using certificate and private keys stored in pillar in state files

As with any pillar data, the certificate and private key data stored in pillars can be used in state files. The Venafi pillar module provides the following pillar data elements:

venafi:<CN of certificate>:end_entity_certificate venafi:<CN of certificate>:private_key venafi:<CN of certificate>:intermediate_certificates venafi:<CN of certificate>:root_certificate  

 

Below is an example of a simple state file for a minion that will create a certificate and private key in the /etc/tls directory on a minion (hostname.invalid is the CN value of the issued certificate in this case):

update tls_keys:

  file.managed:

      - name: /etc/tls/privkey.pem

      - contents_pillar: venafi:hostname.invalid:private_key

      - replace: True

 

update tls_ee_cert:

  file.managed:

      - name: /etc/tls/cert.pem

      - contents_pillar: venafi:hostname.invalid:end_entity_certificate

      - replace: True

 

NOTE: Issued certificates may contain 1 or more intermediate certificates. To reference these properly in your state files, use jinja template files to loop through all pillar data for intermediate certificates and  use the file.append state to create the chain and append it to your certificate file:

 

update tls_inter_cert:

  file.append:

      - name: /etc/tls/cert.pem

      - source: salt://icert.jinja

      - template: jinja

 

update tls_root_cert:

  file.append:

      - name: /etc/tls/cert.pem

      - source: salt://rcert.jinja

      - template: jinja

 

The referenced jinja template files would then contain the following:

[root@localhost salt]#cat icert.jinja

{% for cert in  salt['pillar.get']('venafi:hostname.invalid:intermediate_certificates') %}

{{ cert }}

{% endfor %}

[root@localhost salt]# cat rcert.jinja

{{ salt['pillar.get']('venafi:hostname.invalid:root_certificate') }}