Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >





Overview

JFrog Cloud provides the same cutting edge functionalities of a self-hosted JFrog Platform Deployment (JPD), without the overhead of managing the databases and systems. If you are an existing JFrog self-hosted customer, you might want to move to JFrog Cloud to ease operations. JFrog provides a solution that allows you to replicate your self-hosted JPD to a JFrog Cloud JPD painlessly. 
The Artifactory Transfer solution, currently transfers the config and data of JFrog Artifactory only. Other products such as JFrog Xray and JFrog Pipelines are currently not supported by this solution.
In this page, we refer the source self-hosted instance as the source instance, and the target JFrog Cloud instance as the target instance.

Artifactory Version Support

to the target instanceThe Artifactory Transfer solution is supported for any version of Artifactory 7.x and Artifactory version 6.23.21 and above.

Page Contents

Transfer phases

The transfer process include two phases, that you must perform in the following order:

  1. Configuration Transfer: Transfers the configuration entities like users, permissions, and repositories from the source instance to the target instance.
  2. File Transfer: Transfers the files (binaries) stored in the source instance repositories to the target instance repositories.

You can do both steps while the source instance is in use. No downtime on the source instance is required while the transfer is in progress.


Limitations

The following limitations need to be kept in mind before you start the migration process

  • The Archive Search Enabled feature is not supported on JFrog Cloud.
  • System Properties are not transferred and JFrog Cloud defaults are applied after the transfer.
  • Artifacts in remote repositories caches and federated repositories are not transferred.
  • User plugins are not supported on JFrog Cloud.
  • Artifact properties longer than 2.4K characters are not supported in JFrog Cloud. Properties greater than 2.4 K characters are generally seen in Conan artifacts. The artifacts will transferred without the properties in this case. A report with these artifacts will become available to you at the end of the transfer. 
  • Artifact Cold Storage is not supported in JFrog Cloud.

Before you begin

  1. Ensure that you can login to the UI of both the source and target instances with users that have admin permissions.
  2. Ensure that the target instance license does not support less features than the source instance license.
  3. Since the files (binaries) are going to be pushed from the source instance nodes directly to the target instance, ensure the network connectivity between all the source Artifactory nodes and the target instance.
  4. Ensure that all the remote and federated repositories on the source Artifactory instance have network access to their destination URL once they are created in the target instance. Even if one remote or federated repository does not have access, the configuration transfer operation will be canceled. You do have the option of excluding specific repositories from being transferred.
  5. Ensure that all the replications configured on the source Artifactory instance have network access to their destination URL once they are created in the target instance.
  6. Ensure that you have a user that can log in to MyJFrog. For more information on MyJFrog, see MyJFrog Cloud Portal.
  7. Ensure that you can login to the primary node of your source instance through a terminal.

Running the transfer process

Perform the following steps to transfer configuration and artifacts from the source to the target instance. You must run the steps in the exact sequence and do not run any of the commands in parallel.

Step 1: Enabling configuration transfer on the target instance

By default, the target does not have the APIs required for the configuration transfer. Enabling the target instance for configuration transfer is done through MyJFrog. Once the configuration transfer is complete, you must disable the configuration transfer in MyJFrog.

  1. Log in to MyJFrog.
  2. Under the Actions menu, choose Enable Configuration Transfer.
  3. Select the acknowledgment checkbox.
    You cannot enable configuration transfer until you select the checkbox.
  4. If you have an Enterprise+ subscription with more than one Artifactory instance, select the target instance from the drop-down menu.
  5. Toggle Enable Configuration Transfer on to enable the transfer.

    Enabling the target instance for transfer might take some time.

The configuration transfer is now enabled and you can continue with the transfer process.


Step 2: Set up the source instance for pushing files to the target instance

To set up the source instance, you must install the data-transfer user plugin in the primary node of the source instance.

  1. Download data-transfer.jar from https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/[RELEASE]/lib/data-transfer.jar.
  2. Download dataTransfer.groovy from https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/[RELEASE]/dataTransfer.groovy.
  3. Connect to the primary node machine of the source instance.
  4. Place the  data-transfer.jar file under $JFROG_HOME/artifactory/var/etc/artifactory/plugins/lib.

    $JFROG_HOME usually points to the /opt/jfrog directory.
    For more information about $JFROG_HOME and the JFrog directory structure, see JFrog Product Directory Structure

  5. Place the dataTransfer.groovy file under $JFROG_HOME/artifactory/var/etc/artifactory/plugins.
  6. Run the following curl command to load the data-transfer user plugin on the source instance.

    curl -X POST <source instance URL>/artifactory/api/plugins/reload -u {USERNAME}:{PASSWORD}

Step 3: Transfer configuration from the source instance to the target instance

  1. Install JFrog CLI on the source instance machine as described here.
  2. Configure the connection details of the source Artifactory instance with your admin credentials by running the following command from the terminal.

    jf c add source-server
  3. Configure the connection details of the target Artifactory server with your admin credentials by running the following command from the terminal.

    jf c add target-server
  4. Run the transfer-config command.

    jf rt transfer-config source-server target-server

    This command might take up to two minutes to run.

    In case you do not wish to transfer all repositories, you can use the --include-repos and --exclude-repos command options. Run the following command to see the usage of these options.

    jf rt transfer-config -h
  5. View the command output in the terminal to verify that there are no errors.
    The command output is divided in to the following four phases:

    ========== Phase 1/4 - Preparations ==========
    ========== Phase 2/4 - Export configuration from the source Artifactory ==========
    ========== Phase 3/4 - Download and modify configuration ==========
    ========== Phase 4/4 - Import configuration to the target Artifactory ==========
  6. View the log to verify there are no errors.

The target instance should now be accessible with the admin credentials of the source instance. Log into the target instance UI. The target instance must have the same repositories as the source.

Step 4: Disabling configuration transfer on the target instance

Once the configuration transfer is successful, you need to disable the configuration transfer on the target instance. This is important both for security reasons and the target server is set to be low on resources while configuration transfer is enabled. 

  1. Login to MyJFrog
  2. Under the Actions menu, choose Enable Configuration Transfer.
  3. Toggle Enable Configuration Transfer to off  to disable configuration transfer.
    Disabling the configuration transfer might take some time.

Step 5: Push the files from the source to the target instance

  1. Install JFrog CLI on any machine that has access to the source JFrog instance.
    We recommend that you install JFrog CLI on a machine that has access to the the URL of your JFrog Platform instance, and not just one of the cluster nodes. This way, all the cluster nodes can share the load of pushing files to the target instance.
    Install JFrog CLI by using one of the JFrog CLI Installers. For example:

    curl -fL https://install-cli.jfrog.io | sh
  2. Configure the connection details of the source Artifactory instance with your admin credentials.
    Run the following command and follow the instructions.

    jf c add source-server
  3. Configure the connection details of the target Artifactory instance. 

    jf c add target-server
  4. Run the following command to start pushing the files from all the repositories in source instance to the target instance.

    jf rt transfer-files source-server target-server

    This command may take a few days to push all the files, depending on your system size and your network speed. While the command is running, It displays the transfer progress visually inside the terminal. It is therefore recommended not to run the command as a background process, so that you can view and monitor the progress. 


    In case you do not wish to transfer the files from all repositories, or wish to run the transfer in phases, you can use the --include-repos and --exclude-repos command options. Run the following command to see the usage of these options.

    jf rt transfer-files -h

    While the file transfer is running, monitor the load on your source instance, and if needed, reduce the transfer speed or increase it for better performance. For more information, see Read the Controlling the file transfer speed section for information on how to do this.

  5. A path to an errors summary file will be printed at the end of the run, referring to a generated CSV file. Each line on the summary CSV represents an error log of a file that failed to to be transferred. On subsequent executions of the  jf rt transfer-files command, JFrog CLI will attempt to transfer these files again.

  6. Once the jf rt transfer-files command finishes transferring the files, you can run it again to transfer files which were created or modified while the transfer. You can run the command as many times as needed. Subsequent executions of the command will also attempt to transfer files that failed to be transferred during previous executions of the command.

Read more about how the transfer files works in the this section.



How does files transfer work?

Files transfer phases

The jf rt transfer-files command pushes the files from the source instance to the target instance as follows:

  • The files are pushed for each repository, one by one in sequence.
  • For each repository, the process includes the following two phases:
    • Phase 1 pushes all the files in the repository to the target.
    • Phase 2 pushes all the files which failed to be pushed during previous command executions and also files which were created or modified after phase 1 started running (diffs).

  • If phase 1 finished running for a specific repository, and you run the jf rt transfer-files command again, only phase 2 will be triggered to complete the transfer of diffs. You can run the jf rt transfer-files as many times as needed, till you are ready to move your traffic to the target instance permanently.

Using Replication

To help reduce the time it takes for Phase 2 to run, you may configure Event Based Push Replication for some or all of the local repositories on the source instance. With Replication configured, when files are created or updated on the source repository, they are immediately replicated to the corresponding repository on the target instance.
The replication can be configured at any time. Before, during or after the files transfer process.

Files transfer state

You can run the jf rt transfer-files command multiple times. This is needed to allow transferring files which have been created or updated after previous command executions. To achieve this, JFrog CLI stores the current state of the files transfer process in a directory named transfer under the JFrog CLI home directory. You can usually find this directory at this location ~/.jfrog/transfer.
JFrog CLI uses the state stored in this directory to avoid repeating transfer actions performed in previous executions of the command. For example, once Phase 1 is completed for a specific repository, a subsequent execution of the command will skip Phase 1 and run Phase 2 only.


Installing JFrog CLI on the source instance machine

Install JFrog CLI on your source instance by using one of the JFrog CLI Installers. For example:

curl -fL https://install-cli.jfrog.io | sh

If the source instance is running as a docker container, and you're not able to install JFrog CLI while inside the container, follow these steps.

  1. Connect to the host machine through the terminal.
  2. Download the JFrog CLI executable into the correct directory by running this command.

    curl -fL https://getcli.jfrog.io/v2-jf | sh
  3. Copy the JFrog CLI executable you've just downloaded to the container, by running the following docker command. Make sure to replace <the container name> with the name of the container.

    docker cp jf <the container name>:/usr/bin/jf
  4. Connect to the container and run the following command to ensure JFrog CLI is installed

    jf -v


Controlling the file transfer speed

The jf rt transfer-files command pushes the binaries from the source instance to the target instance. This transfer can take days, depending on the size of the total data transferred, the network bandwidth between the source and the target instance, and additional factors.

Since the process is expected to run while the source instance is still being used, monitor the instance to ensure that the transfer does not add too much load to it. Also, you might decide to increase the load for faster transfer while you monitor the transfer. This section describes how to control the file transfer speed.

By default, the jf rt transfer-files command uses 8 working threads to push files from the source instance to the target instance. Reducing this value will cause slower transfer speed and lower load on the source instance, and increasing it will do the opposite. We therefore recommend increasing it gradually. This value can be changed while the jf rt transfer-files command is running. There's no need to stop the process to change the total of working threads. The new value set will be cached by JFrog CLI and also used for subsequent runs from the same machine. To set the value, simply run the following interactive command from a new terminal window on the same machine which runs the jf rt transfer-files command.

jf rt transfer-settings

Build-info repositories

When transferring files in build-info repositories, JFrog CLI limits the total of working threads to 8. This is done in order to limit the load on the target instance while transferring build-info.


Manually copying the filestore to reduce the transfer time

When your self-hosted Artifactory hosts hundreds of terabytes of binaries, you may consult with your JFrog account manager about the option of reducing the files transfer time by manually copying the entire filestore to the JFrog Cloud storage. This reduces the transfer time, because the binaries content do not need to be transferred over the network.

The jf rt transfer-files command transfers the metadata of the binaries to the database (file paths, file names, properties and statistics). The command also transfers the binaries that have been created and modified after you copy the filestore.


To run the files transfer after you copy the filestore, add the --filestore command option to the jf rt transfer-files command.


Frequently asked questions

It is expected to see sometimes significant differences between the files count on the source and target instances, after the transfer ends. These differences can be caused by many reasons, and in most cases are not an indication for an issue. For example, Artifactory may include file cleanup policies that are triggered by the files deployment. This can cause some files to be cleaned up from the target repository after they are transferred.

There's actually no need to validate that all files were transferred at the end of the transfer process. JFrog CLI performs this validation for you while the process is running. It does that as follows.

  1. JFrog CLI traverses the repositories on the source instance and pushes all files to the target instance.
  2. If a file fails to reach the target instance or isn't deployed there successfully, the source instance logs this error with the file details.
  3. At the end of the transfer process, JFrog CLI provides you with a summary of all files which failed to be pushed.
  4. The failures are also logged inside the transfer directory under the JFrog CLI home directory. This directory is usually located at ~/.jfrog/transfer. Subsequent runs of the jf rt transfer-files command use this information for attempting another transfer of the files.

Yes. The source Artifactory instance stores a checksum for every file it hosts. When files are transferred to the target instance, they are transferred with the checksums as HTTP headers. The target instance calculates the checksum for each file it receives, and then compares it to the received checksum. If the checksums don't match, the target reports this to the source, which will attempt to transfer the file again at a later stage of the process.

You can stop the command at any time by hitting CTRL+C and then run it again. JFrog CLI stores the state of the transfer process in the "transfer" directory under the JFrog CLI home directory. This directory is usually located at ~/.jfrog/transfer. Subsequent executions of the command use the data stored in that directory to try and avoid transferring files that have already been transferred in previous command executions.

  • No labels
Copyright © 2022 JFrog Ltd.