docs: replace manual cross-account setup with quiltx bucket add#4803
Draft
docs: replace manual cross-account setup with quiltx bucket add#4803
Conversation
Customers raised concerns about granting s3:PutBucketNotification to the Quilt control account — it's a security risk and can overwrite existing notifications. quiltx v0.4.0 provides `quiltx bucket add` which runs in the customer's own account, merges (not replaces) policies and notifications, and supports --dry-run for review before mutation. Resolves customer complaint about PutBucketNotification permission. See also quiltdata/quiltx#20 for removing these perms from QUILT_POLICY_ACTIONS. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4803 +/- ##
=======================================
Coverage 44.32% 44.32%
=======================================
Files 813 813
Lines 32736 32736
Branches 5721 5721
=======================================
Hits 14511 14511
Misses 16224 16224
Partials 2001 2001
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
100
to
+116
|
|
||
| ```json | ||
| { | ||
| "Version": "2012-10-17", | ||
| "Statement": [ | ||
| { | ||
| "Sid": "QuiltCrossAccountAccess", | ||
| "Effect": "Allow", | ||
| "Principal": { | ||
| "AWS": "arn:aws:iam::CONTROL-ACCOUNT-ID:root" | ||
| }, | ||
| "Action": [ | ||
| "s3:GetObject", | ||
| "s3:GetObjectAttributes", | ||
| "s3:GetObjectTagging", | ||
| "s3:GetObjectVersion", | ||
| "s3:GetObjectVersionAttributes", | ||
| "s3:GetObjectVersionTagging", | ||
| "s3:ListBucket", | ||
| "s3:ListBucketVersions", | ||
| "s3:DeleteObject", | ||
| "s3:DeleteObjectVersion", | ||
| "s3:PutObject", | ||
| "s3:PutObjectTagging", | ||
| "s3:GetBucketNotification", | ||
| "s3:PutBucketNotification" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:s3:::your-data-bucket", | ||
| "arn:aws:s3:::your-data-bucket/*" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| **Install quiltx:** | ||
|
|
||
| **Apply the Policy:** | ||
|
|
||
| **Console Method:** | ||
| 1. Go to **S3 Console** → **Your Bucket** → **Permissions** → **Bucket Policy** | ||
| 2. Paste the JSON above (replace `CONTROL-ACCOUNT-ID` and `your-data-bucket`) | ||
| 3. Click **Save changes** | ||
|
|
||
| **CLI Method:** | ||
| <!-- pytest-codeblocks:skip --> | ||
| ```bash | ||
| # Save policy to file | ||
| cat > bucket-policy.json << 'EOF' | ||
| { | ||
| "Version": "2012-10-17", | ||
| "Statement": [ | ||
| { | ||
| "Sid": "QuiltCrossAccountAccess", | ||
| "Effect": "Allow", | ||
| "Principal": { | ||
| "AWS": "arn:aws:iam::123456789012:root" | ||
| }, | ||
| "Action": [ | ||
| "s3:GetObject", | ||
| "s3:GetObjectAttributes", | ||
| "s3:GetObjectTagging", | ||
| "s3:GetObjectVersion", | ||
| "s3:GetObjectVersionAttributes", | ||
| "s3:GetObjectVersionTagging", | ||
| "s3:ListBucket", | ||
| "s3:ListBucketVersions", | ||
| "s3:DeleteObject", | ||
| "s3:DeleteObjectVersion", | ||
| "s3:PutObject", | ||
| "s3:PutObjectTagging", | ||
| "s3:GetBucketNotification", | ||
| "s3:PutBucketNotification" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:s3:::your-data-bucket", | ||
| "arn:aws:s3:::your-data-bucket/*" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| EOF | ||
| # Using uvx (recommended, no install required) | ||
| uvx quiltx bucket add your-data-bucket --profile data-account --dry-run | ||
|
|
||
| # Apply the policy | ||
| aws s3api put-bucket-policy \ | ||
| --bucket your-data-bucket \ | ||
| --policy file://bucket-policy.json \ | ||
| --profile data-account | ||
| # Or install with pip | ||
| pip install quiltx | ||
| ``` | ||
|
|
||
| **🔒 Security Note:** | ||
| > Quilt admins can still control user access to this bucket through the Quilt Admin Panel's Roles and Policies. The bucket policy only grants access to Quilt infrastructure, not end users. | ||
|
|
||
| ### Step 3: Configure Cross-Account SNS (Optional) | ||
| **Preview changes with `--dry-run`:** | ||
|
|
||
| **When You Need This:** | ||
| If you're using [EventBridge integration](EventBridge.md) or have existing SNS topics in the Data Account that Quilt should use for notifications. | ||
| <!-- pytest-codeblocks:skip --> | ||
| ```bash | ||
| # Review planned bucket policy, SNS topic, and notification changes |
Contributor
There was a problem hiding this comment.
The "Install quiltx" block shows uvx quiltx bucket add your-data-bucket --profile data-account --dry-run as its uvx example — that is a full command execution, not an installation step. The immediately-following "Preview changes with --dry-run" section then repeats the exact same command (without the uvx prefix), making it unclear whether both blocks should be run or just one.
Consider restructuring so the install block shows only how to get the tool (e.g. a note that uvx needs no install), and the preview block consolidates the dry-run invocation for both uvx and pip-installed usage:
Suggested change
| ```json | |
| { | |
| "Version": "2012-10-17", | |
| "Statement": [ | |
| { | |
| "Sid": "QuiltCrossAccountAccess", | |
| "Effect": "Allow", | |
| "Principal": { | |
| "AWS": "arn:aws:iam::CONTROL-ACCOUNT-ID:root" | |
| }, | |
| "Action": [ | |
| "s3:GetObject", | |
| "s3:GetObjectAttributes", | |
| "s3:GetObjectTagging", | |
| "s3:GetObjectVersion", | |
| "s3:GetObjectVersionAttributes", | |
| "s3:GetObjectVersionTagging", | |
| "s3:ListBucket", | |
| "s3:ListBucketVersions", | |
| "s3:DeleteObject", | |
| "s3:DeleteObjectVersion", | |
| "s3:PutObject", | |
| "s3:PutObjectTagging", | |
| "s3:GetBucketNotification", | |
| "s3:PutBucketNotification" | |
| ], | |
| "Resource": [ | |
| "arn:aws:s3:::your-data-bucket", | |
| "arn:aws:s3:::your-data-bucket/*" | |
| ] | |
| } | |
| ] | |
| } | |
| ``` | |
| **Install quiltx:** | |
| **Apply the Policy:** | |
| **Console Method:** | |
| 1. Go to **S3 Console** → **Your Bucket** → **Permissions** → **Bucket Policy** | |
| 2. Paste the JSON above (replace `CONTROL-ACCOUNT-ID` and `your-data-bucket`) | |
| 3. Click **Save changes** | |
| **CLI Method:** | |
| <!-- pytest-codeblocks:skip --> | |
| ```bash | |
| # Save policy to file | |
| cat > bucket-policy.json << 'EOF' | |
| { | |
| "Version": "2012-10-17", | |
| "Statement": [ | |
| { | |
| "Sid": "QuiltCrossAccountAccess", | |
| "Effect": "Allow", | |
| "Principal": { | |
| "AWS": "arn:aws:iam::123456789012:root" | |
| }, | |
| "Action": [ | |
| "s3:GetObject", | |
| "s3:GetObjectAttributes", | |
| "s3:GetObjectTagging", | |
| "s3:GetObjectVersion", | |
| "s3:GetObjectVersionAttributes", | |
| "s3:GetObjectVersionTagging", | |
| "s3:ListBucket", | |
| "s3:ListBucketVersions", | |
| "s3:DeleteObject", | |
| "s3:DeleteObjectVersion", | |
| "s3:PutObject", | |
| "s3:PutObjectTagging", | |
| "s3:GetBucketNotification", | |
| "s3:PutBucketNotification" | |
| ], | |
| "Resource": [ | |
| "arn:aws:s3:::your-data-bucket", | |
| "arn:aws:s3:::your-data-bucket/*" | |
| ] | |
| } | |
| ] | |
| } | |
| EOF | |
| # Using uvx (recommended, no install required) | |
| uvx quiltx bucket add your-data-bucket --profile data-account --dry-run | |
| # Apply the policy | |
| aws s3api put-bucket-policy \ | |
| --bucket your-data-bucket \ | |
| --policy file://bucket-policy.json \ | |
| --profile data-account | |
| # Or install with pip | |
| pip install quiltx | |
| ``` | |
| **🔒 Security Note:** | |
| > Quilt admins can still control user access to this bucket through the Quilt Admin Panel's Roles and Policies. The bucket policy only grants access to Quilt infrastructure, not end users. | |
| ### Step 3: Configure Cross-Account SNS (Optional) | |
| **Preview changes with `--dry-run`:** | |
| **When You Need This:** | |
| If you're using [EventBridge integration](EventBridge.md) or have existing SNS topics in the Data Account that Quilt should use for notifications. | |
| <!-- pytest-codeblocks:skip --> | |
| ```bash | |
| # Review planned bucket policy, SNS topic, and notification changes | |
| **Install quiltx:** | |
| <!-- pytest-codeblocks:skip --> | |
| ```bash | |
| # Using uvx (recommended, no install required) | |
| # Or install with pip: pip install quiltx |
Preview changes with --dry-run:
# Review planned bucket policy, SNS topic, and notification changes
uvx quiltx bucket add your-data-bucket --profile data-account --dry-run
# or, if installed via pip:
quiltx bucket add your-data-bucket --profile data-account --dry-run
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
Comment on lines
122
to
+137
|
|
||
| Add this statement to your SNS topic's resource policy in the Data Account: | ||
| **Apply changes:** | ||
|
|
||
| ```json | ||
| { | ||
| "Sid": "QuiltCrossAccountSNSAccess", | ||
| "Effect": "Allow", | ||
| "Principal": { | ||
| "AWS": "arn:aws:iam::CONTROL-ACCOUNT-ID:root" | ||
| }, | ||
| "Action": [ | ||
| "sns:GetTopicAttributes", | ||
| "sns:Subscribe", | ||
| "sns:Unsubscribe" | ||
| ], | ||
| "Resource": "arn:aws:sns:region:DATA-ACCOUNT-ID:your-topic-name" | ||
| } | ||
| <!-- pytest-codeblocks:skip --> | ||
| ```bash | ||
| # Configure bucket policy, SNS topic, notifications, and register in Quilt | ||
| quiltx bucket add your-data-bucket --profile data-account | ||
| ``` | ||
|
|
||
| **Apply SNS Policy:** | ||
| `quiltx bucket add` performs the following steps: | ||
| 1. **Merges** a cross-account bucket policy statement (by `Sid`) granting the Quilt | ||
| control account read/write access | ||
| 2. **Creates or reuses** an SNS topic in the Data Account for S3 event notifications | ||
| 3. **Configures** the SNS topic policy to allow S3 to publish and Quilt to subscribe | ||
| 4. **Merges** the SNS notification into the bucket's existing notification configuration | ||
| (by `Id`), preserving any other notifications already in place |
Contributor
There was a problem hiding this comment.
quiltx bucket add is described as step 5 — "Registers the bucket in the Quilt catalog" — but the docs never explain how quiltx discovers which Quilt instance to register with. The command shown is just quiltx bucket add your-data-bucket --profile data-account with no Quilt endpoint, stack name, or environment variable mentioned. A new user following this guide has no idea whether to set a QUILT_STACK env var, pass an --endpoint flag, or rely on a local config file. Even a single sentence covering this would close the gap.
- Restructure install/preview blocks to eliminate redundancy - Add catalog discovery guidance (auto-detects stack, no prerequisite) - Show both uvx and pip usage in preview and apply sections Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
quiltx bucket add(available since quiltx v0.4.0)s3:PutBucketNotificationpermission from docs — customers runquiltxin their own account, so the control account never needs thisquiltxauto-detects the stack, noquiltx stackprerequisite neededContext
Customer complaint: granting
s3:PutBucketNotificationto the Quilt control account is a security risk, and AWS's replace-not-append API means Quilt could stomp existing notifications.quiltx bucket addsolves this by running in the customer's account and merging configurations safely.See also quiltdata/quiltx#20 for removing notification permissions from
QUILT_POLICY_ACTIONS.Related: quiltdata/quiltx@1531596 —
bucket addnow auto-discovers the CloudFormation stack when no cached metadata exists, so users no longer need to runquiltx stackfirst.Test plan
quiltxcommands shown are valid per quiltx v0.4.0🤖 Generated with Claude Code