Docs: IAM permissions needed to use Dynamoid

[acaeti]

I thought it might be useful to list the IAM role permissions required to use Dynamoid in the README.md. In my case I am using Dynamoid within an AWS Lambda, and I discovered the below permissions requirements through trial and error.

Some permissions (GetItem, Query, etc) are fairly obvious so I will instead note the two that I found through trial and error (there may be more!).

The first: to do a Query I also needed DescribeTable.

The second: to do a PutItem I also needed ListTables (note, ListTables requires access to all resources, IE "*", as shown in the DynamoDB API permissions reference, not just the table in question).

I happened to be using the Serverless framework to create resources and deploy the Lambda, so here's an abridged serverless.yml for the next person that may need this:

service: foo
custom:
  tableName: 'bar-table-${self:provider.stage}'
provider:
  name: aws
  runtime: ruby2.5
  environment:
    BAR_TABLE: ${self:custom.tableName}
  iamRoleStatements:
    #this permission grants the Lambda(s) only ListTables with "*"
    - Effect: Allow
      Action:
        - dynamodb:ListTables
      Resource: "*"
    #this permission grants the Lambda(s) DescribeTable and other common permissions only on the single table I am creating with this serverless.yml
    - Effect: Allow
      Action:
        - dynamodb:DescribeTable
        - dynamodb:Query
        - dynamodb:GetItem
        - dynamodb:BatchGetItem
        - dynamodb:PutItem
        - dynamodb:UpdateItem
        - dynamodb:DeleteItem
        - dynamodb:BatchWriteItem
      Resource:
        - { "Fn::GetAtt": ["BarTable", "Arn" ] }
functions:
  baz:
    handler: baz.handler
    description: baz
    events:
      - http:
          path: baz
          method: get
          cors: true
resource
  Resources:
    BarTable:
      Type: 'AWS::DynamoDB::Table'
      Properties:
        AttributeDefinitions:
          - AttributeName: qux
            AttributeType: S
          - AttributeName: quux
            AttributeType: S
        KeySchema:
          - AttributeName: qux
            KeyType: HASH
          - AttributeName: quux
            KeyType: RANGE
        ProvisionedThroughput:
          ReadCapacityUnits: 1
          WriteCapacityUnits: 1
        TableName: ${self:custom.tableName}

[andrykonchin]

Looks great. It makes sense to add the example and description to documentation. But there is no proper place right now - we have only Readme.md and generated with YARD documentation.

So let it be here for now and I hope we will have a site with documentation and guides in the near future

[acaeti]

How about a subsection under Prerequisites in the README.md? Could be just a simple call-out in "AWS Configuration" or its own section, e.g.:

AWS DynamoDB IAM role permissions

The AWS user requires IAM role permissions to access DynamoDB. Some permissions (GetItem, Query, etc) are fairly obvious, but note that Dynamoid requires DescribeTable on your table resource(s) to perform a Query (used by ActiveModel .find methods), and ListTables on all DynamoDB resources ("*") to perform PutItem (used by ActiveModel .save methods). See this issue for more details: #380

Thoughts?

[andrykonchin]

Sounds good 👍. PR is welcome.

[andrykonchin]

The full list of API operations used by Dynamoid:

• ListTables
• CreateTable
• DescribeTable
• DeleteTable
• DeleteItem
• PutItem
• GetItem
• UpdateItem
• BatchGetItem
• BatchWriteItem
• Query
• Scan
• UpdateTimeToLive