> ## Documentation Index
> Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# S3 Ingestion

## 1. Concepts

### What S3 Ingestion configures

**Settings > S3 Ingestion** is where an organization connects an AWS S3 bucket to Zenskar so usage event files uploaded to that bucket are ingested automatically. This tab manages one connection for the whole organization. Enabling ingestion for a specific usage event, and choosing which folder in the bucket that event reads from, happens separately, when creating or editing a usage event, not on this tab. For the full AWS-side setup, see [Set up S3 event sync](/docs/20240301/product-modules/usage/usage-event/how-to-set-up-s3-event-sync).

### Processor Role ARN and SQS Queue ARN

Zenskar provides a **Processor Role ARN** and an **SQS Queue ARN** on this tab. These identify the AWS role and queue Zenskar uses to read from S3 buckets and receive event notifications, and the same values are shown to every organization in a given Zenskar environment. Access to a specific bucket depends entirely on that bucket's own policy granting the Processor Role ARN read permission, not on these ARNs being unique per organization.

### Region requirement

The S3 bucket and its event notifications must be in the **us-east-1** AWS region. Buckets in other regions cannot be used.

### Connection status is not a live connectivity check

<Warning>
  The Connected or Not Connected status on this tab reflects only whether ingestion is enabled and a bucket name has been saved. It does not verify that Zenskar can actually reach the bucket, that the bucket policy is correct, or that the bucket is in the right region. A configuration can show Connected even when the AWS-side setup is incomplete. Upload a test file to confirm ingestion is working end to end.
</Warning>

***

## 2. How-to guides

### Find the Processor Role ARN and SQS Queue ARN

Go to **Settings > S3 Ingestion**. The **Processor Role ARN** and **SQS Queue ARN** are shown read-only, each with a copy action. These values are needed to configure the bucket policy and event notifications on the AWS side.

### Connect an S3 bucket

1. Go to **Settings > S3 Ingestion**.
2. Enter the **S3 Bucket Name**, without the `s3://` prefix.
3. Optionally enter an **Ingestion Error Bucket**, a location where events that fail validation are logged. Left empty, failed events are not captured anywhere.
4. Click **Save Config**.

Complete the AWS-side bucket policy and event notification setup separately. See [Set up S3 event sync](/docs/20240301/product-modules/usage/usage-event/how-to-set-up-s3-event-sync).

### Disconnect an S3 bucket

1. Go to **Settings > S3 Ingestion**.
2. Use **Disconnect S3 Bucket**.
3. Confirm the action.

### Enable ingestion for a specific usage event

This is configured on the usage event itself, not on this tab. See [Set up S3 event sync](/docs/20240301/product-modules/usage/usage-event/how-to-set-up-s3-event-sync).

### Troubleshooting

* **Status shows Connected but no events are being ingested**: Connected only means a bucket name is saved; it does not confirm the AWS-side setup is correct. Verify the bucket policy grants the Processor Role ARN read access, the bucket is in us-east-1, and event notifications are configured to the SQS Queue ARN shown on this tab.
* **Failed events are not appearing anywhere**: an Ingestion Error Bucket was not set. Add one and save to start capturing failed events going forward.

***

## 3. Reference

### Location

**Settings > S3 Ingestion**.

### Fields

| Field                  | Editable | Notes                                                                                                         |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| Processor Role ARN     | No       | Shared across organizations in this Zenskar environment; grant it read access through the bucket's own policy |
| SQS Queue ARN          | No       | Destination for the bucket's S3 event notifications                                                           |
| S3 Bucket Name         | Yes      | Required; enter without the `s3://` prefix                                                                    |
| Ingestion Error Bucket | Yes      | Optional; location where events failing validation are logged                                                 |

### Actions

| Action               | Effect                                                        |
| -------------------- | ------------------------------------------------------------- |
| Save Config          | Saves the bucket name and error bucket, and enables ingestion |
| Disconnect S3 Bucket | Removes the configuration, with a confirmation step           |

### Status values

| Status        | Meaning                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------- |
| Connected     | Ingestion is enabled and a bucket name is saved. Does not confirm actual AWS connectivity |
| Not Connected | Ingestion is not enabled, or no bucket name has been saved                                |

### Scope

One S3 Ingestion configuration exists per organization. It is not scoped per business entity.

### Region requirement

The S3 bucket must be in us-east-1. The SQS queue and the bucket must be in the same AWS region for event notifications to work.