Merge pull request #9324 from chef/systctl_comments

sysctl: Add new comments property for adding comments to configs

3 files changed, 85 insertions, 3 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 50a6e5dd83..e1a634addd 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,5 +1,41 @@
 This file holds "in progress" release notes for the current release under development and is intended for consumption by the Chef Documentation team. Please see <https://docs.chef.io/release_notes.html> for the official Chef release notes.
 
+# UNRELEASED
+
+### sysctl now accepts a comments parameter
+
+The `sysctl` resource has been updated to allow the inclusion of descriptive comments. Comments may be passed as an array or as a string. Any comments provided are prefixed with '#' signs and precede the `sysctl` setting in generated files.
+
+An example:
+
+```ruby
+sysctl 'vm.swappiness' do
+  value 10
+  comment [
+     "define how aggressively the kernel will swap memory pages.",
+     "Higher values will increase aggressiveness",
+     "lower values decrease the amount of swap.",
+     "A value of 0 instructs the kernel not to initiate swap",
+     "until the amount of free and file-backed pages is less",
+     "than the high water mark in a zone.",
+     "The default value is 60."
+    ]
+end
+```
+
+which results in `/etc/sysctl.d/99-chef-vm.swappiness.conf` as follows:
+
+```
+# define how aggressively the kernel will swap memory pages.
+# Higher values will increase aggressiveness
+# lower values decrease the amount of swap.
+# A value of 0 instructs the kernel not to initiate swap
+# until the amount of free and file-backed pages is less
+# than the high water mark in a zone.
+# The default value is 60.
+vm.swappiness = 10
+```
+
 # Chef Infra Client 15.7
 
 ## Updated Resources
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index a6c316c5bc..edbeb23daa 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -1,6 +1,6 @@
 #
 # Copyright:: 2018, Webb Agile Solutions Ltd.
-# Copyright:: 2018-2018, Chef Software Inc.
+# Copyright:: 2018-2020, Chef Software Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -45,6 +45,11 @@ class Chef
         coerce: proc { |v| coerce_value(v) },
         required: true
 
+      property :comment, [Array, String],
+        description: "Comments, placed above the resource setting in the generated file. For multi-line comments, use an array of strings, one per line.",
+        default: [],
+        introduced: "15.8"
+
       property :conf_dir, String,
         description: "The configuration directory to write the config to.",
         default: "/etc/sysctl.d"
@@ -81,7 +86,7 @@ class Chef
           directory new_resource.conf_dir
 
           file "#{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf" do
-            content "#{new_resource.key} = #{new_resource.value}"
+            content contruct_sysctl_content
           end
 
           execute "Load sysctl values" do
@@ -112,9 +117,28 @@ class Chef
       end
 
       action_class do
+        #
+        # Shell out to set the sysctl value
+        #
+        # @param [String] key The sysctl key
+        # @param [String] value The value of the sysctl key
+        #
         def set_sysctl_param(key, value)
           shell_out!("sysctl #{"-e " if new_resource.ignore_error}-w \"#{key}=#{value}\"")
         end
+
+        #
+        # construct a string, joining members of new_resource.comment and new_resource.value
+        #
+        # @return [String] The text file content
+        #
+        def contruct_sysctl_content
+          sysctl_lines = Array(new_resource.comment).map { |c| "# #{c.strip}" }
+
+          sysctl_lines << "#{new_resource.key} = #{new_resource.value}"
+
+          sysctl_lines.join("\n")
+        end
       end
 
       private
diff --git a/spec/unit/resource/sysctl_spec.rb b/spec/unit/resource/sysctl_spec.rb
index ba4b23f098..5d978d3b38 100644
--- a/spec/unit/resource/sysctl_spec.rb
+++ b/spec/unit/resource/sysctl_spec.rb
@@ -1,5 +1,5 @@
 #
-# Copyright:: Copyright 2018, Chef Software, Inc.
+# Copyright:: Copyright 2018-2020, Chef Software, Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,6 +19,7 @@ require "spec_helper"
 
 describe Chef::Resource::Sysctl do
   let(:resource) { Chef::Resource::Sysctl.new("fakey_fakerton") }
+  let(:provider) { resource.provider_for_action(:create) }
 
   it "sets resource name as :sysctl" do
     expect(resource.resource_name).to eql(:sysctl)
@@ -51,4 +52,25 @@ describe Chef::Resource::Sysctl do
     resource.value 1.1
     expect(resource.value).to eql("1.1")
   end
+
+  context "#contruct_sysctl_content" do
+    before do
+      resource.key("foo")
+      resource.value("bar")
+    end
+
+    context "when comment is a String" do
+      it "Returns content for use with a file resource" do
+        resource.comment("This sets foo / bar on our system")
+        expect(provider.contruct_sysctl_content).to eql("# This sets foo / bar on our system\nfoo = bar")
+      end
+    end
+
+    context "when comment is an Array" do
+      it "Returns content for use with a file resource" do
+        resource.comment(["This sets foo / bar on our system", "We need for baz"])
+        expect(provider.contruct_sysctl_content).to eql("# This sets foo / bar on our system\n# We need for baz\nfoo = bar")
+      end
+    end
+  end
 end