PersistentClientCache.xml

   1 <?xml version='1.0' encoding='UTF-8'?><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="pcc"
   2     condition="l2D">
   3   <title xml:id="pcc.title">Persistent Client Cache (PCC)</title>
   4   <para>This chapter describes Persistent Client Cache (PCC).</para>
   5   <section xml:id="pcc.intro">
   6     <title>Introduction</title>
   7     <para> Flash-based SSDs help to (partly) close the ever-increasing
   8       performance gap between magnetic disks and CPUs. SSDs build a new level
   9       in the storage hierarchy, both in terms of price and performance.  The
  10       large size of data sets stored in Lustre, ranging up to hundreds of PiB
  11       in the largest centers, makes it more cost-effective to store most of the
  12       data on HDDs and only an active subset of data on SSDs.</para>
  13     <para>The PCC mechanism allows clients equipped with internal SSDs to
  14       deliver additional performance for both read and write intensive
  15       applications that have node-local I/O patterns without losing the benefits
  16       of the global Lustre namespace. PCC is combined with Lustre HSM and layout
  17       lock mechanisms to provide persistent caching services using the local SSD
  18       storage, while allowing migration of individual files between local and
  19       shared storage. This enables I/O intensive applications to read and write
  20       data on client nodes without losing the benefits of the global Lustre
  21       namespace.</para>
  22     <para>The main advantages to use this cache on the Lustre clients is
  23       that the I/O stack is much simpler for the cached data, as there is no
  24       interference with I/Os from other clients, which enables performance
  25       optimizations. There are no special requirements on the hardware of
  26       the client nodes. Any Linux filesystem, such as ext4 on an NVMe device,
  27       can be used as PCC cache. Local file caching reduces the pressure on the
  28       object storage targets (OSTs), as small or random I/Os can be aggregated
  29       to large sequential I/Os and temporary files do not even need to be
  30       flushed to OSTs.</para>
  31   </section>
  32   <section xml:id="pcc.design">
  33     <title>Design</title>
  34     <section xml:id="pcc.design.rwpcc">
  35       <title>Lustre Read-Write PCC Caching</title>
  36       <figure xml:id="pcc.rwpccarch.fig">
  37         <title>Overview of PCC-RW Architecture</title>
  38         <mediaobject>
  39           <imageobject>
  40             <imagedata scalefit="1" width="50%"
  41               fileref="figures/pccarch.png" />
  42           </imageobject>
  43           <textobject>
  44             <phrase>Overview of PCC-RW Architecture</phrase>
  45           </textobject>
  46         </mediaobject>
  47       </figure>
  48       <para>Lustre typically uses its integrated HSM mechanism to interface
  49         with larger and slower archival storage using tapes or other media.
  50         PCC-RW, on the contrary, is actually an HSM backend storage system which
  51         provides a group of high-speed local caches on Lustre clients.
  52         <xref linkend="pcc.rwpccarch.fig"/> shows the PCC-RW architecture. Each
  53         client uses its own local storage, usually in the form of NVMe,
  54         formatted as a local file system for the local cache. Cached I/Os are
  55         directed to files in the local file system, while normal I/O are
  56         directed to OSTs.</para>
  57       <para>PCC-RW uses Lustre's HSM mechanism for data synchronization. Each
  58         PCC node is actually an HSM agent and has a copy tool instance running
  59         on it. The Lustre HSM copytool is used to restore files from the local
  60         cache to Lustre OSTs. Any remote access for a PCC cached file from
  61         another Lustre client triggers this data synchronization. If a PCC
  62         client goes offline, the cached data becomes temporarily inaccessible
  63         to other clients. The data will be accessible again after the PCC
  64         client reboots, mounts the Lustre filesystem, and restarts the
  65         copytool.</para>
  66       <para>Currently, PCC clients cache entire files on their local
  67         filesystems. A file has to be attached to PCC before I/O can be directed
  68         to a client cache. The Lustre layout lock feature is used to ensure that
  69         the caching services are consistent with the global file system state.
  70         The file data can be written/read directly to/from the local PCC cache
  71         after a successful attach operation. If the attach has not been
  72         successful, the client will simply fall back to the normal I/O path and
  73         direct I/Os to OSTs. PCC-RW cached files are automatically restored to
  74         the global filesystem when a process on another client tries to read or
  75         modify them. The corresponding I/O will be blocked, waiting for the
  76         released file to be restored. This is transparent to the application.
  77       </para>
  78       <para>The revocation of the layout lock can automatically detach the file
  79         from the PCC cache at any time. The PCC-RW cached file can be
  80         manually detached by the <literal>lfs pcc detach</literal> command. After
  81         the cached file is detached from the cache and restored to OSTs, it
  82         will be removed from the PCC filesystem.</para>
  83       <para>Failed PCC-RW operations usually return corresponding error codes.
  84         There is a special case when the space of the local PCC file system is
  85         exhausted. In this case, PCC-RW can fall back to the normal I/O path
  86         automatically since the capacity of the Lustre file system is much
  87         larger than the capacity of the PCC device.</para>
  88     </section>
  89     <section xml:id="pcc.design.rules">
  90       <title>Rule-based Persistent Client Cache</title>
  91       <para>PCC includes a rule-based, configurable caching infrastructure that
  92         enables it to achieve various objectives, such as customizing I/O
  93         caching and providing performance isolation and QoS guarantees.</para>
  94       <para>For PCC-RW, when a file is being created, a rule-based policy is
  95         used to determine whether it will be cached. It supports rules for
  96         different users, groups, projects, or filenames extensions.</para>
  97       <para>Rule-based PCC-RW caching of newly created files can determine
  98         which file can use a cache on PCC directly without administrator's
  99         intervention.</para>
 100     </section>
 101   </section>
 102   <section xml:id="pcc.operations">
 103     <title>PCC Command Line Tools</title>
 104     <para>Lustre provides <literal>lfs</literal> and <literal>lctl</literal>
 105       command line tools for users to interact with PCC feature.</para>
 106     <section xml:id="pcc.operations.add">
 107       <title>Add a PCC backend on a client</title>
 108       <para><emphasis role="strong">Command:</emphasis></para>
 109       <screen>client# lctl pcc add <replaceable>mountpoint</replaceable> <replaceable>pccpath</replaceable> [--param|-p <replaceable>cfgparam</replaceable>]</screen>
 110       <para>The above command will add a PCC backend to the Lustre client.</para>
 111       <informaltable>
 112         <tgroup cols="2">
 113           <colspec align="left" colwidth="1*"/>
 114           <colspec align="left" colwidth="2*"/>
 115           <thead>
 116             <row>
 117               <entry>Option</entry>
 118               <entry>Description</entry>
 119             </row>
 120           </thead>
 121           <tbody>
 122             <row>
 123               <entry>mountpoint</entry>
 124               <entry>
 125                 <para>The Lustre client mount point.
 126                 </para>
 127               </entry>
 128             </row>
 129             <row>
 130               <entry>pccpath</entry>
 131               <entry>
 132                 <para>The directory path on local filesystem for PCC cache. The
 133                   whole filesystem does not need to be exclusively dedicated to
 134                   the PCC cache, but the directory should not be accessible to
 135                   regular users.</para>
 136               </entry>
 137             </row>
 138             <row>
 139               <entry>
 140                 <para>cfgparam</para>
 141               </entry>
 142               <entry>
 143                 <para>A string in the form of name-value pairs to config the
 144                   PCC backend such as read-write attach id (archive ID),
 145                   and auto caching rule, etc.</para>
 146               </entry>
 147             </row>
 148           </tbody>
 149         </tgroup>
 150       </informaltable>
 151       <para><emphasis role="strong">Note:</emphasis> when a client node has
 152         more than one Lustre mount point or Lustre filesystem instance, the
 153         parameter <replaceable>mountpoint</replaceable> makes sure that only
 154         the PCC backend on specified Lustre filesystem instance or Lustre
 155         mount point is configured. This Lustre mount point must be the same as
 156         the HSM (lhsmtool_posix) configuration, if the PCC backend is used as
 157         PCC-RW caching. Also, the parameter <replaceable>pccpath</replaceable>
 158         should be the same as the HSM root parameter of the POSIX copytool
 159         (lhsmtool_posix).</para>
 160       <para>PCC-RW uses Lustre's HSM mechanism for data synchronization.
 161         Before using PCC-RW on a client, it is still necessary to setup HSM on
 162         the MDTs and the PCC client nodes.</para>
 163       <para>First, a coordinator must be activated on each of the filesystem
 164         MDTs. This can be achieved with the command:</para>
 165       <screen>mds# lctl set_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm_control=enabled
 166 mdt.lustre-MDT0000.hsm_control=enabled</screen>
 167       <para>Next, launch the copytool on each agent node (PCC client node)
 168         to connect to your HSM storage. This command will be of the form:</para>
 169       <screen>client# lhsmtool_posix --daemon --hsm-root <replaceable>$PCCPATH</replaceable> --archive=<replaceable>$ARCHIVE_ID</replaceable> <replaceable>$LUSTREPATH</replaceable></screen>
 170       <para><emphasis role="strong">Examples:</emphasis></para>
 171       <para>The following command adds a PCC backend on a client:</para>
 172       <screen>client# lctl pcc add /mnt/lustre /mnt/pcc  --param "projid={500,1000}&amp;fname={*.h5},uid=1001 rwid=2"</screen>
 173       <para>The first substring of the config parameter is the auto-cache rule,
 174         where "&amp;" represents the logical AND operator while "," represents
 175         the logical OR operator. The example rule means that new files are only
 176         auto cached if either of the following conditions are satisfied:</para>
 177       <itemizedlist>
 178         <listitem>
 179           <para>The project ID is either 500 or 1000 and the suffix of the file
 180             name is "h5";</para>
 181         </listitem>
 182         <listitem>
 183           <para>The user ID is 1001;</para>
 184         </listitem>
 185       </itemizedlist>
 186       <para>The currently supported name-value pairs for PCC backend
 187         configuration are listing as follows:</para>
 188       <itemizedlist>
 189         <listitem>
 190           <para><literal>rwid</literal> PCC-RW attach ID which
 191             is same as the archive ID of the copytool agent running on this PCC
 192             node.</para>
 193         </listitem>
 194         <listitem>
 195           <para><literal>auto_attach</literal> <literal>"auto_attach=1"
 196             </literal> enables auto attach at the next open or during I/O.
 197             Enabling this option should cause automatic attaching of valid
 198             PCC-cached files which were detached due to the manual <literal>
 199             lfs pcc detach</literal> command or revocation of layout lock (i.e.
 200             LRU lock shrinking). <literal>"auto_attach=0"</literal> means that
 201             auto file attach is disabled and is the default mode.
 202           </para>
 203         </listitem>
 204       </itemizedlist>
 205     </section>
 206     <section xml:id="pcc.operations.del">
 207       <title>Delete a PCC backend from a client</title>
 208       <para><emphasis role="strong">Command:</emphasis></para>
 209       <screen>lctl pcc del &lt;mountpoint&gt; &lt;pccpath&gt;</screen>
 210       <para>The above command will delete a PCC backend from a Lustre client.
 211       </para>
 212       <informaltable>
 213         <tgroup cols="2">
 214           <colspec align="left" colwidth="1*"/>
 215           <colspec align="left" colwidth="2*"/>
 216           <thead>
 217             <row>
 218               <entry>Option</entry>
 219               <entry>Description</entry>
 220             </row>
 221           </thead>
 222           <tbody>
 223             <row>
 224               <entry>mountpoint</entry>
 225               <entry>
 226                 <para>The Lustre client mount point.
 227                 </para>
 228               </entry>
 229             </row>
 230             <row>
 231               <entry>pccpath</entry>
 232               <entry>
 233                 <para>A PCC backend is specified by this path. Please refer to
 234                   <literal>lctl pcc add</literal> for details.</para>
 235               </entry>
 236             </row>
 237           </tbody>
 238         </tgroup>
 239       </informaltable>
 240       <para><emphasis role="strong">Examples:</emphasis></para>
 241       <para>The following command will delete a PCC backend referenced by
 242         <replaceable>"/mnt/pcc"</replaceable> on a client with the mount point
 243         of <replaceable>"/mnt/lustre"</replaceable>.</para>
 244       <screen>client# lctl pcc del /mnt/lustre /mnt/pcc</screen>
 245     </section>
 246     <section xml:id="pcc.operations.clear">
 247       <title>Remove all PCC backends on a client</title>
 248       <para><emphasis role="strong">Command:</emphasis></para>
 249       <screen>lctl pcc clear &lt;mountpoint&gt;</screen>
 250       <para>The above command will remove all PCC backends on a Lustre client.
 251       </para>
 252       <informaltable>
 253         <tgroup cols="2">
 254           <colspec align="left" colwidth="1*"/>
 255           <colspec align="left" colwidth="2*"/>
 256           <thead>
 257             <row>
 258               <entry>Option</entry>
 259               <entry>Description</entry>
 260             </row>
 261           </thead>
 262           <tbody>
 263             <row>
 264               <entry>mountpoint</entry>
 265               <entry>
 266                 <para>The Lustre client mount point.
 267                 </para>
 268               </entry>
 269             </row>
 270           </tbody>
 271         </tgroup>
 272       </informaltable>
 273       <para><emphasis role="strong">Examples:</emphasis></para>
 274       <para>The following command will remove all PCC backends from a client
 275         with the mount point of <replaceable>"/mnt/lustre"</replaceable>.
 276       </para>
 277       <screen>client# lctl pcc clear /mnt/lustre</screen>
 278     </section>
 279     <section xml:id="pcc.operations.list">
 280       <title>List all PCC backends on a client</title>
 281       <para><emphasis role="strong">Command:</emphasis></para>
 282       <screen>lctl pcc list &lt;mountpoint&gt;</screen>
 283       <para>The above command will list all PCC backends on a Lustre client.
 284       </para>
 285       <informaltable>
 286         <tgroup cols="2">
 287           <colspec align="left" colwidth="1*"/>
 288           <colspec align="left" colwidth="2*"/>
 289           <thead>
 290             <row>
 291               <entry>Option</entry>
 292               <entry>Description</entry>
 293             </row>
 294           </thead>
 295           <tbody>
 296             <row>
 297               <entry>mountpoint</entry>
 298               <entry>
 299                 <para>The Lustre client mount point.
 300                 </para>
 301               </entry>
 302             </row>
 303           </tbody>
 304         </tgroup>
 305       </informaltable>
 306       <para><emphasis role="strong">Examples:</emphasis></para>
 307       <para>The following command will list all PCC backends on a client with
 308         the mount point of <replaceable>"/mnt/lustre"</replaceable>.</para>
 309       <screen>client# lctl pcc list /mnt/lustre</screen>
 310     </section>
 311     <section xml:id="pcc.operations.attach">
 312       <title>Attach given files into PCC</title>
 313       <para><emphasis role="strong">Command:</emphasis></para>
 314       <screen>lfs pcc attach --id|-i &lt;NUM&gt; &lt;file...&gt;</screen>
 315       <para>The above command will attach the given files onto PCC.</para>
 316       <informaltable>
 317         <tgroup cols="2">
 318           <colspec align="left" colwidth="1*"/>
 319           <colspec align="left" colwidth="2*"/>
 320           <thead>
 321             <row>
 322               <entry>Option</entry>
 323               <entry>Description</entry>
 324             </row>
 325           </thead>
 326           <tbody>
 327             <row>
 328               <entry>--id|-i &lt;NUM&gt;</entry>
 329               <entry>
 330                 <para>Attach ID to select which PCC backend to use.
 331                 </para>
 332               </entry>
 333             </row>
 334           </tbody>
 335         </tgroup>
 336       </informaltable>
 337       <para><emphasis role="strong">Examples:</emphasis></para>
 338       <para>The following command will attach the file referenced by
 339         <replaceable>/mnt/lustre/test</replaceable> onto the PCC backend with
 340         PCC-RW attach ID that equals 2.</para>
 341       <screen>client# lfs pcc attach -i 2 /mnt/lustre/test</screen>
 342     </section>
 343     <section xml:id="pcc.operations.attach_fid">
 344       <title>Attach given files into PCC by FID(s)</title>
 345       <para><emphasis role="strong">Command:</emphasis></para>
 346       <screen>lfs pcc attach_fid --id|-i &lt;NUM&gt; --mnt|-m &lt;mountpoint&gt; &lt;fid...&gt;</screen>
 347       <para>The above command will attach the given files referenced by their
 348         FIDs into PCC.</para>
 349       <informaltable>
 350         <tgroup cols="2">
 351           <colspec align="left" colwidth="1*"/>
 352           <colspec align="left" colwidth="2*"/>
 353           <thead>
 354             <row>
 355               <entry>Option</entry>
 356               <entry>Description</entry>
 357             </row>
 358           </thead>
 359           <tbody>
 360             <row>
 361               <entry>--id|-i &lt;NUM&gt;</entry>
 362               <entry>
 363                 <para>Attach ID to select which PCC backend to use.
 364                 </para>
 365               </entry>
 366             </row>
 367             <row>
 368               <entry>--mnt|-m &lt;mountpoint&gt;</entry>
 369               <entry>
 370                 <para>The Lustre mount point.</para>
 371               </entry>
 372             </row>
 373           </tbody>
 374         </tgroup>
 375       </informaltable>
 376       <para><emphasis role="strong">Examples:</emphasis></para>
 377       <para>The following command will attach the file referenced by FID
 378         <replaceable>0x200000401:0x1:0x0</replaceable> onto the PCC backend
 379         with PCC-RW attach ID that equals 2.</para>
 380       <screen>client# lfs pcc attach_fid -i 2 -m /mnt/lustre 0x200000401:0x1:0x0</screen>
 381     </section>
 382     <section xml:id="pcc.operations.detach">
 383       <title>Detach given files from PCC</title>
 384       <para><emphasis role="strong">Command:</emphasis></para>
 385       <screen>lfs pcc detach [--keep|-k] &lt;file...&gt;</screen>
 386       <para>The above command will detach given files from PCC.</para>
 387       <informaltable>
 388         <tgroup cols="2">
 389           <colspec align="left" colwidth="1*"/>
 390           <colspec align="left" colwidth="2*"/>
 391           <thead>
 392             <row>
 393               <entry>Option</entry>
 394               <entry>Description</entry>
 395             </row>
 396           </thead>
 397           <tbody>
 398             <row>
 399               <entry>--keep|-k</entry>
 400               <entry>
 401                 <para>By default, the <literal>detach</literal> command will
 402                   detach the file from PCC permanently and remove the PCC copy
 403                   after detach. This option will only detach the file, but keep
 404                   the PCC copy in cache. It allows the detached file to be
 405                   attached automatically at the next open if the cached copy of
 406                   the file is still valid.</para>
 407               </entry>
 408             </row>
 409           </tbody>
 410         </tgroup>
 411       </informaltable>
 412       <para><emphasis role="strong">Examples:</emphasis></para>
 413       <para>The following command will detach the file referenced by
 414         <replaceable>/mnt/lustre/test</replaceable> from PCC permanently and
 415         remove the corresponding cached file on PCC.
 416       </para>
 417       <screen>client# lfs pcc detach /mnt/lustre/test</screen>
 418       <para>The following command will detach the file referenced by
 419         <replaceable>/mnt/lustre/test</replaceable> from PCC, but allow the file
 420         to be attached automatically at the next open.</para>
 421       <screen>client# lfs pcc detach -k /mnt/lustre/test</screen>
 422     </section>
 423     <section xml:id="pcc.operations.detach_fid">
 424       <title>Detach given files from PCC by FID(s)</title>
 425       <para><emphasis role="strong">Command:</emphasis></para>
 426       <screen>lfs pcc detach_fid [--keep|-k] &lt;mountpoint&gt; &lt;fid...&gt;</screen>
 427       <para>The above command will detach the given files from PCC by FID(s).
 428       </para>
 429       <informaltable>
 430         <tgroup cols="2">
 431           <colspec align="left" colwidth="1*"/>
 432           <colspec align="left" colwidth="2*"/>
 433           <thead>
 434             <row>
 435               <entry>Option</entry>
 436               <entry>Description</entry>
 437             </row>
 438           </thead>
 439           <tbody>
 440             <row>
 441               <entry>--keep|-k</entry>
 442               <entry>
 443                 <para>Please refer to the command <literal>lfs pcc detach
 444                   </literal> for details</para>
 445               </entry>
 446             </row>
 447           </tbody>
 448         </tgroup>
 449       </informaltable>
 450       <para><emphasis role="strong">Examples:</emphasis></para>
 451       <para>The following command will detach the file referenced by FID
 452         <replaceable>0x200000401:0x1:0x0</replaceable> from PCC permanently and
 453         remove the corresponding cached file on PCC.</para>
 454       <screen>client# lfs pcc detach_fid /mnt/lustre 0x200000401:0x1:0x0</screen>
 455       <para>The following command will detach the file referenced by FID
 456         <replaceable>0x200000401:0x1:0x0</replaceable> from PCC, but allow the
 457         file to be attached automatically at the next open.</para>
 458       <screen>client# lfs pcc detach_fid -k /mnt/lustre 0x200000401:0x1:0x0</screen>
 459     </section>
 460     <section xml:id="pcc.operations.state">
 461       <title>Display the PCC state for given files</title>
 462       <para><emphasis role="strong">Command:</emphasis></para>
 463       <screen>lfs pcc state &lt;file...&gt;</screen>
 464       <para>The above command will display the PCC state for given files.</para>
 465       <para><emphasis role="strong">Examples:</emphasis></para>
 466       <para>The following command will display the PCC state of the file
 467         referenced by <replaceable>/mnt/lustre/test</replaceable>.</para>
 468       <screen>client# lfs pcc state /mnt/lustre/test
 469 file: /mnt/lustre/test, type: readwrite, PCC file: /mnt/pcc/0004/0000/0bd1/0000/0002/0000/0x200000bd1:0x4:0x0, user number: 1, flags: 4</screen>
 470       <para>If the file "/mnt/lustre/test" is not cached on PCC, the output of
 471         its PCC state is as follow:</para>
 472       <screen>client# lfs pcc state /mnt/lustre/test
 473 file: /mnt/lustre/test, type: none</screen>
 474     </section>
 475   </section>
 476   <section xml:id="pcc.examples">
 477     <title>PCC Configuration Example</title>
 478     <orderedlist>
 479       <listitem>
 480         <para>Setup HSM on MDT</para>
 481         <screen>mds# lctl set_param mdt.lustre-MDT0000.hsm_control=enabled</screen>
 482       </listitem>
 483       <listitem>
 484         <para>Setup PCC on the clients</para>
 485         <screen>client1# lhsmtool_posix --daemon --hsm-root /mnt/pcc --archive=1 /mnt/lustre &lt; /dev/null &gt; /tmp/copytool_log 2&gt;&amp;1
 486 client1# lctl pcc add /mnt/lustre /mnt/pcc "projid={1000},uid={500} rwid=1"</screen>
 487       <screen>client2# lhsmtool_posix --daemon --hsm-root /mnt/pcc --archive=2 /mnt/lustre &lt; /dev/null &gt; /tmp/copytool_log 2&gt;&amp;1
 488 client2# lctl pcc add /mnt/lustre /mnt/pcc "projid={1000}&amp;gid={500} rwid=2"</screen>
 489       </listitem>
 490       <listitem>
 491         <para>Execute PCC commands on the clients</para>
 492         <screen>client1# echo "QQQQQ" > /mnt/lustre/test
 493
 494 client2# lfs pcc attach -i 2 /mnt/lustre/test
 495
 496 client2# lfs pcc state /mnt/lustre/test
 497 file: /mnt/lustre/test, type: readwrite, PCC file: /mnt/pcc/0004/0000/0bd1/0000/0002/0000/0x200000bd1:0x4:0x0, user number: 1, flags: 6
 498
 499 client2# lfs pcc detach /mnt/lustre/test</screen>
 500       </listitem>
 501     </orderedlist>
 502   </section>
 503 </chapter>