# Best Practices

Storage Connections make it easy to connect your S3 buckets to AI applications while maintaining control. These best practices help you get the most out of Storage Connections with straightforward approaches to access control, organization, and operations.

## Access Control Made Simple

### Start Simple, Refine as Needed

Vendia’s two-layer permission system (IAM + Access Policies) gives you flexibility:

- **Quick start**: Grant broad IAM permissions, then use Access Policies for day-to-day control
- **Begin with what you need**: Start with read access, add write/create permissions as use cases emerge
- **Adjust without AWS changes**: Modify Access Policies in Vendia without touching IAM roles
- **Use FILE_CREATE vs FILE_WRITE**: Prevent accidental overwrites by using FILE_CREATE for new content

### Organize Access by Purpose

Access Policies make it straightforward to organize access by what AI agents need to do:

- **Reference content**: Use `FILE_READ` for documentation, templates, and source data
- **Output areas (create only)**: Use `FILE_CREATE` in folders where AI generates new files but shouldn’t overwrite existing ones
- **Output areas (create and update)**: Use both `FILE_CREATE` and `FILE_WRITE` where AI needs to create new files and update existing ones
- **Working directories**: Use all actions (`FILE_READ`, `FILE_WRITE`, `FILE_CREATE`, `FILE_DELETE`) in temporary workspaces where AI needs full control
- **Shared resources**: Combine `FILE_READ` broadly with `FILE_WRITE`/`FILE_CREATE` selectively based on your needs

#### Example: Clean separation of concerns

**IAM Policy** (sets maximum permissions):  
```
{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:ListBucket",
    "s3:PutObject",
    "s3:DeleteObject"
  ],
  "Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]
}
```

**Access Policies** (easy to adjust anytime):  
```
Policy 1 - Reference data access:
  Pattern: reference/**
  Actions: FILE_READ

Policy 2 - Generate new reports:
  Pattern: reports/**
  Actions: FILE_CREATE, FILE_READ

Policy 3 - Temporary workspace:
  Pattern: workspace/temp/**
  Actions: FILE_READ, FILE_WRITE, FILE_CREATE, FILE_DELETE
```

This setup keeps AI agents productive while maintaining clean organization.

### Effective Glob Patterns

Choose patterns that match your folder structure:

| Pattern | Purpose | Example Use Case |
| --- | --- | --- |
| `**` | Full access | Development environments where AI needs complete access |
| `foo/*` | Single directory | Access to immediate files in a specific folder |
| `foo/**` | Recursive access | Access to a folder and all its subfolders |
| `**/*.ext` | File types anywhere | All PDFs, images, or config files across your storage |
| `*.ext` | Root-level files | Specific file types only in the top directory |

**Pro tip:** Start broad during development (`**`), then refine for production (`specific-folders/**`). You can adjust patterns anytime without changing IAM policies.

### Monitor Activity and Usage

Storage Connections includes built-in visibility:

- **MCP Server Logs** - See what AI agents are accessing in real-time
- **S3 Logging** - Track file operations at the storage level
- **CloudTrail** - Monitor IAM and API activity

The Activity Log in MCP Server shows you exactly what’s happening, making it easy to verify everything is working as expected.

## File Organization

### Folder Structure

A well-organized folder structure makes access policies simpler:
```
s3://my-ai-bucket/
├── reference/          # Read-only documentation, manuals
├── reports/            # AI-generated outputs
├── workspace/
│   ├── temp/          # Temporary files with full access
│   └── shared/        # Collaborative files
└── archive/           # Historical data (read-only)
```

This structure makes it easy to create clear access policies and helps teams understand what’s where.

### Naming Conventions

Use descriptive names for connections and files:

- **Storage connections**: `marketing-docs-readonly`, `finance-reports`, `customer-data-full`
- **AI-generated files**: `report-2024-01-15-sales.pdf`, `analysis-2024-01-15-143022.json`

## Getting Started

Start with these simple steps:

1. **Begin with read-only access** using IAM Option A and `FILE_READ` access policies
2. **Test with your AI applications** to ensure everything works
3. **Expand access as needed** by adjusting Access Policies (no IAM changes required)
4. **Monitor activity** through MCP Server logs
5. **Refine your configuration** based on actual usage patterns

The beauty of Storage Connections is that you can start simple and evolve as your needs grow. The combination of broad IAM permissions and fine-grained Access Policies gives you complete control without complexity.