JFrog Distribution enables creating and distributing release bundles from any Artifactory service to which it is connected through JFrog Mission Control. Each release bundle may only contain artifacts from a single Artifactory service.
To create a release bundle, Distribution runs queries against Artifactory in order to retrieve the required artifact references and properties. Only those artifacts to which the triggering user has access can be collected into the release bundle.
To prevent tampering with the release bundle, it is signed by JFrog Distribution using a GPG key. The same GPG key is then used by the Artifactory Edge to validate the release bundle before it is accepted.
Release bundles can be created using the REST API or through the JFrog Distribution UI. In either case, you define the artefacts to be included in the release bundle through a set of queries you can define.
Creating a release bundle requires Release Bundle write permissions.
A Release Bundle version can include up to 3,000 artifacts. This number is not limited in the product, but exceeding it is highly unrecommended. |
You can create release bundles using the Create Release Bundle Version REST API call.
To create a new release bundle:
The Release Bundle page is divided into three panels: General Details, Spec and Release Notes.
General Details:
Name | The release bundle name. |
Version | The release bundle version. |
Description | The release bundle description. |
Spec:
This section specifies the Artifactory service from which the release bundle will be assembled (remember, a release bundle can only be assembled from a single Artifactory service), and the different queries that will be used to assemble the artifacts. For more details on how to define the queries, please refer to Adding a Query.
Source Artifactory | The source Artifactory service from which artifacts will be gathered. |
Name | The query name. |
Query | The query details. |
Release Notes:
This section specifies release notes for the release bundle.
Type | The release notes format. Supported types include: Markdown, Asciidoc and plain text. |
Edit | Preview | Use these links to edit the release notes in your selected format and then preview how they will look once rendered. |
There are two ways to build a query: Using AQL and using a simple query builder.
To select the way you want to build your query, hover over Create Query.
To add an AQL query, under Create Query, select Add AQL Query.
This will launch a 3-step wizard.
In the Query Details step, give your query a name and provide the AQL expression to use for assembling the artifacts.
The query builder lets you build your query by filling a simple form. The parameters you enter are eventually translated into an AQL query which you can view by setting the Show AQL checkbox at the end of the form.
To use the query builder, under Create Query, select Add Query
This will launch a 3-step wizard.
In the Query Details step, start by giving your query a name. You can then specify different search criteria including:
Note that you can specify multiple values for each of these parameters by clicking the '+' button to the right of the parameter.
Using the And | Or options you can add multiple properties in a single click of a button.
After specifying your query details (whether using an AQL query or the query builder), you can view the artifacts that will be included in your release bundle under the Preview Artifacts tab.
To prevent artifacts with issues or vulnerabilities from being delivered to their target Artifactory services, release bundles that contain artifacts which have been blocked for download by JFrog Xray due to a Security Rule or a License Rule, can not be signed, and consequently, can not be distributed. If the query you used to select the artifacts for a release bundle pulls in a blocked artifact, the artifact will be included in the release bundle, and the Xray Status column will indicate that it has been blocked. An attempt to sign this release bundle will fail and Distribution will display an error message. If the artifact ceases to be blocked for download, you need to run the query that pulls the artifact into the release bundle again, so the indication that it is blocked is removed. Once the "Blocked" indication is removed, the release bundle can be signed and distributed. |
Note that if the source or target Artifactory service specified for the release bundle does not have a correct and valid license, Distribution will display an error.
The Additional Details tab lets you specify two more parameters for your release bundle:
Additional Properties | Specify a list of properties which will be attached to all artifacts in your release bundle during the distribution process, in addition to those that they already have. |
Path Mappings | Specify a list of mappings to govern where artifacts will be placed in your target Artifactory service according to their location in your source Artifactory service. You may use any of the Path Mapping Templates provided, or set up custom mappings of your own. |
As a convenience, JFrog Distribution provides a set of commonly used templates you can use to set up your path mappings. Simply select one of the templates listed under Use Template, and then modify the placeholders to correspond with your setup.
The templates provided are:
Change Repository | All files in a specific repository on the source Artifactory service are mapped to a different repository on the target. |
Change Folder | All files are moved to a specific folder in the target. |
Rename Folder | All files in a specific folder on the source Artifactory service are mapped to a different folder on the target. |
From Distribution 1.8.0, as part of creating a new Release Bundle, it is sufficient to specify query criteria that will match the manifest.json of the desired docker image. Distribution will include all the Docker layers of the Docker image associated with that manifest.json file. For example, we have a Docker image of a PostgreSql version 11.1 in a Docker repository called
The docker.manifest.digest All the other files under To include all the artifacts in the image (manifest and layers) it is sufficient to specify a query criteria that will match the
|
The Release Bundle module allows you to view all release bundles managed by JFrog Distribution in one place.
Name | The release bundle name. |
Latest Version | The release bundle latest version. |
Distribution ID | The sequential number of the distribution job. Only the last 3 distribution jobs are displayed. |
Status | The distribution job status. |
Edge Nodes | The edge nodes distribution progress percentage. |
To view a single release bundle, click on it from the Release Bundle module.
The Release Bundle page displays three panels of information:
Versions: The list of versions of this release bundle. Select any version to view its details.
General Info: The panel along the top of the screen displays general information such as the version, description, creation date, status and size of the release bundle
Details: This panel displays details about the selected release bundle version in a series of tabs: Content, Release Notes, Distribution Tracking, and Spec.
These are described below:
The Content tab displays the artifacts, builds and metadata that comprise the release bundle.
Click on any artifact or build to view details about it in the right panel in the tab.
Click on an artifact's source path to be redirected to the right location in the tree browser of the corresponding Artifactory service. |
If the artifact has been blocked for download by JFrog Xray (in which case, you will not be able to sign and distribute the release bundle), this will be indicated in the Xray Status field for the selected artifact in the Content tab.
The Release Notes tab displays release notes for the bundle. These can be written in markdown, asciidoc or plain text.
The Distribution Tracking tab provides a history for this release bundle version.
ID | The ID of the distribution action.
| |
Action | The action that was performed | |
Started | The date and time at which the action started | |
Destination | The distribution target
| |
Status | The status of the action | |
Progress | The percent completion of the action and number of attempts at completion | |
Details | Summary of some details about the action.
|
Distributing a release bundle may fail for different reasons such as network issues or outage of a target Artifactory service. Once you have remediated the problem preventing distribution, you can redistribute the release bundles to the services where distribution failed. To redistribute release bundles, first select them. Distribution presents a Redistribute icon for each distribution selected. You can now click that icon to redistribute each release bundle individually to the specified target service, or select the Redistribute button at the top of the list to redistribute the release bundle to all target services selected in a batch process.
Use the Filter to display only those distributions that have failed. |
The Spec tab displays the source Artifactory service from which the artifacts of this release bundle were assembled as well as the list of queries that assembled the artifacts.
Clicking on the Artifactory service opens a new tab on the home screen of that service |
Clicking on any of the queries expands it displaying the details of the query that governed the assembly of the release bundle artifacts.
You can even check the AQL checkbox to see the final AQL query that was used to assemble the artifacts.
Signing a release bundle finalizes the process of creating a release bundle. This sets the release bundle status to Signed and the release bundle can no longer be edited.
In addition, Distribution will trigger the source Artifactory to clone the contents of the signed release bundle into an isolated release-bundles repository.
Click Sign.
If the release bundle includes any artifacts that have been blocked for download by JFrog Xray, your attempt to sign the release bundle will fail, and Distribution will display an error message. Consequently, you will not be able to distribute this release bundle. |
To clone an existing release bundle version, select Clone Version from the Actions drop down menu.
This will copy the release bundle spec, including its name and queries, into a new release bundle page. Details on the page can then be adjusted and saved accordingly.
When creating a release bundle, the artifact properties are fetched from Artifactory into the release bundle. Additional custom properties can be added during the initial release bundle version creation using the Create Release Bundle REST API. These properties are transferred over to the Edge Node as part of the distribution process.
Once you have created your release bundle, you can distribute it to the Artifactory Edge Nodes that you are privileged to distribute to.
Distribution can only distribute release bundles from an Artifactory service to an Artifactory Edge Node if they are both within the same circle of trust. To learn how to establish a circle of trust, please refer to Cross-Instance Authentication in the JFrog Access User Guide. |
Distribution is responsible for triggering the replication process that happens from the source Artifactory to the Edge Nodes. First, it replicates the release bundle info to each Edge Node, and then initiates the replication process in the source Artifactory.
To distribute your release bundle, click "Distribute" from the Release Bundle module, or use the Distribute Release Bundle REST API.
Distribution fetches the available Edge Nodes from Mission Control, and displays a list of the available Edge Nodes according to the specific user permissions.
To distribute an older version of your release bundle, click on it from the Release Bundle module, select on the version you want to distribute, and click "Distribute".
You can delete release bundles using the Distribution UI or the Delete Release Bundle REST API call. Available for users with Release Bundle delete permissions.
To delete an existing release bundle version, select Delete from the Actions drop down menu.
There are 2 types of delete options:
To search for release bundles in an Artifactory Edge node, you can use the release and release_artifact domains introduced to AQL in Artifactory 6.0. For details, please refer to Entities and Fields.