RFC: Define multiple sources and destinations on a connector

[ccaum]

Status: Closed

We will move forward with part of this RFC. Soon, you will be able to define multiple destinations in a single connector with a single set of permissions.

Problem

SAM connectors currently need to be defined once for each relationship in your stack. This promotes verbosity, bloated SAM templates, and templates that are difficult to quickly understand and maintain. If you were to draw connectors as arrows on a whiteboard signifying how data and events flow between two resources, the only type of relationship that can be expressed is a one-to-one mapping.

For example, the template below demonstrates two connections between a single Lambda and two SQS queues. The connections all require identical Read/Write permissions and all have the same source resource. The connectors take up the majority of the template’s lines of code.

Resources:
  StockCheckerFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_checker/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
        
  StockSellQueue:
    Type: AWS::SQS::Queue
  StockBuyQueue:
    Type: AWS::SQS::Queue
    
  FunctionToSellQueueConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        Id: StockCheckerFunction
       Destination:
        Id: StockSellQueue
      Permissions:
        - Write
  FunctionToBuyQueueConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        Id: StockCheckerFunction
       Destination:
        Id: StockBuyQueue
      Permissions:
        - Write

Similarly, your application may require multiple SAM functions reading and writing to a single DynamoDB. Again, the connectors make up the majority of the template’s lines of code.

Resources:
  StockBuyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_buyer/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
  StockSellFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_seller/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
        
  TransactionTable:
    Type: AWS::Serverless::SimpleTable
    Properties:
      PrimaryKey:
        Name: Id
        Type: String
      ProvisionedThroughput:
        ReadCapacityUnits: 1
        WriteCapacityUnits: 1
        
  BuyFunctionToTableConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        Id: StockBuyFunction
      Destination:
        Id: TransactionTable
      Permissions:
        - Write
  FunctionToBuyQueueConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        Id: StockSellFunction
      Destination:
        Id: TransactionTable 
      Permissions:
        - Write

Proposed Solution

Allow connector resources to define either multiple sources for a single destination and single set of Read/Write permissions, or define multiple destinations for a single source and single set of Read/Write permissions. Conceptually, relationships where a one-to-many or many-to-one relationship exists should be expressed as a single connector.

One-to-many relationship	Many-to-one relationship

To use the first example in the Problem section above, the proposed connector definition would look like this:

Resources:
  StockCheckerFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_checker/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
        
  StockSellQueue:
    Type: AWS::SQS::Queue
  StockBuyQueue:
    Type: AWS::SQS::Queue
    
  FunctionToQueueConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        Id: StockCheckerFunction
      Destination:
        - Id: StockSellQueue
        - Id: StockBuyQueue
      Permissions:
        - Write

For the second example in the Problem section above, the proposed connector definition would look like this:

Resources:
  StockBuyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_buyer/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
  StockSellFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_seller/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
        
  TransactionTable:
    Type: AWS::Serverless::SimpleTable
    Properties:
      PrimaryKey:
        Name: Id
        Type: String
      ProvisionedThroughput:
        ReadCapacityUnits: 1
        WriteCapacityUnits: 1
        
  FunctionToTableConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        - Id: StockBuyFunction
        - Id: StockSellFunction
      Destination:
        Id: TransactionTable
      Permissions:
        - Write

Pros/Cons

Pros

Cons

1) Simpler to read and write 2) Easier to quickly understand 3) Expanding a one-to-many or many-to-one relationship is easy

1) If an additional resource needs to be added to a one-to-many or many-to-one relationship but requires a different set of permissions, it must be defined as a new connector. This makes sense as it is a new type of relationship. 2) If an existing resource in a one-to-many or many-to-one relationship needs to be updated to require different permissions than the other resources in the relationship, it must be refactored out of the existing connector and into a new connector. Again, this makes sense because it is a new type of relationship.

FAQ

Why not allow both multiple sources and multiple destinations simultaneously?
It promotes misuse of connectors. SAM connectors are intended to simplify architecting an application by describing how resources interact. Permissions are automatically generated from the relationships defined by connectors. If the defined interactions become too obscure, it defeats the purpose of connectors. If three sources interact with multiple destinations, it is unclear if each possible relationship is actually needed for the application to function properly. In short, allowing both multiple sources and multiple destinations to be defined in the same connector promotes authoring code that is difficult to understand and maintain over time.

Can different sets of permissions be applied to different sources/destinations in the same connector?
No. Ideally, connectors are used to easily model how resources in your application interact. Each connector models one type of interaction. By limiting each connector to defining a single type of interaction, SAM code is easier to read and understand how resources interact with each other.

[CGarces]

Why not use and aproach like policy templates?

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-policy-templates.html

For me the syntaxes is more simpler, the code is more compact and easy to follow. Also the connector is declared in the policy section, made more sense (for me) than declare the policy in another part of the template.

Resources:
  StockCheckerFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/stock_checker/
      Handler: app.lambda_handler
      Runtime: python3.9
      Architectures:
        - x86_64
    Policies:
       - serverlessConnectorPolicy:
         - Destination:
          - Id: StockSellQueue
          - Id: StockBuyQueue
        - Permissions:
           - Write
   
  StockSellQueue:
    Type: AWS::SQS::Queue
  StockBuyQueue:
    Type: AWS::SQS::Queue

[ccaum]

Thanks @CGarces. Are you commenting on where the connector definition should live or on how multiple sources and destinations are defined in a single connector? In a future release we will be allowing you to define a connector as part of a source or destination resource. This RFC is just focused on how multiple sources or destinations should be defined in a single connector.

[hoffa]

I like how succinct the syntax is, but unsure how beneficial it is if we merge #2772.

If this RFC gets implemented and #2772 gets merged, there'll be essentially 4 ways of specifying the same connections:

1. Multiple AWS::Serverless::Connectors referencing same Source:

   Bar:
     Type: AWS::Serverless::Connector
     Properties:
       Source:
         Id: Foo
       Destination:
         Id: Bar
       Permissions:
         - Write
   
   Egg:
     Type: AWS::Serverless::Connector
     Properties:
       Source:
         Id: Foo
       Destination:
         Id: Egg
       Permissions:
         - Write

2. Multiple Destinations on the same AWS::Serverless::Connector (i.e. this RFC):

   BarAndEgg:
     Type: AWS::Serverless::Connector
     Properties:
       Source:
         Id: Foo
       Destination:
         - Id: Bar
         - Id: Egg
       Permissions:
         - Write

3. Multiple connectors attached to source resource (i.e. feat: Attach connectors to source #2772):

   Foo:
     Type: ...
     Properties:
       ...
     Connectors:
       Bar:
         Destination:
           Id: Bar
         Permissions:
           - Write
       Egg:
         Destination:
           Id: Egg
         Permissions:
           - Write

4. Multiple Destinations on the same connector attached to source resource (i.e. this RFC + feat: Attach connectors to source #2772):

   Foo:
     Type: ...
     Properties:
       ...
     Connectors:
       BarAndEgg:
         Destination:
           - Id: Bar
           - Id: Egg
         Permissions:
           - Write

One concern is the potential added cognitive load in having to understand and choose one of the alternatives above.
Another is that this RFC doesn't adapt well to changing templates.

For example, assume the following connector:

Foo:
  Type: AWS::Serverless::Connector
  Properties:
    Source:
      - Id: Foo
    Destination:
      - Id: Bar
      - Id: Egg
    Permissions:
      - Read

If we then want to also give Write permissions to Egg, we'd have to either create a separate connector that gives Foo Write permissions to Egg (reducing clarity), or move Egg from Foo into its separate connector with Read/Write permissions (requiring multiple lines of diffs).

If we only support #2772, it requires writing more lines, but potentially improves clarity and consistency (and diffs in changes are purely additive).

[ljacobsson]

Starting a bit off topic-

One thing I don't like with both PolicyTemplates and Connectors is that developers have to rely on documentation to understand what IAM policy it generates, but I can see beyond that and appreciate simplifying IAM anyway :-)

However - the Write permission includes Delete, which to me is problematic. Writing data is not the same as deleting it, and developers should be encouraged to follow principle of least principle.

I suggest introducting a new Permissions option, namely Delete. This will make refactoring even worse with the suggested solution as there will be too many permutations of connections to choose from.

Could the following make that a bit simpler?

  MyConnector:
    Type: AWS::Serverless::Connector
    Properties:
      Source:
        - Id: Foo
      Destination:
        Read:
          - Id: Bar
        Write:
          - Id: Bar
          - Id: Egg
        Delete:
          - Id: Bar

In this example, Foo is allowed to read and delete from Bar, but only write to Egg

[ccaum]

Thanks, Lars. I'll respond to each point individually. Please correct me if I misunderstood any of them

1. The IAM outputs of a connector transformation are opaque. That is very true and something we hope to tackle in the future. There are many ways we could do it, but one obvious way is to provide a simpler way to locally transform a SAM template using the SAM CLI. If we provided a way to transform a single resource in your template, such as a connector, I suspect that would help remove a lot of the magic inherent in the SAM transform. What do you think?

2. Mixing Write and Delete is problematic. We had multiple long discussions about this internally. We settled on maintaining the simplicity of unix-like permissions, but recognized we'd need ways of having more granular permissions if customers ended up needing them. There are two ways we may solve this: 1/ providing more granular permissions like WriteOnly and DeleteOnly (I'm bad at naming things) and 2/ providing customers with a way to descope a permission during transformation (i.e. omit the delete permissions from the final result). I'm curious of your opinion on which you'd prefer, including potentially preferring both.

3. Having one set of permissions per connector is tedious. I like your proposed design where permissions are under the Destination. We explored something very similar internally. Ultimately though I strongly feel that, when it comes to IAM permissions, connectors should be very explicit about what each connector does and each connector should only do one thing. That implies that each connector describes a single set of permissions and all the resources those permissions will be applied to. Though I do understand that makes things more verbose than they would be with your proposed design.

[ccaum]

We have decided to move forward with part of this RFC. We will implement the ability to define multiple destinations for a single connector. We are still considering the developer experience implications of supporting multi-source connector definitions.