Add upgrade instructions ahead of upgrade

rwx-research · Jan 27, 2025 · 731bbae · 731bbae
1 parent 64f7519
commit 731bbae
Show file tree

Hide file tree

Showing 2 changed files with 112 additions and 2 deletions.
diff --git a/aws/assume-role/README.md b/aws/assume-role/README.md
@@ -115,3 +115,114 @@ tasks:
       role-to-assume: arn:aws:iam::your-account-id:role/your-other-role
       profile-name: your-other-profile
 ```
+
+## Upgrading from v1.X.X
+
+In v1.X.X the AWS OIDC token was provided as a leaf parameter.
+Starting in version 2, the AWS OIDC token is provided to tasks that use the assume role leaf task as an environment variable (default: `AWS_OIDC_TOKEN`).
+
+As a result of this, upon retrying a task, a new token will be used, preventing the incidental use of expired credentials.
+
+### Assuming a Role
+
+#### Before
+
+```yaml
+tasks:
+  - key: aws-cli
+    call: aws/install-cli 1.0.1
+
+  - key: assume-role
+    use: aws-cli
+    call: aws/assume-role 1.1.4
+    with:
+      region: us-east-2
+      role-to-assume: arn:aws:iam::your-account-id:role/your-role
+      oidc-token: ${{ vaults.your-vault.oidc.your-token }}
+
+  - key: your-task
+    use: assume-role
+    run: # ...
+```
+
+#### After
+
+```yaml
+tasks:
+  - key: aws-cli
+    call: aws/install-cli 1.0.1
+
+  - key: assume-role
+    use: aws-cli
+    call: aws/assume-role 2.0.0 # replaces aws/assume-role 1.1.4
+    with:
+      region: us-east-2
+      role-to-assume: arn:aws:iam::your-account-id:role/your-role
+
+  - key: your-task
+    use: assume-role
+    run: ...
+    env:
+      AWS_OIDC_TOKEN: ${{ vaults.your-vault.oidc.your-token }}
+```
+
+### Role Chaining
+
+#### Before
+
+```yaml
+tasks:
+  - key: aws-cli
+    call: aws/install-cli 1.0.1
+
+  - key: assume-role
+    use: aws-cli
+    call: aws/assume-role 1.1.4
+    with:
+      region: us-east-2
+      role-to-assume: arn:aws:iam::your-account-id:role/your-role
+      oidc-token: ${{ vaults.your-vault.oidc.your-token }}
+
+  - key: chain-role
+    use: assume-role
+    call: aws/assume-role 1.1.4
+    with:
+      region: us-east-2
+      role-to-assume: arn:aws:iam::your-account-id:role/your-other-role
+
+  - key: your-task
+    use: chain-role
+    run: ...
+```
+
+#### After
+
+```yaml
+tasks:
+  - key: aws-cli
+    call: aws/install-cli 1.0.1
+
+  - key: assume-role
+    use: aws-cli
+    call: aws/assume-role 2.0.0 # replaces aws/assume-role 1.1.4
+    with:
+      oidc-token: ${{ vaults.your-vault.oidc.your-token }}
+      region: us-east-2
+      role-to-assume: arn:aws:iam::your-account-id:role/your-role
+
+  - key: chain-role
+    use: aws-cli
+    call: aws/assume-role 2.0.0 # replaces aws/assume-role 1.1.4
+    with:
+      region: us-east-2
+      role-to-assume: arn:aws:iam::your-account-id:role/your-other-role
+      role-chaining: true
+
+  - key: your-task
+    use: [assume-role, chain-role]
+    run: ...
+    env:
+      AWS_OIDC_TOKEN: ${{ vaults.your-vault.oidc.your-token }}
+```
+
+Note that `your-task` _uses_ both `assume-role` and `chain-role` in that order. It first assumes the role, then adds additional roles with  chaining.
diff --git a/aws/assume-role/mint-leaf.yml b/aws/assume-role/mint-leaf.yml
@@ -33,8 +33,7 @@ tasks:
       set -ueo pipefail
 
       cat << EOF > $(mktemp "$MINT_WARNINGS/warning-XXXX")
-      This leaf is deprecated. Please upgrade to \`2.0.0\` or later.
-      Going forward the OIDC token is provided by downstream tasks via AWS_OIDC_TOKEN environment variable.
+      This leaf is being deprecated. Please upgrade to \`2.0.0\` or later. See [upgrade instructions](https://cloud.rwx.com/leaves/aws/assume-role) for more detail.
       EOF
 
       if ! command -v aws &> /dev/null; then