From 9981f55920a6f1c1f20396d42e35b075b22f6a8f Mon Sep 17 00:00:00 2001 From: dfilppi Date: Mon, 7 Aug 2017 20:10:53 +0000 Subject: ARIA multivim plugin initial checkin Change-Id: I3a24ab6fc5ba54466bfecaf596a13b8907248ae8 Issue-id: SO-77 Signed-off-by: DeWayne Filppi --- aria/multivim-plugin/docs/types.rst | 188 ++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 aria/multivim-plugin/docs/types.rst (limited to 'aria/multivim-plugin/docs/types.rst') diff --git a/aria/multivim-plugin/docs/types.rst b/aria/multivim-plugin/docs/types.rst new file mode 100644 index 0000000000..1b02757696 --- /dev/null +++ b/aria/multivim-plugin/docs/types.rst @@ -0,0 +1,188 @@ + +.. highlight:: yaml + +Types +^^^^^ + +Node Types +========== + +.. cfy:node:: cloudify.openstack.nodes.Server + + An OpenStack server. + + +.. cfy:node:: cloudify.openstack.nodes.WindowsServer + + This type has the same properties and operations-mapping as the type above (as it derives from it), yet it overrides some of the agent and plugin installations operations-mapping derived from the built-in cloudify.nodes.Compute type. Use this type when working with a Windows server. + + Additionally, the default value for the use_password property is overridden for this type, and is set to true. When using an image with a preset password, it should be modified to false. + + +.. cfy:node:: cloudify.openstack.nodes.KeyPair + + +.. cfy:node:: cloudify.openstack.nodes.Image + + +.. cfy:node:: cloudify.openstack.nodes.SecurityGroup + + +.. cfy:node:: cloudify.openstack.nodes.Router + + +.. cfy:node:: cloudify.openstack.nodes.Port + + +.. cfy:node:: cloudify.openstack.nodes.Network + + +.. cfy:node:: cloudify.openstack.nodes.Subnet + + +.. cfy:node:: cloudify.openstack.nodes.FloatingIP + + +.. cfy:node:: cloudify.openstack.nodes.Volume + + +.. cfy:node:: cloudify.openstack.nodes.Project + + +Types' Common Behaviors +======================= + +Validations +----------- + +All types offer the same base functionality for the ``cloudify.interfaces.validation.creation`` interface operation: + + * If it's a new resource (``use_external_resource`` is set to ``false``), the basic validation is to verify there's enough quota to allocate a new resource of the given type. + + * When [using an existing resource](#using-existing-resources), the validation ensures the resource indeed exists. + + +Runtime Properties +------------------ + +Node instances of any of the types defined in this plugin get set with the following runtime properties during the ``cloudify.interfaces.lifecycle.create`` operation: + + * ``external_id`` the Openstack ID of the resource + * ``external_type`` the Openstack type of the resource + * ``external_name`` the Openstack name of the resource + +The only exceptions are the two *floating-ip* types - Since floating-ip objects on Openstack don't have a name, the ``external_name`` runtime property is replaced with the ``floating_ip_address`` one, which holds the object's actual IP address. + + +Default Resource Naming Convention +---------------------------------- + +When creating a new resource (i.e. ``use_external_resource`` is set to ``false``), its name on Openstack will be the value of its ``resource_id`` property. However, if this value is not provided, the name will default to the following schema: + +``__`` + +For example, if a server node is defined as so:: + + node_templates: + myserver: + type: cloudify.openstack.nodes.Server + ... + +Yet without setting the ``resource_id`` property, then the server's name on Openstack will be ``server_my-deployment_myserver_XXXXX`` (where the XXXXX is the autogenerated part of the node instance's ID). + + + +Using Existing Resources +------------------------ + +It is possible to use existing resources on Openstack - whether these have been created by a different Cloudify deployment or not via Cloudify at all. + +All Cloudify Openstack types have a property named ``use_external_resource``, whose default value is ``false``. When set to ``true``, the plugin will apply different semantics for each of the operations executed on the relevant node's instances. Specifically, in the case of the ``cloudify.interfaces.lifecycle.create`` operation, rather than creating a new resource on Openstack of the given type, the plugin will behave as follows: + +1. Try to find an existing resource on Openstack whose name (or IP, in the case of one of the **floating-ip** types) is the value specified for the ``resource_id`` property. If more than one is found, an error is raised. + +2. If no resource was found, the plugin will use the value of the ``resource_id`` property to look for the resource by ID instead. If a resource still isn't found, an error is raised. + +3. If a single resource was found, the plugin will use that resource, and set the node instance with the appropriate runtime properties according to the resource's data. + + +The semantics of other operations are affected as well: + +* The ``cloudify.interfaces.lifecycle.start`` operation, where applicable, will only validate that the resource is indeed started, raising an error if it isn't. + +* The ``cloudify.interfaces.lifecycle.stop`` operation, where applicable, won't have any effect. + +* The ``cloudify.interfaces.lifecycle.delete`` operation will not actually delete the resource from Openstack (but will clear the runtime properties from the node instance). + +* The ``cloudify.interfaces.validation.creation`` operation will verify that a resource with the given name or ID indeed exists, or otherwise print a list of all available resources of the given type. + +* The ``cloudify.interfaces.relationship_lifecycle.establish`` operation will behave as normal if the related node is not set with ``use_external_resource`` as ``true``; However if both nodes have this property set to ``true``, the operation will only attempt to verify that they're indeed "connected" on Openstack as well ("connected" in this case also refers to a security-group imposed on a server, floating-ip associated with a server, etc.). + + +Notes +----- + +* As mentioned in the [Relationships section](#relationships), some relationships take effect in non-relationship operations. When ``use_external_resource`` is set to ``true``, the existence of such connections is validated as well. + +* Using an existing resource only makes sense for single-instance nodes. + + + + +Relationships +============= + + Not all relationships have built-in types + (i.e., some types may simply get connected using standard Cloudify relationships such as ``cloudify.relationships.connected_to``). + + Some relationships take effect in non-relationship operations, + e.g. a subnet which is connected to a network actually gets connected on subnet's creation + (in the ``cloudify.interfaces.lifecycle.create`` operation) + and not in a ``cloudify.interfaces.relationship_lifecycle.establish`` operation - this occurs whenever the connection information is required on resource creation. + + +.. cfy:rel:: cloudify.openstack.server_connected_to_port + + A relationship for connecting a server to a port. The server will use this relationship to automatically connect to the port upon server creation. + + +.. cfy:rel:: cloudify.openstack.port_connected_to_security_group + + A relationship for a port to a security group. + + +.. cfy:rel:: cloudify.openstack.server_connected_to_keypair + + +.. cfy:rel:: cloudify.openstack.port_connected_to_subnet + + A relationship for connecting a port to a subnet. This is useful when a network has multiple subnets, and a port should belong to a specific subnet on that network. The port will then receive some IP from that given subnet. + + Note that when using this relationship in combination with the port type's property `fixed_ip`, the IP given should be on the CIDR of the subnet connected to the port. + + *Note*: This relationship has no operations associated with it; The port will use this relationship to automatically connect to the subnet upon port creation. + + +.. cfy:rel:: cloudify.openstack.server_connected_to_security_group + + A relationship for setting a security group on a server. + + +.. cfy:rel:: cloudify.openstack.subnet_connected_to_router + + A relationship for connecting a subnet to a router. + + +.. cfy:rel:: cloudify.openstack.port_connected_to_floating_ip + + A relationship for associating a floating ip with a port. If that port is later connected to a server, the server will be accessible via the floating IP. + + +.. cfy:rel:: cloudify.openstack.server_connected_to_floating_ip + + A relationship for associating a floating ip with a server. + + +.. cfy:rel:: cloudify.openstack.volume_attached_to_server + + A relationship for attaching a volume to a server. -- cgit 1.2.3-korg