github.com/NVIDIA/aistore@v1.3.23-0.20240517131212-7df6609be51d/docs/feature_flags.md (about)

     1  ---
     2  layout: post
     3  title: FEATURE FLAGS
     4  permalink: /docs/feature-flags
     5  redirect_from:
     6   - /feature_flags.md/
     7   - /docs/feature_flags.md/
     8  ---
     9  
    10  ## Table of Contents
    11  
    12  - [Feature flags](#feature-flags)
    13  - [Names and comments](#names-and-comments)
    14  - [Global features](#global-features)
    15  - [Bucket features](#bucket-features)
    16  
    17  ## Feature flags
    18  
    19  `Feature flags` is a 64-bit (bit-wise) field in aistore cluster configuration denoting assorted (named) capabilities that can be individually enabled at runtime.
    20  
    21  The features themselves are enumerated below. Not all feature flags - henceforth, "features" - are cluster-global.
    22  
    23  Assorted features, denoted by `(*)` below, can also be changed on a per-bucket basis.
    24  
    25  By default, all features are disabled, and the corresponding 64-bit field is set to zero.
    26  
    27  ## Names and comments
    28  
    29  | name | comment |
    30  | --- | ------- |
    31  | `Enforce-IntraCluster-Access` | when enabled, aistore targets will make sure _not_ to execute direct (ie., not redirected) API calls |
    32  | `S3-API-via-Root` | handle S3 requests via `aistore-hostname/` (whereby the default: `aistore-hostname/s3`) |
    33  | `Dont-Allow-Passing-FQN-to-ETL` |  do not allow passing fully-qualified name of a locally stored object to (local) ETL containers |
    34  | `Fsync-PUT(*)` | PUT and cold-GET: commit (or sync) the object payload to stable storage |
    35  | `Ignore-LimitedCoexistence-Conflicts` | run in presence of "limited coexistence" type conflicts |
    36  | `Skip-Loading-VersionChecksum-MD(*)` | skip loading existing object's metadata, Version and Checksum (VC) in particular |
    37  | `LZ4-Block-1MB` | .tar.lz4 format, lz4 compression: maximum uncompressed block size=1MB (default: 256K) |
    38  | `LZ4-Frame-Checksum` | checksum lz4 frames |
    39  | `Do-not-Auto-Detect-FileShare` | do not auto-detect file share (NFS, SMB) when _promoting_ shared files to AIS |
    40  | `S3-Presigned-Request(*)` | pass-through client-signed (presigned) S3 requests for subsequent authentication by S3 |
    41  | `Dont-Optimize-Listing-Virtual-Dirs` | when prefix doesn't end with '/' and is a subdirectory: don't assume there are no _prefixed_ object names (as in: `a/subdir/obj1`, `a/subdir/obj2`, but also `a/subdir-obj3`) |
    42  | `Disable-Cold-GET` | do not perform cold GET request when using remote bucket |
    43  | `S3-Reverse-Proxy` | use reverse proxy calls instead of HTTP-redirect for S3 API |
    44  | `S3-Use-Path-Style` | use older path-style addressing (as opposed to virtual-hosted style), e.g., https://s3.amazonaws.com/BUCKET/KEY |
    45  
    46  ## Global features
    47  
    48  ```console
    49  $ ais config cluster features <TAB-TAB>
    50  
    51  Enforce-IntraCluster-Access           Fsync-PUT                             Ignore-LimitedCoexistence-Conflicts
    52  Skip-Loading-VersionChecksum-MD       LZ4-Block-1MB                         S3-Presigned-Request
    53  Do-not-Auto-Detect-FileShare          LZ4-Frame-Checksum                    Dont-Optimize-Listing-Virtual-Dirs
    54  S3-API-via-Root                       Dont-Allow-Passing-FQN-to-ETL         Disable-Cold-GET
    55  S3-Reverse-Proxy                      none
    56  ```
    57  
    58  For example:
    59  
    60  ```console
    61  $ ais config cluster features S3-API-via-Root Skip-Loading-VersionChecksum-MD Ignore-LimitedCoexistence-Conflicts
    62  PROPERTY         VALUE
    63  features         S3-API-via-Root,Ignore-LimitedCoexistence-Conflicts,Skip-Loading-VersionChecksum-MD
    64  
    65  Cluster config updated
    66  ```
    67  
    68  > **Tip**: to select multiple features, type the first letter (or the few first letters) of the one you select, press `<TAB-TAB>` to complete, and then press `<TAB-TAB>` again to keep going, if need be.
    69  
    70  To view the current (configured) setting, type the same command and hit `Enter`:
    71  
    72  ```console
    73  $ ais config cluster features
    74  PROPERTY         VALUE
    75  features         S3-API-via-Root,Ignore-LimitedCoexistence-Conflicts,Skip-Loading-VersionChecksum-MD
    76  ```
    77  
    78  The same in JSON:
    79  
    80  ```console
    81  $ ais config cluster features --json
    82  {
    83      "features": "1552"
    84  }
    85  ```
    86  
    87  Finally, to reset feature flags back to the system defaults, `<TAB-TAB>` to select `none` from the completion list, or simply run:
    88  
    89  ```console
    90  $ ais config cluster features none
    91  
    92  PROPERTY         VALUE
    93  features         none
    94  
    95  Cluster config updated
    96  ```
    97  
    98  ## Bucket features
    99  
   100  By default, created and added (ie., discovered upon remote lookup) buckets inherit their properties from the cluster.
   101  
   102  > For background and details, see [Default Bucket Properties](/docs/bucket.md#default-bucket-properties).
   103  
   104  It is possible, however, to change the defaults both at bucket creation time and/or at any later time.
   105  
   106  Here's a brief 1-2-3 demonstration in re specifically: feature flags.
   107  
   108  ```console
   109  ## 1. show existing bucket-scope features:
   110  
   111  $ ais bucket props set ais://nnn features <TAB-TAB>
   112  Skip-Loading-VersionChecksum-MD   Fsync-PUT        S3-Presigned-Request       none
   113  
   114  ## 2. select and set:
   115  
   116  $ ais bucket props set ais://nnn features S3-Presigned-Request
   117  "features" set to: "512" (was: "0")
   118  
   119  Bucket props successfully updated.
   120  $ ais bucket props set ais://nnn features
   121  PROPERTY         VALUE
   122  features         512
   123  
   124  ## 3. reset feature flags back to zero (or 'none'):
   125  
   126  $ ais bucket props set ais://nnn features none
   127  "features" set to: "0" (was: "512")
   128  
   129  Bucket props successfully updated.
   130  $ ais bucket props set ais://nnn features
   131  PROPERTY         VALUE
   132  features         0
   133  ```