Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms


x509 (5) Versions 1.1.0

Deploy a Chef-managed Certificate Authority

cookbook 'x509', '~> 1.1.0'
cookbook 'x509', '~> 1.1.0', :supermarket
knife cookbook site install x509
knife cookbook site download x509
Quality 33%


Cookbook to manage deployment of X509 certificates across an infrastructure.

Keys and CSRs are generated according to "x509_certificate" resources during a chef-client run on the hosts which will use them, with the CSRs pushed to the Chef server. Later, certificates are signed by the appropriate CAs and pushed to Chef. A subsequent run deploys the signed certificate.

Temporary certificates are issued to enable services to start while the CSRs are waiting to be processed.

Generated keys are encrypted to a key-vault key, and pushed to Chef for backup.


Chef Server

"vt-gpg" Cookbook

"eassl2", "gpgme" gems

GnuPG 2.x


GPG is used to encrypt generated keys for archival purposes.

node['x509']['key_vault'] - the email address of the GPG/PGP recipient.

When set to nil (the default), keys will not be archived.

DN components to use when creating certificate names:

  • node['x509']['country']
  • node['x509']['state']
  • node['x509']['city']
  • node['x509']['organization']
  • node['x509']['department']
  • node['x509']['email']


include_recipe "x509"

Webserver SSL certificate:

x509_certificate "" do
  ca "MyCA"
  key "/etc/ssl/"
  certificate "/etc/ssl/"

Webserver SSL certificate specifying key size and validity period:

x509_certificate "" do
  ca "MyCA"
  key "/etc/ssl/"
  certificate "/etc/ssl/"
  bits 1024
  days 365

REST API Server Certificate, with CA Certificate:

x509_certificate "" do
  ca "Service-CA"
  key "/etc/ssl/"
  certificate "/etc/ssl/"
  cacertificate "/etc/ssl/service_cacert"

REST API Client Certificate:

x509_certificate "service-#{node['fqdn']}" do
  cn node['fqdn']
  ca "Service-CA"
  type "client"
  key "/etc/service/client_key.pem"
  certificate "/etc/service/client_cert.pem"

CA Certificate only, for verification:

x509_ca_certificate "My-CA" do
  cacertificate "/etc/myca.pem"

Signing Client

A client is provided which allows a user to search Chef for outstanding CSRs, sign them, and create data bag items containing the new certificates.

The client is available in this repository, in the client-gem directory, and may be packaged as a gem for installation.

A number of gems are required, and a Gemfile is provided for Bundler's use.

It also needs access to a Chef admin client key, which may be your own client, and to your ~/.chef/knife.rb which configures the server, key path and client name.

There are a number of modes of operation:

  • Find CSRs to be signed by a specific CA, and sign them with that CA.

  • Issue an adhoc certificate to a specific DN.

  • Create a new CA.

  • Find all CSRs awaiting action.

  • Find a specific CSR and provide its signed cert - intended for externally-signed CSRs, such as the public SSL certificate providers.

See the chef-ssl program's embedded help text for options:

$ chef-ssl

Chef-automated SSL certificate signing tool

  autosign             Search for CSRs and sign them with the given CA
  help                 Display global or [command] help documentation.
  issue                Issue an ad hoc certificate
  makeca               Creates a new CA
  search               Searches for outstanding CSRs
  sign                 Search for the given CSR by name and provide a signed certificate

Global Options:
  -h, --help           Display help documentation
  -v, --version        Display version information
  -t, --trace          Display backtrace when an error occurs


1) Use the x509_certificate resource in a recipe, and run chef-client on the node. The first converge of the resource does the following:

  • Creates a new key, with no passphrase.
  • Generates and installs a certificate, signed by an ephemeral CA.
  • Creates a CSR, which is placed in node[:csr_outbox].

2) Use the chef-ssl tool to find and process pending CSRs. The signed certificate is placed into a databag item.

3) Run chef-client on the node again. This converge does the following:

  • Retrieves the certificate databag item.
  • Removes the corresponding entry from node[:csr_outbox].
  • Installs the signed certificate from the databag.


Q) Can I get my CSR signed by a commercial Certificate Authority?

A) Yes - use the chef-ssl sign command to retrieve the CSR, and to supply the text of the signed certificate.

Q) My certificate is about to expire - how can I generate a new CSR?

A) Remove the databag item for the certificate. The next time chef-client is run on the node, a new CSR will be placed in node[:csr_outbox]. The existing key and certificate will not be touched.


There are rspec tests in the spec directory, which use the rspec-chef library bundled with the cookbook. These can be run directly:

$ bundle $ bundle exec rspec spec/*/_spec.rb


Licence and Author

Author:: Chris Andrews ( Author:: Zac Stevens (

Copyright 2011-2012 Venda Ltd

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Dependent cookbooks

vt-gpg >= 0.0.0

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

Collaborator Number Metric

1.1.0 failed this metric

Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric

1.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, and your repo must contain a file

Foodcritic Metric

1.1.0 failed this metric

FC059: LWRP provider does not declare use_inline_resources: x509/providers/ca_certificate.rb:1
FC059: LWRP provider does not declare use_inline_resources: x509/providers/certificate.rb:1
FC064: Ensure issues_url is set in metadata: x509/metadata.rb:1
FC065: Ensure source_url is set in metadata: x509/metadata.rb:1
FC066: Ensure chef_version is set in metadata: x509/metadata.rb:1
FC067: Ensure at least one platform supported in metadata: x509/metadata.rb:1
FC069: Ensure standardized license defined in metadata: x509/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: x509/resources/ca_certificate.rb:1
FC074: LWRP should use DSL to define resource's default action: x509/resources/certificate.rb:1
Run with Foodcritic Version 12.2.1 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

License Metric

1.1.0 failed this metric

x509 does not have a valid open source license.
Acceptable licenses include Apache-2.0, apachev2, Apache 2.0, MIT, mit, GPL-2.0, gplv2, GNU Public License 2.0, GPL-3.0, gplv3, GNU Public License 3.0.

No Binaries Metric

1.1.0 passed this metric

Publish Metric

1.1.0 passed this metric

Supported Platforms Metric

1.1.0 failed this metric

x509 should declare what platform(s) it supports.

Testing File Metric

1.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, and your repo must contain a file

Version Tag Metric

1.1.0 passed this metric