docs/sections/components/component-specification/cdap-specification.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
   2 .. http://creativecommons.org/licenses/by/4.0\r
   3 \r
   4 .. _cdap-specification:\r
   5 \r
   6 Component specification (CDAP)\r
   7 ==============================\r
   8 \r
   9 The CDAP component specification contains the following groups of\r
  10 information. Many of these are common to both CDAP and Docker components\r
  11 and are therefore described in the common specification.\r
  12 \r
  13 -  :any:`Metadata <metadata>`\r
  14 -  :any:`Interfaces <interfaces>` including the\r
  15    associated :any:`Data Formats <data-formats>`\r
  16 -  :any:`Parameters <parameters>` - for specifying parameters in your\r
  17    AppConfig, AppPreferences, and ProgramPreferences to the Designer and\r
  18    Policy. This of course is CDAP-specific and is described below.\r
  19 -  :any:`Auxiliary Details <auxiliary-details>`\r
  20 -  :any:`List of artifacts <artifacts>`\r
  21 \r
  22 Current Limitations and TODOs\r
  23 -----------------------------\r
  24 \r
  25 -  The integration of DMD is likely to significantly change the\r
  26    :any:`Interfaces <interfaces>` section in this specification, see\r
  27    :any:`DMaaP abstraction <dmaap-abstraction>`.\r
  28 \r
  29 .. _parameters:\r
  30 \r
  31 Parameters\r
  32 ----------\r
  33 \r
  34 There is a ``parameters`` section in your component specification. This\r
  35 section contains three optional keys: `app_config <#appconfig>`__,\r
  36 `app_preferences <#apppreferences>`__, and\r
  37 `propram_preferences <#programpreferences>`__:\r
  38 \r
  39 ::\r
  40 \r
  41     "parameters" : {\r
  42         "app_config" : [ ...],               \r
  43         "app_preferences" : [ ...],          \r
  44         "program_preferences" : [...]\r
  45         // any additional keys are ignored\r
  46     }\r
  47 \r
  48 -  Each section details the parameters that are a part of each of these\r
  49    CDAP constructs (see below).\r
  50 -  All such parameters will be exposed to the designer and to policy for\r
  51    override.\r
  52 -  These parameters should have default values specified by the\r
  53    component developer where necessary, i.e., parameters that *must*\r
  54    come from the designer/policy should not have defaults.\r
  55 -  All of these keys are optional because not every CDAP application\r
  56    uses preferences and not every application uses the AppConfig.\r
  57    However, you should specify at least one, or else your application\r
  58    will have no parameters exposed to policy or to the DCAE designer,\r
  59    which means it would be non-configurable.\r
  60 -  Despite the AppConfig being optional to *specify* in the case that\r
  61    you have no parameters in your AppConfig, it is *required for\r
  62    processing* in your application. That is because the DCAE platform\r
  63    will place important information into your AppConfig as discussed\r
  64    below.\r
  65 \r
  66 Parameter\r
  67 ~~~~~~~~~\r
  68 \r
  69 The following CDAP specific definitions use ``param1`` to refer to the\r
  70 common parameter layout in\r
  71 :any:`Parameter <parameters>`\r
  72 \r
  73 AppConfig\r
  74 ~~~~~~~~~\r
  75 \r
  76 The ``app_config`` key refers to the `CDAP AppConfig <http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/configuration.html>`_.\r
  77 It is expected to be a JSON:\r
  78 \r
  79 ::\r
  80 \r
  81     "app_config" : [ // list of JSON\r
  82         param1,      // common parameter layout\r
  83         ...\r
  84     ]\r
  85 \r
  86 Unfortunately, at the time of writing, the AppConfig is a Java map of\r
  87 ``string:string``, which means you cannot have more complex structures\r
  88 (than string) as any value in your AppConfig. However, there is a way to\r
  89 bypass this constraint: you can pass a JSON by encoding the JSON as a\r
  90 string. E.g., the ``json.dumps()`` and it’s converse ``loads`` methods\r
  91 in Python:\r
  92 \r
  93 ::\r
  94 \r
  95     >>> import json\r
  96     >>> json.dumps({"foo" : "bar"})     # This is a real JSON\r
  97     '{"foo": "bar"}'                    # It is now a string: pass this in as your parameter value\r
  98     >>> json.loads('{"foo": "bar"}')    # Do the equivelent of this in your application\r
  99     {u'foo': u'bar'}                    # ...and you'll get back a real JSON \r
 100     >>>\r
 101 \r
 102 The final AppConfig (after the designer and policy override parameter\r
 103 values) is passed into CDAP’s AppConfig API when starting the\r
 104 application.\r
 105 \r
 106 \r
 107 AppPreferences\r
 108 ~~~~~~~~~~~~~~\r
 109 \r
 110 In addition to the CDAP AppConfig, the platform supports `Application Preferences <http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/preferences.html#set-preferences>`_.\r
 111 The format of the ``app_preferences`` value is the same as the above:\r
 112 \r
 113 ::\r
 114 \r
 115     "app_preferences" : [   // list of JSON\r
 116         param1,      // common parameter layout\r
 117         ...\r
 118     ]\r
 119 \r
 120 The final Application Preferences JSON (after the designer and policy\r
 121 override parameter values) is passed into CDAP’s Preferences API when\r
 122 starting your application.\r
 123 \r
 124 \r
 125 ProgramPreferences\r
 126 ~~~~~~~~~~~~~~~~~~\r
 127 \r
 128 Preferences can also be specified `per program <http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/lifecycle.html#program-lifecycle>`_\r
 129 in CDAP. This key’s value is a list of JSON with the following format:\r
 130 \r
 131 ::\r
 132 \r
 133     "program_preferences" : [                // note: this is a list of JSON \r
 134         {\r
 135           "program_id" :   "program name 1",  // the name of this CDAP program\r
 136           "program_type" : "e.g., flows",     // "must be one of flows, mapreduce, schedules, spark, workflows, workers, or services",\r
 137           "program_pref" : [                  // list of JSON\r
 138           param1,      // common parameter layout\r
 139               ...\r
 140           ]\r
 141         },\r
 142         // repeat for each program that receives a program_preferences JSON \r
 143     ]\r
 144 \r
 145 Each ``program_pref`` JSON is passed into the CDAP API as the preference\r
 146 for ``program_id``.\r
 147 \r
 148 NOTE: for CDAP, this section is very likely to change when DMD is\r
 149 available. The *future* vision, as per :any:`DMaaP intentionally abstracted <dmaap-abstraction>` is\r
 150 that you would publish your data as a series of files on HDFS, and DMD\r
 151 will pick them up and send them to the appropriate DMaaP feeds or\r
 152 directly when needed.\r
 153 \r
 154 .. _auxiliary-details:\r
 155 \r
 156 Auxiliary Details\r
 157 -----------------\r
 158 \r
 159 *auxiliary* contains details about CDAP specific parameters.\r
 160 \r
 161 +----------------------+----------------------+----------------------+\r
 162 | Property Name        | Type                 | Description          |\r
 163 +======================+======================+======================+\r
 164 | streamname           | string               | *Required*.          |\r
 165 +----------------------+----------------------+----------------------+\r
 166 | artifact_name        | string               |                      |\r
 167 +----------------------+----------------------+----------------------+\r
 168 | artifact_version     | string               | the version of your  |\r
 169 |                      |                      | CDAP JAR artifact    |\r
 170 +----------------------+----------------------+----------------------+\r
 171 | namespace            | string               | the CDAP namespace   |\r
 172 |                      |                      | to deploy into,      |\r
 173 |                      |                      | default is ‘default’ |\r
 174 +----------------------+----------------------+----------------------+\r
 175 | programs             | array                | contains each CDAP   |\r
 176 |                      |                      | entity represented   |\r
 177 |                      |                      | in the artifact      |\r
 178 +----------------------+----------------------+----------------------+\r
 179 | program_type         | string               | CDAP entity (eg      |\r
 180 |                      |                      | “flows”)             |\r
 181 +----------------------+----------------------+----------------------+\r
 182 | program_id           | string               | name of CDAP entity  |\r
 183 |                      |                      | (eg “WhoFlow”)       |\r
 184 +----------------------+----------------------+----------------------+\r
 185 \r
 186 Example:\r
 187 \r
 188 .. code:: json\r
 189 \r
 190     "auxiliary": {\r
 191         "streamname" : "who",\r
 192         "artifact_name" : "HelloWorld",\r
 193         "artifact_version" : "3.4.3",\r
 194         "namespace" : "hw",\r
 195         "programs" : [\r
 196                         {"program_type" : "flows", "program_id" : "WhoFlow"}, \r
 197                         {"program_type" : "services", "program_id" : "Greeting"},\r
 198                         ...\r
 199                       ],\r
 200     }\r
 201 \r
 202 The ``programs`` key is identical to the ``program_preferences`` key\r
 203 discussed `above <#programpreferences>`__ except:\r
 204 \r
 205 -  each JSON in the list does not contain ``program_pref``\r
 206 -  this is required! You must include all of your programs in this, as\r
 207    it is used to start each program as well as for DCAE to perform\r
 208    periodic healthchecks on your application. Don’t forget about your\r
 209    services; they are programs too.\r