aws-ssm-env 0.1.0

data/README_en.md

@@ -0,0 +1,5 @@
+# aws-ssm-env
+
+Set parameters acquired from `AWS EC2 Parameter Store` as environment variables.  
+
+**TODO** translate

data/lib/aws-ssm-env.rb

@@ -0,0 +1,160 @@
+require 'aws-ssm-env/loader'
+#
+# AWS EC2 Parameters Storeからパラメータを取得してENVに書き込むモジュール。
+#
+# @author Ryohei Sonoda
+# @since 0.1.0
+module AwsSsmEnv
+  module_function
+
+  # メイン処理。EC2 Parameter Storeからパラメータを取得して環境変数にインジェクションする。
+  #
+  # @param [Hash] args この処理で利用するすべての引数をまとめて渡す。
+  #
+  # @option args [Boolean] decryption
+  #
+  #   SecureStringのパラメータを復号化するかどうかを表すフラグ。
+  #   `true`を指定した場合は取得したSecureStringパラメータの値は復号化されている。
+  #   `false`の場合は暗号化されたまた環境変数値として設定される。
+  #   なお、このためのgemなのでデフォルトは`true`(復号化する)。
+  #
+  # @option args [Boolean] overwrite
+  #
+  #   すでに設定されている環境変数を上書きするかどうかを指定する。
+  #   `true`を指定した場合、環境変数が設定されていても取得したパラメータ値で上書きする。
+  #   `false`を指定した場合はすでに設定されている環境変数を上書きしない。
+  #   デフォルトは`false`(上書きしない)。
+  #   なお、`AwsSsmEnv#load!`を実行した場合、このフラグは自動的に`true`になる。
+  #
+  # @option args [Aws::SSM::Client] :client
+  #
+  #   `Aws::SSM::Client`のインスタンスを指定する。
+  #   すでに生成済みのインスタンスがある場合にそれを設定するためのオプション。
+  #   生成済みのインスタンスがない場合は`ssm_client_args`を利用する。
+  #
+  # @option args [Hash] :ssm_client_args
+  #
+  #   `Aws::SSM::Client`のコンストラクタに渡すハッシュを指定する。
+  #   指定しなかった場合は引数なしで`Aws::SSM::Client.new`が呼ばれる。
+  #   環境変数やEC2インスタンスプロファイルによる認証情報を利用する場合は不要。
+  #
+  # @option args [Symbol, AwsSsmEnv::Fetcher, Object] :fetch
+  #
+  #   パラメータ取得方法を指定する。
+  #   指定可能な値は`:path`, `:begins_with`または`AwsSsmEnv::Fetcher`を実装したクラスのインスタンス、`each`メソッドを
+  #   持ったクラスのインスタンスのいずれか。
+  #   何も指定されていない場合は`:path`として扱われるが、後述の`begins_with`が指定されていた場合は自動的に`:begins_with`となる。
+  #
+  #   `:path`を指定した場合はパラメータ階層をパス指定で取得する`AwsSsmEnv::PathFetcher`が利用される。
+  #   この場合は後述の`path`引数が必須となる。また、後述の`recursive`引数を利用する。
+  #   この方法でパラメータを取得する場合は指定するパスに対して`ssm:GetParametersByPath`の権限が必要。
+  #   以下、IAMポリシーの例を示す。
+  #   {
+  #     "Version": "2012-10-17",
+  #     "Statement": [
+  #       {
+  #         "Sid": "",
+  #         "Effect": "Allow",
+  #         "Action": "ssm:GetParametersByPath",
+  #         "Resource": "arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter/your_path"
+  #       }
+  #     ]
+  #   }
+  #
+  #   `:begins_with`を指定した場合はパラメータ名が指定した文字列から開始するパラメータを取得する`AwsSsmEnv::BeginsWithFetcher`が利用される。
+  #   この場合は後述の`begins_with`引数が必須となる。
+  #   この方法でパラメータを取得する場合は指定するパスに対して`ssm:DescribeParameters`および`ssm:GetParameters`の権限が必要。
+  #   以下、IAMポリシーの例を示す。
+  #   {
+  #     "Version": "2012-10-17",
+  #     "Statement": [
+  #       {
+  #         "Sid": "",
+  #         "Effect": "Allow",
+  #         "Action": "ssm:DescribeParameters",
+  #         "Resource": "arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter"
+  #       },
+  #       {
+  #         "Sid": "",
+  #         "Effect": "Allow",
+  #         "Action": "ssm:GetParameters",
+  #         "Resource": "arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter/your_path/*"
+  #       }
+  #     ]
+  #   }
+  #
+  #   `fetch`に`AwsSsmEnv::Fetcher`を実装したクラスのインスタンス、もしくは`each`メソッドを持つ
+  #   インスタンスを指定した場合はそのインスタンスをそのまま利用する。
+  #
+  # @option args [Symbol, AwsSsmEnv::NamingStrategy, Object] :naming
+  #
+  #   環境変数名を導出方法を指定する。
+  #   指定可能な値は`:basename`, `:snakecase`または`AwsSsmEnv::NamingStrategy`を実装したクラスのインスタンス、`parse_name`メソッドを持ったクラスのインスタンスのいずれか。
+  #   デフォルトは`:basename`。
+  #
+  #   `naming`を指定しなかった場合、もしくは`:basename`を指定した場合はパラメータ階層の最後の階層を変数名とする`AwsSsmEnv::BasenameNamingStrategy`が利用される。
+  #   この場合、例えば`/myapp/production/DB_PASSWORD`というパラメータ名であれば`ENV['DB_PASSWORD']`にパラメータ値がインジェクションされる。
+  #
+  #   `:snakecase`を指定した場合はパラメータ名のスラッシュ区切りをアンダースコア区切りにした結果を大文字に変換して環境変数名とする`AwsSsmEnv::SnakeCaseNamingStrategy`が利用される。
+  #   この場合、例えば`/myapp/production/DB_PASSWORD`というパラメータ名であれば`ENV['MYAPP_PRODUCTION_DB_PASSWORD']`にパラメータ値がインジェクションされる。
+  #   後述の`removed_prefix`引数で除外する先頭文字列を指定することができる。
+  #   また、後述の`delimiter`オプションでアンダースコアに変換する文字を指定できる。
+  #   以下の例では`/myapp/production/db/password`というパラメータが`ENV['DB_PASSWORD']`にインジェクションされる。
+  #   > AwsSsmEnv.load(naming: :snakecase, removed_prefix: '/myapp/production')
+  #
+  #   `AwsSsmEnv::NamingStrategy`を実装したクラスのインスタンス、もしくは`parse_name`メソッドを持つ
+  #   インスタンスを指定した場合はそのインスタンスをそのまま利用する。
+  #
+  # @option args [String] :path
+  #
+  #   `fetch`に何も指定していない場合、もしくは`:path`を指定した場合は必須となる。
+  #   パラメータを取得するパス階層を指定する。
+  #   下の例では`/myapp/web/production`直下のパラメータが取得される。
+  #   > AwsSsmEnv.load(path: '/myapp/web/production')
+  #
+  # @option args [Boolean] :recursive
+  #
+  #   `fetch`に何も指定していない場合、もしくは`:path`を指定した場合に利用する。
+  #   指定したパス階層以下のパラメータをすべて取得する。
+  #   下の例では`/myapp/web/production`以下すべてのパラメータが取得される。
+  #   > AwsSsmEnv.load(path: '/myapp/web/production', recursive: true)
+  #
+  # @option args [String, Array<String>] :begins_with
+  #
+  #   `fetch`に`:begins_with`を指定した場合は必須となる。
+  #   取得するパラメータ名のプレフィクスを指定する。配列で複数指定することも可能(OR条件となる)。
+  #   下の例では`myapp.web.production`で始まる名前のパラメータが取得される。
+  #
+  #   下の例では 'myapp.web.production' で始まる名前のパラメータが取得される。
+  #   irb> AwsSsmEnv.load(path: 'myapp.web.production')
+  #
+  # @option args [String] :removed_prefix
+  #
+  #   `naming`に`:snakecase`を指定した場合に利用される。
+  #   環境変数名から除外するパラメータ名のプレフィクスを指定する。
+  #   `:removed_prefix`が指定されておらず、`:begins_with`もしくは`:path`が指定されていた場合はそれを利用する。
+  #
+  # @option args [String, Regexp] :delimiter
+  #
+  #   `naming`に`:snakecase`を指定した場合に利用される。
+  #   アンダースコアに変換する文字列もしくは正規表現を指定する。
+  #   デフォルトはスラッシュ(`/`)。
+  #
+  # @option args [Integer] fetch_size
+  #
+  #   一度のAWS API実行で取得するパラメータ数を指定する。 `:path`指定の場合は最大値は`10`でデフォルトも`10`。
+  #   `:begins_with`指定の場合は最大値は`50`でデフォルトも`50`である。通常このパラメータを指定することはない。
+  #
+  # AwsSsmEnv::Loader#load の委譲メソッド。
+  #
+  # @see AwsSsmEnv::Loader#load
+  def load(**args)
+    AwsSsmEnv::Loader.load(args)
+  end
+
+  # `overwrite`オプションを付与した AwsSsmEnv::Loader#load の委譲メソッド。
+  # @see AwsSsmEnv::Loader#load
+  def load!(**args)
+    AwsSsmEnv::Loader.load(args.merge(overwrite: true))
+  end
+end

data/lib/aws-ssm-env/fetcher.rb

@@ -0,0 +1,120 @@
+require 'aws-sdk-ssm'
+
+module AwsSsmEnv
+  # AWSのParameter Storeからパラメータを取得するための基底抽象クラス。Iteratorパターンを実装。
+  # このクラスのサブクラスは`fetch`メソッドを実装する必要がある。
+  # 実装クラスを AwsSsmEnv#load の引数に渡すことによりパラメータの取得方法を切り替えられるようにする。
+  #
+  # @abstract
+  # @author Ryohei Sonoda
+  # @since 0.1.0
+  class Fetcher
+    # ここの引数は AwsSsmEnv#load の呼び出し時に渡された引数がそのまま渡される。
+    # 実装クラスによって`args`の内容は変化するが、decryption, client, ssm_client_args は全サブクラス共通。
+    #
+    # @param [Hash] args AwsSsmEnv#load の呼び出し時に渡された引数。
+    # @option args [Boolean] :decryption
+    #   <optional> SecureStringパラメータを復号化するかどうか。デフォルトはtrue(復号化する)。
+    # @option args [Aws::SSM::Client] :client
+    #   <optional> Aws::SSM::Clientのインスタンス。
+    #   指定されなかった場合は`ssm_client_args`を引数にして Aws::SSM::Client#new される。
+    # @option args [Hash] :ssm_client_args
+    #   Aws::SSM::Client#new を実行するときの引数。
+    #
+    # @see http://docs.aws.amazon.com/sdk-for-ruby/v3/api/index.html
+    def initialize(**args)
+      @client = create_ssm_client(args)
+      @with_decryption = with_decryption?(args)
+    end
+
+    # Iteratorパターンを実装したメソッド。AwsSsmEnv#load から呼び出される。
+    # 実際のパラメータ取得はサブクラスで実装された fetch メソッドで行う。
+    # @yield [consumer] 取得したパラメータを受け取って処理を行うブロック引数。
+    # @yieldparam [Aws::SSM::Types::Parameter] parameter パラメータ
+    def each
+      next_token = nil
+      loop do
+        response = fetch(next_token)
+        next_token = response.next_token
+        if response.parameters.empty?
+          break
+        end
+        response.parameters.each do |p|
+          yield(p)
+        end
+        if next_token.nil?
+          break
+        end
+      end
+    end
+
+    protected
+
+    # Parameter Storeの値を取得するメソッド。サブクラスでOverrideする。
+    # 戻り値は AwsSsmEnv::FetchResult と同等の構造でなければいけない。
+    #
+    # @abstract
+    # @param [String] _next_token
+    #   NextTokenが必要な場合に渡される。
+    #   利用するAPIによっては１回で取得可能なものもあるので(GetParameters)、
+    #   このパラメータを利用するかどうかはサブクラスの実装に任せる。
+    # @return [AwsSsmEnv::FetchResult] パラメータの配列とNextToken
+    def fetch(_next_token)
+      raise NotImplementedError, 'fetch'
+    end
+
+    # @return [Boolean] SecureStringを復号化するかどうかのフラグ。
+    # サブクラスからのみアクセスを許可するため`attr_reader`は使わない。
+    def with_decryption
+      @with_decryption
+    end
+
+    # @return [Aws::SSM::Client] aws-sdkのSSMクライアントインスタンス。
+    # サブクラスからのみアクセスを許可するため`attr_reader`は使わない。
+    def client
+      @client
+    end
+
+    private
+
+    def with_decryption?(decryption: 'true', **)
+      if decryption.nil?
+        true
+      elsif decryption.to_s.downcase == 'true'
+        true
+      else
+        false
+      end
+    end
+
+    def create_ssm_client(client: nil, ssm_client_args: {}, **)
+      if client.is_a?(Aws::SSM::Client)
+        client
+      else
+        Aws::SSM::Client.new(ssm_client_args)
+      end
+    end
+  end
+
+  # parametersとnext_tokenを持った値オブジェクト。
+  # Fetcerサブクラスのfetchメソッド戻り値として利用する。
+  #
+  # @attr_reader [Array] parameters
+  #   name, value プロパティを持ったパラメータオブジェクトの配列。配列要素の実装クラスは実行されるAPIによって変わる。
+  # @attr_reader [String] next_token
+  #   １回ですべてのパラメータが取得できないAPIを利用する場合に次の値を取得するためのトークン文字列。
+  #   だいたいのAWSのAPIには用意されているため、戻り値の型であるこのクラスに持たせる。
+  #
+  # @author Ryohei Sonoda
+  # @since 0.1.0
+  class FetchResult
+    attr_reader :parameters, :next_token
+
+    def initialize(parameters, next_token = nil)
+      @parameters = parameters
+      @next_token = next_token
+    end
+
+    EMPTY = new([])
+  end
+end

data/lib/aws-ssm-env/fetchers/begins_with.rb

@@ -0,0 +1,84 @@
+require 'aws-ssm-env/fetcher'
+
+module AwsSsmEnv
+  # パラメータ名の前方一致で取得するFetcherクラスの実装サブクラス。
+  # `begins_with`で指定した文字列で始まるパラメータ名に一致するパラメータを取得する。
+  # [`ssm:DescribeParameters`, `ssm:GetParameters`]の認可が必要。
+  #
+  # @author Ryohei Sonoda
+  # @since 0.1.0
+  class BeginsWithFetcher < Fetcher
+    MAX_FETCH_SIZE = 50
+    BASE_FILTER = { key: 'Name', option: 'BeginsWith' }.freeze
+
+    # @param [Hash] args AwsSsmEnv#load の呼び出し時に渡された引数。
+    # @option args [String] :begins_with <required> パラメータ名の開始文字列。この文字列が前方一致するパラメータを取得する。
+    # @option args [Integet] :fetch_size <optional> 一度のAPI実行で取得するパラメータ数。最大50。デフォルトは50。
+    def initialize(**args)
+      super
+      @base_params = base_params(args)
+    end
+
+    protected
+
+    # @see AwsSsmEnv::Fetcher#fetch
+    #
+    # パラメータ名による検索はGetParametersByPathのような便利なAPIはないため、DescribeParametersでパラメータ名による
+    # 前方一致検索をしてからGetParametersでパラメータの値を取得している。
+    # @see http://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeParameters.html
+    # @see http://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html
+    def fetch(next_token)
+      params = fetch_params(next_token)
+      response = client.describe_parameters(params)
+      if response.parameters.empty?
+        AwsSsmEnv::FetchResult::EMPTY
+      else
+        parameters = get_parameters(response.parameters)
+        AwsSsmEnv::FetchResult.new(parameters, response.next_token)
+      end
+    end
+
+    private
+
+    def base_params(begins_with: nil, fetch_size: '50', **)
+      if begins_with.nil?
+        raise ArgumentError, ':begins_with is required.'
+      end
+      {
+        parameter_filters: to_parameter_filters(begins_with),
+        max_results: detect_max_results(fetch_size)
+      }.freeze
+    end
+
+    def detect_max_results(fetch_size)
+      if fetch_size.nil?
+        MAX_FETCH_SIZE
+      elsif fetch_size.to_i > MAX_FETCH_SIZE
+        MAX_FETCH_SIZE
+      else
+        fetch_size.to_i
+      end
+    end
+
+    def to_parameter_filters(begins_with)
+      values = Array(begins_with)
+      [ BASE_FILTER.merge(values: values) ]
+    end
+
+    def fetch_params(next_token)
+      if next_token.nil?
+        @base_params
+      else
+        @base_params.merge(next_token: next_token)
+      end
+    end
+
+    def get_parameters(parameters)
+      response = client.get_parameters(
+        names: parameters.map(&:name),
+        with_decryption: with_decryption
+      )
+      response.parameters
+    end
+  end
+end

data/lib/aws-ssm-env/fetchers/factory.rb

@@ -0,0 +1,67 @@
+require 'aws-ssm-env/fetcher'
+
+module AwsSsmEnv
+  # Parameter Storeからパラメータを取得するためのクラスを取得もしくは生成するファクトリクラス。
+  #
+  # @author Ryohei Sonoda
+  # @since 0.1.0
+  class FetcherFactory
+    PATH_FETCHER = :path
+    BEGINS_WITH_FETCHER = :begins_with
+
+    class << self
+      # Parameter Storeからパラメータを取得するためのクラスを取得もしくは生成する。
+      #
+      # @param [Hash] args AwsSsmEnv#load に渡された引数がそのまま渡される。
+      # @option args [Symbol, AwsSsmEnv::Fetcher, Object] fetch
+      #   引数の詳細は AwsSsmEnv#load の説明を参照。
+      def create_fetcher(**args)
+        fetch_type = args[:fetch]
+        case fetch_type
+        when nil
+          default_fetcher(args)
+        when PATH_FETCHER
+          create_path_fetcher(args)
+        when BEGINS_WITH_FETCHER
+          create_begins_with_fetcher(args)
+        else
+          unless fetcher_instance?(fetch_type)
+            raise ArgumentError, 'Possible values for :fetch are either :path, :begins_with, ' \
+                + '"AwsSsmEnv::Fetcher" implementation class, an object with "each" method.'
+          end
+          fetch_type
+        end
+      end
+
+      private
+
+      def default_fetcher(**args)
+        if args.key?(:begins_with)
+          create_begins_with_fetcher(args)
+        else
+          create_path_fetcher(args)
+        end
+      end
+
+      def create_path_fetcher(**args)
+        require 'aws-ssm-env/fetchers/path'
+        AwsSsmEnv::PathFetcher.new(args)
+      end
+
+      def create_begins_with_fetcher(**args)
+        require 'aws-ssm-env/fetchers/begins_with'
+        AwsSsmEnv::BeginsWithFetcher.new(args)
+      end
+
+      def fetcher_instance?(object)
+        if object.is_a?(AwsSsmEnv::Fetcher)
+          true
+        elsif object.respond_to?(:each)
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/aws-ssm-env/fetchers/path.rb

@@ -0,0 +1,75 @@
+require 'aws-ssm-env/fetcher'
+
+module AwsSsmEnv
+  # Parameter Storeのパス階層を利用したFetcherクラスの実装サブクラス。
+  # `path`と`recursive`を指定してパス階層のパラメータ値をまとめて取得する。
+  # `ssm:GetParametersByPath`の認可が必要。
+  #
+  # @author Ryohei Sonoda
+  # @since 0.1.0
+  class PathFetcher < Fetcher
+    MAX_FETCH_SIZE = 10
+
+    # @see AwsSsmEnv::Fetcher#initialize
+    #
+    # @param [Hash] args AwsSsmEnv#load の呼び出し時に渡された引数。
+    # @option args [String] :path <required> 取得するパラメータのパス。
+    # @option args [Boolean] :recursive <optional> サブパスのパラメータまで取得するかどうか。デフォルトはfalse(pathの階層のみ)。
+    # @option args [Integer] :fetch_size <optional> 一度のAPI実行で取得するパラメータ数。最大10。デフォルトは10。
+    def initialize(**args)
+      super
+      @base_params = base_params(args)
+    end
+
+    protected
+
+    # @see AwsSsmEnv::Fetcher#fetch
+    #
+    # 指定したパス階層配下のパラメータを取得する。
+    # @see http://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html
+    def fetch(next_token)
+      params = fetch_params(next_token)
+      client.get_parameters_by_path(params)
+    end
+
+    private
+
+    def base_params(path: nil, recursive: 'false', fetch_size: 10, **)
+      if path.nil?
+        raise ArgumentError, 'path is required.'
+      end
+      {
+        path: path,
+        recursive: recursive?(recursive),
+        with_decryption: with_decryption,
+        max_results: detect_max_results(fetch_size)
+      }.freeze
+    end
+
+    def recursive?(recursive)
+      if recursive.to_s.downcase == 'true'
+        true
+      else
+        false
+      end
+    end
+
+    def detect_max_results(fetch_size)
+      if fetch_size.nil?
+        MAX_FETCH_SIZE
+      elsif fetch_size.to_i > 10
+        MAX_FETCH_SIZE
+      else
+        fetch_size.to_i
+      end
+    end
+
+    def fetch_params(next_token)
+      if next_token.nil?
+        @base_params
+      else
+        @base_params.merge(next_token: next_token)
+      end
+    end
+  end
+end