From 4fe6717bccd36fccbefd6550ddf7f207b38b52c6 Mon Sep 17 00:00:00 2001
From: Rico Huijbers <rix0rrr@gmail.com>
Date: Tue, 3 May 2022 11:43:06 +0200
Subject: [PATCH] docs(iam): explain restrictions on `addCondition` (#20165)

Multiple calls to `addCondition` aren't as smart as one might want. Clarify that they aren't.

Fixes #20158.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 .../@aws-cdk/aws-iam/lib/policy-statement.ts  | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/packages/@aws-cdk/aws-iam/lib/policy-statement.ts b/packages/@aws-cdk/aws-iam/lib/policy-statement.ts
index 80ff191613e0e..688cf39faea18 100644
--- a/packages/@aws-cdk/aws-iam/lib/policy-statement.ts
+++ b/packages/@aws-cdk/aws-iam/lib/policy-statement.ts
@@ -310,6 +310,27 @@ export class PolicyStatement {
 
   /**
    * Add a condition to the Policy
+   *
+   * If multiple calls are made to add a condition with the same operator and field, only
+   * the last one wins. For example:
+   *
+   * ```ts
+   * declare const stmt: iam.PolicyStatement;
+   *
+   * stmt.addCondition('StringEquals', { 'aws:SomeField': '1' });
+   * stmt.addCondition('StringEquals', { 'aws:SomeField': '2' });
+   * ```
+   *
+   * Will end up with the single condition `StringEquals: { 'aws:SomeField': '2' }`.
+   *
+   * If you meant to add a condition to say that the field can be *either* `1` or `2`, write
+   * this:
+   *
+   * ```ts
+   * declare const stmt: iam.PolicyStatement;
+   *
+   * stmt.addCondition('StringEquals', { 'aws:SomeField': ['1', '2'] });
+   * ```
    */
   public addCondition(key: string, value: Condition) {
     const existingValue = this.condition[key];
@@ -318,6 +339,8 @@ export class PolicyStatement {
 
   /**
    * Add multiple conditions to the Policy
+   *
+   * See the `addCondition` function for a caveat on calling this method multiple times.
    */
   public addConditions(conditions: Conditions) {
     Object.keys(conditions).map(key => {
@@ -327,6 +350,8 @@ export class PolicyStatement {
 
   /**
    * Add a condition that limits to a given account
+   *
+   * This method can only be called once: subsequent calls will overwrite earlier calls.
    */
   public addAccountCondition(accountId: string) {
     this.addCondition('StringEquals', { 'sts:ExternalId': accountId });