Add examples to various resources

This let's us get these onto the docs site as well.

Signed-off-by: Tim Smith <tsmith@chef.io>

10 files changed, 195 insertions, 4 deletions

diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 4d57ae648f..59db9fb953 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -22,9 +22,24 @@ class Chef
       resource_name :hostname
       provides :hostname
 
-      description "Use the hostname resource to set the system's hostname, configure hostname and hosts config"\
-                  " file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks."
+      description "Use the hostname resource to set the system's hostname, configure hostname and hosts config file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks."
       introduced "14.0"
+      examples <<~DOC
+        Set the hostname using the IP address, as detected by Ohai
+
+        ```ruby
+        hostname 'example'
+        ```
+
+        Manually specify the hostname and IP address
+
+        ```ruby
+        hostname 'statically_configured_host' do
+          hostname 'example'
+          ipaddress '198.51.100.2'
+        end
+        ```
+      DOC
 
       property :hostname, String,
         description: "An optional property to set the hostname if it differs from the resource block's name.",
diff --git a/lib/chef/resource/notify_group.rb b/lib/chef/resource/notify_group.rb
index 94ca261f62..b452ed569a 100644
--- a/lib/chef/resource/notify_group.rb
+++ b/lib/chef/resource/notify_group.rb
@@ -27,11 +27,10 @@ class Chef
 
       description "The notify_group resource does nothing, and always fires notifications which are set on it.  Use it to DRY blocks of notifications that are common to multiple resources, and provide a single target for other resources to notify.  Unlike most resources, its default action is :nothing."
       introduced "15.8"
-
       examples <<~DOC
         Wire up a notification from a service resource to stop and start the service with a 60 second delay.
 
-        ```
+        ```ruby
         service "crude" do
           action [ :enable, :start ]
         end
diff --git a/lib/chef/resource/openssl_dhparam.rb b/lib/chef/resource/openssl_dhparam.rb
index 254a840a48..9d8d82c4ba 100644
--- a/lib/chef/resource/openssl_dhparam.rb
+++ b/lib/chef/resource/openssl_dhparam.rb
@@ -28,6 +28,16 @@ class Chef
 
       description "Use the openssl_dhparam resource to generate dhparam.pem files. If a valid dhparam.pem file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid dhparam file, it will be overwritten."
       introduced "14.0"
+      examples <<~DOC
+        Create a 1024bit dhparam file
+
+        ```ruby
+        openssl_dhparam '/etc/ssl_files/dhparam.pem' do
+          key_length 1024
+          action :create
+        end
+        ```
+      DOC
 
       property :path, String,
         description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_ec_private_key.rb b/lib/chef/resource/openssl_ec_private_key.rb
index 746322dfc5..7d6d95f51b 100644
--- a/lib/chef/resource/openssl_ec_private_key.rb
+++ b/lib/chef/resource/openssl_ec_private_key.rb
@@ -28,6 +28,28 @@ class Chef
 
       description "Use the openssl_ec_private_key resource to generate an elliptic curve (EC) private key file. If a valid EC key file can be opened at the specified location, no new file will be created. If the EC key file cannot be opened, either because it does not exist or because the password to the EC key file does not match the password in the recipe, then it will be overwritten."
       introduced "14.4"
+      examples <<~DOC
+        Generate a new ec privatekey with prime256v1 key curve and default des3 cipher
+
+        ```ruby
+        openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
+          key_curve 'prime256v1'
+          key_pass 'something'
+          action :create
+        end
+        ```
+
+        Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher
+
+        ```ruby
+        openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
+          key_curve 'prime256v1'
+          key_cipher 'aes-128-cbc'
+          key_pass 'something'
+          action :create
+        end
+        ```
+      DOC
 
       property :path, String,
         description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_ec_public_key.rb b/lib/chef/resource/openssl_ec_public_key.rb
index 0be9885df6..d0208315bd 100644
--- a/lib/chef/resource/openssl_ec_public_key.rb
+++ b/lib/chef/resource/openssl_ec_public_key.rb
@@ -28,6 +28,26 @@ class Chef
 
       description "Use the openssl_ec_public_key resource to generate elliptic curve (EC) public key files from a given EC private key."
       introduced "14.4"
+      examples <<~DOC
+        Generate new ec public key from a private key on disk
+
+        ```ruby
+        openssl_ec_public_key '/etc/ssl_files/eckey_prime256v1_des3.pub' do
+          private_key_path '/etc/ssl_files/eckey_prime256v1_des3.pem'
+          private_key_pass 'something'
+          action :create
+        end
+        ```
+
+        Generate new ec public key by passing in a private key
+
+        ```ruby
+        openssl_ec_public_key '/etc/ssl_files/eckey_prime256v1_des3_2.pub' do
+          private_key_content "-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEII2VAU9re44mAUzYPWCg+qqwdmP8CplsEg0b/DYPXLg2oAoGCCqGSM49\nAwEHoUQDQgAEKkpMCbIQ2C6Qlp/B+Odp1a9Y06Sm8yqPvCVIkWYP7M8PX5+RmoIv\njGBVf/+mVBx77ji3NpTilMUt2KPZ87lZ3w==\n-----END EC PRIVATE KEY-----\n"
+          action :create
+        end
+        ```
+      DOC
 
       property :path, String,
         description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index 38ffa2c394..7da6700764 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -29,6 +29,26 @@ class Chef
 
       description "Use the openssl_rsa_private_key resource to generate RSA private key files. If a valid RSA key file can be opened at the specified location, no new file will be created. If the RSA key file cannot be opened, either because it does not exist or because the password to the RSA key file does not match the password in the recipe, it will be overwritten."
       introduced "14.0"
+      examples <<~DOC
+        Generate new 2048bit key with the default des3 cipher
+
+        ```ruby
+        openssl_rsa_private_key '/etc/ssl_files/rsakey_des3.pem' do
+          key_length 2048
+          action :create
+        end
+        ```
+
+        Generate new 1024bit key with the aes-128-cbc cipher
+
+        ```ruby
+        openssl_rsa_key '/etc/ssl_files/rsakey_aes128cbc.pem' do
+          key_length 1024
+          key_cipher 'aes-128-cbc'
+          action :create
+        end
+        ```
+      DOC
 
       property :path, String,
         description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_rsa_public_key.rb b/lib/chef/resource/openssl_rsa_public_key.rb
index c7c125fb9e..f62c382c27 100644
--- a/lib/chef/resource/openssl_rsa_public_key.rb
+++ b/lib/chef/resource/openssl_rsa_public_key.rb
@@ -26,6 +26,28 @@ class Chef
       resource_name :openssl_rsa_public_key
       provides(:openssl_rsa_public_key) { true }
 
+      examples <<~DOC
+        Generate new public key from a private key on disk
+
+        ```ruby
+        openssl_rsa_public_key '/etc/ssl_files/rsakey_des3.pub' do
+          private_key_path '/etc/ssl_files/rsakey_des3.pem'
+          private_key_pass 'something'
+          action :create
+        end
+        ```
+
+        Generate new public key by passing in a private key
+
+        ```ruby
+        openssl_rsa_public_key '/etc/ssl_files/rsakey_2.pub' do
+          private_key_pass 'something'
+          private_key_content "-----BEGIN RSA PRIVATE KEY-----\nProc-Type: 4,ENCRYPTED\nDEK-Info: DES-EDE3-CBC,5EE0AE9A5FE3342E\n\nyb930kj5/4/nd738dPx6XdbDrMCvqkldaz0rHNw8xsWvwARrl/QSPwROG3WY7ROl\nEUttVlLaeVaqRPfQbmTUfzGI8kTMmDWKjw52gJUx2YJTYRgMHAB0dzYIRjeZAaeS\nypXnEfouVav+jKTmmehr1WuVKbzRhQDBSalzeUwsPi2+fb3Bfuo1dRW6xt8yFuc4\nAkv1hCglymPzPHE2L0nSGjcgA2DZu+/S8/wZ4E63442NHPzO4VlLvpNvJrYpEWq9\nB5mJzcdXPeOTjqd13olNTlOZMaKxu9QShu50GreCTVsl8VRkK8NtwbWuPGBZlIFa\njzlS/RaLuzNzfajaKMkcIYco9t7gN2DwnsACHKqEYT8248Ii3NQ+9/M5YcmpywQj\nWGr0UFCSAdCky1lRjwT+zGQKohr+dVR1GaLem+rSZH94df4YBxDYw4rjsKoEhvXB\nv2Vlx+G7Vl2NFiZzxUKh3MvQLr/NDElpG1pYWDiE0DIG13UqEG++cS870mcEyfFh\nSF2SXYHLWyAhDK0viRDChJyFMduC4E7a2P9DJhL3ZvM0KZ1SLMwROc1XuZ704GwO\nYUqtCX5OOIsTti1Z74jQm9uWFikhgWByhVtu6sYL1YTqtiPJDMFhA560zp/k/qLO\nFKiM4eUWV8AI8AVwT6A4o45N2Ru8S48NQyvh/ADFNrgJbVSeDoYE23+DYKpzbaW9\n00BD/EmUQqaQMc670vmI+CIdcdE7L1zqD6MZN7wtPaRIjx4FJBGsFoeDShr+LoTD\nrwbadwrbc2Rf4DWlvFwLJ4pvNvdtY3wtBu79UCOol0+t8DVVSPVASsh+tp8XncDE\nKRljj88WwBjX7/YlRWvQpe5y2UrsHI0pNy8TA1Xkf6GPr6aS2TvQD5gOrAVReSse\n/kktCzZQotjmY1odvo90Zi6A9NCzkI4ZLgAuhiKDPhxZg61IeLppnfFw0v3H4331\nV9SMYgr1Ftov0++x7q9hFPIHwZp6NHHOhdHNI80XkHqtY/hEvsh7MhFMYCgSY1pa\nK/gMcZ/5Wdg9LwOK6nYRmtPtg6fuqj+jB3Rue5/p9dt4kfom4etCSeJPdvP1Mx2I\neNmyQ/7JN9N87FsfZsIj5OK9OB0fPdj0N0m1mlHM/mFt5UM5x39u13QkCt7skEF+\nyOptXcL629/xwm8eg4EXnKFk330WcYSw+sYmAQ9ZTsBxpCMkz0K4PBTPWWXx63XS\nc4J0r88kbCkMCNv41of8ceeGzFrC74dG7i3IUqZzMzRP8cFeps8auhweUHD2hULs\nXwwtII0YQ6/Fw4hgGQ5//0ASdvAicvH0l1jOQScHzXC2QWNg3GttueB/kmhMeGGm\nsHOJ1rXQ4oEckFvBHOvzjP3kuRHSWFYDx35RjWLAwLCG9odQUApHjLBgFNg9yOR0\njW9a2SGxRvBAfdjTa9ZBBrbjlaF57hq7mXws90P88RpAL+xxCAZUElqeW2Rb2rQ6\nCbz4/AtPekV1CYVodGkPutOsew2zjNqlNH+M8XzfonA60UAH20TEqAgLKwgfgr+a\nc+rXp1AupBxat4EHYJiwXBB9XcVwyp5Z+/dXsYmLXzoMOnp8OFyQ9H8R7y9Y0PEu\n-----END RSA PRIVATE KEY-----\n"
+          action :create
+        end
+        ```
+      DOC
+
       description "Use the openssl_rsa_public_key resource to generate RSA public key files for a given RSA private key."
       introduced "14.0"
 
diff --git a/lib/chef/resource/openssl_x509_certificate.rb b/lib/chef/resource/openssl_x509_certificate.rb
index a501fbdaac..1c0a2ee65d 100644
--- a/lib/chef/resource/openssl_x509_certificate.rb
+++ b/lib/chef/resource/openssl_x509_certificate.rb
@@ -29,6 +29,42 @@ class Chef
 
       description "Use the openssl_x509_certificate resource to generate signed or self-signed, PEM-formatted x509 certificates. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate. If a CA private key and certificate are provided, the certificate will be signed with them. Note: This resource was renamed from openssl_x509 to openssl_x509_certificate. The legacy name will continue to function, but cookbook code should be updated for the new resource name."
       introduced "14.4"
+      examples <<~DOC
+        Create a simple self-signed certificate file
+
+        ```ruby
+        openssl_x509_certificate '/etc/httpd/ssl/mycert.pem' do
+          common_name 'www.f00bar.com'
+          org 'Foo Bar'
+          org_unit 'Lab'
+          country 'US'
+        end
+        ```
+
+        Create a certificate using additional options
+
+        ```ruby
+        openssl_x509_certificate '/etc/ssl_files/my_signed_cert.crt' do
+          common_name 'www.f00bar.com'
+          ca_key_file '/etc/ssl_files/my_ca.key'
+          ca_cert_file '/etc/ssl_files/my_ca.crt'
+          expire 365
+          extensions(
+            'keyUsage' => {
+              'values' => %w(
+                keyEncipherment
+                digitalSignature),
+              'critical' => true,
+            },
+            'extendedKeyUsage' => {
+              'values' => %w(serverAuth),
+              'critical' => false,
+            }
+          )
+          subject_alt_name ['IP:127.0.0.1', 'DNS:localhost.localdomain']
+        end
+        ```
+      DOC
 
       property :path, String,
         description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_x509_crl.rb b/lib/chef/resource/openssl_x509_crl.rb
index 650db6863e..73c4c79a4e 100644
--- a/lib/chef/resource/openssl_x509_crl.rb
+++ b/lib/chef/resource/openssl_x509_crl.rb
@@ -28,6 +28,17 @@ class Chef
 
       description "Use the openssl_x509_crl resource to generate PEM-formatted x509 certificate revocation list (CRL) files."
       introduced "14.4"
+      examples <<~DOC
+        Generate a CRL file given a cert file and key file
+
+        ```ruby
+        openssl_x509_crl '/etc/ssl_files/my_ca2.crl' do
+          ca_cert_file '/etc/ssl_files/my_ca2.crt'
+          ca_key_file '/etc/ssl_files/my_ca2.key'
+          expire 1
+        end
+        ```
+      DOC
 
       property :path, String,
         description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_x509_request.rb b/lib/chef/resource/openssl_x509_request.rb
index 982f29dd75..cac03f7d98 100644
--- a/lib/chef/resource/openssl_x509_request.rb
+++ b/lib/chef/resource/openssl_x509_request.rb
@@ -28,6 +28,42 @@ class Chef
 
       description "Use the openssl_x509_request resource to generate PEM-formatted x509 certificates requests. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate."
       introduced "14.4"
+      examples <<~DOC
+        Generate new ec key and csr file
+
+        ```ruby
+        openssl_x509_request '/etc/ssl_files/my_ec_request.csr' do
+          common_name 'myecrequest.example.com'
+          org 'Test Kitchen Example'
+          org_unit 'Kitchens'
+          country 'UK'
+        end
+        ```
+
+        Generate a new csr file from an existing ec key
+
+        ```ruby
+        openssl_x509_request '/etc/ssl_files/my_ec_request2.csr' do
+          common_name 'myecrequest2.example.com'
+          org 'Test Kitchen Example'
+          org_unit 'Kitchens'
+          country 'UK'
+          key_file '/etc/ssl_files/my_ec_request.key'
+        end
+        ```
+
+        Generate new rsa key and csr file
+
+        ```ruby
+        openssl_x509_request '/etc/ssl_files/my_rsa_request.csr' do
+          common_name 'myrsarequest.example.com'
+          org 'Test Kitchen Example'
+          org_unit 'Kitchens'
+          country 'UK'
+          key_type 'rsa'
+        end
+        ```
+      DOC
 
       property :path, String, name_property: true,
                description: "An optional property for specifying the path to write the file to if it differs from the resource block's name."