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 currently support Amazon S3 for storing user avatars, issue type icons, and project icons. In Jira Service Management, this also includes request type icons.

Learn how to configure S3 bucket to store avatar data

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

Diagram of how S3 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 your avatar data, read through the following sections to make sure this storage method is suitable for you.

You can now use Amazon S3 for storing Jira avatar data. We’re working on introducing the same storage method for Jira attachments.

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:

  • This is currently the only Jira-supported object storage solution.

  • S3 object storage is for avatars only at this stage. You still need to use file system storage for other data, like attachments, 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. 

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 of Amazon S3 features, it’s not compatible with certain feature configurations. They are listed in the following table.

Bucket versioning

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

Jira doesn’t reuse object keys when updating avatars, 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 sucessfully 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 bucket with Jira. Learn how to configure S3 bucket to store avatar data

Troubleshoot Amazon S3

Having problems after configuring Amazon S3? Read how to troubleshoot Amazon S3 for avatars storage

Last modified on May 29, 2023

Was this helpful?

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