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

     1  - Feature Name: Configs for structured data
     2  - Status: completed
     3  - Start Date: 2015-08-19
     4  - RFC PR: [#2183](https://github.com/cockroachdb/cockroach/pull/2183)
     5  - Cockroach Issue: [#2090](https://github.com/cockroachdb/cockroach/issues/2090)
     6  
     7  # Summary
     8  
     9  This RFC describes the application of various configurations to the structured data
    10  representation. We address storage, distribution, and modification.
    11  
    12  # Motivation
    13  
    14  Structured data will soon be the only publicly accessible API. This requires a change
    15  in the way configurations are specified and applied, moving from prefix-based logic
    16  to databases and tables.
    17  
    18  The following configs currently exist:
    19  * Accounting: usage limits (bytes, counts). Not currently used.
    20  * Permissions: user read/write permissions. Used by the KV endpoint.
    21  * Users: password storage for the web interface. Currently settable, but not used.
    22  * Zones: replication configuration. Used to make allocation decisions.
    23  
    24  # Prerequisites
    25  
    26  Complete implementation of this RFC depends on the following:
    27  * Gossip system database: [#2179](https://github.com/cockroachdb/cockroach/issues/2179)
    28  * Disable KV endpoint: [#2089](https://github.com/cockroachdb/cockroach/issues/2089)
    29  * Usage accounting: [#2185](https://github.com/cockroachdb/cockroach/issues/2185)
    30  
    31  # Detailed design
    32  
    33  ## Storage
    34  
    35  We propose moving all configuration files to the `system` database as separate tables.
    36  
    37  The table schema depends on the configuration. Some (eg: `users`) apply globally,
    38  while some (eg: `accounting`, `zones`) apply to databases and tables.
    39  
    40  For each configuration, we propose the following schemas:
    41  
    42  #### Accounting
    43  
    44  The accounting table applies to databases and potentially to tables as well.
    45  Its contents have yet to be determined.
    46  
    47  The initial use of this table will be usage limits (a.k.a quotas). Actual usage
    48  storage is still TBD, see: [#2185](https://github.com/cockroachdb/cockroach/issues/2185).
    49  
    50  #### Permissions
    51  
    52  The permissions table is only used for the KV endpoint. It will not be migrated
    53  to the structured data API and will instead be removed after
    54  [#2089](https://github.com/cockroachdb/cockroach/issues/2089) is resolved.
    55  
    56  #### Users
    57  
    58  The users table is currently the only configuration applicable globally.
    59  It contains a mapping of username to password hash and salt.
    60  
    61  Schema:
    62  ```SQL
    63  CREATE TABLE system.users (
    64    "username"  CHAR primary key,
    65    "hashed"    BLOB
    66  )
    67  ```
    68  
    69  #### Zones
    70  
    71  The zone config applies to tables, with a database-level entry used as default.
    72  When a database is created, it will use a global default.
    73  When a table is created, it will inherit its database zone config.
    74  
    75  Schema:
    76  ```SQL
    77  CREATE TABLE system.zones (
    78    "target"           INT primary key,
    79    "attributes"       CHAR,
    80    "range_min_bytes"  INT,
    81    "range_max_bytes"  INT,
    82    "gc_ttl_seconds"   INT
    83  )
    84  ```
    85  
    86  The `target` field is the ID of the database or table the config applies to.
    87  We will also want a global default using ID 0 (which is not a valid database or table ID).
    88  
    89  ## Privileges
    90  
    91  The default privileges for the `system` database and all its tables is `GRANT, SELECT` for
    92  the `root` only. `root` must always keep these exact permissions. Other users may be
    93  granted `GRANT, SELECT`, or a subset, but never more.
    94  
    95  Since the configurations are mutable, we also allow `INSERT, UPDATE, DELETE` to `root` by
    96  default and allow these privileges to be granted.
    97  
    98  The default `root` privileges and maximum grantable privileges now become:
    99  
   100  | Table name | Maximum privileges                    |
   101  |------------|---------------------------------------|
   102  | namespace  | GRANT, SELECT                         |
   103  | descriptor | GRANT, SELECT                         |
   104  | accounting | GRANT, SELECT, INSERT, UPDATE, DELETE | 
   105  | users      | GRANT, SELECT, INSERT, UPDATE, DELETE | 
   106  | zones      | GRANT, SELECT, INSERT, UPDATE, DELETE | 
   107  
   108  ## Setting configuration parameters
   109  
   110  The table structure and privilege settings allow modification of the configuration
   111  through sql commands.
   112  
   113  For ease of use and bulk modifications, the current command-line commands
   114  should be modified to function with the new format.
   115  
   116  # Implementation
   117  
   118  Due to the current state of the system, this RFC will implement table-based configuration
   119  in multiple steps:
   120  
   121  | Configuration | Implementation date |
   122  |---------------|---------------------|
   123  | accounting    | immediately         |
   124  | permissions   | after [#2089](https://github.com/cockroachdb/cockroach/issues/2089) |
   125  | users         | immediately         |
   126  | zones         | after [#2179](https://github.com/cockroachdb/cockroach/issues/2179) |
   127  
   128  # Drawbacks
   129  
   130  # Alternatives
   131  
   132  Some of the configurations could be stored in the `descriptor` table.
   133  However, we would need to implement column-based privileges to allow modification of the configuration
   134  while preventing any changes to the descriptors.
   135  
   136  The specific column names and types for each table are flexible. Specifically, the accounting
   137  configuration contents are unknown.
   138  
   139  # Unresolved questions
   140  
   141  It may be desirable to move the privilege configuration from the database and table descriptors and
   142  store them in their own table.
   143  
   144  The database/table IDs in the config tables are not particularly clear. It would be nice to
   145  dynamically show/use the database/table names, or introduce new `SHOW` statements that would perform
   146  a join on the config tables and the descriptor table.