{inrmonly}
The Procurement Suite of {pro} provides an organization with control over what components are allowed into a repository from an external, proxied repository such as the Central Repository. Such control can be a prerequisite for organizations unwilling or unable to trust the entire contents of an external public repository. If an organization is developing mission critical code, they will likely want to subject every third party dependency to intense scrutiny and testing before making the component available to build a release or support a team of developers. In most Enterprise development environments, a developer can’t just decide to add in a new dependency to Hibernate or to the Spring Framework on a whim; the decision to add dependencies to third-party libraries will need to be funnelled through an oversight process that relies on an architect or an administrator to promote components to a certified release repository.
Another more common experience is an organization that needs to proxy like the Central Repository or any other public repository, but wants to limit access to specific versions of components or prevent dependencies on all components contained under a specific group. Some organizations are more amenable to trusting the contents of a remote, proxied repository like the Central Repository, but they also need the ability to block certain dependencies. Maybe you work on a team that needs to limit access to dependencies with a certain license, or maybe you just want to make sure no one uses a problematic version of Hibernate with a known bug? The procurement suite is the tool that provides for both coarse and fine-grained control of the components that can appear in a repository.
A procured repository is a hosted Repository that procures components from a Proxy Repository while procurement is enabled. For example, one could create a hosted repository named "Approved From Central" and then configure this hosted repository to procure components from the "Central" repository. Once the hosted repository has been created and the source of procurement has been configured, the repository will obtain components from the proxy repository as long as procurement is activated. If you start procurement for a hosted repository, the hosted repository will fetch components from the proxy repository specified in the procurement settings. If you stop procurement for a hosted repository, no additional components will be retrieved from the proxy repository specified in the procurement settings. Without procurement active it is a hosted repository and therefore completely static.
The ability to enable or disable procurement for a hosted repository comes in very handy when you want to "certify" a hosted repository as containing all of the components (no more and no less) required for a production build. You can start procurement, run a build that triggers component procurement, and then stop procurement, knowing that the procured repository now contains all of the components required for building a specific project. Stopping procurement assures you that the contents of the repository will not change if the third-party, external proxied repository does. This is an extra level of assurance that your release components depend on a set of components under your complete control.
There are two main use cases for the Procurement Suite. In the first use case, the 'Procured Release Repository', the procurement features are used to create a procured release repository to make sure that the organization has full control over the components that are making it into a production release. The other use case, the 'Procured Development Repository', is for organizations that need more up-front control over which components are allowed during the development of a project. The following sections describe these two uses cases in more detail.
The Procurement Suite can be used in two different ways. In the "Procured Release" mode, developers work with a proxied third-party repository exactly as they would without the Procurement Suite. When a developer needs to add a dependency on a new component, the repository manager will retrieve the component from the third-party repository (like Central or Apache Snapshots) and this component will be served to Maven via a proxied repository. When a QA or Release engineer needs to build a release or staging component, the Release or QA build would be configured to execute against a procured repository or repository group with only approved and procured repositories. A procured repository is one that only serves the components that have been explicitly approved using the Procurement Suite.
In this model, developers can add as many third-party dependencies as they want, and it is the responsibility of the QA and release engineers to approve (or procure) components from the development Repository to the QA/Release repository. Developers can move forward, adding dependencies freely from a third-party, proxied repository, but once it is time to populate a release repository, an administrator can audit the required components, create a hosted repository, turn on procurement, populate the repository, and then deactivate procurement. This has the effect of "locking down" the components that are involved in a production release.
There are some development environments that require even more control over which components can be used and referenced by developers. In these situations, it might make sense to only allow developers to work with a procured repository. In this mode, a developer must ask an administrator for permission to add a dependency on a particular third-party component. A procurement manager would then have to approve the component or group of components so that they would be made available to the developers. This is the "ask-first" model for organizations that want to control which components make it into the development cycle.
This is a model common in industries that have strict oversight requirements. More often than not, banks, hospitals, and government agencies have fairly strict regulations on the software that can be used by large development teams. With the Procured Development Repository approach, an architecture group can have full control over what components can be referenced by a large development team.
In a typical usage a software build relies on approved components that have successfully passed procurement and additional components that have been authored internally in the organization and are available on the repository manager as well.
In order to use a combination of such components together with the procured component, you should set up a repository group that contains all repositories with preapproved components as well as the procurement repository. For example, the release and snapshot repositories could be added to the group, based on the assumption that any internally authored components deployed there are automatically approved. In addition, you could add the third-party repository, if all uploads to it are done with prior approval of the specific components.
Once this repository group is set up, you can reference it from any tool just like the public group, e.g., in a separate settings.xml used by builds that can only have access to the approved components.
|
Tip
|
When running builds you need to make sure that you run to run clean builds. No components from other builds, accessing non-procured repositories, should be in the local repository of the build. This ensures that only approved components are used in the build. The easiest way to achieve this is to clear the local repository before a build or to run the build against a project specific local repository. |
If you installed {pro}, the procurement Suite is already installed and available via the 'Artifact Procurement' option in the 'Enterprise' menu of the user interface.
This section will walk through the process of creating and configuring a hosted repository named 'Approved From Central' which will be procured from the 'Central' proxy repository. Setting up a procured repository consists of the following steps:
-
Enable the remote index downloads for the proxy repository, that will act as the source of the procured components.
-
Create a hosted repository, which will be the target of the procurement.
-
Configure procurement for the hosted repository.
-
Configure the procurement rules.
Before configuring a procured repository, you need to make sure that you have enabled Remote Index downloading for the proxied repository that will serve as the source for your procured repository.
|
Note
|
If you are attempting to procure components from a remote repository that does not have a repository index, you can still use the procurement suite. Without a remote repository index, you will need to configure procurement rules manually without the benefit of the already populated repository tree shown in Configuring Procurement. |
When you configure procurement rules for a hosted repository, the administrative interface displays the repository as a tree view using the Maven repository format of the of groups and components using populated from remote repository’s index. {nxrm} ships with a set of proxy repositories, but remote index downloading is disabled by default.
To use procurement effectively, you will need to tell {pro} to download the remote indexes for a proxy repository. Click on 'Repositories' under 'Views/Repositories' in the main menu, then click on the 'Central Repository' in the list of repositories. Click on the 'Configuration' tab, locate 'Download Remote Indexes', and switch this option to 'True' as shown in Enabling Remote Index Downloads for a Proxy Repository.
Click on the 'Save' button in the dialog shown in Enabling Remote Index Downloads for a Proxy Repository. Right-click on the repository row in the Repositories list and select 'Update Index'. The repository manager will then download the remote repository index and recreate the index for any repository groups that contain this proxied repository.
The repository manager may take a few minutes to download the remote index for a large repository. Depending on your connection to the Internet, this process can take anywhere from under a minute to a few minutes. The size of the remote index for the Central Repository currently exceeds 50MB and is growing in parallel to the size of the repository itself.
To check on the status of the remote index download, click on 'System Feeds' under 'Views/Repositories' in the main menu. Click on the last feed to see a list of 'System Changes in Nexus'. If you see a log entry like the one highlighted in Verification that the Remote Index has been Downloaded, the repository manager has successfully completd the download of the remote index from the Central Repository.
When you configure procurement you are establishing a relationship between a proxy repository and a hosted repository. The hosted repository will be the static container for the components, while the proxy repository acts as the component source. To create a hosted repository, select 'Repositories' from the 'Views/Repositories' section of the main menu, and click on the 'Add' button selecting 'Hosted Repository' as shown in Adding the "Approved From Central" Hosted Repository.
Selecting 'Hosted Repository' will then load the configuration form. Create a repository with a 'Repository ID' of approved-from-central and a name of Approved From Central. Make the release policy Release. Click the 'Save' button to create the new hosted repository.
At this point, the list of Repositories will have a new Hosted repository named +Approved From Central=. The next step is to start procurement for the new repository. When you do this, you are establishing a relationship between the new hosted repository and another repository as source of components. Typically, this source is a proxy repository. In this case, we’re configuring procurement for the repository and we’re telling the Procurement Suite to procure components from the 'Central' proxy repository. To configure this relationship and to start procurement, click on 'Artifact Procurement' under the 'Enterprise' menu. In the 'Procurement' panel, click on 'Add Procured Repository' as shown in Adding a Procured Repository.
You will then be presented with the Start Procurement dialog as shown in Configuring Procurement for a Hosted Repository. Select the "Central" proxy repository from the list of available Source repositories.
Procurement is now configured and started. If you are using an instance of {pro} installed on localhost port 8081, you can configure your clients to reference the new repository at http://localhost:8081/nexus/content/repositories/approved-from-central.
By default, all components are denied and without further customization of the procurement rules no components will be available in the new repository.
One interesting thing to note about the procured repository is that the repository type changed once procurement was started. When procurement is activated for a hosted repository, the repository will not show up in the repositories list as a 'User Managed Repository'. Instead it will show up as a proxy repository in the list of 'Nexus Managed Repositories'. Use the drop-down for 'User Managed/Nexus Managed Repositories' in the Repositories list. Click Refresh in the Repositories list, and look at the 'Approved From Central' repository in the list of Nexus Managed Repositories. You will see that the repository type column contains proxy as shown in Hosted Repository is a Nexus Managed Proxy Repository while Procurement is Active. When procurement is started for a hosted repository, it is effectively a proxy repository, and when it is stopped it will revert back to being a normal hosted repository.
Once you’ve defined the relationship between a hosted repository and a proxy repository and you have started procurement, you can start defining the rules that will control which components are allowed in a procured repository and which components are denied. You can also start and stop procurement. This section details some of the administration panels and features that are available for a procured repository.
A procurement rule is a rule to allow or deny the procurement of a group, component, or a collection of groups or components. You load the Artifact Procurement interface by selecting Artifact Procurement in the Enterprise menu of the left-hand navigation. Clicking on this link will load a list of procured repositories. Clicking on the repository will display the proxied source repository and the current content of the procured repository in a tree as shown in Viewing a Repository in the Artifact Procurement Interface.
This section will illustrate the steps required for blocking access to a specific component and then selectively allowing access to a particular version of that same component. This is a common use case in organizations that want to standardize specific versions of a particular dependency.
|
Note
|
If you are attempting to procure components from a remote repository that does not have a repository index, you can still use the procurement suite. Without a remote repository index, you will need to configure procurement rules manually without the benefit of the already populated repository tree shown in this section. |
The directory tree in Viewing a Repository in the Artifact Procurement Interface is the index of the proxy repository from which components are being procured.
To configure a procurement rule, right-click on a folder in the tree. Applying a Rule to a Component Folder for org/elipse/aether displays the procurement interface after right-clicking on the org/eclipse/aether component folder.
In this dialog, we are deciding to configure a rule for everything within the group and its sub groups that display the rule configuration dialog displayed in Approving org.eclipse.aether Components. The dialog to add rules allows you to select the available rule, e.g., a Forced Approve/Deny Rule, and configure the rule properties. The displayed dialog approves all components Eclipse Aether components.
By right-clicking on the top level folder of the repository, as displayed in Accessing the Global Repository Configuration, you can configure rules for the complete repository as well as access all configured rules via the 'Applied Rules' option.
This allows you to set up a global rule, like blocking all components from the repository. Once you have configured this you can then selectively allow specific versions of a component. Procurement Configurations Options for a Specific Component Version displays the options available for configuring rules for a specific component version of the Apache Commons Collections component.
Once you approve a specific version, the tree view will change the icons for the component displaying green checkmarks for approved components and red cross lines for denied components as visible in Procurement Repository Tree View with Rule Visualization. The icons are updated for signature validation rule violations, if applicable, showing a yellow icon.
An example dialog of Applied Rules for the complete repository, as configured by '::*', is visible in Applied Rules for the Complete Procurement Repository. This repository currently denies access to all components, only approving components within 'org/apache/maven' and 'org/eclipse/aether''.
This dialog gives the procurement administrator a fine-grained view into the rules that apply to the complete repository. A view of all Applied Rules for a specific repository folder can be access by right-clicking on the folder and selecting Applied Rules. The dialog allows you to remove specific rules or all rules as well.
The 'Refresh' button above the tree view of a repository tree view allows you to update the tree view and to see all of the applied rules. The 'Add Freeform Rule' button allows you to display the dialog to manually configure a procurement rule displayed in Adding a Freeform Rule. This is especially useful if the tree view is not complete due to a missing repository index or if you have detailed knowledge of the component to which you want to apply a rule. The format for entering a specific component in the 'Enter GAV' input field is the short form for a Maven component coordinate using the groupId, artifactId and version separated by ':'. The '*' character can be used as a wildcard for a complete coordinate.
Examples for freeform rule coordinates are:
::*-
matches any component in the complete repository
org.apache.ant:*:*-
matches any component with the groupId org.apache.ant located in org/apache/ant
org.apache.ant.::*-
matches any component with the groupId org.apache.ant located in org/apache/ant as well as any sub-groups e.g., org.apache.ant.ant
These coordinates are displayed in the Maven build output log when retrieving a component fails. You can see them as part of the error message with the addition of the packaging type. It is therefore possible to cut and paste the respective coordinates from the build output and insert them into a freeform rule. Once you have done that you can kick off the build again, potentially forcing downloads with the option -U and continue procurement configuration for further components.
Some organizations may want to lock down the components that a release build can depend upon. It is also a good idea to make sure that your build isn’t going to be affected by changes to a repository not under you control. A procurement administrator can configure a procured repository, start procurement, and run an enterprise build against the repository to populate the procured, hosted repository with all of the necessary components. After this process, the procurement administrator can stop procurement and continue to run the same release build against the hosted repository that now contains all of the procured components while being a completely static repository.
To stop procurement, go to the procurement management interface by clicking on 'Artifact Procurement' under the 'Enterprise' section of the menu. Right-click on the repository and choose 'Stop Procurement' as shown in Stopping Procurement for a Procured Repository.
After choosing 'Stop Procurement', you will then see a dialog confirming your decision to stop procurement. Once procurement is stopped, the procured repository will revert back to being a hosted repository.
In order to add further components, you create a procurement repository off the hosted repository as you did initially. If the repository contains components already, activating procurement will automatically generate rules that allow all components already within the repository.