> For the complete documentation index, see [llms.txt](https://docs.kubemq.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kubemq.io/configuration/connectors/kubemq-targets/aws/s3.md).

# S3

Kubemq aws-s3 target connector allows services using kubemq server to access aws s3 service.

## Prerequisites

The following required to run the aws-s3 target connector:

* kubemq cluster
* aws account with s3 active service
* kubemq-source deployment

## Configuration

s3 target connector configuration properties:

| Properties Key   | Required | Description                             | Example                        |
| ---------------- | -------- | --------------------------------------- | ------------------------------ |
| aws\_key         | yes      | aws key                                 | aws key supplied by aws        |
| aws\_secret\_key | yes      | aws secret key                          | aws secret key supplied by aws |
| region           | yes      | region                                  | aws region                     |
| token            | no       | aws token ("default" empty string       | aws token                      |
| downloader       | no       | if needed to create downloader instance | true                           |
| uploader         | no       | if needed to create uploader instance   | false                          |

Example:

```yaml
bindings:
  - name: kubemq-query-aws-s3
    source:
      kind: kubemq.query
      name: kubemq-query
      properties:
        address: "kubemq-cluster:50000"
        client_id: "kubemq-query-aws-s3-connector"
        auth_token: ""
        channel: "query.aws.s3"
        group:   ""
        auto_reconnect: "true"
        reconnect_interval_seconds: "1"
        max_reconnects: "0"
    target:
      kind: aws.s3
      name: aws-s3
      properties:
        aws_key: "id"
        aws_secret_key: 'json'
        region:  "region"
        token: ""
        downloader:  "true"
        uploader:  "true"
```

## Usage

### List Buckets

list all buckets.

List Buckets:

| Metadata Key | Required | Description    | Possible values |
| ------------ | -------- | -------------- | --------------- |
| method       | yes      | type of method | "list\_buckets" |

Example:

```javascript
{
  "metadata": {
    "method": "list_buckets"
  },
  "data": null
}
```

### List Bucket Items

list all items in the selected bucket

List Bucket Items:

| Metadata Key | Required | Description    | Possible values       |
| ------------ | -------- | -------------- | --------------------- |
| method       | yes      | type of method | "list\_bucket\_items" |
| bucket\_name | yes      | s3 bucket name | "my\_bucket\_name"    |

Example:

```javascript
{
  "metadata": {
    "method": "list_bucket_items",
    "bucket_name": "my_bucket_name"
  },
  "data": null
}
```

### Create Bucket

create a new bucket, name must be unique

Create Bucket :

| Metadata Key          | Required | Description               | Possible values                 |
| --------------------- | -------- | ------------------------- | ------------------------------- |
| method                | yes      | type of method            | "create\_bucket"                |
| bucket\_name          | yes      | s3 bucket name            | "my\_bucket\_name"              |
| wait\_for\_completion | no       | wait for operation to end | "true","false" default of false |

Example:

```javascript
{
  "metadata": {
    "method": "create_bucket",
    "bucket_name": "my_bucket_name"
  },
  "data": null
}
```

### Upload Item

upload item to bucket.

Upload Bucket Items:

| Metadata Key          | Required | Description                   | Possible values                    |
| --------------------- | -------- | ----------------------------- | ---------------------------------- |
| method                | yes      | type of method                | "upload\_item"                     |
| bucket\_name          | yes      | s3 bucket name                | "my\_bucket\_name"                 |
| wait\_for\_completion | no       | wait for operation to end     | "true","false" (default of false ) |
| item\_name            | yes      | the name of the item          | "valid-string"                     |
| data                  | yes      | the object data in byte array | "valid-string"                     |

Example:

```javascript
{
  "metadata": {
    "method": "create_bucket",
    "bucket_name": "my_bucket_name",
    "item_name": "my_item_name"
  },
  "data": "bXkgaXRlbSBoZXJl"
}
```

### Get Item

Get item by item name from bucket

Get Bucket Items:

| Metadata Key | Required | Description          | Possible values    |
| ------------ | -------- | -------------------- | ------------------ |
| method       | yes      | type of method       | "get\_item"        |
| bucket\_name | yes      | s3 bucket name       | "my\_bucket\_name" |
| item\_name   | yes      | the name of the item | "valid-string"     |

Example:

```javascript
{
  "metadata": {
    "method": "get_item",
    "bucket_name": "my_bucket_name",
    "item_name": "my_item_name"
  },
  "data": null
}
```

### Delete Item

delete item by item name from bucket

Delete Item:

| Metadata Key          | Required | Description               | Possible values                    |
| --------------------- | -------- | ------------------------- | ---------------------------------- |
| method                | yes      | type of method            | "delete\_item\_from\_bucket"       |
| bucket\_name          | yes      | s3 bucket name            | "my\_bucket\_name"                 |
| wait\_for\_completion | no       | wait for operation to end | "true","false" (default of false ) |
| item\_name            | yes      | the name of the item      | "valid-string"                     |

Example:

```javascript
{
  "metadata": {
    "method": "delete_item_from_bucket",
    "bucket_name": "my_bucket_name",
    "item_name": "my_item_name"
  },
  "data": null
}
```

### Delete All Items

delete all items from a bucket

Delete All Items:

| Metadata Key          | Required | Description               | Possible values                    |
| --------------------- | -------- | ------------------------- | ---------------------------------- |
| method                | yes      | type of method            | "delete\_all\_items\_from\_bucket" |
| bucket\_name          | yes      | s3 bucket name            | "my\_bucket\_name"                 |
| wait\_for\_completion | no       | wait for operation to end | "true","false" (default of false ) |

Example:

```javascript
{
  "metadata": {
    "method": "delete_item_from_bucket",
    "bucket_name": "my_bucket_name"
  },
  "data": null
}
```

### Copy Item

copy an item from one bucket to another

Copy Items:

| Metadata Key          | Required | Description                | Possible values                    |
| --------------------- | -------- | -------------------------- | ---------------------------------- |
| method                | yes      | type of method             | "copy\_item"                       |
| bucket\_name          | yes      | s3 bucket name             | "my\_bucket\_name"                 |
| copy\_source          | yes      | s3 bucket name source name | "my\_bucket\_source\_name"         |
| item\_name            | yes      | the name of the item       | "valid-string"                     |
| wait\_for\_completion | no       | wait for operation to end  | "true","false" (default of false ) |

Example:

```javascript
{
  "metadata": {
    "method": "copy_item",
    "bucket_name": "my_bucket_name",
    "copy_source": "my_bucket_source_name",
    "item_name": "my_item_name"
  },
  "data": null
}
```

### Delete Bucket

delete a bucket by name.

Delete Bucket:

| Metadata Key          | Required | Description               | Possible values                    |
| --------------------- | -------- | ------------------------- | ---------------------------------- |
| method                | yes      | type of method            | "delete\_bucket"                   |
| bucket\_name          | yes      | s3 bucket name            | "my\_bucket\_name"                 |
| wait\_for\_completion | no       | wait for operation to end | "true","false" (default of false ) |

Example:

```javascript
{
  "metadata": {
    "method": "delete_bucket",
    "bucket_name": "my_bucket_name"
  },
  "data": null
}
```