Configuring Amazon S3 object storage

If your team has large or increasing data sets, consider storing your avatars in Amazon S3 object storage for greater scalability. This type of storage is better designed and optimized for storing data, unlike traditional file systems. Learn more about Amazon S3 and how it works

We support Amazon S3 for storing:

The following diagram depicts how object storage works — avatars uploaded to Jira are stored in and retrieved from an Amazon S3 bucket.

Check if Amazon S3 is right for you

If you’re considering using Amazon S3 to store avatars or attachments, read through the following sections to make sure this storage method is suitable for you.

Amazon S3 requirements

To use Amazon S3 object storage, you need to:

Amazon S3 limitations

If you’re planning to use Amazon S3 as your data storage method, consider that:

  • You can use S3 object storage to store avatars. Amazon S3 support for attachments isn't currently available by default and you need to enable the feature flag to access the functionality. Learn how to configure Amazon S3 storage for attachments
  • You still need to use file system storage for other data, like plugins, and index snapshot data.

Configure Amazon S3 as your data storage method

Make sure that you’ve read the configuration requirements and current limitations before you start setting up Amazon S3. 

If you want to store avatars and attachments in S3, you can use separate buckets for each or a single shared bucket for both.

A single bucket should never be shared between multiple Jira instances. This might lead to data loss.

1. Create an Amazon S3 bucket

To start using Amazon S3, you first need to create an S3 bucket for your avatar data. Amazon has official guides on how to do this:

Make sure your bucket is correctly secured and isn’t publicly exposed

You’re responsible for your Amazon S3 bucket configuration and security, and we don't provide direct support for issues related to your S3 setup.

Setting up bucket permissions

Make sure that you grant Jira the necessary permissions to read from and write to your S3 bucket:

  • s3:ListBucket

  • s3:PutObject

  • s3:GetObject

  • s3:DeleteObject

Depending on how you authenticate your bucket, these permissions can be applied at the bucket level via bucket policies and IAM roles for EC2. Check out the following resources for more information:

Here is an example of how Identity and Access Management (IAM) policy provides appropriate permissions (based on the least privilege model):

    "Version": "2012-10-17",
    "Id": "PolicyForS3Access",
    "Statement": [
            "Sid": "StatementForS3Access",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:user/JiraS3"
            "Action": [
            "Resource": [

Amazon S3 feature compatibility

While Jira supports most Amazon S3 features, it’s not compatible with certain feature configurations. They are listed in the following table.

Bucket versioning

Jira can store data in an S3 bucket with versioning enabled. However, we strongly recommend against using versioning for Jira data.

Jira doesn’t reuse object keys when updating avatars or attachments, which minimizes the benefits of keeping multiple versions of an object in the same bucket. Bucket versioning may lead to compliance issues with privacy regulations, such as GDPR because deleted avatars will be preserved when versioning is enabled.

Learn more about enabling versioning on buckets

Amazon S3 Intelligent-Tiering

Jira supports storing avatars in the Intelligent-Tiering storage class. However, the optional archive access and deep archive access tiers aren’t supported.

Learn more about S3 Intelligent-Tiering access tiers

Amazon S3 Glacier

Jira doesn’t support archiving or restoring avatars from the S3 Glacier Storage class.

Learn more about Amazon S3 Glacier storage classes

2. Authenticate your Amazon S3 bucket

Jira uses the AWS SDK for Java 2.x to communicate with Amazon S3. Read more about configuring AWS SDK for Java 2.x

Before the SDK can be authenticated, it searches for credentials in your Jira environment in the following sequence:

  1. Java system properties

  2. Environment variables

  3. Web identity token from AWS Security Token Service (AWS STS)

  4. Shared credentials and config files (~/.aws/credentials)

  5. Amazon ECS container credentials

  6. Amazon EC2 instance profile credentials

For information on setting credentials for your environment, check the following Amazon guides:

Amazon recommends using IAM roles for applications and AWS services that require Amazon S3 access.

Testing your bucket connectivity 

You need to use the AWS S3 CLI to verify that the bucket was properly set up. Check out the Amazon S3 API

To confirm that your bucket was successfully authenticated and the correct permissions are in place, follow these steps:

  1. Create a test file: 

    touch /tmp/test.txt
  2. Confirm S3:PutObject permissions by writing the file to the target bucket: 

    aws s3api put-object --bucket <bucket_name> --key conn-test/test.txt --body /tmp/test.txt
  3. Confirm S3:ListBucket permissions: 

    aws s3api list-objects --bucket <bucket_name> --query 'Contents[].{Key: Key, Size: Size}'
  4. Confirm S3:GetObject permissions:

    aws s3api get-object --bucket <bucket_name> --key conn-test/test.txt /tmp/test.txt
  5. Confirm S3: DeleteObject permissions:

    aws s3api delete-object --bucket <bucket_name> --key conn-test/test.txt
  6. Remove the original test file:

    rm /tmp/test.txt

Connect Amazon S3 bucket with Jira

After you configure Amazon S3 for storing avatar data, you need to connect your S3 buckets with Jira.  Follow the instructions from these guides:

Troubleshoot Amazon S3

Having problems after configuring Amazon S3? Check out the following troubleshooting guides for help:

Last modified on Aug 28, 2023

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.