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.
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 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:
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 that aren’t running Jira in AWS. Learn more about administering Jira Data Center on AWS
Have a dedicated Amazon S3 bucket to store Jira avatars. 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:
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: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 of 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 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. |
| 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 sucessfully 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
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