AWS S3

Aidbox integrates with AWS S3 to handle file storage, generating secure presigned URLs that let clients upload and download directly from S3.

Authentication methods

Aidbox provides two ways to authenticate with AWS S3:

• Default credentials — uses AWS environment credentials (Pod Identity, Task Role, IRSA, etc.). Recommended for production deployments on AWS.
• Access keys — explicit credentials stored in AwsAccount. Required for S3-compatible services (MinIO, Garage) and legacy setups.

When access-key-id is present in AwsAccount, Aidbox uses explicit credentials. Otherwise, it uses the default credentials provider chain .

AwsAccount configuration

Create an AwsAccount resource to configure S3 access. The region field is required. When access-key-id is omitted, Aidbox uses the default credentials provider.

Default credentials mode (recommended for AWS):

PUT /AwsAccount/my-aws

region: us-east-1

Access keys mode (for S3-compatible services or legacy):

PUT /AwsAccount/my-aws

region: us-east-1
access-key-id: AKIAIOSFODNN7EXAMPLE
secret-access-key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

API endpoints

All endpoints work identically regardless of authentication method.

Generate upload URL

Request a presigned URL for uploading a file to S3.

POST /aws/storage/<account-id>/<bucket-name>

filename: documents/report.pdf

Response:

{
  "url": "https://your-bucket.s3.us-east-1.amazonaws.com/documents/report.pdf?X-Amz-Algorithm=..."
}

Upload the file directly to S3:

curl -X PUT '<presigned-url>' \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

Generate download URL

GET /aws/storage/<account-id>/<bucket-name>/<file-path>

Example:

GET /aws/storage/my-aws/my-bucket/documents/report.pdf

The file path can include multiple directory levels (e.g., documents/2024/january/report.pdf).

Generate delete URL

DELETE /aws/storage/<account-id>/<bucket-name>/<file-path>

URL expiration

All endpoints accept an optional expiration query parameter (seconds). Default: 86400 (24 hours).

POST /aws/storage/my-aws/my-bucket?expiration=3600

filename: data.txt

Default credentials setup

When AwsAccount has no access-key-id, Aidbox uses the AWS default credentials provider chain. This works across all AWS compute environments:

IAM permissions

The IAM role needs S3 permissions for your bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

EKS Pod Identity

Pod Identity is the recommended approach for EKS.

1. Install the Pod Identity Agent

The agent runs on each node and provides temporary AWS credentials to pods based on their ServiceAccount.

aws eks create-addon \
  --cluster-name my-cluster \
  --addon-name eks-pod-identity-agent

2. Create an IAM role

Create an IAM role with S3 permissions and a trust policy for Pod Identity:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pods.eks.amazonaws.com"
      },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }
  ]
}

3. Create a Pod Identity association

Link the Kubernetes ServiceAccount to the IAM role. Pods using this ServiceAccount will receive the role's permissions.

aws eks create-pod-identity-association \
  --cluster-name my-cluster \
  --namespace aidbox \
  --service-account aidbox \
  --role-arn arn:aws:iam::111122223333:role/aidbox-s3-role

4. Configure Aidbox ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: aidbox
  namespace: aidbox

Reference it in your Deployment:

spec:
  template:
    spec:
      serviceAccountName: aidbox

Access keys setup

When using explicit access keys, create an IAM user with the S3 permissions for your bucket.

Create AwsAccount with credentials

PUT /AwsAccount/my-aws

region: us-east-1
access-key-id: AKIAIOSFODNN7EXAMPLE
secret-access-key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

S3-compatible services

Services like MinIO or Garage provide S3-compatible APIs. Use access keys with custom host settings:

PUT /AwsAccount/my-minio

host: 127.0.0.1:9000
path-style: true
use-ssl: false
# ... other options

See also

• AWS S3 presigned URLs
• EKS Pod Identity
• Default credentials provider chain