From 5f38b350f68d77cc724c538f136745c183b246f6 Mon Sep 17 00:00:00 2001 From: Timur Sufiev Date: Wed, 14 May 2014 15:41:31 +0400 Subject: [PATCH] Add more info to dynamic UI devdoc article More fields' attributes are described, as well as rules for validators' evaluation and different YAQL contexts. Also replace Telnet example with Active Directory. Change-Id: I4fb19edfc862b2654409b17053cac31ee11b52be --- doc/source/articles/ad-ui.rst | 189 +++++++++++++++++++++++++ doc/source/articles/dynamic_ui.rst | 219 ++++++++++++++++++++++------- doc/source/articles/telnet-ui.rst | 124 ---------------- 3 files changed, 354 insertions(+), 178 deletions(-) create mode 100644 doc/source/articles/ad-ui.rst delete mode 100644 doc/source/articles/telnet-ui.rst diff --git a/doc/source/articles/ad-ui.rst b/doc/source/articles/ad-ui.rst new file mode 100644 index 00000000..ec45989d --- /dev/null +++ b/doc/source/articles/ad-ui.rst @@ -0,0 +1,189 @@ +.. + Copyright 2014 2014 Mirantis, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http//www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _active-directory-yaml: + +============= +*ad.yaml* +============= + +.. code-block:: yaml + + Version: 2 + + Templates: + primaryController: + ?: + type: io.murano.windows.activeDirectory.PrimaryController + host: + ?: + type: io.murano.windows.Host + adminPassword: $.appConfiguration.adminPassword + name: generateHostname($.appConfiguration.unitNamingPattern, 1) + flavor: $.instanceConfiguration.flavor + image: $.instanceConfiguration.osImage + assignFloatingIp: $.appConfiguration.assignFloatingIP + + secondaryController: + ?: + type: io.murano.windows.activeDirectory.SecondaryController + host: + ?: + type: io.murano.services.windows.Host + adminPassword: $.appConfiguration.adminPassword + name: generateHostname($.appConfiguration.unitNamingPattern, $index + 1) + flavor: $.instanceConfiguration.flavor + image: $.instanceConfiguration.osImage + + Application: + ?: + type: io.murano.windows.activeDirectory.ActiveDirectory + name: $.appConfiguration.name + primaryController: $primaryController + secondaryControllers: repeat($secondaryController, $.appConfiguration.dcInstances - 1) + + Forms: + - appConfiguration: + fields: + - name: configuration + type: string + hidden: true + initial: standalone + - name: name + type: string + label: Domain Name + description: >- + Enter a desired name for a new domain. This name should fit to + DNS Domain Name requirements: it should contain + only A-Z, a-z, 0-9, (.) and (-) and should not end with a dash. + DNS server will be automatically set up on each of the Domain + Controller instances. Note: Only first 15 characters or characters + before first period is used as NetBIOS name. + minLength: 2 + maxLength: 255 + validators: + - expr: + regexpValidator: '^([0-9A-Za-z]|[0-9A-Za-z][0-9A-Za-z-]*[0-9A-Za-z])\.[0-9A-Za-z][0-9A-Za-z-]*[0-9A-Za-z]$' + message: >- + Only letters, numbers and dashes in the middle are + allowed. Period characters are allowed only when they + are used to delimit the components of domain style + names. Single-level domain is not + appropriate. Subdomains are not allowed. + - expr: + regexpValidator: '(^[^.]+$|^[^.]{1,15}\..*$)' + message: >- + NetBIOS name cannot be shorter than 1 symbol and + longer than 15 symbols. + - expr: + regexpValidator: '(^[^.]+$|^[^.]*\.[^.]{2,63}.*$)' + message: >- + DNS host name cannot be shorter than 2 symbols and + longer than 63 symbols. + helpText: >- + Just letters, numbers and dashes are allowed. + A dot can be used to create subdomains + - name: dcInstances + type: integer + label: Instance Count + description: >- + You can create several Active Directory instances by setting + instance number larger than one. One primary Domain Controller + and a few secondary DCs will be created. + minValue: 1 + maxValue: 100 + initial: 1 + helpText: Enter an integer value between 1 and 100 + - name: adminAccountName + type: string + label: Account Name + initial: Administrator + regexpValidator: '^[-\w]+$' + errorMessages: + invalid: 'Just letters, numbers, underscores and hyphens are allowed.' + - name: adminPassword + type: password + label: Administrator password + descriptionTitle: Passwords + description: >- + Windows requires strong password for service administration. + Your password should have at least one letter in each + register, a number and a special character. Password length should be + a minimum of 7 characters. + + Once you forget your password you won't be able to + operate the service until recovery password would be entered. So it's + better for Recovery and Administrator password to be different. + - name: recoveryPassword + type: password + label: Recovery password + - name: assignFloatingIP + required: false + type: boolean + label: Assign Floating IP + description: >- + Select to true to assign floating IP automatically to Primary DC + initial: false + required: false + widgetMedia: + css: {all: ['muranodashboard/css/checkbox.css']} + - name: unitNamingPattern + type: string + label: Hostname template + description: >- + For your convenience all instance hostnames can be named + in the same way. Enter a name and use # character for incrementation. + For example, host# turns into host1, host2, etc. Please follow Windows + hostname restrictions. + required: false + regexpValidator: '^(([a-zA-Z0-9#][a-zA-Z0-9-#]*[a-zA-Z0-9#])\.)*([A-Za-z0-9#]|[A-Za-z0-9#][A-Za-z0-9-#]*[A-Za-z0-9#])$' + # FIXME: does not work for # turning into 2-digit numbers + maxLength: 15 + helpText: Optional field for a machine hostname template + # temporaryHack + widgetMedia: + js: ['muranodashboard/js/support_placeholder.js'] + css: {all: ['muranodashboard/css/support_placeholder.css']} + validators: + # if unitNamingPattern is given and dcInstances > 1, then '#' should occur in unitNamingPattern + - expr: $.appConfiguration.dcInstances < 2 or not $.appConfiguration.unitNamingPattern.bool() or '#' in $.appConfiguration.unitNamingPattern + message: Incrementation symbol "#" is required in the Hostname template + - instanceConfiguration: + fields: + - name: title + type: string + required: false + hidden: true + descriptionTitle: Instance Configuration + description: Specify some instance parameters on which service would be created. + - name: flavor + type: flavor + label: Instance flavor + description: >- + Select registered in Openstack flavor. Consider that service performance + depends on this parameter. + required: false + - name: osImage + type: image + imageType: windows + label: Instance image + description: >- + Select valid image for a service. Image should already be prepared and + registered in glance. + - name: availabilityZone + type: azone + label: Availability zone + description: Select availability zone where service would be installed. + required: false diff --git a/doc/source/articles/dynamic_ui.rst b/doc/source/articles/dynamic_ui.rst index 1df0abe7..70d713b4 100644 --- a/doc/source/articles/dynamic_ui.rst +++ b/doc/source/articles/dynamic_ui.rst @@ -19,10 +19,13 @@ Dynamic UI Definition specification =================================== -The main purpose of Dynamic UI is to generate application creation forms "on-the-fly". - Murano dashboard doesn't know anything about what applications can be deployed and which web form are needed to create application instance. - So all application definitions should contain a yaml file which tells dashboard how to create an application and what validations are to be applied. - This document will help you to compose a valid UI definition for your application. +The main purpose of Dynamic UI is to generate application creation +forms "on-the-fly". Murano dashboard doesn't know anything about what +applications can be deployed and which web form are needed to create +application instance. So all application definitions should contain a +yaml file which tells dashboard how to create an application and what +validations are to be applied. This document will help you to compose +a valid UI definition for your application. Structure ========= @@ -45,15 +48,40 @@ Murano 0.5 - version 2 Application and Templates ========================= -In the Application *application object model* section is described. This model will be translated into json and according to that json application will be deployed. -Application section should contain all necessary keys that are required by murano-engine to deploy an application. Note that under ''?'' section goes system part of the model. -You can pick parameters you got from the user (they should be described in the Forms section) and pick the right place where they should be set. -To do this `YAQL `_ is used. All lines are going to be checked for a yaql expressions. Thus, *generateHostname* will be recognized as yaql function and will generate machine hostname . +In the Application section an *application object model* is +described. This model will be translated into json and according to +that json application will be deployed. Application section should +contain all necessary keys that are required by murano-engine to +deploy an application. Note that under *?* section goes system part +of the model. You can pick parameters you got from the user (they +should be described in the Forms section) and pick the right place +where they should be set. To do this `YAQL +`_ is +used. All lines are going to be checked for a yaql +expressions. Currently, 2 yaql functions are provided for object model +generation: +* **generateHostname** is used for machine hostname generation; it + accepts 2 arguments: name pattern (string) and index (integer). If + '#' symbol is present in name pattern, it will be replaced with the + index provided. If pattern is not given, a random name will be + generated. +* **repeat** is used to produce a list of data snippets, given the + template snippet (first argument) and number of times it should be + reproduced (second argument). Inside that template snippet current + step can be referenced as *$index*. + +Note that while evaluating YAQL expressions referenced from +**Application** section (as well as almost all attributes inside +**Forms** section, see later) *$* root object is set to the list of +dictionaries with cleaned forms' data. So to obtain cleaned value of +e.g. field *name* of form *appConfiguration* , you should reference it +as *$.appConfiguration.name*. This context will be called as +**standard context** throughout the text. *Example:* .. code-block:: yaml - + Templates: primaryController: ?: type: io.murano.windows.activeDirectory.PrimaryController @@ -76,6 +104,14 @@ To do this `YAQL `_ is us flavor: $.instanceConfiguration.flavor image: $.instanceConfiguration.osImage + Application: + ?: + type: io.murano.windows.activeDirectory.ActiveDirectory + name: $.serviceConfiguration.name + primaryController: $primaryController + secondaryControllers: repeat($secondaryController, $.serviceConfiguration.dcInstances - 1) + + Forms ===== @@ -83,63 +119,138 @@ This section describes Django forms. Set name for your form and provide fields a Each field should contain: * **name** - system field name, could be any -* **label** - name, that will be displayed in the form -* **description** - description, that will be displayed in the form description area. Use yaml line folding character >- to keep the correct formatting during data transferring. * **type** - system field type - * string - Django string field - * boolean - Django boolean field - * text - Django boolean field - * integer - Django integer field +Currently supported options for **type** attribute are: + + * string - Django CharField with one-line text input + * boolean - Django BooleanField + * text - Django CharField with multi-line text input + * integer - Django IntegerField * password - Specific field with validation for strong password * clusterip - Specific field, used for cluster IP * domain - Specific field, used for Active Directory domain - * databaselist - Specific field, a list of databases (comma-separated list of database names, where each name has the following syntax first symbol should be latin letter or underscore; subsequent symbols can be Latin letter, numeric, underscore, at the sign, number sign or dollar sign) + * databaselist - Specific field, a list of databases + (comma-separated list of databases' names, where each name has the + following syntax first symbol should be latin letter or + underscore; subsequent symbols can be latin letter, numeric, + underscore, at the sign, number sign or dollar sign) * table - Specific field, used for defining table in a form * flavor - Specific field, used for defining flavor in a form * keypair - Specific field, used for defining KeyPair in a form * image- Specific field, used for defining image in a form - * azone - Specific field, used for defining availability zone in a form + * azone - Specific field, used for defining availability zone in a + form + +Other arguments (and whether they are required or not) depends on +field's type and other attributes values. Among the most common +attributes are: +* **label** - name, that will be displayed in the form; defaults to + **name** being capitalized. +* **description** - description, that will be displayed in the form + description area. Use yaml line folding character >- to keep the + correct formatting during data transferring. +* **descriptionTitle** - title of the description, defaults to + **label**. +* **hidden** whether field should be visible or not in the form's left + side. Note that hidden field's description will still be visible + in the form's right side (if given). Hidden fields are used + storing some data to be used by other, visible fields. +* **minLength**, **maxLength** (for string fields) and **minValue**, + **maxValue** (for integer fields) are transparently translated + into django validation properties. +* **validators** is a list of validators dictionaries, each validator + should at least have *expr* key, under that key either some `YAQL + ` + expression is stored, either one-element dictionary with + *regexpValidator* key (and some regexp string as value). Another + possible key of a validator dictionary is *message*, and although + it is not required, it is highly desirable to specify it - + otherwise, when validator fails (i.e. regexp doesn't match or YAQL + expression evaluates to false) no message will be shown. Note that + field-level validators use YAQL context different from all other + attributes and section: here *$* root object is set to the value + of field being validated (to make expressions shorter). +* **widgetMedia** sets some custom *CSS* and *JavaScript* used for the + field's widget rendering. Mostly they are used to do some + client-side field enabling/disabling, hiding/unhiding etc. This is + a temporary field which will be dropped once Version 3 of Dynamic + UI is implemented (since it will transparently translate YAQL + expressions into the appropriate *JavaScript*). + +Besides field-level validators form-level validators also exist. They +use **standard context** for YAQL evaluation and are required when +there is need to validate some form's constraint across several +fields. *Example* .. code-block:: yaml - Forms: - - serviceConfiguration: - fields: - - name: name - type: string - label: Service Name - description: >- - To identify your service in logs please specify a service name - - name: dcInstances - type: integer - hidden: true - initial: 1 - required: false - maxLength: 15 - helpText: Optional field for a machine hostname template - - instanceConfiguration: - fields: - - name: flavor - type: flavor - label: Instance flavor - description: >- - Select registered in Openstack flavor. Consider that service performance - depends on this parameter. - required: false - - name: osImage - type: image - imageType: linux - label: Instance image - description: >- - Select valid image for a service. Image should already be prepared and - registered in glance. - - name: availabilityZone - type: azone - label: Availability zone - description: Select availability zone where service would be installed. - required: false + Forms: + - serviceConfiguration: + fields: + - name: name + type: string + label: Service Name + description: >- + To identify your service in logs please specify a service name + - name: dcInstances + type: integer + hidden: true + initial: 1 + required: false + maxLength: 15 + helpText: Optional field for a machine hostname template + - name: unitNamingPattern + type: string + label: Hostname template + description: >- + For your convenience all instance hostnames can be named + in the same way. Enter a name and use # character for incrementation. + For example, host# turns into host1, host2, etc. Please follow Windows + hostname restrictions. + required: false + regexpValidator: '^(([a-zA-Z0-9#][a-zA-Z0-9-#]*[a-zA-Z0-9#])\.)*([A-Za-z0-9#]|[A-Za-z0-9#][A-Za-z0-9-#]*[A-Za-z0-9#])$' + # FIXME: does not work for # turning into 2-digit numbers + maxLength: 15 + helpText: Optional field for a machine hostname template + # temporaryHack + widgetMedia: + js: ['muranodashboard/js/support_placeholder.js'] + css: {all: ['muranodashboard/css/support_placeholder.css']} + validators: + # if unitNamingPattern is given and dcInstances > 1, then '#' should occur in unitNamingPattern + - expr: $.serviceConfiguration.dcInstances < 2 or not $.serviceConfiguration.unitNamingPattern.bool() or '#' in$.serviceConfiguration.unitNamingPattern + message: Incrementation symbol "#" is required in the Hostname template + - instanceConfiguration: + fields: + - name: title + type: string + required: false + hidden: true + descriptionTitle: Instance Configuration + description: Specify some instance parameters on which service would be created. + - name: flavor + type: flavor + label: Instance flavor + description: >- + Select registered in Openstack flavor. Consider that service performance + depends on this parameter. + required: false + - name: osImage + type: image + imageType: windows + label: Instance image + description: >- + Select valid image for a service. Image should already be prepared and + registered in glance. + - name: availabilityZone + type: azone + label: Availability zone + description: Select availability zone where service would be installed. + required: false + +Full example with Active Directory application form definitions is available here :ref:`active-directory-yaml` + -Full example with Telnet application form definitions is available here :ref:`telnet-yaml` diff --git a/doc/source/articles/telnet-ui.rst b/doc/source/articles/telnet-ui.rst deleted file mode 100644 index 171c32db..00000000 --- a/doc/source/articles/telnet-ui.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. - Copyright 2014 2014 Mirantis, Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http//www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -.. _telnet-yaml: - -============= -*telnet.yaml* -============= - -.. code-block:: yaml - - Version: 2 - - Templates: - instance: - ?: - type: io.murano.resources.Instance - name: generateHostname($.appConfiguration.unitNamingPattern, 1) - flavor: $.instanceConfiguration.flavor - image: $.instanceConfiguration.osImage - assignFloatingIp: $.appConfiguration.assignFloatingIP - - Application: - ?: - type: io.murano.apps.linux.Telnet - name: $.appConfiguration.name - instance: $instance - - - Forms: - - appConfiguration: - fields: - - name: title - type: string - required: false - hidden: true - description: Telnet is a service that allows a Telnet client to connect across a network and access a command session - - name: name - type: string - label: Application Name - description: >- - Enter a desired name for the application. Just A-Z, a-z, 0-9, dash and - underline are allowed. - minLength: 2 - maxLength: 64 - regexpValidator: '^[-\w]+$' - errorMessages: - invalid: Just letters, numbers, underscores and hyphens are allowed. - helpText: Just letters, numbers, underscores and hyphens are allowed. - - name: dcInstances - type: integer - hidden: true - initial: 1 - - name: assignFloatingIP - type: boolean - label: Assign Floating IP - description: >- - Select to true to assign floating IP automatically - initial: false - required: false - widgetMedia: - css: {all: ['muranodashboard/css/checkbox.css']} - - name: unitNamingPattern - type: string - label: Hostname - description: >- - For your convenience instance hostname can be specified. - Enter a name or leave blank for random name generation. - required: false - regexpValidator: '^(([a-zA-Z0-9#][a-zA-Z0-9-#]*[a-zA-Z0-9#])\.)*([A-Za-z0-9#]|[A-Za-z0-9#][A-Za-z0-9-#]*[A-Za-z0-9#])$' - helpText: Optional field for a machine hostname - # temporaryHack - widgetMedia: - js: ['muranodashboard/js/support_placeholder.js'] - css: {all: ['muranodashboard/css/support_placeholder.css']} - validators: - # if unitNamingPattern is given and dcInstances > 1, then '#' should occur in unitNamingPattern - - expr: $.appConfiguration.dcInstances < 2 or not $.appConfiguration.unitNamingPattern.bool() or '#' in $.appConfiguration.unitNamingPattern - message: Incrementation symbol "#" is required in the Hostname template - - instanceConfiguration: - fields: - - name: title - type: string - required: false - hidden: true - description: Specify some instance parameters on which the application would be created - - name: flavor - type: flavor - label: Instance flavor - description: >- - Select registered in Openstack flavor. Consider that application performance - depends on this parameter. - required: false - - name: osImage - type: image - imageType: linux - label: Instance image - description: >- - Select valid image for the application. Image should have Murano agent installed and - registered in Glance. - - name: keyPair - type: keypair - label: Key Pair - description: >- - Select the Key Pair to control access to instances. You can login to - instances using this KeyPair after application deployment - required: false - - name: availabilityZone - type: azone - label: Availability zone - description: Select availability zone where the application would be installed. - required: false