Skip to main content

Configuring Blob Stores

Before configuring blob stores, be sure to check out Storage Planning for more about blob store types and planning storage requirements.

You can configure new blob stores by navigating to AdministrationRepositoryBlob Stores in Nexus Repository. You will need nx-all or nx-blobstore privileges to access this portion of Nexus Repository.

The following fields appear in the blob store listing:

  • Name- The blob store's name as displayed in repository administration.

  • Type- The type of the blob store backend. See the System Requirements for a full list of supported file systems. The following options are available:

    • Azure Cloud Storage PRO - Stores blobs in Azure cloud storage.

    • File - Store blobs in file system-based storage.

    • Group PRO - Combines multiple blob stores into one.

    • S3- Store blobs in AWS S3 cloud storage.

  • State- The state of the blob store.

    • Started indicates it is running as expected.

    • Failed indicates that there is a configuration issue and, as a consequence, the blob store failed to initialise.

  • Blob Count - The number of blobs currently stored in a blob store.

  • Total Size - The blob store's total size in bytes.

  • Available Space- A blob store's remaining storage capacity.

Click on a specific row to see the absolute Path to the file system storage (for file system blob stores) and the Soft Quota of the selected blob store.

We recommend that your blob store location be outside of the $data-dir directory and read/write accessible by the node.

Creating a New Blob Store

  1. To create a new blob store, select the Create blob store button.

  2. Select the Type and provide a Name for your blob store.

  3. For file system blob stores, in thePathfield, provide the absolute path to the desired file system location. It must be fully accessible by the operating system user account that is running Nexus Repository.

Once you have created a blob store, you will not be able to modify it. You will also not be able to delete any blob store that a repository or repository group uses.

Blobs deleted in a repository are only marked for deletion (i.e., a soft delete). You can use the Compact blob store task to permanently delete these soft-deleted blobs and therefore free up the used storage space.

The following sections cover specific information for each supported file system or blob store type.

NFS v4 File System

The recommended settings for an NFS v4 server in /etc/exports are as follows:

/srv/blobstores 10.0.0.0/8(rw,no_subtree_check)

The recommended settings for mounting the NFS filesystem on the node:

defaults,noatime,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,vers=4.1

Note

Versions of NFS older than v4 are not supported.

AWS Elastic File System (EFS)

EFS acts as a limitless NFS v4 server and is an option if Nexus Repository is running in AWS. Mount the EFS volume with the same settings as NFS v4.

Note

EFS performance will be lower than a dedicated NFS server.

AWS Simple Storage Service (S3)

You can configure blob stores to use AWS Simple Storage Service.

Blobs are stored in an S3 bucket by using AWS REST APIs over HTTP. Object PUTs use multi-part uploads of approximately 5MB chunks. Since HTTP traffic to S3 blobstores introduces more I/O latency across the network, we recommend using S3 only if Nexus Repository is running on EC2 instances within AWS.

The following sections explain each field you will see when selecting S3 as your blob store type on the Create Blob Store screen.

Name Field

Give your blob store a unique name.

Region Field

Here you will see 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.

Bucket Field

Provide either the existing or desired AWS S3 bucket name (See the AWS documentation for working with buckets). Nexus Repository automatically creates an S3 bucket when you create a blob store if one does not already exist; however, you may also create the bucket yourself. Note the following:

  • Nexus Repository will automatically apply a lifecycle rule to expire deleted content.

  • The bucket can use server-side encryption with KMS key management transparently or S3 managed encryption.

  • If running on EC2 instances, Nexus Repository can use the IAM role assigned to those instances when accessing S3 buckets.

The AWS user for accessing the S3 Blobstore bucket needs to be granted permission for these actions on the S3 bucket resource:

  • s3:PutObject

  • s3:GetObject

  • s3:DeleteObject

  • s3:ListBucket

  • s3:GetLifecycleConfiguration

  • s3:PutLifecycleConfiguration

  • s3:PutObjectTagging

  • s3:GetObjectTagging

  • s3:DeleteObjectTagging

  • s3:GetBucketPolicy

In addition, for Nexus Repository to create and delete buckets automatically, an IAM policy associated with the Nexus Repository user must include the following additonal permissions:

  • s3:DeleteBucket

  • s3:CreateBucket

Below is a sample minimal bucket policy where <user-arn> is the ARN of the AWS user and <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:PutObjectTagging",
                "s3:GetObjectTagging",
                "s3:DeleteObjectTagging",
                "s3:GetBucketAcl"
            ],
            "Resource": [
                "arn:aws:s3:::<s3-bucket-name>",
                "arn:aws:s3:::<s3-bucket-name>/*"
            ]
        }
    ]
}

Here is a sample IAM policy to allow creation and deletion of buckets:

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

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, then the prefix is BucketA/ProjectA/FilesA/.

Expiration Days Field

Use the Expiration Days field to configure the number of days until deleted blobs are finally removed from the S3 bucket. Nexus Repository will still soft delete blobs; however, S3 will hard delete through its policy after the configured number of days. See the AWS documentation on deleting Amazon S3 objects for more information.

If you set this field to 0, Nexus Repository will hard delete blobs, and you will not need to wait for the S3 policy to delete them.

If you set it to -1, Nexus Repository will still soft delete blobs, and S3 policy will not hard delete them.

Warning

We do not recommend setting this configuration to -1 as there will be no way to hard delete blobs. The Admin - Compact blob store task is only for file-based blob stores and will not hard delete blobs from S3 blob stores.

For more information on soft and hard deletion, see the Storage Guide.

Optional Authentication Section

In this section, you can provide AWS Identity and Access Management (IAM) authentication information (i.e., Access Key ID and secret, Assume Role and Session Token Amazon Resource Names (ARNs)). See the Temporary security credentials in IAM section of the AWS documentation for more information on AWS IAM.

Optional Encryption Type Section

If desired, you can select either S3 Managed Encryption or KMS Managed Encryption as the encryption type used for objects in the S3 blob store.

Note

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

You can also optionally provide a KMS key ID; if you leave this field blank, Nexus Repository will use the default. If 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

As a best practice, we recommend both upgrading Nexus Repository to the latest available version and scheduling a Nexus Repository shut down before enabling encryption. While the access to encrypted S3 objects is transparent, if you need to configure a KMS key, 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.

Optional Advanced Connection Settings

Typically you should not need to configure the following fields when using AWS directly; however, you may find them useful when configuring third-party storage devices that claim to implement the S3 API.

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 in 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.

Optional 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.

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.

Note that S3 has a hard limit of 10,000 parts for multi-part uploads. The chunk size when uploading to S3 can be adjusted by setting the property nexus.s3.multipartupload.chunksize in the nexus.properties file. The unit is bytes and the default is 5242880 (5MB). This can be tuned for optimal performance on your network and to reduce the number of parts uploaded to S3 so as not to receive 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.

Azure Blob Store

PRO

You must create the Azure storage account in Azure before using Nexus Repository to create an Azure blob store. Below are the recommended storage account settings:

  • Location: the location hosting Nexus Repository

  • Performance: Standard or Premium

  • Account kind: StorageV2

  • Replication: Any

Nexus Repository will automatically create an Azure container when a blob store is created if one does not already exist.

Warning

The Azure storage container name must be a valid DNS name that follows the rules that Microsoft states in its documentation.

Changing the Blob Store Server

If you need to change the server that is contacted for Azure blob storage from "blob.core.windows.net" to something else, edit the existing <data-dir>/etc/nexus.properties file or set a Java system property as demonstrated below:

nexus.azure.server=<your.desired.blob.storage.server>

You will then need to restart Nexus Repository for the change to take effect.

Accessing the Azure Storage Account

There are three methods of gaining access to the Azure storage account from Nexus Repository:

  1. Use a secret access key supplied by the Azure storage account.

  2. If you're running Nexus Repository on an Azure VM, you can use System Managed Identity access.

  3. Use environment variables.

System Managed Identity Access

System Managed Identity allows Azure to manage the access via roles assigned to the VM in which you are running Nexus Repository. See the Microsoft documentation for details.

To properly use the System Managed Identity, the Azure VM will need the following roles assigned to the Azure storage container:

  • Storage Account Contributor

  • Storage Blob Data Contributor

Warning

Nexus Repository does not validate that the proper roles are assigned before storing the configuration. If the aforementioned roles are not properly granted to the VM, you will need to delete the blob store and then add it again after the roles have been set up in the Azure storage instance.

Environment Variables

There are three environment variables for Azure blob stores:

  • AZURE_CLIENT_ID

  • AZURE_CLIENT_SECRET

  • AZURE_TENANT_ID

To use environment variables, you will need to register an Azure AD application and give it access to the blob storage.

Following Microsoft's documentation, complete the following steps:

  1. Create an application.

  2. Grant permission to Azure storage.

  3. Create a client secret.

  4. Copy the secret value (Not Secret Id) to use as AZURE_CLIENT_SECRET.

    Note

    You must copy this immediately as you will not be able to access it later.

  5. From the app registration overview screen, retrieve the other values for your environment variables:

    1. The Directory (tenant) ID provides the value for AZURE_TENANT_ID.

    2. The Application (client) ID provides the value for AZURE_CLIENT_ID.

You must then navigate to the storage container and grant the Storage Blob Data Contributor role to the application:

  1. Select Storage Accounts and then the storage account to which you want to grant access.

  2. Select Access Control (IAM); then, add a role assignment.

  3. Select Storage Blob Data Contributor.

  4. Select Next and then Add Member.

  5. Search for your application and add it as the member.

Now, set the environment variables in the terminal before launching Nexus Repository.

Optimizing Performance

For optimum performance, you'll want to take the following steps:

  • Run Nexus Repository on Azure on virtual machines

  • Ensure that the Azure connection is using the location where Nexus Repository is being run

The chunk size when uploading to Azure can be adjusted by setting the property nexus.azure.blocksize in the nexus.properties file (e.g., nexus.azure.blocksize=1000000). By default, this is set to 5242880 bytes (5MB). You can tune this for optimal performance on your network.

Promoting a Blob Store to a Group

To promote a blob store to a group, select the Convert to group button. This launches the promotion process to add your blob store to a group for more flexibility. Follow the on-screen prompts to create the blob store group, which will contain the previously concrete blob store and to which you can add other blob stores.

Warning

You cannot undo promoting a blob store to a group.

What is a Fill Policy?

When configuring a blob store group, you will be asked to select a fill policy (i.e., a write policy). A fill policy is the method that the blob store group uses to choose a member for writing blobs. You can change the fill policy at any time.

Available fill policy choices include the following:

  • Round Robin - Incoming writes alternate between all blob stores in the group. This is useful when you have a number of blob stores available and you want each of them to receive a roughly equal number of writes. This does not balance based upon any other metric.

  • Write to First - All incoming writes are given to the first writeable blob store (skipping blob stores in a read-only state). If you need to direct all blobs to a specific blob store (e.g., you have a blob store for a new empty disk), then this fill policy will ensure that the new blob store gets all the writes.

Removing a Blob Store from a Group

To remove a blob store from a group, you will need to use the Admin - Remove a member from a blob store group task to ensure that repositories still have access to their blobs. Groups allow you to add members dynamically, but removing a blob store requires a task to ensure that repositories still have access to their blobs.

Moving a Blob Store

Note

Before proceeding, you should ensure you have backed up your blob store.

The following steps can be used to move a blob store to a new location.

  1. Create a new blobstore with the storage path set to the new location.

  2. Promoting a Blob Store to a Group.

  3. When asked in the form, set the new group's Fill Policy to Write to First.

  4. Add the new blobstore that you created in step 1 to the newly promoted group blobstore underneath the original blob store.

  5. Schedule and run an Admin - Remove a member from blob store group task via Administration → System → Tasks to remove the original blob store from the group.

The original blob store's contents will be moved over to the new blob store before the original blob store is removed.

Migrating from an On-Premises Blob Store to a Cloud Blob Store Using Vendor-Provided Tools

For greatest efficiency, we recommend using your cloud vendor's tools to migrate to a cloud blob store. Before proceeding with any migration, you should back up your blob store.

Note

If you need to migrate multiple Terabytes of blob data, you should consult directly with your cloud provider for guidance to avoid prolonged downtime.

Amazon Web Services (AWS)

For migrating to Amazon S3, we suggest using a tool such as AWS DataSync. Amazon provides documentation for using DataSync to move data between other storage systems and AWS storage services.

Microsoft Azure

For migrating to Azure Blob, we suggest using Microsoft's AzCopy. Microsoft provides documentation for using AzCopy to move data to and from Azure Blob.

Google Cloud Platform

Google offers a Storage Transfer Service and provides documentation for moving data between other storage systems and GCP.

Splitting a Blob Store

Note

The Admin - Change repository blob store task is a Pro-only feature and requires a PostgreSQL or H2 database and Sonatype Nexus Repository version 3.58.0+.

  1. Determine the repositories you wish to move. (Also see this Support article Investigating Blob Store and Repository Size and Space Usage.)

  2. Create new blob store(s) (See Configuring Blob Stores).

  3. Use the Admin - Change Repository Blob Store task to move content. PRO

Adding a Soft Quota

Note

A soft quota will never block read or write operations on the blob store

When you set a soft quota, Nexus Repository monitors a blob store and raises an alert when it exceeds your configured constraint. You can configure a soft quota by following these steps:

  1. Navigate to AdministrationBlob Stores in the Nexus Repository menu.

  2. Select the blob store for which you would like to configure the soft quota.

  3. In the blob store form, check the Enable Soft Quotabox.

  4. Select the Type of Quota from the following choices available in the drop-down menu:

    1. Space Used - Issues an alert when a blob store exceeds your quota limit for total bytes used.

    2. Space Remaining - Issues an alert when the space available for new blobs drops below your quota limit.

  5. Under Quota Limit in MB, enter the number of MB at which you would like to receive an alert for the quota type you selected.

  6. Select Save.

When a soft quota is violated, that information will be available in the following locations:

  • A WARN level message in the logs.

  • Under AdministrationSupportStatus, all soft quotas' statuses are aggregated in the BlobStores status.

  • A REST API endpoint.