doc/user/topics/arv-copy.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Using arv-copy"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 This tutorial describes how to copy Arvados objects from one cluster to another by using @arv-copy@.
  13
  14 {% include 'tutorial_expectations' %}
  15
  16 h2. arv-copy
  17
  18 @arv-copy@ allows users to copy collections, workflow definitions and projects from one cluster to another.  You can also use @arv-copy@ to import resources from HTTP URLs into Keep.
  19
  20 For projects, @arv-copy@ will copy all the collections workflow definitions owned by the project, and recursively copy subprojects.
  21
  22 For workflow definitions, @arv-copy@ will recursively go through the workflow and copy all associated dependencies (input collections and Docker images).
  23
  24 For example, let's copy from the <a href="https://playground.arvados.org/">Arvados Playground</a>, also known as *pirca*, to *dstcl*. The names *pirca* and *dstcl* are interchangable with any cluster ID. You can find the cluster ID from the prefix of the UUID of the object you want to copy. For example, in <notextile><code><strong>zzzzz</strong>-4zz18-tci4vn4fa95w0zx</code></notextile>, the cluster name is *zzzzz*.
  25
  26 In order to communicate with both clusters, you must create custom configuration files for each cluster.  The "Getting an API token":{{site.baseurl}}/user/reference/api-tokens.html page describes how to get a token and create a configuration file.  However, instead of creating the default @~/.config/arvados/settings.conf@ you need two configuration files, one for each cluster, with filenames in the format of <notextile><code><strong>ClusterID</strong>.conf</code></notextile>. For this example, follow these steps:
  27
  28 {% include 'notebox_begin' %}
  29 @arv-copy@ searches for configuration files following the XDG Base Directory Specification. This is uncommon, but if you have customized the @XDG_CONFIG_HOME@ environment variable, save both configuration files under @$XDG_CONFIG_HOME/arvados/@ instead of the default @~/.config/arvados/@ shown below.
  30 {% include 'notebox_end' %}
  31
  32 # Open the "Arvados Playground Workbench":https://playground.arvados.org.
  33 # On the system where you'll run @arv-copy@, start a new file named @~/.config/arvados/pirca.conf@ in your editor.
  34 # In Workbench, open the user menu in the upper right, and select "Get API token."
  35 # In the Workbench "Get API Token" dialog, under the "API Host" header, copy the value to your clipboard using the button.
  36 # In your editor, write the text @ARVADOS_API_HOST=@, then paste the "API Host" value you copied in the previous step, and start a new line.
  37 # In the Workbench "Get API Token" dialog, under the "API Token" header, copy the value to your clipboard using the button.
  38 # In your editor, write the text @ARVADOS_API_TOKEN=@, then paste the "API Token" value you copied in the previous step, and start a new line.
  39 # Review your work. In your editor, @pirca.conf@ should look like this, with a different value for @ARVADOS_API_TOKEN@:
  40   <pre><code>ARVADOS_API_HOST=pirca.arvadosapi.com
  41 ARVADOS_API_TOKEN=v2/jutro-gj3su-12345abcde67890/abcdefghijklmnopqrstuvwxyz1234567890
  42 </code></pre> If it looks right, save and close the file.
  43 # Open Workbench for your destination cluster *dstcl*.
  44 # On the system where you'll run @arv-copy@, start a new file named <notextile><code>~/.config/arvados/<b>dstcl</b>.conf</code></notextile> in your editor. Replace *@dstcl@* in the filename with the actual cluster ID of your destination cluster.
  45 # Repeat steps 3-8 to create a settings file with credentials for *dsctl*.
  46
  47 h3. How to copy a collection
  48
  49 First, determine the UUID or portable data hash of the collection you want to copy from the source cluster. The UUID can be found in the collection display page in the collection summary area (top left box), or from the URL bar (the part after @collections/...@)
  50
  51 Now copy the collection from *pirca* to *dstcl*. We will use the UUID @jutro-4zz18-tv416l321i4r01e@ as an example. You can find this collection on <a href="https://playground.arvados.org/collections/jutro-4zz18-tv416l321i4r01e">playground.arvados.org</a>.
  52 <notextile>
  53 <pre><code>~$ <span class="userinput">arv-copy --src pirca --dst dstcl jutro-4zz18-tv416l321i4r01e</span>
  54 jutro-4zz18-tv416l321i4r01e: 6.1M / 6.1M 100.0%
  55 arvados.arv-copy[1234] INFO: Success: created copy with uuid dstcl-4zz18-xxxxxxxxxxxxxxx
  56 </code></pre>
  57 </notextile>
  58
  59 You can also copy by content address:
  60
  61 <notextile>
  62 <pre><code>~$ <span class="userinput">arv-copy --src pirca --dst dstcl 2463fa9efeb75e099685528b3b9071e0+438</span>
  63 2463fa9efeb75e099685528b3b9071e0+438: 6.1M / 6.1M 100.0%
  64 arvados.arv-copy[1234] INFO: Success: created copy with uuid dstcl-4zz18-xxxxxxxxxxxxxxx
  65 </code></pre>
  66 </notextile>
  67
  68 The output of arv-copy displays the UUID of the collection generated in the destination cluster. By default, the output is placed in your home project in the destination cluster. If you want to place your collection in an existing project, you can specify the project you want it to be in using the tag @--project-uuid@ followed by the project UUID.
  69
  70 For example, this will copy the collection to project @dstcl-j7d0g-a894213ukjhal12@ in the destination cluster.
  71
  72 <notextile> <pre><code>~$ <span class="userinput">arv-copy --src pirca --dst dstcl --project-uuid dstcl-j7d0g-a894213ukjhal12 jutro-4zz18-tv416l321i4r01e
  73 </code></pre>
  74 </notextile>
  75
  76 Additionally, if you need to specify the storage classes where to save the copied data on the destination cluster, you can do that by using the @--storage-classes LIST@ argument, where @LIST@ is a comma-separated list of storage class names.
  77
  78 h3. How to copy a workflow
  79
  80 Copying workflows requires @arvados-cwl-runner@ to be available in your @$PATH@.
  81
  82 We will use the UUID @jutro-7fd4e-mkmmq53m1ze6apx@ as an example workflow.
  83
  84 Arv-copy will infer the source cluster is @jutro@ from the object UUID, and destination cluster is @pirca@ from @--project-uuid@.
  85
  86 <notextile>
  87 <pre><code>~$ <span class="userinput">arv-copy --project-uuid pirca-j7d0g-ecak8knpefz8ere jutro-7fd4e-mkmmq53m1ze6apx</span>
  88 ae480c5099b81e17267b7445e35b4bc7+180: 23M / 23M 100.0%
  89 2463fa9efeb75e099685528b3b9071e0+438: 156M / 156M 100.0%
  90 jutro-4zz18-vvvqlops0a0kpdl: 94M / 94M 100.0%
  91 2020-08-19 17:04:13 arvados.arv-copy[4789] INFO:
  92 2020-08-19 17:04:13 arvados.arv-copy[4789] INFO: Success: created copy with uuid pirca-7fd4e-s0tw9rfbkpo2fmx
  93 </code></pre>
  94 </notextile>
  95
  96 The name, description, and workflow definition from the original workflow will be used for the destination copy. In addition, any *collections* and *Docker images* referenced in the source workflow definition will also be copied to the destination.
  97
  98 If you would like to copy the object without dependencies, you can use the @--no-recursive@ flag.
  99
 100 h3. How to copy a project
 101
 102 We will use the UUID @jutro-j7d0g-xj19djofle3aryq@ as an example project.
 103
 104 Arv-copy will infer the source cluster is @jutro@ from the source project UUID, and destination cluster is @pirca@ from @--project-uuid@.
 105
 106 <notextile>
 107 <pre><code>~$ <span class="userinput">arv-copy --project-uuid pirca-j7d0g-lr8sq3tx3ovn68k jutro-j7d0g-xj19djofle3aryq</span>
 108 2021-09-08 21:29:32 arvados.arv-copy[6377] INFO:
 109 2021-09-08 21:29:32 arvados.arv-copy[6377] INFO: Success: created copy with uuid pirca-j7d0g-ig9gvu5piznducp
 110 </code></pre>
 111 </notextile>
 112
 113 The name and description of the original project will be used for the destination copy.  If a project already exists with the same name, collections and workflow definitions will be copied into the project with the same name.
 114
 115 If you would like to copy the project but not its subproject, you can use the @--no-recursive@ flag.
 116
 117 h3. Importing HTTP resources to Keep
 118
 119 You can also use @arv-copy@ to copy the contents of a HTTP URL into Keep.  When you do this, Arvados keeps track of the original URL the resource came from.  This allows you to refer to the resource by its original URL in Workflow inputs, but actually read from the local copy in Keep.
 120
 121 <notextile>
 122 <pre><code>~$ <span class="userinput">arv-copy --project-uuid tordo-j7d0g-lr8sq3tx3ovn68k https://example.com/index.html</span>
 123 tordo-4zz18-dhpb6y9km2byb94
 124 2023-10-06 10:15:36 arvados.arv-copy[374147] INFO: Success: created copy with uuid tordo-4zz18-dhpb6y9km2byb94
 125 </code></pre>
 126 </notextile>
 127
 128 In addition, when importing from HTTP URLs, you may provide a different cluster than the destination in @--src@. This tells @arv-copy@ to search the other cluster for a collection associated with that URL, and if found, copy the collection from that cluster instead of downloading from the original URL.
 129
 130 The following @arv-copy@ command line options affect the behavior of HTTP import.
 131
 132 table(table table-bordered table-condensed).
 133 |_. Option |_. Description |
 134 |==--varying-url-params== VARYING_URL_PARAMS|A comma separated list of URL query parameters that should be ignored when storing HTTP URLs in Keep.|
 135 |==--prefer-cached-downloads==|If a HTTP URL is found in Keep, skip upstream URL freshness check (will not notice if the upstream has changed, but also not error if upstream is unavailable).|