diff --git a/doc/source/draft/appdev-guide/muranopackages/dynamic_ui.rst b/doc/source/draft/appdev-guide/muranopackages/dynamic_ui.rst index a38ae343..cc8396d8 100644 --- a/doc/source/draft/appdev-guide/muranopackages/dynamic_ui.rst +++ b/doc/source/draft/appdev-guide/muranopackages/dynamic_ui.rst @@ -39,7 +39,7 @@ For example, Murano Dynamic UI platform of version 2.2 is able to process UI definitions of versions 2.0, 2.1 and 2.2, but is unable to process 2.3, 3.0 or 1.9. -Currently the latest version of Dynamic UI platform is 2.0. It is incompatible +Currently the latest version of Dynamic UI platform is 2.1. It is incompatible with UI definitions of Version 1, which were used in Murano releases before Juno. @@ -69,7 +69,7 @@ used. Two yaql functions are used 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: +.. note:: 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 @@ -144,6 +144,8 @@ Currently supported options for **type** attribute are: * flavor - specific field, used for selection instance flavor from a list * keypair - specific field, used for selecting a keypair from a list * azone - specific field, used for selecting instance availability zone from a list +* network - specific field, used to select a network and subnet from a list of + the ones available to the current user * any other value is considered to be a fully qualified name for some Application package and is rendered as a pair of controls: one for selecting already existing Applications of that type in an Environment, second - for creating a new Application of that type and selecting it Other arguments (and whether they are required or not) depends on a @@ -177,6 +179,41 @@ attributes are the following: min_vcpus: 2 min_memory_mb: 2048 +* **include_subnets** is used only with network field. `True` by default. + If `True`, the field list includes all the possible combinations of network + and subnet. E.g. if there are two available networks X and Y, and X has two + subnets A and B, while Y has a single subnet C, then the list will include 3 + items: (X, A), (X, B), (Y, C). If set to `False` only network names will be + listed, without their subnets. + +* **filter** is used only with network field. `None` by default. If set to a + regexp string, will be used to display only the networks with names matching + the given regexp. + +* **murano_networks** is used only with network field. `None` by default. May + have values `None`, `exclude` or `translate`. Defines the handling of + networks which are created by murano. + Such networks usually have very long randomly generated names, and thus look + ugly when displayed in the list. If this value is set to `exclude` then these + networks are not shown in the list at all. If set to `translate` the + names of such networks are replaced by a string `Network of %env_name%`. + + .. note:: + This functionality is based on the simple string matching of the + network name prefix and the names of all the accessible murano + environments. If the environment is renamed after the initial deployment + this feature will not be able to properly translate or exclude its network + name. + +* **allow_auto** is used only with network field. `True` by default. Defines if + the default value of the dropdown (labeled "Auto") should be present in the + list. The default value is a tuple consisting of two `None` values. The logic + on how to treat this value is up to application developer. It is suggested to + use this field to indicate that the instance should join default environment + network. For use-cases where such behavior is not desired, this parameter + should be set to `False`. + + Besides field-level validators, form-level validators also exist. They use **standard context** for YAQL evaluation and are required when there is a need to validate some form's constraint across several diff --git a/doc/source/draft/appdev-guide/use_cases.rst b/doc/source/draft/appdev-guide/use_cases.rst index d1196947..95d08ac1 100644 --- a/doc/source/draft/appdev-guide/use_cases.rst +++ b/doc/source/draft/appdev-guide/use_cases.rst @@ -155,4 +155,85 @@ So, you need to specify the maximum instance number in the UI form related to th After the deployment, the LB virtual IP, by which an application is accessible, is displayed. +Configuring Network Access for VMs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, each VM instance deployed by ``io.murano.resources.Instance`` class +or its descendants joins an environment's default network. This network gets +created when the Environment is deployed for the first time, a subnet is +created in it and is uplinked to a router which is detected automatically based +on its name. + +This behavior may be overridden in two different ways. + +Using existing network as environment's default +----------------------------------------------- + +This option is available for users when they create a new environment in the +Dashboard. A dropdown control is displayed next to the input field prompting +for the name of environment. By default this control provides to create a new +network, but the user may opt to choose some already existing network to be the +default for the environment being created. If the network has more than one +subnet, the list will include all the available options with their CIDRs +shown. The selected network will be used as environment's default, so no new +network will be created. + +.. note:: + + Murano does not check the configuration or topology of the network selected + this way. It is up to the user to ensure that the network is uplinked to some + external network via a router - otherwise the murano engine will not be able + to communicate with the agents on the deployed VMs. If the Applications being + deployed require internet connectivity it is up to the user to ensure that + this net provides it, than DNS nameservers are set and accessible etc. + + +Modifying the App UI to prompt user for network +----------------------------------------------- + +The application package may be designed to ask user about the network they want +to use for the VMs deployed by this particular application. This allows to +override the default environment's network setting regardless of its value. + +To do this, application developer has to include a ``network`` field into the +Dynamic UI definition of the app. The value returned by this field is a tuple +of network_id and a subnet_id. This values may be passed as the +input properties for ``io.murano.resources.ExistingNeutronNetwork`` object +which may be in its turn passed to an instance of +``io.murano.resources.Instance`` as its network configuration. + +The UI definition may look like this: + +.. code-block:: yaml + + Templates: + customJoinNet: + - ?: + type: io.murano.resources.ExistingNeutronNetwork + internalNetworkName: $.instanceConfiguration.network[0] + internalSubnetworkName: $.instanceConfiguration.network[1] + Application: + ?: + type: com.example.someApplicationName + instance: + ?: + type: io.murano.resources.LinuxMuranoInstance + networks: + useEnvironmentNetwork: $.instanceConfiguration.network[0]=null + useFlatNetwork: false + customNetworks: switch($.instanceConfiguration.network[0], $=null=>list(), $!=null=>$customJoinNet) + Forms: + - instanceConfiguration: + fields: + - name: network + type: network + label: Network + description: Select a network to join. 'Auto' corresponds to a default environment's network. + required: false + murano_networks: translate + +For more details on the Dynamic UI its controls and templates please refer to +its :ref:`specification `. + +