.. _lcm-definitions: Config File Definitions ======================= Definitions describe config files that LCM needs to generate configs for the target nodes. The LCM UI uses these to generate forms, but an API consumer can use them to know what the valid properties are for each config file. As with most of the LCM API, definitions are *discoverable*. The running API can be navigated by going to /api/v1/lcm/definitions/. Routes ------ .. http:method:: GET /api/v1/lcm/definitions/ :label-name: get-definitions :title: GET /api/v1/lcm/definitions/ Gets a list of all of the DSE versions supported by OpsCenter and LCM, with links to the definitions for each version. **Example** .. code-block:: bash curl http://localhost:8888/api/v1/lcm/definitions/ Output: .. code-block:: js { "dse": [ { "version": "4.7.0", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.0/" }, { "version": "4.7.1", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.1/" }, { "version": "4.7.2", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.2/" }, { "version": "4.7.3", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.3/" }, { "version": "4.7.4", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.4/" }, { "version": "4.7.5", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.5/" }, { "version": "4.7.6", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.6/" }, { "version": "4.7.7", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.7/" }, { "version": "4.7.8", "href": "http://localhost:8888/api/v1/lcm/definitions/4.7.8/" }, { "version": "4.8.0", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.0/" }, { "version": "4.8.1", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.1/" }, { "version": "4.8.2", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.2/" }, { "version": "4.8.3", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.3/" }, { "version": "4.8.4", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.4/" }, { "version": "4.8.5", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.5/" }, { "version": "4.8.6", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.6/" }, { "version": "4.8.7", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.7/" }, { "version": "4.8.8", "href": "http://localhost:8888/api/v1/lcm/definitions/4.8.8/" }, { "version": "5.0.0", "href": "http://localhost:8888/api/v1/lcm/definitions/5.0.0/" } ] } .. http:method:: GET /api/v1/lcm/definitions/{version}/ :label-name: get-definitions-version :title: GET /api/v1/lcm/definitions/{version}/ Gets the definitions for a specific version of DSE. At the top level are *file-id* keys. These loosely look like the filename, when there is an actual distinctive filename. Examples: *cassandra-yaml* for /etc/dse/cassandra/cassandra.yaml. There are a number of properties you may notice missing from *cassandra-yaml* - these are node-specific properties like *listen_address* and *rpc_address*, and should be configured via the fields on :ref:`lcm-node`. The value for each definitions key is an object with the following attributes: renderer Used internally by LCM to generate the output for the config file. display-name Used by LCM UI. groupings Used by LCM UI. properties Each key represents the name of a config file property. Some properties are simple scalar values, but they can also be nested objects or lists. See *Property Fields* below for more info. **Example**: .. code-block:: bash curl http://localhost:8888/api/v1/lcm/definitions/4.8.6/ Output: Go to the actual endpoint on your OpsCenter machine in a browser (we recommend using a JSON viewer plugin for easy reading). A single definitions response can be rather large, and is subject to change during operation when OpsCenter automatically downloads updated definitions. Property Fields --------------- When using definitions as a reference for building a :http:response:`config-profile` it will be important to understand the different types of properties, and how they translate into a config structure. Note that much of the property meta-data is related to the LCM UI. Here we will only cover the attributes that are important for generating properly formed config profiles. Default Values ^^^^^^^^^^^^^^ When the field has a ``default_value``, that value will be rendered in the config file by LCM automatically. You do not need to include such values in your config profile unless you intend to override the default. Scalar Types ^^^^^^^^^^^^ The simplest properties are scalar values (int, float, string, etc) ============= ===================================== Type JSON ============= ===================================== int ``{"property": 14}`` float ``{"property": 0.1`` string ``{"property": "value"}`` boolean ``{"property": true}`` ============= ===================================== Dict Type ^^^^^^^^^ Nested properties are defined as property type ``dict``. In this case the value will be a JSON object. All ``dict`` type properties will have a ``fields`` attribute defining the object keys and what types their values are. This is best show with an example: **Property Definition** .. code-block:: js { "request_scheduler_options": { "conditional": [ { "eq": "org.apache.cassandra.scheduler.RoundRobinScheduler" } ], "depends": "request_scheduler", "type": "dict", "required": false, "fields": { "default_weight": { "default_value": 5, "type": "int", "required": true }, "throttle_limit": { "default_value": 80, "type": "int", "required": true, "unit": "requests" } } } } **Sample Profile** .. code-block:: js { "datastax-version":"5.0.0", "name":"dev", "comment":"development profile", "json":{ "cassandra-yaml":{ "request_scheduler_options":{ "default_weight":6, "throttle_limit": 90 } } } } List Type ^^^^^^^^^ Some config file property values are lists. A ``list`` type definition will have a ``value_type`` attribute, indicating the type of the values in the list. The ``value_type`` could be any of the valid property types defined in this document. **Property Definition** .. code-block:: js { "data_file_directories": { "value_type": "string", "default_value": [ "/var/lib/cassandra/data" ], "type": "list", "required": true } } **Sample Profile** .. code-block:: js { "datastax-version":"5.0.0", "name":"dev", "comment":"development profile", "json":{ "cassandra-yaml":{ "data_file_directories": ["/mnt/data1","/mnt/data2"] } } } User-defined Type ^^^^^^^^^^^^^^^^^ A ``user_defined`` type is almost the same as a ``dict`` type (the value is an object), but the keys are defined by the user. **Property Definition** .. code-block:: js { "request_scheduler_options": { "conditional": [ { "eq": "org.apache.cassandra.scheduler.RoundRobinScheduler" } ], "depends": "request_scheduler", "type": "dict", "required": false, "fields": { "weights": { "value_type": "int", "type": "user_defined", "required": false, "key_name": "keyspace" } } } } **Sample Profile** .. code-block:: js { "datastax-version":"5.0.0", "name":"dev", "comment":"development profile", "json":{ "cassandra-yaml":{ "request_scheduler_options":{ "keyspace_1": 1, "keyspace_2": 1 } } } }