# 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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kubemq.io/configuration/connectors/kubemq-targets/aws/s3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.