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

# Amazon S3

> Configure log shipping from Control Plane to Amazon S3 for scalable, durable cloud storage of your org logs.

## Overview

[Amazon S3](https://aws.amazon.com/s3/) (Simple Storage Service) is a highly scalable, durable, and secure cloud storage service offered by Amazon Web Services (AWS). It is commonly used for various data storage purposes, including storing server logs.

Using [S3](https://aws.amazon.com/s3/) to store server logs provides a reliable, scalable, and secure solution for retaining valuable log data. The centralized storage also simplifies log management, enhances data analysis capabilities, and supports compliance and auditing requirements. AWS's extensive global infrastructure ensures that your log data is available and accessible from anywhere with low latency, making [S3](https://aws.amazon.com/s3/) a popular choice for log storage in the cloud.

Follow the steps below to configure log shipping to [Amazon S3](https://aws.amazon.com/s3/).

## Step 1 - Credential Procurement

Authentication credentials are required to ship logs to [S3](https://aws.amazon.com/s3/).

Follow these steps to obtain the credentials, store them as an [AWS Secret](/reference/secret#amazon-web-services-aws), and
configure external logging.

1. Refer to [these instructions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to create a new AWS IAM user in your AWS account.

   * Select `Programmatic access` when creating the user and take note of the Access and Secret Key.

2. This user, at a minimum, must have an associated policy with the `s3:PutObject` action.

**Sample AWS Policy (substitute S3\_BUCKET\_NAME):**

```json JSON theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*"
    }
  ]
}
```

3. From the Control Plane Console UI, click `Secrets` from the left menu.
4. Click the `New` button.
5. Enter a `Name` for the secret, and select `AWS` from the Secret Type list.
6. Enter the `Access Key` and `Secret Key` and click `Save`.
7. This secret can now be used when configuring logging using the [UI Console](#enable-logging-using-the-ui-console) or [CLI](#enable-logging-using-the-cli).

## Step 2 - Configure External Logging

External logging can be configured by using either the [UI Console](#enable-logging-using-the-ui-console) or the [CLI](#enable-logging-using-the-cli).

### Enable Logging using the UI Console

1. From the Control Plane Console UI, click on `Org` in the left menu.
2. Click `External Logs` in the middle context menu.
3. Select `S3` and fill out the required fields.
4. Select the AWS secret to authenticate to S3. Refer to the [credential procurement](#step-1-credential-procurement) section to obtain and configure the necessary credentials.
5. Click `Save`.
6. After the configuration is complete, log entries will be available at S3 within a few minutes.

<Tip>
  The `prefix` will be the folder where the logs will be written.

  The folder structure will follow the format:

  `PREFIX/ORG_NAME/YEAR/MONTH/DAY/HOUR/MINUTE/LOG_FILE.jsonl`

  The .jsonl file will contain \~1-3k of single line log entries in JSON.

  Each entry will contain the following keys:

  * time
  * log
  * location,
  * version
  * provider
  * container
  * replica
  * workload
  * gvc
  * org
  * stream
</Tip>

### Enable Logging using the CLI

The external logging configuration can be created / updated using the CLI's `cpln org patch ORG_NAME -f FILE.yaml` command.

Below is an example [Org](/reference/org) manifest (in YAML). Edit and save the YAML as a file and use it as an input to the CLI's `cpln org patch ORG_NAME -f FILE.yaml` command.

Refer to the [credential procurement](#step-1-credential-procurement) section to obtain and configure the necessary credentials.

* Substitute: `ORG_NAME`, `S3_BUCKET_NAME`, `AWS_SECRET`, and `AWS_REGION`.

```yaml YAML theme={null}
kind: org
name: ORG_NAME
spec:
  logging:
    s3:
      bucket: S3_BUCKET_NAME
      credentials: //secret/AWS_SECRET
      prefix: /
      region: AWS_REGION
```