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:
- Avatars (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
Attachments. This feature is currently available behind the feature flag. Learn how to configure Jira to store attachments in Amazon S3
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:
Have a Jira Data Center license.
Plan to host Jira on AWS or already run Jira in AWS. This feature isn't supported for on-premise deployments or for any customers who aren’t running Jira in AWS. Learn more about administering Jira Data Center on AWS
Have one or more dedicated Amazon S3 buckets to store avatars or attachments. Learn how to create, configure, and connect an S3 bucket to Jira
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:ListBuckets3:PutObjects3:GetObjects3: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": [
"s3:ListBucket",
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::jira-avatar-data/*",
"arn:aws:s3:::jira-avatar-data"
]
}
]
}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.
| Feature | Description |
|---|---|
| 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. |
| 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. |
Amazon S3 Glacier | Jira doesn’t support archiving or restoring avatars from the S3 Glacier Storage class. |
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:
Java system properties
Environment variables
Web identity token from AWS Security Token Service (AWS STS)
Shared credentials and
configfiles(~/.aws/credentials)Amazon ECS container credentials
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:
Create a test file:
touch /tmp/test.txtConfirm
S3:PutObjectpermissions by writing the file to the target bucket:aws s3api put-object --bucket <bucket_name> --key conn-test/test.txt --body /tmp/test.txtConfirm
S3:ListBucketpermissions:aws s3api list-objects --bucket <bucket_name> --query 'Contents[].{Key: Key, Size: Size}'Confirm
S3:GetObjectpermissions:aws s3api get-object --bucket <bucket_name> --key conn-test/test.txt /tmp/test.txtConfirm
S3: DeleteObjectpermissions:aws s3api delete-object --bucket <bucket_name> --key conn-test/test.txtRemove the original test file:
rm /tmp/test.txt
3. RECOMMENDED Clear up incomplete file uploads
To provide a more reliable asynchronous way of uploading and downloading files in multiple parts, we’ve changed the Amazon S3 client to the CRT-based asynchronous version.
However, in case the system fails or the connection breaks, the upload process may not be completed successfully, resulting in storing incomplete file chunks on S3. To address the retainment of incomplete file parts over the long term, there is a recommended solution.
AWS recommends that you enable the AbortIncompleteMultipartUpload lifecycle rule on your Amazon S3 buckets.
This rule directs Amazon S3 to abort multipart uploads that don’t complete within a specified number of days after being initiated. When the set time limit is exceeded, Amazon S3 aborts the upload and then, deletes the incomplete upload data.
For more information, check out Lifecycle Configuration for a Bucket with Versioning.
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: