Allow versioned secrets via DSL

    Versioning is commonly supported across most major secrets services.

    This change allows the DSL to support fetching a specific secret
    version.   Implementations are expected to default to fetching the most
    recent version when no version is provided.

    Usage:

      secret(name: 'secret1', version: 'version1', service: :example)

Signed-off-by: Marc A. Paradise <marc.paradise@gmail.com>

6 files changed, 33 insertions, 46 deletions

diff --git a/lib/chef/dsl/secret.rb b/lib/chef/dsl/secret.rb
index 9cc7d6b3da..28f49a52a6 100644
--- a/lib/chef/dsl/secret.rb
+++ b/lib/chef/dsl/secret.rb
@@ -29,12 +29,15 @@ class Chef
       # that resource as 'sensitive', preventing resource data from being logged.  See [Chef::Resource#sensitive].
       #
       # @option name [Object] The identifier or name for this secret
+      # @option version [Object] The secret version. If a service supports versions
+      #                          and no version is provided, the latest version will be fetched.
       # @option service [Symbol] The service identifier for the service that will
-      #                         perform the secret lookup
+      #                         perform the secret lookup. See
+      #                         [Chef::SecretFetcher::SECRET_FETCHERS]
       # @option config [Hash] The configuration that the named service expects
       #
-      # @return result [Object] The response object type is determined by the fetcher. See fetcher documentation
-      # to know what to expect for a given service.
+      # @return result [Object] The response object type is determined by the fetcher but will usually be a string or a hash.
+      # See individual fetcher documentation to know what to expect for a given service.
       #
       # @example
       #
@@ -44,20 +47,11 @@ class Chef
       #   value = secret(name: "test1", service: :example, config: { "test1" => "value1" })
       #   log "My secret is #{value}"
       #
-      #   value = secret(name: "test1", service: :aws_secrets_manager, config: { region: "us-west-1" })
-      #   log "My secret is #{value.secret_string}"
-      #
-      # @note
-      #
-      # This is pretty straightforward, but should also extend nicely to support
-      # named config (as 'service') with override config. Some future potential
-      # usage examples:
-      #   value = secret(name: "test1") # If a default is configured
-      #   value = secret(name: "test1", service: "my_aws_east")
-      #   value = secret(name: "test1", service: "my_aws_west", config: { region: "override-region" })
-      def secret(name: nil, service: nil, config: nil)
+      #   value = secret(name: "test1", service: :aws_secrets_manager, version: "v1", config: { region: "us-west-1" })
+      #   log "My secret is #{value}"
+      def secret(name: nil, version: nil, service: nil, config: nil)
         sensitive(true) if is_a?(Chef::Resource)
-        Chef::SecretFetcher.for_service(service, config).fetch(name)
+        Chef::SecretFetcher.for_service(service, config).fetch(name, version)
       end
     end
   end
diff --git a/lib/chef/secret_fetcher/aws_secrets_manager.rb b/lib/chef/secret_fetcher/aws_secrets_manager.rb
index f5508cf59b..a04d90dcdf 100644
--- a/lib/chef/secret_fetcher/aws_secrets_manager.rb
+++ b/lib/chef/secret_fetcher/aws_secrets_manager.rb
@@ -24,6 +24,9 @@ class Chef
   # A fetcher that fetches a secret from AWS Secrets Manager
   # In this initial iteration it defaults to authentication via instance profile.
   # It is possible to pass options that configure it to use alternative credentials.
+  # This implementation supports fetching with version.
+  #
+  # NOTE: This does not yet support automatic retries, which the AWS client does by default.
   #
   # For configuration options see https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SecretsManager/Client.html#initialize-instance_method
   #
@@ -33,31 +36,18 @@ class Chef
   # Usage Example:
   #
   # fetcher = SecretFetcher.for_service(:aws_secrets_manager, { region: "us-east-1" })
-  # fetcher.fetch("secretkey1")
+  # fetcher.fetch("secretkey1", "v1")
   class SecretFetcher
     class AWSSecretsManager < Base
-      DEFAULT_AWS_OPTS = {} # rubocop: disable Style/MutableConstant
-      def validate!
-        # Note that we are not doing any validation of required configuration here, we will
-        # rely on the API client to do that for us, since it will work with the merge of
-        # the config we provide, env-based config, and/or an appropriate profile in ~/.aws
-
-        # Instantiating the client is an opportunity for an API provider to do validation,
-        # so we'll do that first here.
-        client
-      end
-
       # @param identifier [String] the secret_id
+      # @param version [String] the secret version. Not usd at this time
       # @return Aws::SecretsManager::Types::GetSecretValueResponse
-      def do_fetch(identifier)
-        result = client.get_secret_value(secret_id: identifier)
+      def do_fetch(identifier, version)
+        client = Aws::SecretsManager::Client.new()
+        result = client.get_secret_value(secret_id: identifier, version_stage: version)
         # These fields are mutually exclusive
         result.secret_string || result.secret_binary
       end
-
-      def client
-        @client ||= Aws::SecretsManager::Client.new(DEFAULT_AWS_OPTS.merge(config))
-      end
     end
   end
 end
diff --git a/lib/chef/secret_fetcher/base.rb b/lib/chef/secret_fetcher/base.rb
index a80ecea0fb..bfc3a44e4c 100644
--- a/lib/chef/secret_fetcher/base.rb
+++ b/lib/chef/secret_fetcher/base.rb
@@ -37,14 +37,14 @@ class Chef
       # Fetch the named secret by invoking implementation-specific [Chef::SecretFetcher::Base#do_fetch]
       #
       # @param name [Object] the name or identifier of the secret.
+      # @param version [Object] Optional version of the secret to fetch.
       # @note - the name parameter will probably see a narrowing of type as we learn more about different integrations.
-      # @return [Object] the result of the secret fetch
+      # @return [Object] the fetched secret
       # @raise [Chef::Exceptions::Secret::MissingSecretName] when secret name is not provided
       # @raise [Chef::Exceptions::Secret::FetchFailed] when the underlying attempt to fetch the secret fails.
-      def fetch(name)
-        raise Chef::Exceptions::Secret::MissingSecretName.new if name.nil? || name.to_s == ""
-
-        do_fetch(name)
+      def fetch(name, version = nil)
+        raise Chef::Exceptions::Secret::MissingSecretName.new if name.to_s == ""
+        do_fetch(name, version)
       end
 
       # Validate that the instance is correctly configured.
@@ -57,12 +57,15 @@ class Chef
       # @param identifier [Object] Unique identifier of the secret to be retrieved.
       # When invoked via DSL, this is pre-verified to be not nil/not empty string.
       # The expected data type and form can vary by implementation.
+      # @param version [Object] Optional version of the secret to be retrieved.  If not
+      # provided, implementations are expected to fetch the most recent version of the
+      # secret by default.
       #
       # @return [Object] The secret as returned from the implementation.  The data type
       # will vary implementation.
       #
       # @raise [Chef::Exceptions::Secret::FetchFailed] if the secret could not be fetched
-      def do_fetch(identifier); raise NotImplementedError.new; end
+      def do_fetch(identifier, version); raise NotImplementedError.new; end
     end
   end
 end
diff --git a/lib/chef/secret_fetcher/example.rb b/lib/chef/secret_fetcher/example.rb
index 7a0e671929..28b806bf31 100644
--- a/lib/chef/secret_fetcher/example.rb
+++ b/lib/chef/secret_fetcher/example.rb
@@ -36,7 +36,7 @@ class Chef
         end
       end
 
-      def do_fetch(identifier)
+      def do_fetch(identifier, version)
         raise Chef::Exceptions::Secret::FetchFailed.new("Secret #{identifier}) not found.") unless config.key?(identifier)
 
         config[identifier]
diff --git a/spec/unit/dsl/secret_spec.rb b/spec/unit/dsl/secret_spec.rb
index 99699b253e..ee25c511ee 100644
--- a/spec/unit/dsl/secret_spec.rb
+++ b/spec/unit/dsl/secret_spec.rb
@@ -24,7 +24,7 @@ class SecretDSLTester
 end
 
 class SecretFetcherImpl < Chef::SecretFetcher::Base
-  def do_fetch(name)
+  def do_fetch(name, version)
     name
   end
 end
@@ -38,7 +38,7 @@ describe Chef::DSL::Secret do
   it "uses SecretFetcher.for_service to find the fetcher" do
     substitute_fetcher = SecretFetcherImpl.new({})
     expect(Chef::SecretFetcher).to receive(:for_service).with(:example, {}).and_return(substitute_fetcher)
-    expect(substitute_fetcher).to receive(:fetch).with "key1"
+    expect(substitute_fetcher).to receive(:fetch).with("key1", nil)
     dsl.secret(name: "key1", service: :example, config: {})
   end
 
diff --git a/spec/unit/secret_fetcher_spec.rb b/spec/unit/secret_fetcher_spec.rb
index c352585266..f2a1f96cbb 100644
--- a/spec/unit/secret_fetcher_spec.rb
+++ b/spec/unit/secret_fetcher_spec.rb
@@ -20,7 +20,7 @@ require "chef/secret_fetcher"
 require "chef/secret_fetcher/example"
 
 class SecretFetcherImpl < Chef::SecretFetcher::Base
-  def do_fetch(name)
+  def do_fetch(name, version)
     name
   end
 
@@ -67,8 +67,8 @@ describe Chef::SecretFetcher do
     }
 
     it "fetches from the underlying service when secret name is provided " do
-      expect(fetcher_impl).to receive(:fetch).with("key1")
-      fetcher.fetch("key1")
+      expect(fetcher_impl).to receive(:fetch).with("key1", "v1")
+      fetcher.fetch("key1", "v1")
     end
 
     it "raises an error when the secret name is not provided" do