Skip to content

Commit 8bca061

Browse files
natemccurdynatemccurdy
authored
Merge pull request #73 from voxpupuli/readme
README updates: more examples, explain auth methods
2 parents bea0ed4 + 7e8b9ef commit 8bca061

1 file changed

Lines changed: 165 additions & 103 deletions

File tree

‎README.md‎

Lines changed: 165 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -15,106 +15,34 @@ agents with Hashicorp Vault.
1515
#### Table of Contents
1616

1717
1. [Description](#description)
18-
2. [Setup - The basics of getting started with vault_lookup](#setup)
19-
3. [Usage - Configuration options and additional functionality](#usage)
18+
2. [Requirements](#setup)
19+
3. [Usage, Configuration, and Examples](#usage)
20+
4. [Authentication Methods](#authentication-methods)
2021

2122
## Description
2223

23-
For users with a Puppet Enterprise 2019 or open source Puppet 6 infrastructure
24-
wanting to leverage secrets from an existing [Hashicorp
25-
Vault](https://www.vaultproject.io/) server. Used with Puppet 6's Deferred type,
26-
this allows agents to retrieve secrets from Vault when a catalog is applied. In
27-
this way, the secret data is not embedded in the catalog and the master never
28-
sees it. See [this blog
29-
post](https://puppet.com/blog/secret-agents-man-secrets-store-integrations-puppet-6)
30-
for more information and other secret store integrations.
24+
For Puppet 6+ or Puppet Enterprise 2019+ users wanting to use secrets from
25+
[Hashicorp Vault](https://www.vaultproject.io/) on their Puppet agents, this
26+
Puppet module provides the `vault_lookup::lookup()` function.
3127

32-
Authentication with Vault is achieved via Puppet certificates or by using the
33-
Approle authentication method. See the Vault documentation for more information
34-
on setting up finer grained access controls.
28+
When used with Puppet 6's [`Deferred`
29+
type](https://puppet.com/docs/puppet/7/deferring_functions.html), the function
30+
allows agents to retrieve secrets from Vault when a catalog is applied rather
31+
than compiled. In this way, the secret data is not embedded in the catalog and
32+
the Puppetserver does not need permissions to read all your Vault secrets.
3533

36-
## Requirements
37-
38-
This is expected to be run using the `Deferred` type, which requires Puppet
39-
6.0.0 or later, and of course [Vault](https://www.vaultproject.io/) to store the
40-
data.
41-
42-
## Setup
43-
44-
### To set up Vault to use the Puppet Server CA cert:
45-
46-
The `vault::vault_lookup()` function can use the Puppet agent's certificates in
47-
order to authenticate to the Vault server; this means that before any agents
48-
contact a Vault server, you must configure the Vault server with the Puppet
49-
Server's CA certificate, and Vault must be part of the same certificate
50-
infrastructure.
51-
52-
1. Set up Vault using Puppet certs (if not already set up this way)
53-
If the Vault host has a Puppet agent on it then you can just use the existing
54-
certificates. Otherwise generate a new certificate with `puppetserver ca` and
55-
copy the files.
56-
57-
```
58-
puppetserver ca generate --certname my-vault.my-domain.me
59-
```
60-
61-
In the Vault listener configuration, set `tls_client_ca_file` as the Puppet CA
62-
cert, `tls_cert_file` as the agent or generated certificate, and
63-
`tls_key_file` as the agent or generated private key.
64-
65-
2. Enable cert auth for Vault
66-
Hashicorp’s Vault supports a variety of auth methods that are listed in their
67-
documentation; the auth method required for usage with the
68-
`vault:vault_lookup()` function is named cert, and can be turned on with the
69-
Vault CLI:
70-
71-
```
72-
$ vault auth enable cert
73-
```
74-
3. Upload the Puppet Server CA certificate to Vault.
75-
After cert auth has been enabled for Vault, upload the CA certificate from
76-
your Puppet Server to Vault and add it as a trusted certificate.
7734

78-
```
79-
$ vault write auth/cert/certs/puppetserver \
80-
display_name=puppet \
81-
policies=prod,test \
82-
certificate=@/path/to/puppetserver/ca.pem \
83-
ttl=3600
84-
```
85-
86-
Once the certificate has been uploaded, any Puppet agent with a signed
87-
certificate will be able to authenticate with Vault.
88-
89-
### To use AppRole Authentication
90-
91-
`vault:vault_lookup()` can also use AppRole authentication to authenticate against Vault with a valid `role_id` and `secret_id`. See [The Approle Vault Documentation](https://www.vaultproject.io/docs/auth/approle) for detailed explanations of creating and obtaining the security credentials. You will need the Role ID (non sensitive) and the Secret ID (sensitive!). The Secret ID can be provided as an argument to the `vault:vault_lookup()` function but it is recommended to pass this as an environment variable and not bake this into code.
92-
93-
Example:
94-
```
95-
# vault read auth/approle/role/puppet/role-id
96-
Key Value
97-
--- -----
98-
role_id XXXXX-XXXX-XXX-XX-XXXXXXXXXX
99-
```
35+
## Requirements
10036

101-
```
102-
# vault write -f auth/approle/role/puppet/secret-id
103-
Key Value
104-
--- -----
105-
secret_id YYYYY-YYYY-YYY-YY-YYYYYYYYYYY
106-
secret_id_accessor ZZZZZ-ZZZZZZ-ZZZZZZ-ZZZZZZZZ-ZZZZ
107-
secret_id_ttl 0s
108-
```
37+
This modules assumes the following:
38+
1. Puppet 6+
39+
2. An existing [Vault](https://www.vaultproject.io/) infrastructure
10940

110-
In order to use the AppRole auth engine you must set the `VAULT_AUTH_METHOD` environment variable (defaults to cert) to `approle`
111-
112-
```
113-
export VAULT_AUTH_METHOD=approle
114-
export VAULT_ROLE_ID=XXXXX-XXXX-XXX-XX-XXXXXXXXXX
115-
export VAULT_SECRET_ID=YYYYY-YYYY-YYY-YY-YYYYYYYYYYY
116-
```
41+
The `vault_lookup::lookup()` function is expected to be run with the `Deferred`
42+
type; as such, Puppet 6 or later is required.
11743

44+
And as this function is meant to read secrets from Vault, an existing Vault
45+
infrastructure is assumed to be up and reachable by your Puppet agents.
11846

11947

12048
## Usage
@@ -157,37 +85,80 @@ node default {
15785

15886
### Configuring the Vault lookup
15987

160-
The lookup done by `vault::vault_lookup()` can be configured in two ways: positional arguments or with a hash of options.
88+
The lookup done by `vault_lookup::lookup()` can be configured in three ways:
89+
positional arguments, a hash of options, and/or environment variables.
90+
91+
In all cases, the path to the secret is the first positional argument and is
92+
required. All other arguments are optional. Arguments in `[square brackets]`
93+
below are optional.
16194

162-
In both cases, the path to the secret is the first positional argument and is required. All other arguments are optional.
95+
#### Positional Arguments
16396

164-
Positional arguments signature:
16597
```
166-
vault::vault_lookup( <path>, [<vault_addr>], [<cert_path_segment>], [<cert_role>], [<namespace>], [<field>], [<auth_method>], [<role_id>], [<secret_id>], [<approle_path_segment>] )
98+
vault_lookup::lookup( <path>, [<vault_addr>], [<cert_path_segment>], [<cert_role>], [<namespace>], [<field>], [<auth_method>], [<role_id>], [<secret_id>], [<approle_path_segment>] )
16799
```
168100

169-
Options hash signature:
101+
#### Options Hash
102+
170103
```
171-
vault::vault_lookup( <path>, [<options_hash>] )
104+
vault_lookup::lookup( <path>, [<options_hash>] )
172105
```
173106

174-
Arguments in `[square brackets]` are optional.
107+
#### Environment Variables
108+
109+
Not all options can be set with environment variables. Use the table below to find the matching env var, if available. Also note that environment variables are only used if the option is not supplied to the function.
110+
111+
| Option Name | Environment Variable |
112+
| ----------- | -------------------- |
113+
| `vault_addr` | `VAULT_ADDR` |
114+
| `cert_path_segment` | ---- |
115+
| `cert_role` | ---- |
116+
| `namespace` | `VAULT_NAMESPACE` |
117+
| `field` | ---- |
118+
| `auth_method` | `VAULT_AUTH_METHOD` |
119+
| `role_id` | `VAULT_ROLE_ID` |
120+
| `secret_id` | `VAULT_SECRET_ID` |
121+
| `approle_path_segment` | ---- |
175122

176123

124+
### Usage Examples
125+
177126
Here are some examples of each method:
178-
```
127+
```puppet
179128
# Positional arguments
180-
$data_1a = vault::vault_lookup('secret/db/password', 'https://vault.corp.net:8200')
181-
$data_2a = vault::vault_lookup('secret/db/blah', 'https://vault.corp.net:8200', undef, undef, undef, undef, 'approle', 'team_a', 'abcd1234!@#')
182129
130+
## Using the default 'cert' auth method.
131+
$data_1a = vault_lookup::lookup('secret/db/password', 'https://vault.corp.net:8200')
132+
133+
## Using the 'approle' auth method.
134+
$data_2a = vault_lookup::lookup('secret/db/blah', 'https://vault.corp.net:8200', undef, undef, undef, undef, 'approle', 'team_a', 'abcd1234!@#')
135+
136+
## Pulling out a specific field.
137+
$password = vault_lookup::lookup('secret/test', 'http://vault.corp.net:8200', undef, undef, undef, 'password')
138+
```
139+
140+
```puppet
183141
# Options hash
184-
$data_1b = vault::vault_lookup('secret/db/password', { 'vault_addr' => 'https://vault.corp.net:8200' })
185-
$data_2b = vault::vault_lookup('secret/db/blah', {
142+
143+
## Using the default 'cert' auth method.
144+
$data_1b = vault_lookup::lookup('secret/db/password', { 'vault_addr' => 'https://vault.corp.net:8200' })
145+
146+
## Using the 'approle' auth method.
147+
$data_2b = vault_lookup::lookup('secret/db/blah', {
186148
'vault_addr' => 'https://vault.corp.net:8200',
187149
'auth_method' => 'approle',
188150
'role_id' => 'team_a',
189151
'secret_id' => 'abcd1234!@#',
190152
})
153+
154+
# Using 'field' to pull out a specific field from the data.
155+
$password = vault_lookup::lookup('secret/test', {'vault_addr' => 'http://127.0.0.1:8200', 'field' => 'password'})
156+
157+
# Using Deferred is simpler with the options hash.
158+
$password_deferred = Deferred('vault_lookup::lookup', ["secret/test", {
159+
vault_addr => 'http://127.0.0.1:8200',
160+
field => 'password',
161+
}])
191162
```
192163

193164
### A note about caching
@@ -261,3 +232,94 @@ notify { 'show the dev namespace DB password':
261232
}
262233
```
263234

235+
## Authentication Methods
236+
237+
The `vault_lookup::lookup()` function can authenticate to Vault in a number of ways. This table shows the currently supported `auth_method` types:
238+
239+
| `auth_method` | Description |
240+
| --- | --- |
241+
| `cert` | (this is the default) Uses the Puppet agent's certificate via the [TLS Certificates](https://developer.hashicorp.com/vault/docs/auth/cert) auth method. |
242+
| `approle` | Uses the [AppRole](https://developer.hashicorp.com/vault/docs/auth/approle) auth method. |
243+
244+
245+
### Puppetserver CA and agent certificates
246+
247+
The `vault_lookup::lookup()` function by default will use the Puppet agent's
248+
certificates to authenticate to the Vault server. This means that before any
249+
agents contact a Vault server, you must configure the Vault server with the
250+
Puppet Server's CA certificate, and Vault must be part of the same certificate
251+
infrastructure.
252+
253+
1. Set up Vault using Puppet certs (if not already set up this way). If the
254+
Vault host has a Puppet agent on it then you can just its existing host
255+
certificates. Otherwise generate a new certificate with `puppetserver ca`
256+
and copy the files.
257+
258+
```
259+
$ puppetserver ca generate --certname my-vault.my-domain.me
260+
```
261+
262+
In the Vault listener configuration, set `tls_client_ca_file` as the Puppet
263+
CA cert, `tls_cert_file` as the agent's or generated certificate, and
264+
`tls_key_file` as the agent's or generated private key.
265+
266+
2. Enable the `cert` auth backend in Vault.
267+
268+
```
269+
$ vault auth enable cert
270+
```
271+
272+
3. Upload the Puppet Server CA certificate to Vault. After `cert` auth has been
273+
enabled for Vault, upload the CA certificate from your Puppet Server to
274+
Vault, and add it as a trusted certificate.
275+
276+
```
277+
$ vault write auth/cert/certs/puppetserver \
278+
display_name=puppet \
279+
policies=prod,test \
280+
certificate=@/path/to/puppetserver/ca.pem \
281+
ttl=3600
282+
```
283+
284+
285+
Once the certificate has been uploaded, any Puppet agent with a signed
286+
certificate will be able to authenticate with Vault.
287+
288+
### AppRole
289+
290+
`vault:vault_lookup()` can also use AppRole authentication to authenticate
291+
against Vault with a valid `role_id` and `secret_id`. See [The Approle Vault
292+
Documentation](https://www.vaultproject.io/docs/auth/approle) for detailed
293+
explanations of creating and obtaining the security credentials. You will need
294+
the Role ID (non sensitive) and the Secret ID (sensitive!). The Secret ID can
295+
be provided as an argument to the `vault:vault_lookup()` function but it is
296+
recommended to pass this as an environment variable and not bake this into
297+
code.
298+
299+
Example:
300+
```
301+
$ vault read auth/approle/role/puppet/role-id
302+
Key Value
303+
--- -----
304+
role_id XXXXX-XXXX-XXX-XX-XXXXXXXXXX
305+
```
306+
307+
```
308+
# vault write -f auth/approle/role/puppet/secret-id
309+
Key Value
310+
--- -----
311+
secret_id YYYYY-YYYY-YYY-YY-YYYYYYYYYYY
312+
secret_id_accessor ZZZZZ-ZZZZZZ-ZZZZZZ-ZZZZZZZZ-ZZZZ
313+
secret_id_ttl 0s
314+
```
315+
316+
In order to use the AppRole auth method, either set the `VAULT_AUTH_METHOD`
317+
environment variable on the Puppet process to `approle` or set the
318+
`auth_method` option to `approle` when calling the function:
319+
320+
```shell
321+
export VAULT_AUTH_METHOD=approle
322+
export VAULT_ROLE_ID=XXXXX-XXXX-XXX-XX-XXXXXXXXXX
323+
export VAULT_SECRET_ID=YYYYY-YYYY-YYY-YY-YYYYYYYYYYY
324+
```
325+

0 commit comments

Comments
 (0)