Upgrading Staging
This topic provides Nexus Repository administrators valuable information about the change in staging implementation between Nexus Repository 2 and 3 as well as guidance on migrating your data and processes. For detailed information on using the staging feature in Nexus Repository 3, see the Staging topic.
Staging in Nexus Repository 2 vs. Nexus Repository 3
In Nexus Repository 2, staging is done through the staging suite; in Nexus Repository 3, staging is done through tagging and REST API calls. This difference means that upgrading from Nexus Repository 2 to 3 lets you go from a dynamic repo-based model to a tag-based model.
When designing staging in Nexus Repository 3, the Sonatype Nexus Repository team had a chance to look for areas of improvement in Nexus Repository 2 and then develop the new staging feature to mitigate these issues.
Some of the issues identified in Nexus Repository 2 staging were as follows:
It only works for the Maven2 format.
Deployment/approval workflows are increasingly external to Nexus Repository.
It doesn’t scale. Failing to apply proper housekeeping controls means there can be 1000’s of repositories, leading to significant performance problems in Nexus Repository 2.
It’s easy to lose track of build identity after promotion (the staging repo goes away).
The Nexus Repository team worked to resolve these issues and develop features in Nexus Repository 3 that let you do the following:
Administer access control to in-house components at different phases of the SDLC. Components can be restricted until fully tested.
Store components in a single hosted repository for each stage, while identifying individual builds and managing retention periods by stage.
Move components between release stages using the REST API.
Associate custom metadata to builds as components are uploaded to the repository.
Manage workflows with external CI/CD tools.
A side by side comparison:
Staging in Nexus Repository 2 | Staging in Nexus Repository 3 |
|---|---|
Workflow defined in Nexus Repository 2 | Workflow defined externally (i.e., Jenkins) |
Each build is a separate repository | Each build is a tag |
Hundreds of repositories accumulate | Small, fixed number of repositories |
Builds are absorbed into release repo | Build metadata outlives promotion |
UI-driven | Powered by REST, no UI |
Maven2 only | Maven2, raw, Docker, npm, Nuget, YUM |
Rules defined in Nexus Repository 2 | Rules invoked externally by CI/CD |
“Staging” is a feature | Toolkit APIs used to build staging |
Due to the extent to which we redesigned staging in Nexus Repository 3, it is not compatible with Nexus Repository 2 staging. Nexus Repository 3 staging provides a set of flexible building block capabilities that can be combined and arranged as needed to accommodate your organization’s software build and release pipeline. The set of REST endpoints that expose these capabilities allow for easy integration into CI/CD systems, and are easily customized to the workflows or client tooling and technologies needed to interact with them.
Benefits of Tagging and Staging in Nexus Repository 3
There are several advantages to upgrading to Nexus Repository 3:
Flexible Workflow
Staging is a set of powerful REST endpoints that are highly customizable to your environment. This new implementation makes build deployment configuration more flexible for teams as they expand beyond CI server usage to the staging repository and the ability to dynamically select builds for promotion.
Staging for Nexus Repository 3 also helps empower teams to take control of the build deployment process using advanced metadata capabilities. This includes deciding how the metadata changes along the release workflow, as well as how to isolate the right builds for the right teams.
Tags
Staging also works closely together with our tagging feature. In Nexus Repository Pro, staging works by moving components across hosted repositories. For instance, you could have hosted repositories for development, UAT, and production. You can then promote software components matching your organization’s software development lifecycle phases by moving components between these hosted repositories. This is where the tagging feature comes in. Tagging in Nexus Repository 3 is more powerful because you can easily group multiple builds and promote them as if they were a single unit.
For example, a complex project like Nexus Repository has thousands of files and all sorts of components that go into a build. The Nexus Repository teams needs a way to take all of these components that span multiple different coordinates and group them together in a way that lets us know it’s a single build. You can use the tagging REST endpoints to create and delete tags, list all tags, and attach metadata to tags. This is the Nexus Repository 3 equivalent to custom metadata.
As you can see from the example above, using tags provides a way to group and move your artifacts. Nexus Repository 3 provides several means for tagging, which usually happens on upload, but can also be done after upload as well. You can tag components with your automated CI/CD processes using the Jenkins Platform plugin. Alternatively, you can also tag components during upload within the UI.
Path from Nexus Repository 2 to 3
Now that you understand how staging in Nexus Repository 3 works, the next step is redefining your process from Nexus Repository 2 to the new instance. Upgrading to Nexus Repository 3 will give you a staging feature with a set of extremely configurable building blocks that can be adapted to your organization’s needs.
Although there is no direct upgrade path from Nexus Repository 2 to 3, this section will go over some steps you can take to get started.
A basic setup workflow for staging in Nexus Repository 3 might look something like this:
Ensure that your upgrade from Nexus Repository 2 to Nexus Repository 3 is complete.
Identify the staging workflow from your Nexus Repository 2 configuration.
Create matching hosted repos in Nexus Repository 3.
Incorporate the stages of your agile software development lifecycle into the Nexus Platform Plugin for Staging.
Add a tagging call to the build.
Update the Nexus Repository 2 Maven calls to the Nexus Repository 3 REST calls.
Associate custom metadata to tags. Custom information is an extension of tagging. See Viewing Tags for more info.
Use the Move REST API endpoint to promote tagged components among the hosted repos.
Use the Delete REST API endpoint to delete tagged components among the hosted repos.
Run a cleanup task to delete tags you no longer need.
The above steps represent a basic scenario. Our REST APIs give you a lot of flexibility to make this more robust and well integrated into your CI/CD pipeline.
For more information on our staging workflow, please see the staging and tagging topics in our help documentation.
Best Practices and Troubleshooting
Although migration from Nexus Repository 2 staging to Nexus Repository 3 staging is not supported, there are a few things you can do to make the move easier. Here are a few ideas to help you make the switch:
Keep in mind that this is an opportunity to start fresh with a new set of features that are compatible with modern CI/CD pipelines.
Review what worked in Nexus Repository 2 staging and what didn’t. This can help you determine what needs to be implemented similarly and where there are areas for improvement.
For example, you may need to keep your Nexus Repository 2 staging repos for data retention purposes. These types of requirements should be taken into account.
When you upgrade, any “in flight” staging repositories in Nexus Repository 2 are not migrated. This means upgraded components in a build promotion repo or staging repo are not moved. This is an important setup step that should be thought about prior to upgrade.
Get familiar with concepts and terminology, such as the following:
Tag names are a string (or label) that are the primary key for what gets “staged.”
Metadata is extra information.
You cannot stage or create permissions based on metadata.
Invest your time in establishing a strategy for naming tags and your management approach for tags. For example, think about things like the following:
Will tags be used? (This may depend on your organization’s approach to naming builds and repos.)
How will tags be routinely aged off?
What is the best way to implement tag creation and assignment to your artifacts?
Keep in mind the benefits of staging in Nexus Repository 3:
You can control who can see in-house components at different parts of the SDLC, so they aren’t used before they’re ready.
You can batch components together and easily identify builds.
Stagings REST APIs are powerful and flexible.
You can control the workflow from your CI/CD pipeline.
The “toolkit” style implementation means it supports other use cases.
Maven and Jenkins integration (e.g., automatically tested, manually tested, signed, approved, etc.).