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