AWS Simple Storage Service (S3)

Configure blob stores to use AWS Simple Storage Service instead of a local file system. We recommend only using S3 as a blob store when Nexus Repository is running on EC2 instances within AWS. Files are stored in an S3 bucket by using the AWS REST APIs over HTTP. HTTP traffic to S3 blob stores introduces significant I/O latency across the network from other networks.

Nexus Repository uses the IAM role assigned to the current EC2 instance to access the S3 buckets.
The bucket may use server-side encryption with KMS key management transparently or S3-managed encryption.
Nexus Repository applies a lifecycle rule to expire deleted content.

Required AWS Permission

The AWS user needs permission for the following actions for accessing the S3 bucket resource.

CreateBucket and DeleteBucket are required to automatically add new buckets but are not needed to use an existing one.

s3:PutObject
s3:GetObject
s3:DeleteObject
s3:ListBucket
s3:GetLifecycleConfiguration
s3:PutLifecycleConfiguration
s3:GetObjectTagging
s3:PutObjectTagging
s3:DeleteObjectTagging
s3:GetBucketPolicy
s3:CreateBucket
s3:DeleteBucket

Sample bucket policy

Replace the following parameters for your environment.

<user-arn> - the ARN of the AWS user
<s3-bucket-name> - the S3 bucket name

{
  "Version": "2012-10-17",
  "Id": "NexusS3BlobStorePolicy",
  "Statement": [
    {
      "Sid": "NexusS3BlobStoreAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<user-arn>"
      },
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetLifecycleConfiguration",
        "s3:PutLifecycleConfiguration",
        "s3:GetObjectTagging",                
        "s3:PutObjectTagging",
        "s3:DeleteObjectTagging",
        "s3:GetBucketPolicy"
      ],
      "Resource": [
        "arn:aws:s3:::<s3-bucket-name>",
        "arn:aws:s3:::<s3-bucket-name>/*"
      ]
        }
    ]
}

Sample IAM policy to allow the creation and deletion of buckets

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:DeleteBucket",
                "s3:CreateBucket"
            ],
            "Resource": [
                "arn:aws:s3:::*"
            ]
        }
    ]
}

The following sections explain the S3-specific fields when selecting S3 as the blob store.

Name Field

Give your blob store a unique name.

Region Field

A drop-down list populated with a list of AWS regions. Select the appropriate region for your blob store; for optimum performance, it should be the same region in which Nexus Repository is run.

See the Custom S3 Regions to add other regions.

Bucket Field

Provide an existing or new AWS S3 bucket name. Nexus Repository automatically creates the S3 bucket when the provided name does not yet exist.

See the AWS documentation for working with buckets

Prefix Field

The prefix is the complete path in front of the object name, which includes the bucket name.

For instance, if ObjectA.txt is stored as BucketA/ProjectA/FilesA/ObjectA.txt, the prefix is BucketA/ProjectA/FilesA/.

Expiration Days Field

Use the Expiration Days field to configure the number of days until deleted files are removed from the S3 bucket.

See the AWS documentation on deleting Amazon S3 objects for details.

1 or greater: the files are soft deleted in the blob store and the S3 policy hard deletes them at the set number of days.
0: the files are hard deleted right away. Does not require the S3 policy to delete them.
-1: Nexus Repository soft delete blobs while the S3 policy will not hard delete them.
This is not recommended as files are never deleted. The compact blob store task is used for file-based blob stores and does not delete files on the S3 blob store.
For more information on soft and hard deletion, see the Storage Guide.

Authentication

In this optional section, provide AWS Identity and Access Management (IAM) authentication information.

See Temporary security credentials in the IAM section of the AWS documentation for more information on AWS IAM.

Encryption Type

Setting the encryption type is not required to use S3 buckets. When desired, select either S3 Managed Encryption or KMS Managed Encryption as the encryption type used for objects in the S3 blob store.

Nexus Repository has tested using SSE-S3 and SSE-KMS. See the AWS server-side encryption documentation for more information.

Providing a KMS key ID

When left blank Nexus Repository uses a default key.
When providing a KMS key ID, enter the full KMS key ID rather than the human-readable key alias.

Enabling Encryption on an Existing Blob Store

To avoid errors when encrypting an existing blob store, we recommend the following steps before enabling encryption:

Upgrade Nexus Repository to the latest available version
Schedule a Nexus Repository shutdown
Add the KMS key in the blob store user interface immediately after encryption is enabled

While the access to encrypted S3 objects is transparent, it would be best to start Nexus Repository after encryption is enabled and then immediately add the KMS key in the blob store user interface to enable bucket decryption.

Advanced Connection Settings

The following configuration is useful when configuring third-party storage devices that implement the S3 API. These settings are not needed when using AWS directly.

Endpoint URL

Use this field to provide the storage device's URL.

Max Connection Pool Size

The maximum number of connections that can be created to meet client requests. When set, this value overrides the default connection pool size defined by Nexus Repository or the AWS Client. For better performance or to avoid timeouts, large deployments with a lot of traffic may want to increase the connection pool that the S3 client uses.

Signature Version

Identifies the AWS Signature version that you want to support for authenticated requests. For authenticated requests, Amazon S3 supports both Signature Version 4 and Signature Version 2. You can add this condition to your bucket policy to require a specific signature version.

Use path-style access

AWS uses the bucket as a subdomain of the URL. Enabling this setting will result in using the older style that appends the bucket name to the path of the URL.

AWS S3 Replication Buckets

Only available in Sonatype Nexus Repository Pro. Interested in a free trial? Start here.

For highly available deployments, failover buckets in alternate regions may be configured in case of failure in the primary region. At startup, Nexus Repository chooses the bucket based on the detected AWS region. The primary bucket is used when the operating region does not match the configured failovers.

The Region Status found when editing the blob store reports which region is available and is in use.

Bi-directional Replication

Nexus Repository does not upload or remove content in both buckets. Content is only added to the currently active bucket.

Bi-directional replication should be configured between the primary bucket and the replication bucket to copy artifacts added to either bucket. Set this configuration via the AWS console API. Include deletes as well as additions and redeployment of existing artifacts.

Select an alternate region to use in case the primary region is not available.
Provide the alternate bucket name. This bucket must be created in the alternate region manually. See the Bi-Directional Replication note above.
Multiple failover buckets may be added however S3 replication should be configured to copy content added to any one to all of the others.

AWS S3 Replication Buckets are only intended for regional failover support when the Nexus instance is started in the failover region. Failover buckets should not be used by multiple Nexus Repository clusters connected to different databases. This functionality is not intended for replication across different repository instances and attempting this use case is not supported.

Soft Quota

This section allows you to enable a soft quota for the blob store, which will raise an alert when a blob store exceeds a constraint.

See Adding a Soft Quota for more information.

Custom S3 Regions

To use a custom S3 region, create the capability by performing these steps:

Navigate to Administration → System → Capabilities
Select the Create capability button
Select the Custom S3 Regions capability type
Enter a list of custom S3 region names separated with a comma, and no spaces
```
region-1,region-2,region-3
```
Select Create capability

The list of custom regions is available in the Regions drop-down menu when configuring an S3 blob store.

Performance Notes

For optimum performance, take the following measures:

Run Nexus Repository on AWS on EC2 instances.
Ensure that the S3 connection is using the region in which Nexus Repository is run.

S3 has a hard limit of 10 thousand parts for multi-part uploads. The chunk size when uploading to S3 can be adjusted by setting the following property in the nexus.properties file.

nexus.s3.multipartupload.chunksize = 5242880

The default value in bytes is 5242880 (5MB). This may be tuned to reduce the number of parts uploaded to S3 and avoid errors on large uploads.

Access Denied Errors

Access denied errors are an indication that the user configured to connect to the bucket has insufficient permissions. AWS does not provide information specific to which permission is required to perform the failed action. For this reason, Nexus Repository will generically report access-denied errors.

An error occurred while saving data. ValidationErrorXO{id='*', message='Unable to initialize blob store bucket: name, Cause: Failed to find encrypter for id:'}