github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/docs/RFCS/20170117_enterprise.md (about)

     1  - Feature Name: Enterprise Registration
     2  - Status: completed
     3  - Start Date: 2017-01-17
     4  - Authors: Daniel Harrison and David Taylor
     5  - RFC PR: [#14114]
     6  
     7  # Summary
     8  
     9  CockroachDB's [business model] describes a set of "enterprise features", which
    10  (after an evaluation period) must be purchased to be used by commercial
    11  entities. This document describes the technical mechanisms involved.
    12  
    13  # Context
    14  
    15  The goal of the mechanisms described here is to prevent usage of "enterprise
    16  features" without a valid license. However the source code of both the Open
    17  Source and Enterprise portions of CockroachDB is publicly available, according
    18  to its respective licensing terms, in our published Github repository. Thus
    19  there is a limited extent to which it makes sense to add increasingly complex
    20  technical barriers to circumvention, e.g. signing keys, obfuscation, etc.
    21  
    22  In short: our goal is to put a lock on the front door, not to build Fort Knox.
    23  
    24  # Detailed design
    25  
    26  An enterprise license is represented as a `License` protobuf. It contains
    27  the user organization's name, a valid_until date (for an N-day evaluation
    28  license), a list of cluster_ids, and whatever other information is necessary.
    29  The protobuf is serialized and base64 encoded.
    30  
    31  ```
    32  message License {
    33      repeated bytes cluster_id = 1 [(gogoproto.nullable) = false,
    34          (gogoproto.customname) = "ClusterID",
    35          (gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID"];
    36      int64 valid_until_unix_sec = 2;
    37  
    38      enum Type {
    39        NonCommercial = 0;
    40        Evaluation = 1;
    41        Enterprise = 2;
    42      }
    43  
    44      Type type = 3;
    45  
    46      string organization_name = 4;
    47  }
    48  
    49  ```
    50  
    51  The latest license will be stored as a gossiped [cluster
    52  setting](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20170317_settings_table.md).
    53  Once viewing historical settings is supported, it can be used to show historical
    54  licensing information. When nodes observe the setting change, the value is
    55  decoded to update an in-memory copy of the `License` struct.
    56  
    57   When a SQL statement using an enterprise feature is executed, the time and
    58   executing clusterID are checked against the current license to determine if it
    59   is valid (the result of this check could potentially be cached until the
    60   expiration or next change if or when it becomes a performance concern).
    61  
    62  To acquire a license, a user visits the registration page on
    63  https://cockroachlabs.com. Further details are out of scope.
    64  
    65  The user applies a license to a cluster in either of two ways: via a page on the
    66  admin ui or `SET CLUSTER LICENSE` SQL command (run as the `root` user). Both
    67  methods must immediately return an error if the license is invalid (malformed or
    68  not currently valid for the executing cluster), rather than updating the setting
    69  and potentially leading to subsequent SQL commands failing (e.g. a nightly
    70  unattended `BACKUP`).
    71  
    72  The current registration status is surfaced in the admin ui and can be inspected
    73  via a new `SHOW CLUSTER LICENSE` SQL command.
    74  
    75  ## Grace Period
    76  
    77  Suddenly breaking existing workflows can be very disruptive, and would create a
    78  poor experience for paying customers. Thus Enterprise licenses may remain usable
    79  for some grace period beyond their expiration time.
    80  
    81  ## Licenses Without Expirations
    82  
    83  In some situations, we may want to issue licenses that are not time-bound.
    84  Leaving the expiration unset (0) signifies a license has no expiration.
    85  
    86  ## Cluster-specific vs Site Licenses
    87  
    88  Including the ClusterID(s) for which a license is valid is intended to help
    89  prevent reuse of a license string except by the licensee to which it was issued,
    90  e.g. if someone accidentally included their `SET LICENSE abcdef` string in a
    91  tutorial or question online.
    92  
    93  In some situations, we may want to issue licenses that are not tied to specific
    94  clusterIDs -- e.g. if a team is creating clusters for testing or evaluation,
    95  having to acquire a new license from Cockroach Labs every time a testing cluster
    96  is started would become very tedious.
    97  
    98  As specified above, Licenses include the organization to which they are issued.
    99  Licenses that do not specify individual clusterIDs for which they are valid are
   100  treated as valid if their organization field matches a new "Organization"
   101  cluster attribute -- likely stored as a cluster setting, set during explicit
   102  `init` or  via the UI or a setting after initialization.
   103  
   104  # Drawbacks
   105  
   106  `BACKUP` and `RESTORE` are a natural fit for this model, but `PARTITION` is more
   107  difficult as a table may be created using an evaluation license and used after
   108  it expires. We'll require that a valid license is present to create or edit a
   109  partition, but not to use a table with a partition.
   110  
   111  # Alternatives
   112  
   113  ## Command-line Flag
   114  
   115  An alternative to the system table is a command line flag specifying the path of
   116  a file with the serialized license data. This doesn't require gossiping or a new
   117  system table.
   118  
   119  Unfortunately, there is potential for disagreements between nodes, which will
   120  lead to confusing behavior. Plus licensing (or re-licensing) a cluster is more
   121  difficult operationally and SQL is a more natural interface, especially as
   122  licenses get more complicated (e.g with rights management).
   123  
   124  ## A Separate Table
   125  The settings table is used above to avoid taking another table ID in the system
   126  config range, of which we have a very limited number. However, licenses are
   127  different enough from other settings that we're likely to want to treat them
   128  differently in the future, so we'll create a separate table when/if we need it.
   129  
   130  # Unresolved questions
   131  
   132  When a user's license is expired (or near expired), they need to be notified.
   133  Assuming that not every customer will regularly use the admin ui, how should we
   134  do these sorts of notifications? Some candidates are during node start-up (next
   135  to where we report candidate updates for the binary), periodically in the logs,
   136  and/or in an email to the cluster administrator (address provided when they
   137  register for the license).
   138  
   139  [#14114]: https://github.com/cockroachdb/cockroach/pull/14114
   140  [business model]: https://www.cockroachlabs.com/blog/how-were-building-a-business-to-last/
   141  [settings table]: https://github.com/cockroachdb/cockroach/pull/14230