Repository Management with Nexus
6.4. Managing Routing
Routing can be considered the internal activities Nexus perform in order to determine, where to look for a specific component in a Maven repository. The routing information has an impact on the performance of component retrieval as well as determining the availability of components.
A large portion of the performance gains achievable with correct and optimized routing information is configured by Nexus itself with Automatic Routing documented in Section 6.4.1, “Automatic Routing”. Fine grained control and further customizations in terms of access provision can be achieved with some manual routing configuration documented in Section 6.4.2, “Manual Routing Configuration”.
Automatic Routing is handled by Nexus on a per repository basis. You can access the configuration and further details in the Routing tab after selecting a repository in the list accessible via Repositories item in the the Views/Repositories left hand menu.
The Routing information consists of the top two levels of the directory structure of the repository and is stored in a prefixes.txt file. It allows Nexus to automatically route only component requests with the corresponding groupId values to a repository avoid unnecessary index or even remote repository access.
Nexus generates the prefixes.txt file for a hosted repository and makes it available for remote downloads. Each deployment of a new component will trigger an update of the file for the hosted repository as well as the prefix files for any repoisitory groups that contain the hosted repository. You can access it in the Routing tab of a hosted repository as displayed in Figure 6.24, “Automatic Routing for a Hosted Repository” by clicking on the Show prefix file link on the right. In addition the Publishing section shows the Status of the routing information, a Message with further details and the date and time of the last update in the Published On field.
The Routing tab for a proxy repository displayed in Figure 6.25, “Automatic Routing for a Proxy Repository” contains the Discovery section. It displays the Status and a more detailed Message about the prefix file access. The Last run field displays the date and time of the last execution of the prefix file discovery. Such an execution can be triggered by pressing the Update now button. Otherwise the Update Interval allows you to trigger a new discovery every one, two, three, six, nine or twelve hours or as a daily or weekly execution.
For a proxy repository the prefix file is either downloaded from the remote repository or a generation is attempted by scraping the remote repository. This generation is not attempted for remote Nexus repository groups, since they are too dynamic in nature and should not be proxied directly. Scraping of hosted or proy repositories as well as svn based repositories is supported.
The generation of the prefix file in all the Nexus deployments proxying each other greatly improves performance for all Nexus instances. It lowers network traffic and load on the servers, since failing requests and serving the respective http error pages for a component that is not found is avoided for each component. Instead the regularly light weight download of the prefix file establishes a good high level knowledge of components available.
Automatic Routing is configured by Nexus automatically brings significant performance benefits to all Nexus instances proxying each other in a network and on the wider internet. It does not need to be changed apart from tweaking the update interval. To exercise even finer control than provided by Automatic Routing use Routing as documented in Section 6.4.2, “Manual Routing Configuration”.
Nexus Routes are like filters you can apply to Nexus Groups in terms of security access and general component retrieval and can reduce the number of repositories within a group accessed in order to retrieve an artifact. The administration interface for routes can be accesses via the Routing menu item in the View/Repositories menu in the left hand navigation panel.
Routes allow you to configure Nexus to include or exclude specific repository content paths from a particular artifact search when Nexus is trying to locate an artifact in a repository group. There are a number of different scenarios in which you might configure a route in Nexus.
The most commonly configured scenario is when you want to make sure that you are retrieving artifacts in a particular group ID from a particular repository. This is especially useful when you want your own organization’s artifacts from the hosted Release and Snapshot repositories only.
Routes are applicable when you are trying to resolve an artifact from a repository group; using routes allows you to modify the repositories Nexus will consult when it tries to resolve an artifact from a group of repositories.
Figure 6.26, “Routing Configuration Screen in Nexus” shows the Routing configuration screen. Clicking on a route will bring up a screen which will allow you to configure the properties of a route. The configuration options available for a route are:
- URL Pattern
This is the pattern which Nexus will use to match a request to Nexus. If the regular expression in this pattern is matched, Nexus will either include or exclude the listed repositories from a particular artifact query. In Figure 6.26, “Routing Configuration Screen in Nexus” the two patterns are:
- This pattern would match all paths which includes either "/com/somecompany/" or "/org/somecompany/". The expression in the parenthesis matches either com or org, and the ".*" matches zero or more characters. You would use a route like this to match your own organization’s artifacts and map these requests to the hosted Nexus Releases and Snapshots repositories.
- This pattern is used in an exclusive route. It matches every path that contains "/org/some-oss/". This particular exclusive route excludes the local hosted Releases and Snapshots directory for all artifacts which match this path. When Nexus tries to resolve artifacts that match this path, it will exclude the Releases and Snapshots repositories.
- Example "(?!/org/some-oss/.)."
- Using this pattern in an exclusive route allows you to exclude everything, but the "org/some-oss" project(s).
- Rule Type
- Rule Type can be either "inclusive", "exclusive" or "blocking". An inclusive rule type defines the set of repositories which should be searched for artifacts when the URL pattern has been matched. An exclusive rule type defines repositories which should not be searched for a particular artifact. A blocking rule will completely remove accessibility to the components under the specific pattern in a specified repository group.
- Ordered Route Repositories
- This is an ordered list of repositories which Nexus will search to locate a particular artifact. Nexus searches top to bottom; if it’s looking for an artifact, it will return the first match. When Nexus is looking for metadata, all repositories in a group are checked and the results are merged. The merging is applied giving preference to the earlier repositories. This is relevant when a project is looking for a LATEST or a RELEASE version. Within a Nexus Group, you should define the release repositories before the snapshot repositories, otherwise LATEST may incorrectly resolve to a snapshot version.
In this figure you can see the two dummy routes that Nexus has configured as default routes. The first route is an inclusive route, it is provided as an example of a custom route an organization might use to make sure that internally generated artifacts are resolved from the Releases and Snapshots repositories only. If your organization’s group IDs all start with com.somecompany, and if you deploy internally generated artifacts to the Releases and Snapshots repositories, this Route will make sure that Nexus doesn’t waste time trying to resolve these artifacts from public Maven repositories like the Maven Central Repository or the Apache Snapshots repository.
The second dummy route is an exclusive route. This route excludes the Releases and Snapshots repositories when the request path contains "/org/some-oss". This example might make more sense if we replaced "some-oss" with "apache" or "codehaus". If the pattern was "/org/apache", this rule is telling Nexus to exclude the internal Releases and Snapshots repositories when it is trying to resolve these dependencies. In other words, don’t bother looking for an Apache dependency in your organization’s internal repositories.
Exclusive rules will positively impact performance, since the number of repositories that qualify for locating the artifact and therefore the search effort is reduced.
What if there is a conflict between two routes? Nexus will process inclusive routes before it will process the exclusive routes. Remember that routes only affect Nexus' resolution of artifacts when it is searching a Group. When Nexus starts to resolve an artifact from a repository group it will start with the list of repositories in a group. If there are matching inclusive routes, Nexus will then take the intersection of the repositories in the group and the repositories in the inclusive route. The order as defined in the group will not be affected by the inclusive route. Nexus will then take the result of applying the inclusive route and apply the exclusive route to that list of repositories. The resulting list is then searched for a matching artifact.
One straightforward use of routes is to create a route that excludes the Central Repository from all searches for your own organization’s hosted artifacts. If you are deploying your own artifacts to Nexus under a groupId of org.mycompany, and if you are not deploying these artifacts to a public repository, you can create a rule that tells Nexus not to interrogate Central for your own organization’s artifacts. This will improve performance because Nexus will not need to communicate with a remote repository when it serves your own organization’s artifacts. In addition to the performance benefits, excluding the Central Repository from searches for your own artifacts will reduce needless queries to the public repositories.
This practice of defining an inclusive route for your internal artifacts to only hit internal repositories is a crucial best practice of implementing a secure component lifecycle management in your organization and a recommended step for initial Nexus configuration. Without this configuration requests for internal artifacts will be broadcasted to all configured external proxy repositories. This could lead to an information leak where e.g. your internet traffic reveals that your organization works on a component with the artifact coordinates of com.yourcompany.website:new-super-secret-feature:1.0-SNAPSHOT.
In addition to defining inclusive and exclusive routes, you can define blocking routes. A blocking route can be created by creating a route with no repositories in the ordered list of repositories. It allows you to completely block access to artifacts with the specified pattern(s) from the group. As such blocking routes are a simplified, coarse grained access control.
Check out Chapter 9, Nexus Procurement Suite for fine grained control of artifact availability and use blocking routes sparingly.
To summarize, there are creative possibilities with routes that the designers of Nexus may not have anticipated, but we advise you to proceed with caution if you start relying on conflicting or overlapping routes. Use routes sparingly, and use coarse URL patterns. Remember that routes are only applied to groups, routes are not used when an artifact is requested from a specific repository.