aws-ssm-env 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 02a1b7f6e19f94121b951fa081dab24f07a19b63
4
- data.tar.gz: 91ea648fbd61babe279737fe07bf67d379976fa0
2
+ SHA256:
3
+ metadata.gz: 42b51ae8562dfef400fdc2a244ac04ee333d76e836b80b1cd722ca3027bde2d4
4
+ data.tar.gz: 351176835c06d118460bb5455a34cfdd3198771b161aca9c1d8e66aac0eb0368
5
5
  SHA512:
6
- metadata.gz: 1494b25e51d89ed45f473a373d462b6f84e9d7735c204e5e1ebb1e398470ee60c641c08c5f3b1f93dd29cc8fe56e3af8cb6f4512213f1cb9eb3674c0c3086958
7
- data.tar.gz: 682c81baa1ff424184e5a2ac1e1b00698edda851e9b4118bb87d1ad966dc7c15f864cabc3ef190271f9cbe5e118162ace305ea0cfe1dcb274b667584f792e2ae
6
+ metadata.gz: 27a30b575fd1b1b1ca6b951df0bff61f61b549f59f8568039007d352ae61b65f5c204b88e43ef23f95cf9caff66d5437ac2fad8d3091a964b499747afc6b1615
7
+ data.tar.gz: 7cab36b73fa5adeb5c2532695239777aa97be74128668b34ec8a48a57833f7b53dd19e7e68bd5518087fa1d4f9795685876d5f5a1170f6f15c915d3d84e8f74f
@@ -0,0 +1,7 @@
1
+ # CHANGELOG
2
+
3
+ ## 0.1.1 (2018-01-16)
4
+
5
+ - Translate README.
6
+ - Added ruby 2.5 tests.
7
+
data/README.md CHANGED
@@ -1,14 +1,23 @@
1
+ [![Build Status](https://travis-ci.org/sonodar/aws-ssm-env-ruby.svg?branch=master)](https://travis-ci.org/sonodar/aws-ssm-env-ruby)
2
+ [![Coverage Status](https://coveralls.io/repos/github/sonodar/aws-ssm-env-ruby/badge.svg?branch=master)](https://coveralls.io/github/sonodar/aws-ssm-env-ruby?branch=master)
3
+ [![Gem Version](https://badge.fury.io/rb/aws-ssm-env.svg)](https://badge.fury.io/rb/aws-ssm-env)
4
+
1
5
  # aws-ssm-env
2
6
 
3
- AWS EC2 Parameter Storeから取得したパラメータを環境変数として設定します。
7
+ This tool sets parameters acquired from `AWS EC2 Parameter Store` as environment variables.
4
8
 
5
- デフォルトでは、パラメータ名の最後の階層が環境変数名として設定されます。
9
+ By default, the last hierarchy of the parameter name is
10
+ set as the environment variable name.
6
11
 
7
- 例えば、`/staging/secure/DB_PASSWORD`というパラメータ名であれば、`ENV['DB_PASSWORD']`にパラメータ値が設定されます。
8
- この環境変数のネーミングはオプションでカスタマイズ可能です。(後述)
12
+ For example, if the parameter name is `/staging/secure/DB_PASSWORD`,
13
+ the parameter value is set to `ENV['DB_PASSWORD']`.
14
+ The naming of environment variables is optional and can be customized.
15
+ (described later)
9
16
 
10
17
  ## Installation
11
18
 
19
+ This gem has been tested with ruby version 2.2 to 2.5.
20
+
12
21
  ```
13
22
  gem install aws-ssm-env
14
23
  ```
@@ -31,21 +40,22 @@ end
31
40
 
32
41
  ```ruby
33
42
  require 'aws-ssm-env'
34
- AwsSsmEnv.load!(begins_with: "myapp.ENV['RACK_ENV'].")
43
+ AwsSsmEnv.load!(begins_with: "myapp.#{ENV['RACK_ENV']}.")
35
44
  ```
36
45
 
37
46
  ## Quick Start
38
47
 
39
- 事前にAWS EC2 Parameter Storeにパラメータを登録しておく必要があります。
48
+ First of all, register the parameters in `AWS EC2 Parameter Store`.
40
49
 
41
50
  ```shell
42
- # ) /myservice/staging/RDS_PASSWORDSecureStringで登録
51
+ # ex) register /myservice/staging/RDS_PASSWORD with SecureString
43
52
  aws ssm --region ap-northeast-1 put-parameter \
44
53
  --name /myservice/staging/RDS_PASSWORD \
45
54
  --type SecureString --value <secret value>
46
55
  ```
47
56
 
48
- AWSの認証情報を設定します。例えば、以下のように環境変数を利用したり、
57
+ Then, set authentication information of AWS.
58
+ For example, you can use environment variables as follows,
49
59
 
50
60
  ```shell
51
61
  export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
@@ -53,7 +63,7 @@ export AWS_SECRET_ACCESS_KEY=YOURSECRETKEY
53
63
  bundle exec rails start
54
64
  ```
55
65
 
56
- 引数で`ssm_client_args`を渡したり、
66
+ Or, you can pass `ssm_client_args` as the argument for `AwsSsmEnv#load`:
57
67
 
58
68
  ```ruby
59
69
  AwsSsmEnv.load(
@@ -66,7 +76,7 @@ AwsSsmEnv.load(
66
76
  )
67
77
  ```
68
78
 
69
- `Aws.config`を利用することもできます。
79
+ You can also use `Aws.config`.
70
80
 
71
81
  ```ruby
72
82
 
@@ -80,52 +90,100 @@ if defined?(AwsSsmEnv)
80
90
  end
81
91
  ```
82
92
 
83
- 詳細はaws-sdkのドキュメントを参照してください。
93
+ For details, refer to the document of aws-sdk.
94
+
95
+ ## Develop
96
+
97
+ ### Unit test
98
+
99
+ ```shell
100
+ bundle exec rspec
101
+ bundle exec rubocop
102
+ ```
103
+
104
+ ### Integration test
105
+
106
+ ```shell
107
+ export AWS_ACCESS_KEY_ID=xxxx
108
+ export AWS_SECRET_ACCESS_KEY=xxxx
109
+ export AWS_REGION=xxxx
110
+ bundle exec rspec --tag integration
111
+ ```
112
+
113
+ IAM users who run tests need the following authorization policy:
114
+
115
+ ```json
116
+ {
117
+ "Version": "2012-10-17",
118
+ "Statement": [
119
+ {
120
+ "Sid": "",
121
+ "Effect": "Allow",
122
+ "Action": [
123
+ "ssm:PutParameter",
124
+ "ssm:DeleteParameters",
125
+ "ssm:DescribeParameters",
126
+ "ssm:GetParameters*"
127
+ ],
128
+ "Resource": "*"
129
+ }
130
+ ]
131
+ }
132
+ ```
133
+
84
134
 
85
135
  ## Usage
86
136
 
87
- `AwsSsmEnv#load`に渡すオプションの説明です。
137
+ Here are descriptions of the options passed to `AwsSsmEnv#load`.
88
138
 
89
139
  ### decryption: [Boolean]
90
140
 
91
- SecureStringのパラメータを復号化するかどうかを表すフラグ。
92
- `true`を指定した場合は取得したSecureStringパラメータの値は復号化されている。
93
- `false`の場合は暗号化されたまた環境変数値として設定される。
94
- なお、このためのgemなのでデフォルトは`true`(復号化する)
141
+ Flag indicating whether to decrypt SecureString parameters.
142
+ If `true` is specified, the value of the acquired SecureString parameter is decrypted.
143
+ In case of `false` it is set as encrypted and environment variable value.
144
+ Since it is a gem for this, the default is `true` (decrypt).
95
145
 
96
146
  ### overwrite: [Boolean]
97
147
 
98
- すでに設定されている環境変数を上書きするかどうかを指定する。
99
- `true`を指定した場合、環境変数が設定されていても取得したパラメータ値で上書きする。
100
- `false`を指定した場合はすでに設定されている環境変数を上書きしない。
101
- デフォルトは`false`(上書きしない)。
102
- なお、`AwsSsmEnv#load!`を実行した場合、このフラグは自動的に`true`になる。
148
+ Specify whether to overwrite an already set environment variable.
149
+ If `true` is specified, even if the environment variable is set,
150
+ it overwrites it with the acquired parameter value.
151
+ If `false` is specified, do not overwrite already set environment variables.
152
+ The default is `false` (do not overwrite).
153
+ If you invoke `AwsSsmEnv#load!`, This flag will automatically be set to `true`.
103
154
 
104
155
  ### client: [Aws::SSM::Client]
105
156
 
106
- `Aws::SSM::Client`のインスタンスを指定する。
107
- すでに生成済みのインスタンスがある場合にそれを設定するためのオプション。
108
- 生成済みのインスタンスがない場合は`ssm_client_args`を利用する。
157
+ Specify an instance of `Aws::SSM::Client`.
158
+ An option to set it if there are already created instances.
159
+ If there are no instances created, use `ssm_client_args` instead.
109
160
 
110
161
  ### ssm_client_args: [Hash]
111
162
 
112
- `Aws::SSM::Client`のコンストラクタに渡すハッシュを指定する。
113
- 指定しなかった場合は引数なしで`Aws::SSM::Client.new`が呼ばれる。
114
- 環境変数やEC2インスタンスプロファイルによる認証情報を利用する場合は不要。
163
+ Specify a hash to pass to the constructor of `Aws::SSM::Client`.
164
+ If not specified, `Aws::SSM::Client#new` is called with an empty argument.
165
+ It is unnecessary when using environment variable
166
+ or authentication information by `EC2 InstanceProfile`.
115
167
 
116
168
  ### fetch: [Symbol, AwsSsmEnv::Fetcher, Object]
117
169
 
118
- パラメータ取得方法を指定する。
119
- 指定可能な値は`:path`, `:begins_with`または`AwsSsmEnv::Fetcher`を実装したクラスのインスタンス、`each`メソッドを
120
- 持ったクラスのインスタンスのいずれか。
121
- 何も指定されていない場合は`:path`として扱われるが、後述の`begins_with`が指定されていた場合は自動的に`:begins_with`となる。
170
+ Specify parameter fetch strategy.
171
+ Possible values are `:path`,`:begins_with`
172
+ or an instance of a class that implements `AwsSsmEnv::Fetcher`,
173
+ or an instance of a class with a `each` method.
174
+ If nothing is specified, it is treated as `:path`.
175
+ But when `begins_with` (which is described later) is specified,
176
+ it will automatically be `:begins_with`.
122
177
 
123
- #### :fetch => :path
178
+ #### `:fetch => :path` or default
124
179
 
125
- `:path`を指定した場合はパラメータ階層をパス指定で取得する`AwsSsmEnv::PathFetcher`が利用される。
126
- この場合は後述の`path`引数が必須となる。また、後述の`recursive`引数を利用する。
127
- この方法でパラメータを取得する場合は指定するパスに対して`ssm:GetParametersByPath`の権限が必要。
128
- 以下、IAMポリシーの例を示す。
180
+ When `:path` is specified, `AwsSsmEnv::PathFetcher` which fetches
181
+ parameter hierarchy by path specification is used.
182
+ In this case, the `path` argument described below is required.
183
+ Also, the `recursive` argument (described later) is used.
184
+ When acquiring parameters in this way, you need `ssm:GetParametersByPath` authority
185
+ for the specified path.
186
+ An example of the IAM policy is shown below.
129
187
 
130
188
  ```json
131
189
  {
@@ -141,12 +199,15 @@ SecureStringのパラメータを復号化するかどうかを表すフラグ
141
199
  }
142
200
  ```
143
201
 
144
- #### :fetch => :begins_with
202
+ #### `:fetch => :begins_with`
145
203
 
146
- `:begins_with`を指定した場合はパラメータ名が指定した文字列から開始するパラメータを取得する`AwsSsmEnv::BeginsWithFetcher`が利用される。
147
- この場合は後述の`begins_with`引数が必須となる。
148
- この方法でパラメータを取得する場合は指定するパスに対して`ssm:DescribeParameters`および`ssm:GetParameters`の権限が必要。
149
- 以下、IAMポリシーの例を示す。
204
+ If `:begins_with` is specified, `AwsSsmEnv::BeginsWithFetcher` is used to fetch
205
+ parameters starting from the character string specified by the parameter name.
206
+ In this case, the `begins_with` argument described below is required.
207
+ When acquiring parameters in this way,
208
+ you need the authority of `ssm:DescribeParameters` and `ssm:GetParameters`
209
+ for the specified path.
210
+ An example of the IAM policy is shown below.
150
211
 
151
212
  ```json
152
213
  {
@@ -170,41 +231,58 @@ SecureStringのパラメータを復号化するかどうかを表すフラグ
170
231
 
171
232
  #### other
172
233
 
173
- `fetch`に`AwsSsmEnv::Fetcher`を実装したクラスのインスタンス、もしくは`each`メソッドを持つインスタンスを指定した場合はそのインスタンスをそのまま利用する。
234
+ If you specify an instance of a class that implements `AwsSsmEnv::Fetcher` in` fetch`,
235
+ or an instance with a `each` method, that instance will be used as is.
174
236
 
175
237
  ### naming: [Symbol, AwsSsmEnv::NamingStrategy, Object]
176
238
 
177
- 環境変数名を導出方法を指定する。
178
- 指定可能な値は`:basename`, `:snakecase`または`AwsSsmEnv::NamingStrategy`を実装したクラスのインスタンス、`parse_name`メソッドを持ったクラスのインスタンスのいずれか。
179
- デフォルトは`:basename`。
180
-
181
- #### :naming => :basename or :naming => nil
182
-
183
- `naming`を指定しなかった場合、もしくは`:basename`を指定した場合はパラメータ階層の最後の階層を変数名とする`AwsSsmEnv::BasenameNamingStrategy`が利用される。
184
- この場合、例えば`/myapp/production/DB_PASSWORD`というパラメータ名であれば`ENV['DB_PASSWORD']`にパラメータ値がインジェクションされる。
185
-
186
- #### :naming => :snakecase
187
-
188
- `:snakecase`を指定した場合はパラメータ名のスラッシュ区切りをアンダースコア区切りにした結果を大文字に変換して環境変数名とする`AwsSsmEnv::SnakeCaseNamingStrategy`が利用される。
189
- この場合、例えば`/myapp/production/DB_PASSWORD`というパラメータ名であれば`ENV['MYAPP_PRODUCTION_DB_PASSWORD']`にパラメータ値がインジェクションされる。
190
- 後述の`removed_prefix`引数で除外する先頭文字列を指定することができる。
191
- また、後述の`delimiter`オプションでアンダースコアに変換する文字を指定できる。
192
- 以下の例では`/myapp/production/db/password`というパラメータが`ENV['DB_PASSWORD']`にインジェクションされる。
239
+ Specify the naming strategy for the environment variable name.
240
+ Possible values are `:basename`,`:snakecase`
241
+ or an instance of a class that implements `AwsSsmEnv::NamingStrategy`,
242
+ or an instance of a class with a `parse_name` method.
243
+ If nothing is specified, it is treated as `:basename`.
244
+
245
+ #### `:naming => :basename` or default
246
+
247
+ If `naming` is not specified or `:basename` is specified,
248
+ `AwsSsmEnv::BasenameNamingStrategy` whose variable name is
249
+ the last hierarchy of the parameter hierarchy is used.
250
+ In this case, for example, if the parameter name is `/myapp/production/DB_PASSWORD`,
251
+ the parameter value is set to `ENV['DB_PASSWORD']`.
252
+
253
+ #### `:naming => :snakecase`
254
+
255
+ When `:snakecase` is specified, `AwsSsmEnv::SnakeCaseNamingStrategy` which uses
256
+ the underscore delimiter of the parameter name's slash delimiter and converts
257
+ it to uppercase letters as the environment variable name is used.
258
+ In this case, for example, if the parameter name is `/myapp/production/DB_PASSWORD`,
259
+ the parameter value is set to `ENV['MYAPP_PRODUCTION_DB_PASSWORD']`.
260
+ You can specify first part of string to exclude with
261
+ the `removed_prefix` argument described below.
262
+ In addition, you can specify characters to be converted to
263
+ underscores with the `delimiter` option described below.
264
+ In the following example, the parameter `/myapp/production/db.password` is
265
+ set to `ENV['DB_PASSWORD']`.
193
266
 
194
267
  ```ruby
195
- AwsSsmEnv.load(naming: :snakecase, removed_prefix: '/myapp/production')
268
+ AwsSsmEnv.load!(
269
+ naming: :snakecase,
270
+ removed_prefix: '/myapp/production',
271
+ delimiter: /[\/.]/
272
+ )
196
273
  ```
197
274
 
198
275
  #### other
199
276
 
200
- `AwsSsmEnv::NamingStrategy`を実装したクラスのインスタンス、もしくは`parse_name`メソッドを持つ
201
- インスタンスを指定した場合はそのインスタンスをそのまま利用する。
277
+ If you specify an instance of a class that implements `AwsSsmEnv::NamingStrategy` in` fetch`,
278
+ or an instance with a `parse_name` method, that instance is used as is.
279
+
202
280
 
203
281
  ### path: [String]
204
282
 
205
- `fetch`に何も指定していない場合、もしくは`:path`を指定した場合は必須となる。
206
- パラメータを取得するパス階層を指定する。
207
- 下の例では`/myapp/web/production`直下のパラメータが取得される。
283
+ Required if nothing is specified for `fetch` or if `:path` is specified.
284
+ This option specifies the path hierarchy for acquiring parameters from `Parameter Store`.
285
+ In the example below, the parameter immediately under `/myapp/web/production` is acquired.
208
286
 
209
287
  ```ruby
210
288
  AwsSsmEnv.load(path: '/myapp/web/production')
@@ -212,9 +290,10 @@ AwsSsmEnv.load(path: '/myapp/web/production')
212
290
 
213
291
  #### recursive: [Boolean]
214
292
 
215
- `fetch`に何も指定していない場合、もしくは`:path`を指定した場合に利用する。
216
- 指定したパス階層以下のパラメータをすべて取得する。
217
- 下の例では`/myapp/web/production`以下すべてのパラメータが取得される。
293
+ Used when no parameter is specified for `fetch` option or when `:path` is specified.
294
+ If true is specified, acquires all parameters below the specified path hierarchy.
295
+ If nothing is specified this parameter, it is treated as `false`(one level).
296
+ In the following example, all parameters below `/myapp/web/production` are acquired.
218
297
 
219
298
  ```ruby
220
299
  AwsSsmEnv.load(path: '/myapp/web/production', recursive: true)
@@ -222,9 +301,10 @@ AwsSsmEnv.load(path: '/myapp/web/production', recursive: true)
222
301
 
223
302
  ### begins_with: [String, Array<String>]
224
303
 
225
- `fetch`に`:begins_with`を指定した場合は必須となる。
226
- 取得するパラメータ名のプレフィクスを指定する。配列で複数指定することも可能(OR条件となる)。
227
- 下の例では`myapp.web.production`で始まる名前のパラメータが取得される。
304
+ Required if `:begins_with` is specified in `fetch`.
305
+ You can specify the prefix of the parameter name to be acquired by this option.
306
+ It is also possible to specify more than one in an array (OR condition).
307
+ In the example below, parameters with names starting with `myapp.web.production` are acquired.
228
308
 
229
309
  ```ruby
230
310
  AwsSsmEnv.load(path: 'myapp.web.production')
@@ -232,36 +312,39 @@ AwsSsmEnv.load(path: 'myapp.web.production')
232
312
 
233
313
  ### removed_prefix: [String]
234
314
 
235
- `naming`に`:snakecase`を指定した場合に利用される。
236
- 環境変数名から除外するパラメータ名のプレフィクスを指定する。
237
- `:removed_prefix`が指定されておらず、`:begins_with`もしくは`:path`が指定されていた場合はそれを利用する。
315
+ Used when `:snakecase` is specified in `naming`.
316
+ By this option, you can specify the prefix of the parameter name to exclude
317
+ from the environment variable name.
318
+ If `:removed_ prefix` is not specified, and `:begins_with` or `:path` is specified, that will be used.
238
319
 
239
320
  ### delimiter: [String, Regexp]
240
321
 
241
- `naming`に`:snakecase`を指定した場合に利用される。
242
- アンダースコアに変換する文字列もしくは正規表現を指定する。
243
- デフォルトはスラッシュ(`/`)
322
+ Used when `:snakecase` is specified in `naming`.
323
+ By this option, you can specify a string or a regular expression to be converted to an underscore.
324
+ The default is a slash (`/`).
244
325
 
245
326
  ### fetch_size: [Integer]
246
327
 
247
- 一度のAWS API実行で取得するパラメータ数を指定する。 `:path`指定の場合は最大値は`10`でデフォルトも`10`。
248
- `:begins_with`指定の場合は最大値は`50`でデフォルトも`50`である。通常このパラメータを指定することはない。
249
-
250
-
251
- ## Motivation
252
-
253
- RailsアプリケーションをECSで起動する場合、環境変数を渡すのが面倒だったので作りました。
328
+ Specify the number of parameters to be acquired with one execution of AWS API.
329
+ If `:path` is specified, the maximum value is `10` and the default is `10`.
330
+ If `:begins_with` is specified, the maximum value is `50` and the default is `50`.
331
+ Usually this parameter is never specified.
254
332
 
255
333
  ## Security
256
334
 
257
- シークレット情報を取得するための権限を付与しなければならないため、セキュリティ運用には十分な注意が必要です。
335
+ Because you must grant authority to acquire secret information,
336
+ careful attention is required for security operation.
337
+
258
338
 
259
- EC2インスタンスプロファイルが設定されていた場合、そのEC2上であればどのアカウントでもパラメータが見えるようになるため、
260
- EC2インスタンスプロファイルとは別にIAMユーザを用意するなどセキュリティレベルを上げる工夫が必要です。
339
+ When the `EC2 InstanceProfile` is set, the parameters can be seen by any account on EC2,
340
+ It is necessary to improve the security level by preparing an IAM User separately
341
+ from the `EC2 InstanceProfile`.
261
342
 
262
- EC2にログインできるのが管理者のみであればファイルで持つのと大差ありません。
343
+ If it is only the administrator that you can log in to EC2,
344
+ it is not much different from having it in a file.
263
345
 
264
- `AWS Fargate`であればコンテナ上でコマンドの実行はできないので、シークレット情報が見られることはありません。
346
+ Since `AWS Fargate` makes it difficult to execute commands on containers,
347
+ this risk is mitigated.
265
348
 
266
349
  ## License
267
350
 
@@ -0,0 +1,322 @@
1
+ [![Build Status](https://travis-ci.org/sonodar/aws-ssm-env-ruby.svg?branch=master)](https://travis-ci.org/sonodar/aws-ssm-env-ruby)
2
+ [![Coverage Status](https://coveralls.io/repos/github/sonodar/aws-ssm-env-ruby/badge.svg?branch=master)](https://coveralls.io/github/sonodar/aws-ssm-env-ruby?branch=master)
3
+ [![Gem Version](https://badge.fury.io/rb/aws-ssm-env.svg)](https://badge.fury.io/rb/aws-ssm-env)
4
+
5
+ # aws-ssm-env
6
+
7
+ AWS EC2 Parameter Storeから取得したパラメータを環境変数として設定します。
8
+
9
+ デフォルトでは、パラメータ名の最後の階層が環境変数名として設定されます。
10
+
11
+ 例えば、`/staging/secure/DB_PASSWORD`というパラメータ名であれば、`ENV['DB_PASSWORD']`にパラメータ値が設定されます。
12
+ この環境変数のネーミングはオプションでカスタマイズ可能です。(後述)
13
+
14
+ ## Installation
15
+
16
+ このgemはRuby2.2から2.5まででテストされています。
17
+
18
+ ```
19
+ gem install aws-ssm-env
20
+ ```
21
+
22
+ ### Rails
23
+
24
+ ```ruby
25
+ # Gemfile
26
+ gem 'aws-ssm-env', group: :aws
27
+ ```
28
+
29
+ ```ruby
30
+ # config/application.rb
31
+ if defined?(AwsSsmEnv)
32
+ AwsSsmEnv.load(path: "/myapp/#{ENV['RAILS_ENV']}", recursive: true)
33
+ end
34
+ ```
35
+
36
+ ### Other ruby program
37
+
38
+ ```ruby
39
+ require 'aws-ssm-env'
40
+ AwsSsmEnv.load!(begins_with: "myapp.#{ENV['RACK_ENV']}.")
41
+ ```
42
+
43
+ ## Quick Start
44
+
45
+ 事前にAWS EC2 Parameter Storeにパラメータを登録しておく必要があります。
46
+
47
+ ```shell
48
+ # 例) /myservice/staging/RDS_PASSWORDをSecureStringで登録
49
+ aws ssm --region ap-northeast-1 put-parameter \
50
+ --name /myservice/staging/RDS_PASSWORD \
51
+ --type SecureString --value <secret value>
52
+ ```
53
+
54
+ AWSの認証情報を設定します。例えば、以下のように環境変数を利用したり、
55
+
56
+ ```shell
57
+ export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
58
+ export AWS_SECRET_ACCESS_KEY=YOURSECRETKEY
59
+ bundle exec rails start
60
+ ```
61
+
62
+ 引数で`ssm_client_args`を渡したり、
63
+
64
+ ```ruby
65
+ AwsSsmEnv.load(
66
+ fetch: "/myservice/#{ENV['RAILS_ENV']}",
67
+ ssm_client_args: {
68
+ access_key_id: 'ACCESS_KEY_ID',
69
+ secret_access_key: 'SECRET_ACCESS_KEY',
70
+ region: 'ap-northeast-1',
71
+ }
72
+ )
73
+ ```
74
+
75
+ `Aws.config`を利用することもできます。
76
+
77
+ ```ruby
78
+
79
+ if defined?(AwsSsmEnv)
80
+ AWS.config({
81
+ access_key_id: 'ACCESS_KEY_ID',
82
+ secret_access_key: 'SECRET_ACCESS_KEY',
83
+ region: 'ap-northeast-1',
84
+ })
85
+ AwsSsmEnv.load(path: "/myservice/#{ENV['RAILS_ENV']}")
86
+ end
87
+ ```
88
+
89
+ 詳細はaws-sdkのドキュメントを参照してください。
90
+
91
+ ## Develop
92
+
93
+ ### Unit test
94
+
95
+ ```shell
96
+ bundle exec rspec
97
+ bundle exec rubocop
98
+ ```
99
+
100
+ ### Integration test
101
+
102
+ ```shell
103
+ export AWS_ACCESS_KEY_ID=xxxx
104
+ export AWS_SECRET_ACCESS_KEY=xxxx
105
+ export AWS_REGION=xxxx
106
+ bundle exec rspec --tag integration
107
+ ```
108
+
109
+ IAMユーザには以下の認可ポリシーが必要です。
110
+
111
+ ```json
112
+ {
113
+ "Version": "2012-10-17",
114
+ "Statement": [
115
+ {
116
+ "Sid": "",
117
+ "Effect": "Allow",
118
+ "Action": [
119
+ "ssm:PutParameter",
120
+ "ssm:DeleteParameters",
121
+ "ssm:DescribeParameters",
122
+ "ssm:GetParameters*"
123
+ ],
124
+ "Resource": "*"
125
+ }
126
+ ]
127
+ }
128
+ ```
129
+
130
+
131
+ ## Usage
132
+
133
+ `AwsSsmEnv#load`に渡すオプションの説明です。
134
+
135
+ ### decryption: [Boolean]
136
+
137
+ SecureStringのパラメータを復号化するかどうかを表すフラグ。
138
+ `true`を指定した場合は取得したSecureStringパラメータの値は復号化されている。
139
+ `false`の場合は暗号化されたまた環境変数値として設定される。
140
+ なお、このためのgemなのでデフォルトは`true`(復号化する)。
141
+
142
+ ### overwrite: [Boolean]
143
+
144
+ すでに設定されている環境変数を上書きするかどうかを指定する。
145
+ `true`を指定した場合、環境変数が設定されていても取得したパラメータ値で上書きする。
146
+ `false`を指定した場合はすでに設定されている環境変数を上書きしない。
147
+ デフォルトは`false`(上書きしない)。
148
+ なお、`AwsSsmEnv#load!`を実行した場合、このフラグは自動的に`true`になる。
149
+
150
+ ### client: [Aws::SSM::Client]
151
+
152
+ `Aws::SSM::Client`のインスタンスを指定する。
153
+ すでに生成済みのインスタンスがある場合にそれを設定するためのオプション。
154
+ 生成済みのインスタンスがない場合は`ssm_client_args`を利用する。
155
+
156
+ ### ssm_client_args: [Hash]
157
+
158
+ `Aws::SSM::Client`のコンストラクタに渡すハッシュを指定する。
159
+ 指定しなかった場合は引数なしで`Aws::SSM::Client.new`が呼ばれる。
160
+ 環境変数やEC2インスタンスプロファイルによる認証情報を利用する場合は不要。
161
+
162
+ ### fetch: [Symbol, AwsSsmEnv::Fetcher, Object]
163
+
164
+ パラメータ取得方法を指定する。
165
+ 指定可能な値は`:path`, `:begins_with`または`AwsSsmEnv::Fetcher`を実装したクラスのインスタンス、`each`メソッドを
166
+ 持ったクラスのインスタンスのいずれか。
167
+ 何も指定されていない場合は`:path`として扱われるが、後述の`begins_with`が指定されていた場合は自動的に`:begins_with`となる。
168
+
169
+ #### `:fetch => :path` or default
170
+
171
+ `:path`を指定した場合はパラメータ階層をパス指定で取得する`AwsSsmEnv::PathFetcher`が利用される。
172
+ この場合は後述の`path`引数が必須となる。また、後述の`recursive`引数を利用する。
173
+ この方法でパラメータを取得する場合は指定するパスに対して`ssm:GetParametersByPath`の権限が必要。
174
+ 以下、IAMポリシーの例を示す。
175
+
176
+ ```json
177
+ {
178
+ "Version": "2012-10-17",
179
+ "Statement": [
180
+ {
181
+ "Sid": "",
182
+ "Effect": "Allow",
183
+ "Action": "ssm:GetParametersByPath",
184
+ "Resource": "arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter/YOUR_PATH"
185
+ }
186
+ ]
187
+ }
188
+ ```
189
+
190
+ #### `:fetch => :begins_with`
191
+
192
+ `:begins_with`を指定した場合はパラメータ名が指定した文字列から開始するパラメータを取得する`AwsSsmEnv::BeginsWithFetcher`が利用される。
193
+ この場合は後述の`begins_with`引数が必須となる。
194
+ この方法でパラメータを取得する場合は指定するパスに対して`ssm:DescribeParameters`および`ssm:GetParameters`の権限が必要。
195
+ 以下、IAMポリシーの例を示す。
196
+
197
+ ```json
198
+ {
199
+ "Version": "2012-10-17",
200
+ "Statement": [
201
+ {
202
+ "Sid": "",
203
+ "Effect": "Allow",
204
+ "Action": "ssm:DescribeParameters",
205
+ "Resource": "arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter"
206
+ },
207
+ {
208
+ "Sid": "",
209
+ "Effect": "Allow",
210
+ "Action": "ssm:GetParameters",
211
+ "Resource": "arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter/YOUR_PREFIX*"
212
+ }
213
+ ]
214
+ }
215
+ ```
216
+
217
+ #### other
218
+
219
+ `fetch`に`AwsSsmEnv::Fetcher`を実装したクラスのインスタンス、もしくは`each`メソッドを持つインスタンスを指定した場合はそのインスタンスをそのまま利用する。
220
+
221
+ ### naming: [Symbol, AwsSsmEnv::NamingStrategy, Object]
222
+
223
+ 環境変数名を導出方法を指定する。
224
+ 指定可能な値は`:basename`, `:snakecase`または`AwsSsmEnv::NamingStrategy`を実装したクラスのインスタンス、`parse_name`メソッドを持ったクラスのインスタンスのいずれか。
225
+ デフォルトは`:basename`。
226
+
227
+ #### `:naming => :basename` or default
228
+
229
+ `naming`を指定しなかった場合、もしくは`:basename`を指定した場合はパラメータ階層の最後の階層を変数名とする`AwsSsmEnv::BasenameNamingStrategy`が利用される。
230
+ この場合、例えば`/myapp/production/DB_PASSWORD`というパラメータ名であれば`ENV['DB_PASSWORD']`にパラメータ値がインジェクションされる。
231
+
232
+ #### `:naming => :snakecase`
233
+
234
+ `:snakecase`を指定した場合はパラメータ名のスラッシュ区切りをアンダースコア区切りにした結果を大文字に変換して環境変数名とする`AwsSsmEnv::SnakeCaseNamingStrategy`が利用される。
235
+ この場合、例えば`/myapp/production/DB_PASSWORD`というパラメータ名であれば`ENV['MYAPP_PRODUCTION_DB_PASSWORD']`にパラメータ値がインジェクションされる。
236
+ 後述の`removed_prefix`引数で除外する先頭文字列を指定することができる。
237
+ また、後述の`delimiter`オプションでアンダースコアに変換する文字を指定できる。
238
+ 以下の例では`/myapp/production/db.password`というパラメータが`ENV['DB_PASSWORD']`にインジェクションされる。
239
+
240
+ ```ruby
241
+ AwsSsmEnv.load!(
242
+ naming: :snakecase,
243
+ removed_prefix: '/myapp/production',
244
+ delimiter: /[\/.]/
245
+ )
246
+ ```
247
+
248
+ #### other
249
+
250
+ `AwsSsmEnv::NamingStrategy`を実装したクラスのインスタンス、もしくは`parse_name`メソッドを持つ
251
+ インスタンスを指定した場合はそのインスタンスをそのまま利用する。
252
+
253
+ ### path: [String]
254
+
255
+ `fetch`に何も指定していない場合、もしくは`:path`を指定した場合は必須となる。
256
+ パラメータを取得するパス階層を指定する。
257
+ 下の例では`/myapp/web/production`直下のパラメータが取得される。
258
+
259
+ ```ruby
260
+ AwsSsmEnv.load(path: '/myapp/web/production')
261
+ ```
262
+
263
+ #### recursive: [Boolean]
264
+
265
+ `fetch`に何も指定していない場合、もしくは`:path`を指定した場合に利用する。
266
+ 指定したパス階層以下のパラメータをすべて取得する。
267
+ 下の例では`/myapp/web/production`以下すべてのパラメータが取得される。
268
+
269
+ ```ruby
270
+ AwsSsmEnv.load(path: '/myapp/web/production', recursive: true)
271
+ ```
272
+
273
+ ### begins_with: [String, Array<String>]
274
+
275
+ `fetch`に`:begins_with`を指定した場合は必須となる。
276
+ 取得するパラメータ名のプレフィクスを指定する。配列で複数指定することも可能(OR条件となる)。
277
+ 下の例では`myapp.web.production`で始まる名前のパラメータが取得される。
278
+
279
+ ```ruby
280
+ AwsSsmEnv.load(path: 'myapp.web.production')
281
+ ```
282
+
283
+ ### removed_prefix: [String]
284
+
285
+ `naming`に`:snakecase`を指定した場合に利用される。
286
+ 環境変数名から除外するパラメータ名のプレフィクスを指定する。
287
+ `:removed_prefix`が指定されておらず、`:begins_with`もしくは`:path`が指定されていた場合はそれを利用する。
288
+
289
+ ### delimiter: [String, Regexp]
290
+
291
+ `naming`に`:snakecase`を指定した場合に利用される。
292
+ アンダースコアに変換する文字列もしくは正規表現を指定する。
293
+ デフォルトはスラッシュ(`/`)。
294
+
295
+ ### fetch_size: [Integer]
296
+
297
+ 一度のAWS API実行で取得するパラメータ数を指定する。 `:path`指定の場合は最大値は`10`でデフォルトも`10`。
298
+ `:begins_with`指定の場合は最大値は`50`でデフォルトも`50`である。通常このパラメータを指定することはない。
299
+
300
+
301
+ ## Motivation
302
+
303
+ RailsアプリケーションをECSで起動する場合、環境変数を渡すのが面倒だったので作りました。
304
+
305
+ ## Security
306
+
307
+ シークレット情報を取得するための権限を付与しなければならないため、セキュリティ運用には十分な注意が必要です。
308
+
309
+ EC2インスタンスプロファイルが設定されていた場合、そのEC2上であればどのアカウントでもパラメータが見えるようになるため、
310
+ EC2インスタンスプロファイルとは別にIAMユーザを用意するなどセキュリティレベルを上げる工夫が必要です。
311
+
312
+ EC2にログインできるのが管理者のみであればファイルで持つのと大差ありません。
313
+
314
+ `AWS Fargate`であればコンテナ上でコマンドの実行は困難なため、このリスクは軽減されます。
315
+
316
+ ## License
317
+
318
+ Apache License 2.0
319
+
320
+ ## Contributors
321
+
322
+ - Ryohei Sonoda <[sonodar](https://github.com/sonodar)>