cookbook 'certificate', '= 2.1.0'
certificate
(30) Versions
2.1.0
-
Follow6
Installs and configures certificates, private keys, CA root bundles from encrypted data bags.
cookbook 'certificate', '= 2.1.0', :supermarket
knife supermarket install certificate
knife supermarket download certificate
Certificate cookbook
Description
This recipe automates the common task of managing x509 certificates and keys from encrypted Data Bags. This cookbook
provides a flexible and reusable resource to set up certificates from various sources.
Warning about Vault mode
Pulling data from Chef Vault is not supported when using chef-solo
, and will result in a failure condition.
Testing with encrypted data_bags
The stub files in test/integration
are for testing only and should not be used in production. These files include a
self-signed "snake oil" certificate/key and an encrypted_data_bag_secret
file which are not secure to use beyond
testing.
Requirements
Prepping certificate data
The certificate strings in the data bag need all newlines replaced with literal \n
s. This conversion can be done with
a Ruby one-liner:
ruby -e 'p ARGF.read' <filename>
This will turn the input file from the normal certificate format:
-----BEGIN CERTIFICATE----- MIIEEDCCA3mgAwIBAgIJAO4rOcmpIFmPMA0GCSqGSIb3DQEBBQUAMIG3MQswCQYD -----END CERTIFICATE-----
Into this:
-----BEGIN CERTIFICATE-----\nMIIEEDCCA3mgAwIBAgIJAO4rOcmpIFmPMA0GCSqGSIb3DQEBBQUAMIG3MQswCQYD\n-----END CERTIFICATE-----
Add the converted certificate / chain / key to the desired databag, attributes, or Chef Vault store:
{ "id": "example", "cert": "-----BEGIN CERTIFICATE-----\nCertificate Here...", "key": "-----BEGIN PRIVATE KEY\nPrivate Key Here...", "chain": "-----BEGIN CERTIFICATE-----\nCA Root Chain Here..." }
The chain
entry may be optional if the CA's root chain is already trusted by the server.
Recipes
This cookbook comes with three simple example recipes for using the certificate_manage LWRP.
certificate::default
Creates certificates from the data bag item certificates/$HOSTNAME
.
certificate::wildcard
Same as the default recipe, except for the data bag item name is wildcard
instead of the node hostname.
The resulting files will be named wildcard.pem (cert), wildcard.key (key), and wildcard-bundle.crt (CA Root chain)
certificate::manage_by_attributes
Defines certificate_manage
resources dynamically from node attributes.
<table>
<tr>
<td> Attributes </td> <td> Equivalent resources </td>
</tr>
<tr>
<td>
node['certificate'] = [ { 'foo' => { data_bag_type: 'none', plaintext_cert: 'plain_cert', plaintext_key: 'plain_key', plaintext_chain: 'plain_chain', } }, {'test' => {}}, ]
</td>
<td>
certificate_manage 'foo' do data_bag_type 'none' plaintext_cert 'plain_cert' plaintext_key 'plain_key' plaintext_chain 'plain_chain' end certificate_manage 'test'
</td>
</tr>
</table>
Resources
certificate_manage
Sets up certificates from data bags or Chef Vault stores.
Property | Default | Description |
---|---|---|
data_bag |
certificate |
Name of the data bag to look in |
data_bag_secret |
Chef::Config['encrypted_data_bag_secret'] |
Path to the file with the data bag secret |
data_bag_type |
encrypted |
Where to get certificate data from: encrypted or unencrypted data bag, vault for Chef Vault, or none for plaintext properties |
search_id |
Resource name | Name of the data bag item to use |
plaintext_cert |
Manual cert input for none data bag type |
|
plaintext_key |
Manual key input for none data bag type |
|
plaintext_chain |
Manual chain input for none data bag type |
|
cert_path |
/etc/pki/tls on RHEL, else /etc/ssl
|
Directory to place certificates in |
create_subfolders |
true |
Whether to use private/ and certs/ subdirectories under cert_path
|
cert_file |
$FQDN.pem |
Basename of the certificate |
key_file |
$FQDN.key |
Basename of the private key |
chain_file |
$HOSTNAME-bundle.pem |
Basename of the chain certificate |
nginx_cert |
false |
Whether to create a combined cert/chain certificate for use with Nginx instead of separate certs |
combined_file |
false |
Whether to combine the cert, chain, and key into a single file |
owner |
root |
File owner of the certificates |
group |
root |
File group of the certificates |
cookbook |
certificate |
Cookbook containing the certificate file template. |
Example
The following example will place certificates defined in the certificates/mail
data bag item under /etc/postfix/ssl
owned by postfix.
certificate_manage "mail" do cert_path "/etc/postfix/ssl" owner "postfix" group "postfix" end
.certificate, .key, .chain helper method usage
Some helper methods are exposed for retrieving key/certificate paths in other recipes:
-
.certificate
- The final path of the certificate file. i.e.#{cert_path}/certs/#{cert_file}
-
.key
- The final path of the key file. i.e.#{cert_path}/private/#{key_file}
-
.chain
- The final path of the chain file. i.e.#{cert_path}/certs/#{chain_file}
# where node.fqdn = 'example.com' tld = certificate_manage 'top_level_domain' tld_cert_location = tld.certificate # => /etc/ssl/certs/example.com.pem # where node.fqdn = 'sub.example.com' sbd = certificate_manage 'sub_domain' do cert_path '/bobs/emporium' create_subfolders false end sbd_cert_location = sbd.key # => /bobs/emporium/sub.example.com.key
Setting FQDN during the converge
If the FQDN of the node is updated during converge, be sure to use lazy attribute
evaluation to ensure node['fqdn']
refers to the
updated value.
certificate_manage "wildcard" do cert_file lazy { "#{node['fqdn']}.pem" } key_file lazy { "#{node['fqdn']}.key" } chain_file lazy { "#{node['fqdn']}-bundle.crt" } end
Using the none
data bag type
The none
option does not use a data bag, requiring the certificate, key, and/or chain to be passed directly to the
resource. This allows you to use the certificate_manage
resource for all of your certificate needs, even if the
certificate data is stored in an unsupported location.
certificate_manage "fqdn-none-plaintext" do cert_file lazy { "#{node['fqdn']}.pem" } key_file lazy { "#{node['fqdn']}.key" } chain_file lazy { "#{node['fqdn']}-bundle.crt" } data_bag_type 'none' plaintext_cert "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n\n" plaintext_key "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n\n", plaintext_chain "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n\n", end
Contributors
This project exists thanks to all the people who contribute.
Backers
Thank you to all our backers!
Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
Dependent cookbooks
This cookbook has no specified dependencies.
Contingent cookbooks
There are no cookbooks that are contingent upon this one.
certificate Cookbook CHANGELOG
This file is used to list changes made in each version of the certificate cookbook.
2.1.0 - 2024-05-03
- Allow owner and group to be String or Integer
2.0.24 - 2024-05-03
2.0.23 - 2024-05-03
2.0.22 - 2023-12-27
2.0.21 - 2023-10-31
2.0.20 - 2023-09-28
2.0.19 - 2023-09-04
2.0.18 - 2023-07-10
2.0.17 - 2023-05-17
2.0.16 - 2023-04-19
- Various CI and Documentation cleanup
2.0.15 - 2023-04-07
- Standardise files with files in sous-chefs/repo-management
2.0.14 - 2023-04-01
- Update gaurav-nelson/github-action-markdown-link-check action to v1.0.15
2.0.13 - 2023-04-01
- Update actions/stale action to v8
2.0.12 - 2023-04-01
- Standardise files with files in sous-chefs/repo-management
2.0.11 - 2023-03-15
- Standardise files with files in sous-chefs/repo-management
2.0.10 - 2023-03-02
- Standardise files with files in sous-chefs/repo-management
2.0.9 - 2023-02-23
- Standardise files with files in sous-chefs/repo-management
2.0.8 - 2023-02-16
- Standardise files with files in sous-chefs/repo-management
2.0.7 - 2023-02-15
- Standardise files with files in sous-chefs/repo-management
2.0.6 - 2023-02-14
- Remove CircleCI
2.0.5 - 2022-12-13
- Standardise files with files in sous-chefs/repo-management
2.0.4 - 2022-02-03
- Standardise files with files in sous-chefs/repo-management
2.0.3 - 2022-02-02
- Fix
cert_path
usage when usingcreate_subfolders
- Remove delivery and move to calling RSpec directly via a reusable workflow
- Update tested platforms
2.0.2 - 2021-08-30
- Standardise files with files in sous-chefs/repo-management
2.0.1 - 2021-07-09
- Standardise files with files in sous-chefs/repo-management
2.0.0 - 2021-07-06
- Sous Chefs Adoption
1.0.0 - 2015-04-03
- #45 @dmlb2000 added
data_bag_type
parameter and support for vault, or unencrypted modes. - Update documentation for helper methods.
0.8.2 - 2015-03-02
- #43 @hartfordfi## e added sensitive mode to hide certificates and keys in console output.
- #47 @fletchowns added documentation note concerning lazy attribute evaluation.
0.8.1 - 2015-02-05
- Fix bad pick on merge conflict from revert.
0.8.0 - 2015-02-04
- Revert #38: This previous change worked around a bug in Knife that limited use of characters in data bags. See CHEF-3531 for more information.
0.7.0 - 2015-01-23
- #33 expose final path of managed objects.
- #38 normalize dots to underscore in search_id
- #40 chefspec matcher deprecation
- Update travis config
v0.6.3
- #30 Hash rockets
- #34 Rescue version
v0.6.0
- Add thor-scmversion
- Add use_inline_resources, if defined
- Add ignore_missing parameter
v0.5.2
- Update documentation
- Update gitignore
- Rubocop whitespace corrections
v0.5.0
- ChefSpec create_certificate_manage matcher added.
- Added combined_file resource.
- Update build files.
- Added Rubocop.
- Added BATS tests.
v0.4.3
- Issue #16, fix handling of subdir creation
v0.4.2
- Issue #15, Revert FC017 change
v0.4.1
- FC017: LWRP does not notify when updated: ./providers/manage.rb:24
v0.4.0
- Add
nginx_cert
knob for chained certificates
v0.3.0
- Add test-kitchen coverage and documentation.
v0.2.3
- Fix typo in "manage" resource definitions
v0.2.2
- Add :create_subfolders attribute, to toggle off folder creation of private/certs directories.
v0.2.1
- Fixes issue #11, reported by @tmatilia
v0.2.0
Cleaning up the backlog of PRs
- @kechagia added data_bag_secret attribute
- @sawanoboly added smartos paths, and recipe
certificate::manage_by_attributes
- allow specification of data bag secret
- new attribute added: data_bag_secret
- defaults to /etc/chef/encrypted_data_bag_secret
- openssl certs path for smartos
- add recipe manage_by_attributes
- Add :data_bag_keyfile attribute to the LWRP.
v0.1.0
Thanks Teemu, and Kris, for their outstanding work!
-
Teemu Matilainen
- Add whyrun mode support.
- Extract directory and file creation to generic methods.
- Corrected outstanding issues related to updated_by_last_action
-
Kris Kechagia
- Corrected the updated_by_last_action to avoid unneccessary notification.
0.0.6
- Fix incorrect has_key conditional
- Disable incorrect foodcritic warning about repetition
0.0.5
- Add foodcritic linting
- Anyone have ideas on testing LWRPs?
0.0.4
- Fix default action
0.0.3
- Minor typo fixes
0.0.2
- LWRP conversion of recipe
0.0.1
- Recipe prototype
Collaborator Number Metric
2.1.0 passed this metric
Contributing File Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Cookstyle Metric
2.1.0 passed this metric
No Binaries Metric
2.1.0 passed this metric
Testing File Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
2.1.0 passed this metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Cookstyle Metric
2.1.0 passed this metric
No Binaries Metric
2.1.0 passed this metric
Testing File Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
2.1.0 passed this metric
2.1.0 passed this metric
Testing File Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
2.1.0 failed this metric
2.1.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number