diff --git a/api-ref/source/api-ref-blockstorage-v2-cgcs-ext.rst b/api-ref/source/api-ref-blockstorage-v2-cgcs-ext.rst new file mode 100644 index 000000000..822dd1e08 --- /dev/null +++ b/api-ref/source/api-ref-blockstorage-v2-cgcs-ext.rst @@ -0,0 +1,555 @@ +==================================================== +Block Storage API v2 StarlingX extensions +==================================================== + +StarlingX extensions to the OpenStack Block Storage API such as backup +status and export/import actions for volumes and snapshots. + +The typical port used for the Block Storage REST API is 8776. However, +proper technique would be to look up the cinderv2 service endpoint in +keystone. + +----------- +Extensions +----------- + +The Extensions entity lists all available extensions + +********************** +Lists all extensions +********************** + +.. rest_method:: GET /v2/​{tenant_id}​/extensions + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "namespace (Optional)", "plain", "xsd:string", "Indicates namespace of the extension." + "name (Optional)", "plain", "xsd:string", "Indicates name of the extension." + "updated (Optional)", "plain", "xsd:string", "Indicates updated time of the extension." + "description (Optional)", "plain", "xsd:string", "Indicates description of the extension." + "alias (Optional)", "plain", "xsd:string", "Indicates alias of the extension." + "links (Optional)", "plain", "xsd:list", "A list of links for the extension." + +:: + + { + "extensions" : [ + ... + { + "namespace" : "http://docs.windriver.com/volume/ext/wrs-snapshot/api/v1.0", + "name" : "WrsSnapshotExportAction", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "Enable snapshot export to file", + "alias" : "wrs-snapshot", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.com/volume/ext/wrs-volume/api/v1.0", + "name" : "WrsVolumeExport", + "updated" : "2014-08-11T00:00:00+00:00", + "description" : "Enable volume export/import", + "alias" : "wrs-volume", + "links" : [] + }, + ... + ] + } + +This operation does not accept a request body. + +********************************************** +Gets information about a specified extension +********************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/extensions/​{extension_alias}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + "extension_alias", "URI", "xsd:string", "The alias for the extension to list." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "namespace (Optional)", "plain", "xsd:string", "Indicates namespace of the extension." + "name (Optional)", "plain", "xsd:string", "Indicates name of the extension." + "updated (Optional)", "plain", "xsd:string", "Indicates updated time of the extension." + "description (Optional)", "plain", "xsd:string", "Indicates description of the extension." + "alias (Optional)", "plain", "xsd:string", "Indicates alias of the extension." + "links (Optional)", "plain", "xsd:list", "A list of links for the extension." + +:: + + { + "extension" : { + "namespace" : "http://docs.windriver.com/volume/ext/wrs-volume/api/v1.0", + "name" : "WrsVolumeExport", + "updated" : "2014-08-11T00:00:00+00:00", + "description" : "Enable volume export/import", + "alias" : "wrs-volume", + "links" : [] + } + } + + OR + + { + "extension" : { + "namespace" : "http://docs.windriver.com/volume/ext/wrs-snapshot/api/v1.0", + "name" : "WrsSnapshotExportAction", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "Enable snapshot export to file", + "alias" : "wrs-snapshot", + "links" : [] + } + } + +This operation does not accept a request body. + +-------- +Volumes +-------- + +StarlingX extensions include export and import actions for performing +backup and restores of volumes, and a backup status attribute to +indicate the status of the new actions. + +************************************** +Get information about system volumes +************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/volumes/detail + +Preconditions + +- The specified volume must exist in all case. + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-volume:backup_status", "plain", "xsd:string", "Indicates backup status." + +:: + + { + "volumes" : [ + { + "wrs-volume:backup_status" : "Export completed at 2015-02-27 16:35:53.545339", + "volume_type" : "None", + "status" : "available", + "size" : 1, + "created_at" : "2015-02-27T16:26:08.164607", + "id" : "b7db512f-463e-4720-8fbd-154c0f2bc2ae", + "metadata" : {}, + "attachments" : [], + "os-volume-replication:driver_data" : null, + "os-vol-mig-status-attr:migstat" : null, + "display_name" : null, + "availability_zone" : "nova", + "display_description" : null, + "encrypted" : false, + "os-vol-mig-status-attr:name_id" : null, + "os-vol-host-attr:host" : "controller@lvm#lvm", + "os-volume-replication:extended_status" : null, + "snapshot_id" : null, + "os-vol-tenant-attr:tenant_id" : "e0741109067649a8899936e9fefda95b", + "bootable" : "false", + "source_volid" : null + }, + { + "wrs-volume:backup_status" : "Import completed at 2015-02-27 15:04:29.135579", + "volume_type" : "None", + "status" : "available", + "size" : 1, + "created_at" : "2015-02-27T14:04:34.763953", + "id" : "27080551-9d88-4cf0-aa85-c1392dbf38f4", + "metadata" : {}, + "attachments" : [], + "os-volume-replication:driver_data" : null, + "os-vol-mig-status-attr:migstat" : null, + "display_name" : null, + "availability_zone" : "nova", + "display_description" : null, + "encrypted" : false, + "os-vol-mig-status-attr:name_id" : null, + "os-vol-host-attr:host" : "controller@lvm#lvm", + "os-volume-replication:extended_status" : null, + "snapshot_id" : null, + "os-vol-tenant-attr:tenant_id" : "e0741109067649a8899936e9fefda95b", + "bootable" : "false", + "source_volid" : null + }, + { + "wrs-volume:backup_status" : "Snapshot export completed at 2015-02-27 20:57:29.323714", + "volume_type" : "None", + "status" : "available", + "size" : 1, + "created_at" : "2015-02-27T13:44:55.317995", + "id" : "2c4f094b-f6d8-4ff6-800e-e5998cb4d6fa", + "metadata" : {}, + "attachments" : [], + "os-volume-replication:driver_data" : null, + "os-vol-mig-status-attr:migstat" : null, + "display_name" : null, + "availability_zone" : "nova", + "display_description" : null, + "encrypted" : false, + "os-vol-mig-status-attr:name_id" : null, + "os-vol-host-attr:host" : "controller@lvm#lvm", + "os-volume-replication:extended_status" : null, + "snapshot_id" : null, + "os-vol-tenant-attr:tenant_id" : "e0741109067649a8899936e9fefda95b", + "bootable" : "false", + "source_volid" : null + } + ] + } + +****************************************** +Get information about a specified volume +****************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/volumes/​{volume_id}​ + +Preconditions + +- The specified volume must exist in all case. + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + "volume_id", "URI", "csapi:UUID", "The ID for the volume to list." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-volume:backup_status", "plain", "xsd:string", "Indicates backup status." + +:: + + { + "volumes" : [ + { + "wrs-volume:backup_status" : "Import completed at 2015-02-27 15:04:29.135579", + "volume_type" : "None", + "status" : "available", + "size" : 1, + "created_at" : "2015-02-27T14:04:34.763953", + "id" : "27080551-9d88-4cf0-aa85-c1392dbf38f4", + "metadata" : {}, + "attachments" : [], + "os-volume-replication:driver_data" : null, + "os-vol-mig-status-attr:migstat" : null, + "display_name" : null, + "availability_zone" : "nova", + "display_description" : null, + "encrypted" : false, + "os-vol-mig-status-attr:name_id" : null, + "os-vol-host-attr:host" : "controller@lvm#lvm", + "os-volume-replication:extended_status" : null, + "snapshot_id" : null, + "os-vol-tenant-attr:tenant_id" : "e0741109067649a8899936e9fefda95b", + "bootable" : "false", + "source_volid" : null + }, + ] + } + +****************************************************************** +Executes the specified action or command on the specified volume +****************************************************************** + +.. rest_method:: POST /v2/​{tenant_id}​/volumes/​{volume_id}​/action + +Preconditions + +- The specified volume must exist in all case. + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + "volume_id", "URI", "csapi:UUID", "The ID for the volume to list." + "wrs-volume:os-volume_export", "plain", "xsd:string", "Export volume to a file" + "wrs-volume:os-volume_import", "plain", "xsd:string", "Import a volume from a file " + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "volume_type", "plain", "xsd:string", "Indicates the volume type." + "updated_at", "plain", "xsd:string", "Indicates when the action was performed." + "status", "plain", "xsd:string", "Indicates the state of the export or import action." + "id", "plain", "csapi:UUID", "Indicates the volume UUID." + "display_description", "plain", "xsd:string", "Volume descrition if any." + "size", "plain", "xsd:int", "Indicates the volume size in Gbyte." + +:: + + { + 'wrs-volume:os-volume_export' : { + 'volume_type' : null, + 'updated_at' : '2015-02-27T14:04:35.201969', + 'status' : 'exporting', + 'id' : '27080551-9d88-4cf0-aa85-c1392dbf38f4', + 'display_description' : null, + 'size' : 1 + } + } + or + { + 'wrs-volume:os-volume_import' : { + 'volume_type' : null, + 'updated_at' : '2015-02-27T15:03:54.045796', + 'status' : 'importing', + 'id' : '27080551-9d88-4cf0-aa85-c1392dbf38f4', + 'display_description' : null, + 'size' : 1 + } + } + +---------- +Snapshots +---------- + +StarlingX extensions include export actions for performing backup volumes +already attached to a VM, and a backup status attribute to indicate the +status of the new actions. + +*********************************************** +Get information about system volume snapshots +*********************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/snapshots/detail + +Preconditions + +- The specified volume snapshot must exist in all case. + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-snapshot:backup_status", "plain", "xsd:string", "Indicates backup status." + +:: + + { + "snapshots" : [ + { + "volume_id" : "f15dcbfb-8b41-4fff-adb8-77a4162a318b", + "status" : "available", + "display_description" : null, + "display_name" : null, + "size" : 1, + "created_at" : "2015-02-27T13:19:02.380453", + "os-extended-snapshot-attributes:project_id" : "e0741109067649a8899936e9fefda95b", + "wrs-snapshot:backup_status" : "Export completed at 2015-02-27 13:19:48.914344", + "id" : "7b220cb7-212f-411e-a8cd-41e6bdbac724", + "metadata" : {}, + "os-extended-snapshot-attributes:progress" : "100%" + }, + { + "volume_id" : "2c4f094b-f6d8-4ff6-800e-e5998cb4d6fa", + "status" : "available", + "display_description" : null, + "display_name" : null, + "size" : 1, + "created_at" : "2015-02-27T20:56:32.033427", + "os-extended-snapshot-attributes:project_id" : "e0741109067649a8899936e9fefda95b", + "wrs-snapshot:backup_status" : "Export completed at 2015-02-27 20:57:29.279574", + "id" : "0aa45e0c-74ea-433e-b8f3-0dc778d3972b", + "metadata" : {}, + "os-extended-snapshot-attributes:progress" : "100%" + } + ] + } + +*********************************************** +Get information of a specific volume snapshot +*********************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/snapshots/​{snapshot_id}​ + +Preconditions + +- The specified volume snapshot must exist in all case. + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + "snapshot_id", "URI", "csapi:UUID", "The ID for the snapshot to list." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-snapshot:backup_status", "plain", "xsd:string", "Indicates backup status." + +:: + + { + "snapshot" : { + "volume_id" : "2c4f094b-f6d8-4ff6-800e-e5998cb4d6fa", + "status" : "available", + "display_description" : null, + "display_name" : null, + "size" : 1, + "created_at" : "2015-02-27T20:56:32.033427", + "os-extended-snapshot-attributes:project_id" : "e0741109067649a8899936e9fefda95b", + "wrs-snapshot:backup_status" : "Export completed at 2015-02-27 20:57:29.279574", + "id" : "0aa45e0c-74ea-433e-b8f3-0dc778d3972b", + "metadata" : {}, + "os-extended-snapshot-attributes:progress" : "100%" + } + } + +*************************************************************************** +Executes the specified action or command on the specified volume snapshot +*************************************************************************** + +.. rest_method:: POST /v2/​{tenant_id}​/snapshots/​{snapshot_id}​/action + +Preconditions + +- The specified volume snapshot must exist in all case. + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for the tenant or account in a multi-tenancy cloud." + "snapshot_id", "URI", "csapi:UUID", "The ID for the snapshot to list." + "wrs-snapshot:os-snapshot_export", "plain", "xsd:string", "Export volume snapshot to a file" + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "volume_type", "plain", "xsd:string", "Indicates the volume type." + "updated_at", "plain", "xsd:string", "Indicates when the action was performed." + "status", "plain", "xsd:string", "Indicates the state of the volume snapshot export action." + "id", "plain", "csapi:UUID", "Indicates the volume UUID." + "display_description", "plain", "xsd:string", "Volume descrition if any." + "volume_size", "plain", "xsd:int", "Indicates the volume size in Gbyte." + +:: + + { + "wrs-snapshot:os-export_snapshot" : { + "volume_type" : null, + "updated_at" : "2015-03-03T15:32:31.386661", + "status" : "exporting", + "volume_size" : 1, + "id" : "9ad36199-c5b3-44bf-9273-c298ab7a0a2b", + "display_description" : null + } + } + + diff --git a/api-ref/source/api-ref-compute-v2-cgcs-ext.rst b/api-ref/source/api-ref-compute-v2-cgcs-ext.rst new file mode 100644 index 000000000..ca576ea17 --- /dev/null +++ b/api-ref/source/api-ref-compute-v2-cgcs-ext.rst @@ -0,0 +1,1366 @@ +==================================================== +Compute API v2 StarlingX extensions +==================================================== + +StarlingX extensions to the OpenStack Compute API include: + +- Adding capability to specify VIF-Model on a per-NIC basis when + creating/launching/booting a VM Server. + +- Adding capability to specify VIF-PCI Address on a per-NIC basis when + creating/launching/booting a VM Server. + +- Adding an attribute to allow sorting of a VM Server's IP Addresses in + order of network attachment(NIC). + +- Adding the ability to scale the resources (currently only vCPUs) of a + VM Server up and down without requiring a restart of the VM Server. + +- Adding a number of new attributes and behavior to VM Server Groups; a + project_id attribute for ownership, an affinity-hyperthread policy + and best_effort and max group_size metadata attribute values. + +- Support for various new Flavor Extra Specs to enable + StarlingX-specific optimizations and capabilities for compute servers. + +- Adding the capability of displaying details about Provider Network + with regards to Nova usage. + +The typical port used for the Compute REST API is 8774. However, proper +technique would be to look up the nova service endpoint in keystone. + +----------- +Extensions +----------- + +The Extensions entity lists all available extensions + +********************************** +Lists all extensions - Compute API +********************************** + +.. rest_method:: GET /v2/​{tenant_id}​/extensions + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "namespace (Optional)", "plain", "xsd:string", "Indicates namespace of the extension." + "name (Optional)", "plain", "xsd:string", "Indicates name of the extension." + "updated (Optional)", "plain", "xsd:string", "Indicates updated time of the extension." + "description (Optional)", "plain", "xsd:string", "Indicates description of the extension." + "alias (Optional)", "plain", "xsd:string", "Indicates alias of the extension." + "links (Optional)", "plain", "xsd:list", "A list of links for the extension." + +:: + + { + "extensions" : [ + ... + { + "namespace" : "http://docs.windriver.com/tis/ext/wrs-if/api/v1.0", + "name" : "wrs-server-if", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Interface Related Extensions", + "alias" : "wrs-if", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.com/tis/ext/wrs-res/api/v1.0", + "name" : "wrs-server-resource", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Server Resource Extensions", + "alias" : "wrs-res", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.com/tis/ext/wrs-sg/api/v1.0", + "name" : "wrs-server-group", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Server Grouip Extensions", + "alias" : "wrs-sg", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.com/tis/ext/wrs/api/v1.0", + "name" : "wrs-flavor-extra-spec", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Extended Flavor Extra Spec Keys" + "alias" : "wrs", + "links" : [] + }, + ... + ] + } + +This operation does not accept a request body. + +********************************************************** +Gets information about a specified extension - Compute API +********************************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/extensions/​{extension_alias}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "extension_alias", "URI", "xsd:string", "The alias for the extension to list." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "namespace (Optional)", "plain", "xsd:string", "Indicates namespace of the extension." + "name (Optional)", "plain", "xsd:string", "Indicates name of the extension." + "updated (Optional)", "plain", "xsd:string", "Indicates updated time of the extension." + "description (Optional)", "plain", "xsd:string", "Indicates description of the extension." + "alias (Optional)", "plain", "xsd:string", "Indicates alias of the extension." + "links (Optional)", "plain", "xsd:list", "A list of links for the extension." + +:: + + { + "extension" : { + "namespace" : "http://docs.windriver.com/tis/ext/wrs-if/api/v1.0", + "name" : "wrs-server-if", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Interface Related Extensions", + "alias" : "wrs-if", + "links" : [] + } + } + + OR + + { + "extension" : { + "namespace" : "http://docs.windriver.com/tis/ext/wrs-res/api/v1.0", + "name" : "wrs-server-resource", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Server Resource Extensions", + "alias" : "wrs-res", + "links" : [] + } + } + + OR + + { + "extension" : { + "namespace" : "http://docs.windriver.com/tis/ext/wrs-sg/api/v1.0", + "name" : "wrs-server-group", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Server Group Extensions", + "alias" : "wrs-sg", + "links" : [] + } + } + + OR + + { + "extension" : { + "namespace" : "http://docs.windriver.com/tis/ext/wrs/api/v1.0", + "name" : "wrs-flavor-extra-spec", + "updated" : "2014-08-16T00:00:00+00:00", + "description" : "WRS Extended Flavor Extra Spec Keys" + "alias" : "wrs", + "links" : [] + } + } + +This operation does not accept a request body. + +------- +Server +------- + +The StarlingX extensions to the server entity are: + +- Adding capability to specify VIF-Model on a per-NIC basis when + creating/launching/booting a VM Server. + +- Adding capability to specify VIF-PCI Address on a per-NIC basis when + creating/launching/booting a VM Server. + +- Adding the ability to scale the resources (currently only vCPUs) of a + server up and down without requiring a restart of the VM Server. + +- Adding an attribute to allow sorting of a VM Server's IP Addresses in + order of network attachment(NIC). + +****************** +Creates a server +****************** + +.. rest_method:: POST /v2/​{tenant_id}​/servers + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "networks (Optional)", "plain", "xsd:list", "A ``networks`` object. By default, the server instance is provisioned with all isolated networks for the tenant. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a ``nova-network`` network, specify the UUID in the ``uuid`` attribute in a ``network`` object. To provision the server instance with a NIC for a ``neutron`` network, specify the UUID in the ``port`` attribute in a ``network`` object. In StarlingX, to optionally provision the vif model of the NIC, specify the appropriate value in the wrs-if:vif_model`` attribute in the network`` object. Valid vif model values are: e1000``, virtio``, ne2k_pci``, pcnet``, rtl8139``, pci-passthrough``, pci-sriov``. If not specified, a vif model of virtio`` will be used. To provision the PCI address of the NIC, specify the appropriate value in the ``wrs-if:vif_pci_address`` attribute in the ``network`` object. Valid PCI address values are in the ``domain:bus:slot.function`` format. If not specified, a PCI address will be chosen by the hypervisor. You can specify multiple NICs on the server." + +:: + + { + "server": { + "name": "testvm", + "imageRef": "ec42f67b-1dcd-4f09-aa02-7a426737c20a", + "flavorRef": "2", + "networks": [ + { + "wrs-if:vif_model": "e1000", + "uuid": "06937e9e-0acd-4ad5-a6bb-f82d8896d5e8" + }, + { + "wrs-if:vif_pci_address": "0000:04:12.0", + "uuid": "cdc149b5-9122-4a16-975c-6acb973f49c3" + }, + { + "uuid": "b7adf5a0-3c5a-47f3-b733-8d56d12d2f45" + } + ] + } + } + +:: + + { + "server": { + "adminPass": "yjzytFHb7XHc", + "id": "f8f4f3ce-f6e0-4e05-8f79-bf984fdfce45", + "links": [ + { + "href": "http://openstack.example.com/v2/openstack/servers/f8f4f3ce-f6e0-4e05-8f79-bf984fdfce45", + "rel": "self" + }, + { + "href": "http://openstack.example.com/openstack/servers/f8f4f3ce-f6e0-4e05-8f79-bf984fdfce45", + "rel": "bookmark" + } + ] + } + } + +************************** +Lists details of servers +************************** + +.. rest_method:: GET /v2/​{tenant_id}​/servers/detail + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "servers", "plain", "xsd:list", "The list of ``server`` objects." + "nics (Optional)", "plain", "xsd:list", "A ``nics`` object. Contains the list of NICs provisioned on the server instance. Optionally, in StarlingX, each NIC can contain:
  • A ``wrs-if:vif_model`` attribute specifying the NICs vif model; where valid vif model values are: ``e1000``, ``virtio``, ``ne2k_pci``, ``pcnet``, ``rtl8139``, ``pci-passthrough``, ``pci-sriov``. If not specified, a vif model of ``virtio`` is being used.
  • A ``wrs-if:vif_pci_address`` attibute specifying the NICs PCI address. If not specified, the PCI address in the guest is chosen by the hypervisor and this value is empty.
" + "addresses (Optional)", "plain", "xsd:list", "An ``addresses`` object. Contains the list of addresses associated with the server instance." + "wrs-if:nics (Optional)", "plain", "xsd:list", "An ``wrs-if:nics`` object. Contains the list of NIC devices allocated for a VM instance. These are a VM representation of the neutron port objects associated to the VM. They are listed in the same order which the network attachments were specified when the VM was launched." + "wrs-res:topology (Optional)", "plain", "xsd:string", "This attribute specifies a number of resource details of the VM Server; the number of numa nodes, the amount of memory and the memory page size, and the current number of VCPUs." + "wrs-res:pci_devices (Optional)", "plain", "xsd:string", "List of pci devices associated with the server instance; indicates the numa node, pci address, type of device, vendor id, product id." + "wrs-res:vcpus (min/cur/max) (Optional)", "plain", "xsd:list", "This attribute specifies the minimum number of vcpus, current number of vcpus and maximum number of vcpus of a VM Server." + "wrs-sg:server_group (Optional)", "plain", "xsd:string", "This attribute specifies the server group which the VM Server is in; a null-string if the VM Server is not in a server group." + +:: + + { + "servers" : [ + { + "accessIPv4" : "", + "wrs-if:nics" : [ + { + "nic1" : { + "network" : "tenant1-mgmt-net", + "port_id" : "dc627524-64a9-4fec-957a-b271f353fb22", + "vif_model" : "virtio", + "vif_pci_address": "0000:04:12.0", + "mtu" : 1500 + } + } + ], + "OS-EXT-SRV-ATTR:instance_name" : "instance-0000003d", + "OS-SRV-USG:terminated_at" : null, + "accessIPv6" : "", + "config_drive" : "", + "OS-DCF:diskConfig" : "MANUAL", + "wrs-sg:server_group" : "", + "updated" : "2015-04-01T20:32:57Z", + "metadata" : {}, + "id" : "770a214c-5d22-42ce-9273-f6baab0ad7fd", + "flavor" : { + "id" : "00bbded9-318a-461a-aef8-3904356ca8d9", + "links" : [ + { + "rel" : "bookmark", + "href" : "http://128.224.151.243:8774/101d1cffc5ec4accbdb075c89a4c5cd7/flavors/00bbded9-318a-461a-aef8-3904356ca8d9" + } + ] + }, + "links" : [ + { + "rel" : "self", + "href" : "http://128.224.151.243:8774/v2/101d1cffc5ec4accbdb075c89a4c5cd7/servers/770a214c-5d22-42ce-9273-f6baab0ad7fd" + }, + { + "rel" : "bookmark", + "href" : "http://128.224.151.243:8774/101d1cffc5ec4accbdb075c89a4c5cd7/servers/770a214c-5d22-42ce-9273-f6baab0ad7fd" + } + ], + "OS-EXT-SRV-ATTR:host" : "compute-0", + "OS-EXT-AZ:availability_zone" : "nova", + "name" : "vm07-shared-vcpu-id", + "hostId" : "938254ae1b04aabc901dd4ad2cf2a561a4eab858efa0b0a48eb048ff", + "user_id" : "13dbcb9d22474c39a4a612cd44bf58ad", + "status" : "ACTIVE", + "wrs-res:topology" : "node:1, 1024MB, pgsize:4K, vcpus:3", + "wrs-res:pci_devices": "node:1, addr:0000:83:04.6, type:VF, vendor:8086, product:0443", + "OS-EXT-STS:power_state" : 1, + "OS-EXT-SRV-ATTR:hypervisor_hostname" : "compute-0", + "tenant_id" : "101d1cffc5ec4accbdb075c89a4c5cd7", + "OS-SRV-USG:launched_at" : "2015-04-01T20:32:57.000000", + "OS-EXT-STS:vm_state" : "active", + "OS-EXT-STS:task_state" : null, + "progress" : 0, + "key_name" : null, + "image" : { + "id" : "a99dfaa7-c850-4a63-ad99-d4a5f8da3069", + "links" : [ + { + "rel" : "bookmark", + "href" : "http://128.224.151.243:8774/101d1cffc5ec4accbdb075c89a4c5cd7/images/a99dfaa7-c850-4a63-ad99-d4a5f8da3069" + } + ] + }, + "wrs-res:vcpus (min/cur/max)" : [ + 3, + 3, + 3 + ], + "created" : "2015-04-01T20:32:49Z", + "addresses" : { + "tenant1-mgmt-net" : [ + { + "OS-EXT-IPS:type" : "fixed", + "version" : 4, + "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:fc:65:81", + "addr" : "192.168.102.6" + } + ] + }, + "os-extended-volumes:volumes_attached" : [] + } + ] + } + +This operation does not accept a request body. + +************************************** +Shows details for a specified server +************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/servers/​{server_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "server_id", "URI", "csapi:UUID", "The ID for the server of interest to you." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "server", "plain", "xsd:dict", "The requested ``server`` object." + "nics (Optional)", "plain", "xsd:list", "A ``nics`` object. Contains the list of NICs provisioned on the server instance. Optionally, in StarlingX, each NIC can contain:
  • A ``wrs-if:vif_model`` attribute specifying the NICs vif model; where valid vif model values are: ``e1000``, ``virtio``, ``ne2k_pci``, ``pcnet``, ``rtl8139``, ``pci-passthrough``, ``pci-sriov``. If not specified, a vif model of ``virtio`` is being used.
  • A ``wrs-if:vif_pci_address`` attibute specifying the NICs PCI address. If not specified, the PCI address in the guest is chosen by the hypervisor and this value is empty.
" + "addresses (Optional)", "plain", "xsd:list", "An ``addresses`` object. Contains the list of addresses associated with the server instance." + "wrs-if:nics (Optional)", "plain", "xsd:list", "An ``wrs-if:nics`` object. Contains the list of NIC devices allocated for a VM instance. These are a VM representation of the neutron port objects associated to the VM. They are listed in the same order which the network attachments were specified when the VM was launched." + "wrs-res:topology (Optional)", "plain", "xsd:string", "This attribute specifies a number of resource details of the VM Server; the number of numa nodes, the amount of memory and the memory page size, and the current number of VCPUs." + "wrs-res:pci_devices (Optional)", "plain", "xsd:string", "List of pci devices associated with the server instance; indicates the numa node, pci address, type of device, vendor id, product id." + "wrs-res:vcpus (min/cur/max) (Optional)", "plain", "xsd:list", "This attribute specifies the minimum number of vcpus, current number of vcpus and maximum number of vcpus of a VM Server." + "wrs-sg:server_group (Optional)", "plain", "xsd:string", "This attribute specifies the server group which the VM Server is in; a null-string if the VM Server is not in a server group." + +:: + + { + "server" : { + "accessIPv4" : "", + "wrs-if:nics" : [ + { + "nic1" : { + "network" : "tenant1-mgmt-net", + "port_id" : "dc627524-64a9-4fec-957a-b271f353fb22", + "vif_model" : "virtio", + "vif_pci_address": "0000:04:12.0", + "mtu" : 1500 + } + } + ], + "OS-EXT-SRV-ATTR:instance_name" : "instance-0000003d", + "OS-SRV-USG:terminated_at" : null, + "accessIPv6" : "", + "config_drive" : "", + "OS-DCF:diskConfig" : "MANUAL", + "wrs-sg:server_group" : "", + "updated" : "2015-04-01T20:32:57Z", + "metadata" : {}, + "id" : "770a214c-5d22-42ce-9273-f6baab0ad7fd", + "flavor" : { + "id" : "00bbded9-318a-461a-aef8-3904356ca8d9", + "links" : [ + { + "rel" : "bookmark", + "href" : "http://128.224.151.243:8774/101d1cffc5ec4accbdb075c89a4c5cd7/flavors/00bbded9-318a-461a-aef8-3904356ca8d9" + } + ] + }, + "links" : [ + { + "rel" : "self", + "href" : "http://128.224.151.243:8774/v2/101d1cffc5ec4accbdb075c89a4c5cd7/servers/770a214c-5d22-42ce-9273-f6baab0ad7fd" + }, + { + "rel" : "bookmark", + "href" : "http://128.224.151.243:8774/101d1cffc5ec4accbdb075c89a4c5cd7/servers/770a214c-5d22-42ce-9273-f6baab0ad7fd" + } + ], + "OS-EXT-SRV-ATTR:host" : "compute-0", + "OS-EXT-AZ:availability_zone" : "nova", + "name" : "vm07-shared-vcpu-id", + "hostId" : "938254ae1b04aabc901dd4ad2cf2a561a4eab858efa0b0a48eb048ff", + "user_id" : "13dbcb9d22474c39a4a612cd44bf58ad", + "status" : "ACTIVE", + "wrs-res:topology" : "node:1, 1024MB, pgsize:4K, vcpus:3", + "wrs-res:pci_devices": "node:1, addr:0000:83:04.6, type:VF, vendor:8086, product:0443", + "OS-EXT-STS:power_state" : 1, + "OS-EXT-SRV-ATTR:hypervisor_hostname" : "compute-0", + "tenant_id" : "101d1cffc5ec4accbdb075c89a4c5cd7", + "OS-SRV-USG:launched_at" : "2015-04-01T20:32:57.000000", + "OS-EXT-STS:vm_state" : "active", + "OS-EXT-STS:task_state" : null, + "progress" : 0, + "key_name" : null, + "image" : { + "id" : "a99dfaa7-c850-4a63-ad99-d4a5f8da3069", + "links" : [ + { + "rel" : "bookmark", + "href" : "http://128.224.151.243:8774/101d1cffc5ec4accbdb075c89a4c5cd7/images/a99dfaa7-c850-4a63-ad99-d4a5f8da3069" + } + ] + }, + "wrs-res:vcpus (min/cur/max)" : [ + 3, + 3, + 3 + ], + "created" : "2015-04-01T20:32:49Z", + "addresses" : { + "tenant1-mgmt-net" : [ + { + "OS-EXT-IPS:type" : "fixed", + "version" : 4, + "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:fc:65:81", + "addr" : "192.168.102.6" + } + ] + }, + "os-extended-volumes:volumes_attached" : [] + } + } + +This operation does not accept a request body. + +**************************************************************************************************************************************************** +Allows the resources associated with the server (currently only the number of CPUs) to be scaled up and down without requiring a restart of the VM +**************************************************************************************************************************************************** + +.. rest_method:: POST /v2/​{tenant_id}​/servers/​{server_id}​/action + +**Normal response codes** + +202 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "server_id", "URI", "csapi:UUID", "The ID for the server of interest to you." + "wrs-res:scale", "plain", "xsd:string", "Specify the ``wrs-res:scale`` action in the request body." + "direction", "plain", "xsd:string", "Direction to scale, ""up"" or ""down"". This will result in scaling the specified resource by one unit in the specified direction." + "resource", "plain", "xsd:string", "Resource to scale. Currently only ""cpu"" is supported." + +:: + + { + "wrs-res:scale": { + "direction": "up", + "resource": cpu + } + } + +This operation does not return a response body. + +***************** +Create Interface +***************** + +.. rest_method:: POST /v2/​{tenant_id}​/servers/​{server_id}​/os-interface + +**Normal response codes** + +202 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "server_id", "URI", "csapi:UUID", "The ID for the server of interest to you." + "wrs-if:vif_model (Optional)", "plain", "string", "Requested VIF model." + +:: + + { + "interfaceAttachment": { + "net_id": "e8b9af5e-1f47-429e-9ee0-fef202d4ea14", + "wrs-if:vif_model": "virtio" + } + } + +This operation does not return a response body. + +--------------------------------- +Server Groups (os-server-groups) +--------------------------------- + +The StarlingX extensions to the Server Groups entity are: + +- Added a 'wrs-sg:project_id' attribute to assign tenant ownership to a + Server Group. + +- Added a 'wrs-sg:affinity-hyperthread' policy to indicate that members + of the Server Group are allowed to share hyperthread siblings. + +- Added a boolean 'wrs-sg:best_effort' metadata key/value in order to + specify whether the policy should be strictly enforced or not. + +- Added an integer 'wrs-sg:group_size' metadata key/value in order to + specify the maximum number of members in the group. + +********************* +Lists server groups +********************* + +.. rest_method:: GET /v2/​{tenant_id}​/os-server-groups + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "server_groups", "plain", "xsd:list", "The list of ``server_group`` objects." + "wrs-sg:project_id", "plain", "csapi:UUID", "The tenant or project owning the server group." + "policies", "plain", "xsd:list", "A list of policies associated with the server group. StarlingX added ``wrs-sg:affinity-hyperthread`` policy to indicate that ``only`` the members of this server group can share sibling threads with each other." + "metadata", "plain", "xsd:dict", "Associated metadata key-and-value pairs. StarlingX added a boolean valued ``wrs-sg:best_effort`` metadata key-and-value pair to indicate whether the server groups policy should be strictly enforced or not. StarlingX added an integer valued ``wrs-sg:group_size`` metadata key-and-value pair to indicate the maximum number of members of the server group." + +:: + + { + "server_groups": [ + { + "id": "616fb98f-46ca-475e-917e-2563e5a8cd19", + "wrs-sg:project_id": "28d41dbebab24bdf8854a6632271a3f6" + "name": "callservergroup", + "policies": [ + "wrs-sg:affinity-hyperthread" + ], + "members": [], + "metadata": { + "wrs-sg:best_effort": "1", + "wrs-sg:group_size": "2" + } + }, + { + "id": "2fb919a2-4666-11e4-9255-080027367628", + "wrs-sg:project_id": "28d41dbebab24bdf8854a6632271a3f6" + "name": "antiaffinitygroup", + "policies": [ + "anti-affinity" + ], + "members": [], + "metadata": {} + } + ] + } + +This operation does not accept a request body. + +************************ +Creates a server group +************************ + +.. rest_method:: POST /v2/​{tenant_id}​/os-server-groups + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "wrs-sg:project_id", "plain", "csapi:UUID", "The project or tenant ID which owns this server group." + "policies (Optional)", "plain", "xsd:list", "The scheduler policy to associate with the server group. Modified by StarlingX to include the following additional policy:
  • ``wrs-sg:affinity-hyperthread`` which will try to put servers on the same compute node and have servers sharing sibling hyperthread cores with each other, and only each other. Server Groups using this policy are restriceted to a maximum of 2 members.
" + "metadata (Optional)", "plain", "xsd:dict", "This parameter specifies a dictionary of optional metadata to be associated with the group. Additional keys added by StarlingX are:
  • ``wrs-sg:best_effort`` (where a value of 0 means that the scheduler policy will be strictly applied and a value of 1 means that the server will still be scheduled even if the policy can't be met).
  • ``wrs-sg:group_size`` (where the value is an integer specifying the max number of servers in the group).
" + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "server_group", "plain", "xsd:dict", "The requested ``server_group`` object." + "wrs-sg:project_id", "plain", "csapi:UUID", "The tenant or project owning the server group." + "policies", "plain", "xsd:list", "A list of policies associated with the server group. StarlingX added ``wrs-sg:affinity-hyperthread`` policy to indicate that ``only`` the members of this server group can share sibling threads with each other." + "metadata", "plain", "xsd:dict", "Associated metadata key-and-value pairs. StarlingX added a boolean valued ``wrs-sg:best_effort`` metadata key-and-value pair to indicate whether the server groups policy should be strictly enforced or not. StarlingX added an integer valued ``wrs-sg:group_size`` metadata key-and-value pair to indicate the maximum number of members of the server group." + +:: + + { + "server_group": { + "name": "antiaffinitygroup", + "wrs-sg:project_id": "28d41dbebab24bdf8854a6632271a3f6" + "policies": [ + "anti-affinity" + ], + "metadata": { + "wrs-sg:best_effort": "1", + "wrs-sg:group_size": "2" + } + } + } + +:: + + { + "server_group": { + "id": "5bbcc3c4-1da2-4437-a48a-66f15b1b13f9", + "wrs-sg:project_id": "28d41dbebab24bdf8854a6632271a3f6" + "name": "antiaffinitygroup", + "policies": [ + "anti-affinity" + ], + "members": [], + "metadata": { + "wrs-sg:best_effort": "1", + "wrs-sg:group_size": "2" + } + } + } + +******************************************** +Shows details for a specified server group +******************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/os-server-groups/​{ServerGroup_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "ServerGroup_id", "URI", "csapi:UUID", "The server group ID." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "server_group", "plain", "xsd:dict", "The requested ``server_group`` object." + "wrs-sg:project_id", "plain", "csapi:UUID", "The tenant or project owning the server group." + "policies", "plain", "xsd:list", "A list of policies associated with the server group. StarlingX added ``wrs-sg:affinity-hyperthread`` policy to indicate that ``only`` the members of this server group can share sibling threads with each other." + "metadata", "plain", "xsd:dict", "Associated metadata key-and-value pairs. StarlingX added a boolean valued ``wrs-sg:best_effort`` metadata key-and-value pair to indicate whether the server groups policy should be strictly enforced or not. StarlingX added an integer valued ``wrs-sg:group_size`` metadata key-and-value pair to indicate the maximum number of members of the server group." + +:: + + { + "server_group": { + "id": "616fb98f-46ca-475e-917e-2563e5a8cd19", + "wrs-sg:project_id": "28d41dbebab24bdf8854a6632271a3f6" + "name": "callservergroup", + "policies": [ + "wrs-sg:affinity-hyperthread" + ], + "members": [], + "metadata": { + "wrs-sg:best_effort": "1", + "wrs-sg:group_size": "2" + } + } + } + +This operation does not accept a request body. + +------------------- +Flavor Extra Specs +------------------- + +StarlingX has added several flavor extra specs, e.g. +``sw:wrs:guest:heartbeat``, ``hw:wrs:shared_vcpu``, +``hw:wrs:min_vcpus``, ``sw:wrs:vtpm`` and many more. + +******************************************************** +Lists the extra-specs or keys for the specified flavor +******************************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "flavor_id", "URI", "String", "The ID of the flavor of interest to you." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "extra_specs (Optional)", "plain", "xsd:list", "The list of flavor extra specs." + "sw:wrs:guest:heartbeat (Optional)", "plain", "xsd:boolean", "Indicates whether or not the guest applications running in the virtual machine make use of the StarlingX Heartbeat client API." + "sw:wrs:vtpm (Optional)", "plain", "xsd:boolean", "Indicates whether or not to expose a TPM device to the Guest." + "hw:wrs:shared_vcpu (Optional)", "plain", "xsd:integer", "Indicates the vCPU of the guest virtual machine that will be scheduled to run on a shared CPU of the host. Note, this can be specified even if hw:cpu_policy is set to dedicated; allowing the guest application to use dedicated cores exclusively for its high-load tasks, but use a shared core for its low-load (e.g. management type) tasks." + "hw:wrs:min_vcpus (Optional)", "plain", "xsd:integer", "Indicates the minimum number of vCPUs for the virtual machine. The value must be between one and the number of VCPUs in the flavor of the virtual machine. If this extra_spec is specified then the server is assumed to support vCPU scaling." + "extra spec (Optional)", "plain", "xsd:integer", "StarlingX has added several flavor extra specs." + +:: + + { + "extra_specs": { + "sw:wrs:guest:heartbeat": "True", + "sw:wrs:srv_grp_messaging": "True", + "sw:wrs:vtpm": "False", + "hw:numa_node.0": "1", + "hw:wrs:vcpu:scheduler": "fifo:50:0" + "hw:wrs:min_vcpus": "2" + "hw:wrs:shared_vcpu": "1" + "hw:cpu_model": "Nehalem" + "aggregate_instance_extra_specs:localstorage": "False" + } + } + +This operation does not accept a request body. + +************************************** +Gets the value of the specified key +************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs/​{key_id}​ + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "flavor_id", "URI", "String", "The ID of the flavor of interest to you." + "key_id", "URI", "xsd:string", "The key of the extra-spec of interest to you." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "sw:wrs:guest:heartbeat (Optional)", "plain", "xsd:boolean", "Indicates whether or not the guest applications running in the virtual machine make use of the StarlingX Heartbeat client API." + "sw:wrs:vtpm (Optional)", "plain", "xsd:boolean", "Indicates whether or not to expose a TPM device to the Guest." + "hw:wrs:shared_vcpu (Optional)", "plain", "xsd:integer", "Indicates the vCPU of the guest virtual machine that will be scheduled to run on a shared CPU of the host. Note, this can be specified even if hw:cpu_policy is set to dedicated; allowing the guest application to use dedicated cores exclusively for its high-load tasks, but use a shared core for its low-load (e.g. management type) tasks." + "hw:wrs:min_vcpus (Optional)", "plain", "xsd:integer", "Indicates the minimum number of vCPUs for the virtual machine. The value must be between one and the number of VCPUs in the flavor of the virtual machine. If this extra_spec is specified then the server is assumed to support vCPU scaling." + "extra spec (Optional)", "plain", "xsd:integer", "StarlingX has added several flavor extra specs." + +:: + + { + "sw:wrs:guest:heartbeat": "True", + } + +This operation does not accept a request body. + +****************************************************** +Creates extra-specs or keys for the specified flavor +****************************************************** + +.. rest_method:: POST /v2/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs + +**Normal response codes** + +200 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "flavor_id", "URI", "String", "The ID of the flavor of interest to you." + "extra_specs (Optional)", "plain", "xsd:list", "The list of flavor extra specs." + "sw:wrs:guest:heartbeat (Optional)", "plain", "xsd:boolean", "Indicates whether or not the guest applications running in the virtual machine make use of the StarlingX Heartbeat client API." + "sw:wrs:vtpm (Optional)", "plain", "xsd:boolean", "Indicates whether or not to expose a TPM device to the Guest." + "hw:wrs:shared_vcpu (Optional)", "plain", "xsd:integer", "Indicates the vCPU of the guest virtual machine that will be scheduled to run on a shared CPU of the host. Note, this can be specified even if hw:cpu_policy is set to dedicated; allowing the guest application to use dedicated cores exclusively for its high-load tasks, but use a shared core for its low-load (e.g. management type) tasks." + "hw:wrs:min_vcpus (Optional)", "plain", "xsd:integer", "Indicates the minimum number of vCPUs for the virtual machine. The value must be between one and the number of VCPUs in the flavor of the virtual machine. If this extra_spec is specified then the server is assumed to support vCPU scaling." + "extra spec (Optional)", "plain", "xsd:integer", "StarlingX has added several flavor extra specs." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "sw:wrs:guest:heartbeat (Optional)", "plain", "xsd:boolean", "Indicates whether or not the guest applications running in the virtual machine make use of the StarlingX Heartbeat client API." + "sw:wrs:vtpm (Optional)", "plain", "xsd:boolean", "Indicates whether or not to expose a TPM device to the Guest." + "hw:wrs:shared_vcpu (Optional)", "plain", "xsd:integer", "Indicates the vCPU of the guest virtual machine that will be scheduled to run on a shared CPU of the host. Note, this can be specified even if hw:cpu_policy is set to dedicated; allowing the guest application to use dedicated cores exclusively for its high-load tasks, but use a shared core for its low-load (e.g. management type) tasks." + "hw:wrs:min_vcpus (Optional)", "plain", "xsd:integer", "Indicates the minimum number of vCPUs for the virtual machine. The value must be between one and the number of VCPUs in the flavor of the virtual machine. If this extra_spec is specified then the server is assumed to support vCPU scaling." + "extra spec (Optional)", "plain", "xsd:integer", "StarlingX has added several flavor extra specs." + +:: + + { + "extra_specs": { + "sw:wrs:guest:heartbeat": "True", + } + } + +:: + + { + "extra_specs": { + "sw:wrs:guest:heartbeat": "True", + } + } + +----------------- +Provider Network +----------------- + +The StarlingX extensions to the Provider Network entity are: + +******************************************** +List the provider networks (not supported) +******************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/wrs-providernet + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + +This operation does not accept a request body and does not return a +response body. + +*************************************************** +Show the details of a particular provider network +*************************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/wrs-providernet/​{providernet_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "providernet_id", "URI", "String", "The ID of the provider network of interest to you." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet (Optional)", "plain", "xsd:dict", "The requested ``provider network`` object." + "id (Optional)", "plain", "csapi:UUID", "The ID of the provider network." + "name (Optional)", "plain", "xsd:string", "The name of the provider network." + "pci_pfs_configured (Optional)", "plain", "xsd:integer", "The number of configured PCI devices (PFs)." + "pci_pfs_used (Optional)", "plain", "xsd:integer", "The number of used PCI devices (PFs)." + "pci_vfs_configured (Optional)", "plain", "xsd:integer", "The number of configured SR-IOV PCI devices (VFs)." + "pci_vfs_used (Optional)", "plain", "xsd:integer", "The number of used SR-IOV PCI devices (VFs)." + +:: + + { + "providernet": { + "pci_pfs_used": 0, + "pci_pfs_configured": 0, + "pci_vfs_used": 1, + "pci_vfs_configured": 16, + "id": "21c41131-07fb-43ac-a6f3-8a8020152530", + "name": "group0-data0" + } + } + +This operation does not accept a request body. + +---- +PCI +---- + +The StarlingX extensions to the PCI device entity are: + +******************************************************************************* +List PCI device usage statistics. This excludes network interface cards (NICs) +******************************************************************************* + +.. rest_method:: GET /v2/​{tenant_id}​/wrs-pci + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "device_name (Optional)", "plain", "xsd:string", "The name of device." + "device_id (Optional)", "plain", "xsd:string", "The device id of device." + "vendor_id (Optional)", "plain", "xsd:string", "The vendor id of device." + "class_id (Optional)", "plain", "xsd:string", "The class id of device." + "pci_pfs_configured (Optional)", "plain", "xsd:integer", "The number of configured PCI devices (PFs)." + "pci_pfs_used (Optional)", "plain", "xsd:integer", "The number of used PCI devices (PFs)." + "pci_vfs_configured (Optional)", "plain", "xsd:integer", "The number of configured SR-IOV PCI devices (VFs)." + "pci_vfs_used (Optional)", "plain", "xsd:integer", "The number of used SR-IOV PCI devices (VFs)." + +:: + + { + "pci_device_usage": [ + { + "pci_pfs_used": 0, + "pci_pfs_configured": 0, + "pci_vfs_used": 1, + "vendor_id": "8086", + "pci_vfs_configured": 64, + "device_name": "Coleto Creek PCIe Co-processor", + "device_id": "0443", + "class_id": "0b4000" + } + ] + } + +This operation does not accept a request body. + +**************************************************** +Show the usage details of a particular PCI device +**************************************************** + +.. rest_method:: GET /v2/​{tenant_id}​/wrs-pci/​{device_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "xsd:string", "The ID for the tenant or account in a multi-tenancy cloud." + "device_id", "URI", "String", "The device id of the pci device of interest to you." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "device_name (Optional)", "plain", "xsd:string", "The name of device." + "device_id (Optional)", "plain", "xsd:string", "The device id of device." + "vendor_id (Optional)", "plain", "xsd:string", "The vendor id of device." + "class_id (Optional)", "plain", "xsd:string", "The class id of device." + "host (Optional)", "plain", "xsd:string", "The name of the compute host." + "pci_pfs_configured (Optional)", "plain", "xsd:integer", "The number of configured PCI devices (PFs)." + "pci_pfs_used (Optional)", "plain", "xsd:integer", "The number of used PCI devices (PFs)." + "pci_vfs_configured (Optional)", "plain", "xsd:integer", "The number of configured SR-IOV PCI devices (VFs)." + "pci_vfs_used (Optional)", "plain", "xsd:integer", "The number of used SR-IOV PCI devices (VFs)." + +:: + + { + "pci_device_usage": [ + { + "pci_vfs_used": 0, + "host": "compute-3", + "pci_pfs_used": 0, + "pci_pfs_configured": 0, + "pci_vfs_configured": 0, + "device_name": "Coleto Creek PCIe Co-processor", + "vendor_id": "8086", + "device_id": "0443", + "class_id": "0b4000" + }, + { + "pci_vfs_used": 1, + "host": "compute-1", + "pci_pfs_used": 0, + "pci_pfs_configured": 0, + "pci_vfs_configured": 32, + "device_name": "Coleto Creek PCIe Co-processor", + "vendor_id": "8086", + "device_id": "0443", + "class_id": "0b4000" + }, + { + "pci_vfs_used": 0, + "host": "compute-2", + "pci_pfs_used": 0, + "pci_pfs_configured": 0, + "pci_vfs_configured": 0, + "device_name": "Coleto Creek PCIe Co-processor", + "vendor_id": "8086", + "device_id": "0443", + "class_id": "0b4000" + }, + { + "pci_vfs_used": 0, + "host": "compute-0", + "pci_pfs_used": 0, + "pci_pfs_configured": 0, + "pci_vfs_configured": 32, + "device_name": "Coleto Creek PCIe Co-processor", + "vendor_id": "8086", + "device_id": "0443", + "class_id": "0b4000" + } + ] + } + +This operation does not accept a request body. + +------------ +Hypervisors +------------ + +The StarlingX extensions to the Hypervisor entity are: + +****************************************** +Shows details for a specified hypervisor +****************************************** + +.. rest_method:: GET /v2/os-hypervisors/​{hypervisor_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "hypervisor_id", "URI", "csapi:UUID", "The ID for the hypervisor of interest to you." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "memory_mb_by_node", "plain", "xsd:string", "lists available memory, in Megabytes, based on page size (4K, 2M, 1G) on each NUMA node. The sum total must match the number reported in ``memory_mb``." + "memory_mb_used_by_node", "plain", "xsd:string", "lists memory currently in use, in Megabytes, based on page size (4K, 2M, 1G) on each NUMA node. The sum total must match the number reported in ``memory_mb_used``." + "vcpus_by_node", "plain", "xsd:string", "lists available vcpus, on each NUMA node. The sum total must match the quantity reported by ``vcpus``." + "vcpus_used_by_node", "plain", "xsd:string", "lists vcpus currently in use, on each NUMA node. The sum total must match the quantity reported by ``vcpus_used``." + +:: + + { + "hypervisor":{ + "memory_mb_used_by_node":"{\"0\": {\"2M\": 5120, \"4K\": 0, \"1G\": 0}, \"1\": {\"2M\": 0, \"4K\": 0, \"1G\": 0}}", + "cpu_info":{ + "arch":"x86_64", + "model":"IvyBridge", + "vendor":"Intel", + "features":[ + "pge", + "avx", + "vmx", + "clflush", + "sep", + "syscall", + "vme", + "dtes64", + "tsc", + "sse", + "xsave", + "xsaveopt", + "erms", + "xtpr", + "cmov", + "smep", + "ssse3", + "est", + "pat", + "monitor", + "smx", + "pcid", + "lm", + "msr", + "nx", + "fxsr", + "tm", + "sse4.1", + "pae", + "sse4.2", + "pclmuldq", + "acpi", + "tsc-deadline", + "popcnt", + "mmx", + "osxsave", + "cx8", + "mce", + "de", + "tm2", + "ht", + "dca", + "pni", + "pdcm", + "mca", + "pdpe1gb", + "apic", + "fsgsbase", + "f16c", + "pse", + "ds", + "invtsc", + "lahf_lm", + "aes", + "sse2", + "ss", + "ds_cpl", + "arat", + "pbe", + "fpu", + "cx16", + "pse36", + "mtrr", + "rdrand", + "rdtscp", + "x2apic" + ], + "topology":{ + "cores":10, + "cells":2, + "threads":2, + "sockets":1 + } + }, + "free_disk_gb":208, + "memory_mb_used":5120, + "vcpus_by_node":"{\"0\": 14, \"1\": 20}", + "memory_mb_by_node":"{\"0\": {\"2M\": 21440, \"4K\": 0, \"1G\": 0}, \"1\": {\"2M\": 29088, \"4K\": 0, \"1G\": 0}}", + "service":{ + "host":"compute-1", + "disabled_reason":null, + "id":8 + }, + "local_gb_used":9, + "id":2, + "current_workload":0, + "state":"up", + "vcpus_used_by_node":"{\"0\": {\"shared\": 0.125, \"dedicated\": 6}, \"1\": {\"shared\": 0.0, \"dedicated\": 0}}", + "status":"enabled", + "host_ip":"192.168.205.205", + "hypervisor_hostname":"compute-1", + "hypervisor_version":2006000, + "disk_available_least":208, + "local_gb":219, + "free_ram_mb":45408, + "vcpus_used":6.125, + "hypervisor_type":"QEMU", + "memory_mb":50528, + "vcpus":34, + "running_vms":7 + } + } + +This operation does not accept a request body. + + + diff --git a/api-ref/source/api-ref-image-v2-cgcs-ext.rst b/api-ref/source/api-ref-image-v2-cgcs-ext.rst new file mode 100644 index 000000000..d29fd9628 --- /dev/null +++ b/api-ref/source/api-ref-image-v2-cgcs-ext.rst @@ -0,0 +1,390 @@ +==================================================== +Image API v2 StarlingX extensions +==================================================== + +StarlingX extensions to the OpenStack Image API to support additional +properties on images for customizing migration behaviour, supporting raw +cached images in ceph cluster, disabling VM auto-recovery and indicating +the backend where the image is stored. + +The typical port used for the Image REST API is 9292. However, proper +technique would be to look up the image/glance service endpoint in +Keystone. + +------- +Images +------- + +The Image entity is extended by StarlingX to have additional +properties on images for customizing migration behaviour, supporting raw +cached images in ceph cluster, disabling VM auto-recovery and indicating +the backend where the image is stored. + +****************** +Creates an image +****************** + +.. rest_method:: POST /v2/images + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. NOTE that the extensions listed here are +``additional properties`` which are supported in the Image API and +implemented in a Stack-specific manner. + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "cache_raw (Optional)", "plain", "xsd:bool", "On systems using Ceph storage, boot image files must be converted to RAW format before they can be used to create volumes. You can accelerate volume creation in StarlingX (and therefore instance launch time) by caching the RAW images as they are created. The cached images are maintained in the Glance image storage space and used for volume creation, eliminating conversion time. The default behaviour is to NOT cache the raw format." + "sw_wrs_auto_recovery (Optional)", "plain", "xsd:bool", "Indicates whether auto recovery of failed virutal machine instances is enabled or not. The default is True." + "hw_wrs_live_migration_timeout (Optional)", "plain", "xsd:integer", "Indicates the number of seconds to wait for a live migration to complete for a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the timeout value is provisioned in both the flavor and the image, the smaller value is used. The default is 800 seconds. The minimum timeout is 120 seconds and the maximum timeout value is 800 seconds. To disable the live migration timeout feature, set this value to 0." + "hw_wrs_live_migration_max_downtime (Optional)", "plain", "xsd:integer", "Indicates the maximum amoutn of downtime to tolerate during a live migration of a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the max downtime value is provisioned in both the flavor and the image, the value from the flavor overrides the value from the image. The default is 500 milliseconds. The minimum timer value is 100 milliseconds." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "cache_raw (Optional)", "plain", "xsd:bool", "On systems using Ceph storage, boot image files must be converted to RAW format before they can be used to create volumes. You can accelerate volume creation in StarlingX (and therefore instance launch time) by caching the RAW images as they are created. The cached images are maintained in the Glance image storage space and used for volume creation, eliminating conversion time. The default behaviour is to NOT cache the raw format." + "store (Optional)", "plain", "xsd:string", "Indicates which Glance backend the image is stored in; either ``file`` for the Controller Filesystem or ``rbd`` for the ceph backend." + "sw_wrs_auto_recovery (Optional)", "plain", "xsd:bool", "Indicates whether auto recovery of failed virutal machine instances is enabled or not. The default is ``True``." + "hw_wrs_live_migration_timeout (Optional)", "plain", "xsd:integer", "Indicates the number of seconds to wait for a live migration to complete for a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the timeout value is provisioned in both the flavor and the image, the smaller value is used. The default is 800 seconds. The minimum timeout is 120 seconds and the maximum timeout value is 800 seconds. To disable the live migration timeout feature, set this value to 0." + "hw_wrs_live_migration_max_downtime (Optional)", "plain", "xsd:integer", "Indicates the maximum amoutn of downtime to tolerate during a live migration of a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the max downtime value is provisioned in both the flavor and the image, the value from the flavor overrides the value from the image. The default is 500 milliseconds. The minimum timer value is 100 milliseconds." + +:: + + { + "hw_wrs_live_migration_timeout":"400", + "name":"cirros", + "container_format":"bare", + "cache_raw":"True", + "visibility":"public", + "disk_format":"qcow2", + "sw_wrs_auto_recovery":"False", + "hw_wrs_live_migration_max_downtime":"350" + } + +:: + + { + "hw_wrs_live_migration_timeout":"400", + "disk_format":"qcow2", + "min_ram":0, + "updated_at":"2016-10-25T12:02:09Z", + "file":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67/file", + "owner":"b27359bcdb3e424db43a3e2255777f37", + "id":"9d34ff07-6f66-4107-9363-e38b0b559a67", + "size":null, + "self":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67", + "cache_raw":"True", + "container_format":"bare", + "schema":"/v2/schemas/image", + "status":"queued", + "tags":[ + + ], + "visibility":"public", + "min_disk":0, + "sw_wrs_auto_recovery":"False", + "virtual_size":null, + "hw_wrs_live_migration_max_downtime":"350", + "name":"cirros", + "checksum":null, + "created_at":"2016-10-25T12:02:09Z", + "protected":false + } + +****************** +Lists all images +****************** + +.. rest_method:: GET /v2/images + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. NOTE that the extensions listed here are +``additional properties`` which are supported in the Image API and +implemented in a Stack-specific manner. + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "cache_raw (Optional)", "plain", "xsd:bool", "On systems using Ceph storage, boot image files must be converted to RAW format before they can be used to create volumes. You can accelerate volume creation in StarlingX (and therefore instance launch time) by caching the RAW images as they are created. The cached images are maintained in the Glance image storage space and used for volume creation, eliminating conversion time. The default behaviour is to NOT cache the raw format." + "store (Optional)", "plain", "xsd:string", "Indicates which Glance backend the image is stored in; either ``file`` for the Controller Filesystem or ``rbd`` for the ceph backend." + "sw_wrs_auto_recovery (Optional)", "plain", "xsd:bool", "Indicates whether auto recovery of failed virutal machine instances is enabled or not. The default is ``True``." + "hw_wrs_live_migration_timeout (Optional)", "plain", "xsd:integer", "Indicates the number of seconds to wait for a live migration to complete for a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the timeout value is provisioned in both the flavor and the image, the smaller value is used. The default is 800 seconds. The minimum timeout is 120 seconds and the maximum timeout value is 800 seconds. To disable the live migration timeout feature, set this value to 0." + "hw_wrs_live_migration_max_downtime (Optional)", "plain", "xsd:integer", "Indicates the maximum amoutn of downtime to tolerate during a live migration of a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the max downtime value is provisioned in both the flavor and the image, the value from the flavor overrides the value from the image. The default is 500 milliseconds. The minimum timer value is 100 milliseconds." + +:: + + { + "images":[ + { + "status":"active", + "virtual_size":null, + "name":"sample-guest", + "tags":[ + + ], + "container_format":"bare", + "created_at":"2016-10-24T22:50:17Z", + "size":688914432, + "disk_format":"raw", + "updated_at":"2016-10-24T22:50:26Z", + "visibility":"public", + "self":"/v2/images/ac22a842-27c6-40a5-8475-f15f12e94202", + "min_disk":0, + "protected":false, + "id":"ac22a842-27c6-40a5-8475-f15f12e94202", + "file":"/v2/images/ac22a842-27c6-40a5-8475-f15f12e94202/file", + "checksum":"29514837240a4bb80df0e2362644ae17", + "owner":"b27359bcdb3e424db43a3e2255777f37", + "direct_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/ac22a842-27c6-40a5-8475-f15f12e94202/snap", + "min_ram":0, + "store":"rbd", + "schema":"/v2/schemas/image" + }, + { + "hw_wrs_live_migration_timeout":"400", + "cache_raw":"True", + "min_ram":0, + "updated_at":"2016-10-25T12:06:19Z", + "file":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67/file", + "owner":"b27359bcdb3e424db43a3e2255777f37", + "id":"9d34ff07-6f66-4107-9363-e38b0b559a67", + "size":13287936, + "self":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67", + "disk_format":"qcow2", + "cache_raw_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/9d34ff07-6f66-4107-9363-e38b0b559a67_raw/snap", + "container_format":"bare", + "direct_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/9d34ff07-6f66-4107-9363-e38b0b559a67/snap", + "store":"rbd", + "schema":"/v2/schemas/image", + "status":"active", + "cache_raw_size":"41126400", + "cache_raw_status":"Cached", + "tags":[ + + ], + "visibility":"public", + "min_disk":0, + "sw_wrs_auto_recovery":"False", + "virtual_size":null, + "hw_wrs_live_migration_max_downtime":"350", + "name":"cirros", + "checksum":"ee1eca47dc88f4879d8a229cc70a07c6", + "created_at":"2016-10-25T12:02:09Z", + "protected":false + } + ], + "schema":"/v2/schemas/images", + "first":"/v2/images?sort_key=name&sort_dir=asc&limit=20" + } + +This operation does not accept a request body. + +*************************************************** +Shows detailed information about a specific image +*************************************************** + +.. rest_method:: GET /v2/images/​{image_id}​ + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. NOTE that the extensions listed here are +``additional properties`` which are supported in the Image API and +implemented in a Stack-specific manner. + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "image_id", "URI", "xsd:string", "The name for the image." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "cache_raw (Optional)", "plain", "xsd:bool", "On systems using Ceph storage, boot image files must be converted to RAW format before they can be used to create volumes. You can accelerate volume creation in StarlingX (and therefore instance launch time) by caching the RAW images as they are created. The cached images are maintained in the Glance image storage space and used for volume creation, eliminating conversion time. The default behaviour is to NOT cache the raw format." + "store (Optional)", "plain", "xsd:string", "Indicates which Glance backend the image is stored in; either ``file`` for the Controller Filesystem or ``rbd`` for the ceph backend." + "sw_wrs_auto_recovery (Optional)", "plain", "xsd:bool", "Indicates whether auto recovery of failed virutal machine instances is enabled or not. The default is ``True``." + "hw_wrs_live_migration_timeout (Optional)", "plain", "xsd:integer", "Indicates the number of seconds to wait for a live migration to complete for a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the timeout value is provisioned in both the flavor and the image, the smaller value is used. The default is 800 seconds. The minimum timeout is 120 seconds and the maximum timeout value is 800 seconds. To disable the live migration timeout feature, set this value to 0." + "hw_wrs_live_migration_max_downtime (Optional)", "plain", "xsd:integer", "Indicates the maximum amoutn of downtime to tolerate during a live migration of a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the max downtime value is provisioned in both the flavor and the image, the value from the flavor overrides the value from the image. The default is 500 milliseconds. The minimum timer value is 100 milliseconds." + +:: + + { + "hw_wrs_live_migration_timeout":"400", + "cache_raw":"True", + "min_ram":0, + "updated_at":"2016-10-25T12:06:19Z", + "file":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67/file", + "owner":"b27359bcdb3e424db43a3e2255777f37", + "id":"9d34ff07-6f66-4107-9363-e38b0b559a67", + "size":13287936, + "self":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67", + "disk_format":"qcow2", + "cache_raw_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/9d34ff07-6f66-4107-9363-e38b0b559a67_raw/snap", + "container_format":"bare", + "direct_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/9d34ff07-6f66-4107-9363-e38b0b559a67/snap", + "store":"rbd", + "schema":"/v2/schemas/image", + "status":"active", + "cache_raw_size":"41126400", + "cache_raw_status":"Cached", + "tags":[ + + ], + "visibility":"public", + "min_disk":0, + "sw_wrs_auto_recovery":"False", + "virtual_size":null, + "hw_wrs_live_migration_max_downtime":"350", + "name":"cirros", + "checksum":"ee1eca47dc88f4879d8a229cc70a07c6", + "created_at":"2016-10-25T12:02:09Z", + "protected":false + } + +This operation does not accept a request body. + +*************************** +Modifies a specific image +*************************** + +.. rest_method:: PUT /v2/images/​{image_id}​ + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. NOTE that the extensions listed here are +``additional properties`` which are supported in the Image API and +implemented in a Stack-specific manner. + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "image_id", "URI", "xsd:string", "The name for the image." + "sw_wrs_auto_recovery (Optional)", "plain", "xsd:bool", "Indicates whether auto recovery of failed virutal machine instances is enabled or not. The default is True." + "hw_wrs_live_migration_timeout (Optional)", "plain", "xsd:integer", "Indicates the number of seconds to wait for a live migration to complete for a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the timeout value is provisioned in both the flavor and the image, the smaller value is used. The default is 800 seconds. The minimum timeout is 120 seconds and the maximum timeout value is 800 seconds. To disable the live migration timeout feature, set this value to 0." + "hw_wrs_live_migration_max_downtime (Optional)", "plain", "xsd:integer", "Indicates the maximum amoutn of downtime to tolerate during a live migration of a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the max downtime value is provisioned in both the flavor and the image, the value from the flavor overrides the value from the image. The default is 500 milliseconds. The minimum timer value is 100 milliseconds." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "cache_raw (Optional)", "plain", "xsd:bool", "On systems using Ceph storage, boot image files must be converted to RAW format before they can be used to create volumes. You can accelerate volume creation in StarlingX (and therefore instance launch time) by caching the RAW images as they are created. The cached images are maintained in the Glance image storage space and used for volume creation, eliminating conversion time. The default behaviour is to NOT cache the raw format." + "store (Optional)", "plain", "xsd:string", "Indicates which Glance backend the image is stored in; either ``file`` for the Controller Filesystem or ``rbd`` for the ceph backend." + "sw_wrs_auto_recovery (Optional)", "plain", "xsd:bool", "Indicates whether auto recovery of failed virutal machine instances is enabled or not. The default is ``True``." + "hw_wrs_live_migration_timeout (Optional)", "plain", "xsd:integer", "Indicates the number of seconds to wait for a live migration to complete for a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the timeout value is provisioned in both the flavor and the image, the smaller value is used. The default is 800 seconds. The minimum timeout is 120 seconds and the maximum timeout value is 800 seconds. To disable the live migration timeout feature, set this value to 0." + "hw_wrs_live_migration_max_downtime (Optional)", "plain", "xsd:integer", "Indicates the maximum amoutn of downtime to tolerate during a live migration of a VM created with this image. Note that this can be specified as an extraspec of the flavor as well. If the max downtime value is provisioned in both the flavor and the image, the value from the flavor overrides the value from the image. The default is 500 milliseconds. The minimum timer value is 100 milliseconds." + +:: + + [ + { + "path":"/hw_wrs_live_migration_timeout", + "value":"500", + "op":"replace" + }, + { + "path":"/sw_wrs_auto_recovery", + "value":"True", + "op":"replace" + }, + { + "path":"/hw_wrs_live_migration_max_downtime", + "value":"300", + "op":"replace" + } + ] + +:: + + { + "hw_wrs_live_migration_timeout":"500", + "cache_raw":"True", + "min_ram":0, + "updated_at":"2016-10-25T12:15:41Z", + "file":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67/file", + "owner":"b27359bcdb3e424db43a3e2255777f37", + "id":"9d34ff07-6f66-4107-9363-e38b0b559a67", + "size":13287936, + "self":"/v2/images/9d34ff07-6f66-4107-9363-e38b0b559a67", + "disk_format":"qcow2", + "cache_raw_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/9d34ff07-6f66-4107-9363-e38b0b559a67_raw/snap", + "container_format":"bare", + "direct_url":"rbd://840f16bc-3238-4adb-8700-6b9876c23462/images/9d34ff07-6f66-4107-9363-e38b0b559a67/snap", + "store":"rbd", + "schema":"/v2/schemas/image", + "status":"active", + "cache_raw_size":"41126400", + "cache_raw_status":"Cached", + "tags":[ + + ], + "visibility":"public", + "min_disk":0, + "sw_wrs_auto_recovery":"True", + "virtual_size":null, + "hw_wrs_live_migration_max_downtime":"300", + "name":"cirros", + "checksum":"ee1eca47dc88f4879d8a229cc70a07c6", + "created_at":"2016-10-25T12:02:09Z", + "protected":false + } diff --git a/api-ref/source/api-ref-networking-v2-cgcs-ext.rst b/api-ref/source/api-ref-networking-v2-cgcs-ext.rst new file mode 100644 index 000000000..0578319e2 --- /dev/null +++ b/api-ref/source/api-ref-networking-v2-cgcs-ext.rst @@ -0,0 +1,2888 @@ +==================================================== +Networking API v2 StarlingX extensions +==================================================== + +This section describes changes made to the standard OpenStack Networking +API for the StarlingX. Some existing OpenStack API instances have +been enhanced to add new attributes, or update the semantics of existing +attributes. In other cases, entirely new API instances have been created +to expose StarlingX networking functionality via the standard +RESTful API. + +The typical port used for the Networking REST API is 9696. However, +proper technique would be to look up the neutron service endpoint in +Keystone. + +----------- +Extensions +----------- + +The Extensions entity lists all available extensions; both open-source +extensions and StarlingX extensions. + +************************************* +Lists all extensions - Networking API +************************************* + +.. rest_method:: GET /v2.0/extensions + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "namespace (Optional)", "plain", "xsd:string", "Indicates namespace of the extension." + "name (Optional)", "plain", "xsd:string", "Indicates name of the extension." + "updated (Optional)", "plain", "xsd:string", "Indicates updated time of the extension." + "description (Optional)", "plain", "xsd:string", "Indicates description of the extension." + "alias (Optional)", "plain", "xsd:string", "Indicates alias of the extension." + "links (Optional)", "plain", "xsd:list", "A list of links for the extension." + +:: + + { + "extensions" : [ + ... + { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-provider/v1", + "name" : "wrs-provider-network", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Provider Network Extensions.", + "alias" : "wrs-provider", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-tenant/v1", + "name" : "wrs-tenant-settings", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Tenant Network Settings Extensions.", + "alias" : "wrs-tenant", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-tm/v1", + "name" : "wrs-traffic-management", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Traffic Management Extensions.", + "alias" : "wrs-tm", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-net/v1", + "name" : "wrs-tenant-network", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Tenant Network Extensions.", + "alias" : "wrs-net", + "links" : [] + }, + { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-binding/v1", + "name" : "wrs-port-binding", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Port Binding Extensions.", + "alias" : "wrs-binding", + "links" : [] + }, + ... + ] + } + +This operation does not accept a request body. + +************************************************************* +Gets information about a specified extension - Networking API +************************************************************* + +.. rest_method:: GET /v2.0/extensions/​{extension_alias}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "extension_alias", "URI", "xsd:string", "The alias for the extension to list." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "namespace (Optional)", "plain", "xsd:string", "Indicates namespace of the extension." + "name (Optional)", "plain", "xsd:string", "Indicates name of the extension." + "updated (Optional)", "plain", "xsd:string", "Indicates updated time of the extension." + "description (Optional)", "plain", "xsd:string", "Indicates description of the extension." + "alias (Optional)", "plain", "xsd:string", "Indicates alias of the extension." + "links (Optional)", "plain", "xsd:list", "A list of links for the extension." + +:: + + { + "extensions" : { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-provider/v1", + "name" : "wrs-provider-network", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Provider Network Extensions.", + "alias" : "wrs-provider", + "links" : [] + } + } + + OR + + { + "extensions" : { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-tenant/v1", + "name" : "wrs-tenant-settings", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Tenant Network Settings Extensions.", + "alias" : "wrs-tenant", + "links" : [] + } + } + + OR + + { + "extensions" : { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-tm/v1", + "name" : "wrs-traffic-management", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Traffic Management Extensions.", + "alias" : "wrs-tm", + "links" : [] + } + } + + OR + + { + "extensions" : { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-net/v1", + "name" : "wrs-tenant-network", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Tenant Network Extensions.", + "alias" : "wrs-net", + "links" : [] + } + } + + OR + + { + "extensions" : { + "namespace" : "http://docs.windriver.org/tis/ext/wrs-binding/v1", + "name" : "wrs-port-binding", + "updated" : "2014-10-01T12:00:00-00:00", + "description" : "WRS Port Binding Extensions.", + "alias" : "wrs-binding", + "links" : [] + } + } + +This operation does not accept a request body. + +----------------- +Provider Network +----------------- + +The Provider Network entity is a new entity which was added to the +OpenStack API. It enables management of provider networks via the +RESTful API. The standard OpenStack API included no such entity; +instead, the end user was required to edit static configuration files +through the system to add, or update provider network information. + +This entity and all of its operations are only available to +administrator level users. + +***************************** +Lists all provider networks +***************************** + +.. rest_method:: GET /v2.0/wrs-provider/providernets + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernets (Optional)", "plain", "xsd:list", "The list of provider networks." + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network." + "mtu (Optional)", "plain", "xsd:integer", "The maximum transmit unit (MTU) assigned to the provider network. Must be between 576 and 9216 bytes inclusively. The default value is 1500." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network." + "ranges (Optional)", "plain", "xsd:list", "The list of segmentation ranges defined for this provider network. See the provider network range description for a description of range fields." + "status (Optional)", "plain", "xsd:string", "The current status of the provider network. Returns ``ACTIVE`` if at least one compute node has a data interface associated to this provider network and is available. " + +:: + + { + "providernets": [ + { + "description": "Group0 provider networks for data1 interfaces", + "id": "b67d40aa-3651-4dd6-886f-4bff5caa266e", + "mtu": 1500, + "name": "group0-data1", + "ranges": [ + { + "description": "tenant2 reserved networks", + "id": "a8184bf7-b683-4bc1-a70c-dae34391344c", + "maximum": 631, + "minimum": 616, + "name": "group0-tenant2", + "shared": false, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + } + ], + "status": "ACTIVE", + "type": "vlan", + "vlan_transparent": false, + }, + { + "description": "Group0 provider networks for data0 interfaces", + "id": "c496c429-cb52-4d4b-9171-b4b31fa91a80", + "mtu": 1500, + "name": "group0-data0", + "ranges": [ + { + "description": "Shared internal networks", + "id": "f3e1bc29-29f7-4ee0-a78d-9c3d7a0f53e5", + "maximum": 731, + "minimum": 700, + "name": "group0-shared", + "shared": true, + "tenant_id": null + }, + { + "description": "External network access", + "id": "35ef3460-700a-48a3-8df9-145eb68fcd31", + "maximum": 10, + "minimum": 10, + "name": "group0-external", + "shared": true, + "tenant_id": null + }, + { + "description": "tenant1 reserved networks", + "id": "736b0c0d-945b-4a17-9fe4-cf02a5327132", + "maximum": 615, + "minimum": 600, + "name": "group0-tenant1", + "shared": false, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + ], + "status": "ACTIVE", + "type": "vlan", + "vlan_transparent": false, + } + ] + } + +This operation does not accept a request body. + +************************************************************** +Shows detailed information about a specific provider network +************************************************************** + +.. rest_method:: GET /v2.0/wrs-provider/providernets/​{providernet_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet_id", "URI", "csapi:UUID", "The ID for a provider network." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network." + "mtu (Optional)", "plain", "xsd:integer", "The maximum transmit unit (MTU) assigned to the provider network. Must be between 576 and 9216 bytes inclusively. The default value is 1500." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network." + "ranges (Optional)", "plain", "xsd:list", "The list of segmentation ranges defined for this provider network. See the provider network range description for a description of range fields." + "status (Optional)", "plain", "xsd:string", "The current status of the provider network. Returns ``ACTIVE`` if at least one compute node has a data interface associated to this provider network and is available. " + +:: + + { + "providernet": { + "description": "Group0 provider networks for data1 interfaces", + "id": "b67d40aa-3651-4dd6-886f-4bff5caa266e", + "mtu": 1500, + "name": "group0-data1", + "ranges": [ + { + "description": "tenant2 reserved networks", + "id": "a8184bf7-b683-4bc1-a70c-dae34391344c", + "maximum": 631, + "minimum": 616, + "name": "group0-tenant2", + "shared": false, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + } + ], + "status": "ACTIVE", + "type": "vlan", + "vlan_transparent": false, + } + } + +This operation does not accept a request body. + +**************************** +Creates a provider network +**************************** + +.. rest_method:: POST /v2.0/wrs-provider/providernets + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network." + "type (Optional)", "plain", "xsd:string", "The encapsulation type of the provider network. Valid values are: ``vlan``, ``flat``" + "vlan_transparent (Optional)", "plain", "xsd:bool", "Specifies whether VLAN transparent network are supported on this provider network." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network." + "mtu (Optional)", "plain", "xsd:integer", "The maximum transmit unit (MTU) assigned to the provider network. Must be between 576 and 9216 bytes inclusively. The default value is 1500." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network." + "ranges (Optional)", "plain", "xsd:list", "The list of segmentation ranges defined for this provider network. See the provider network range description for a description of range fields." + "status (Optional)", "plain", "xsd:string", "The current status of the provider network. Returns ``ACTIVE`` if at least one compute node has a data interface associated to this provider network and is available. " + +:: + + { + "providernet": { + "description": "A sample provider network", + "name": "test", + "type": "vlan", + "vlan_transparent": false, + } + } + +:: + + { + "providernet": { + "description": "A sample provider network", + "id": "4da9e42c-e556-470c-8e92-cbd19bcc6a10", + "mtu": 1500, + "name": "test", + "ranges": [], + "status": "DOWN", + "type": "vlan", + "vlan_transparent": false, + } + } + +************************************** +Modifies a specific provider network +************************************** + +.. rest_method:: PUT /v2.0/wrs-provider/providernets/​{providernet_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet_id", "URI", "csapi:UUID", "The ID for a provider network." + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network." + "vlan_transparent (Optional)", "plain", "xsd:bool", "Specifies whether VLAN transparent network are supported on this provider network." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network." + "mtu (Optional)", "plain", "xsd:integer", "The maximum transmit unit (MTU) assigned to the provider network. Must be between 576 and 9216 bytes inclusively. The default value is 1500." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network." + "ranges (Optional)", "plain", "xsd:list", "The list of segmentation ranges defined for this provider network. See the provider network range description for a description of range fields." + "status (Optional)", "plain", "xsd:string", "The current status of the provider network. Returns ``ACTIVE`` if at least one compute node has a data interface associated to this provider network and is available. " + +:: + + { + "providernet": { + "description": "Another sample provider network" + } + } + +:: + + { + "providernet": { + "description": "Another sample provider network", + "id": "4da9e42c-e556-470c-8e92-cbd19bcc6a10", + "mtu": 1500, + "name": "test", + "ranges": [], + "status": "DOWN", + "type": "vlan", + "vlan_transparent": false, + } + } + +************************************* +Deletes a specific provider network +************************************* + +.. rest_method:: DELETE /v2.0/wrs-provider/providernets/​{providernet_id}​ + +**Normal response codes** + +204 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet_id", "URI", "csapi:UUID", "The ID for a provider network." + +This operation does not accept a request body. + +***************************************************************************************************************************************** +Lists networks that are implemented by a given provider network. Each network is listed with its assigned provider network segmentation +***************************************************************************************************************************************** + +.. rest_method:: GET /v2.0/wrs-provider/providernets/​{providernet_id}​/providernet-bindings + +identifier. If the network has any tagged subnets then they will be +listed as separate entities with their corresponding provider network +segmentation identifier. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet_id", "URI", "csapi:UUID", "The ID for a provider network." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "networks (Optional)", "plain", "xsd:list", "The list of tenant networks." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the tenant network." + "name (Optional)", "plain", "xsd:string", "The user defined name of the tenant network." + "providernet_type (Optional)", "plain", "xsd:string", "The encapsulation type of the provider network." + "segmentation_id (Optional)", "plain", "xsd:integer", "The provider network segmentation identifier that is assigned to this tenant network. If the ``vlan_id`` attribute is non-zero then the ``segmentation_id`` represents that identifier which has been associated to a tagged subnet on the listed tenant network." + "vlan_id (Optional)", "plain", "xsd:integer", "The VLAN identifier which has been configured on the tenant subnet." + +:: + + { + "networks": [ + { + "id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "name": "tenant1-net0", + "providernet_type": "vlan", + "segmentation_id": 601, + "vlan_id": 0 + }, + { + "id": "7e5ed852-a990-4fc5-89a2-b17093ca1982", + "name": "internal0-net0", + "providernet_type": "vlan", + "segmentation_id": 700, + "vlan_id": 0 + }, + { + "id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "name": "external-net0", + "providernet_type": "vlan", + "segmentation_id": 10, + "vlan_id": 0 + }, + { + "id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "name": "tenant1-mgmt-net", + "providernet_type": "vlan", + "segmentation_id": 600, + "vlan_id": 0 + } + ] + } + +This operation does not accept a request body. + +----------------------- +Provider Network Range +----------------------- + +The Provider Network Range entity is a new entity which was added to the +OpenStack API. It enables management of provider network segmentation +ranges via the RESTful API. The standard OpenStack API included no such +entity; instead, the end user was required to edit static configuration +files through the system to add, or update provider network segmentation +ranges. + +This entity and all of its operations are only available to +administrator level users. + +*********************************** +Lists all provider network ranges +*********************************** + +.. rest_method:: GET /v2.0/wrs-provider/providernet-ranges + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernetranges (Optional)", "plain", "xsd:list", "The list of provider network ranges." + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network segmentation range." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network segmentation range." + "maximum (Optional)", "plain", "xsd:integer", "The upper bound of the segmentation range (inclusive)." + "minimum (Optional)", "plain", "xsd:integer", "The lower bound of the segmentation range (inclusive)." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network segmentation range." + "providernet_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the parent provider network." + "providernet_name (Optional)", "plain", "xsd:string", "The user defined name of the parent provider network." + "shared (Optional)", "plain", "xsd:bool", "The shared attribute indicates that the range is available to any tenant." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the range. Only valid if the shared attribute is False." + +:: + + { + "providernet_ranges": [ + { + "description": "Shared internal networks", + "id": "f3e1bc29-29f7-4ee0-a78d-9c3d7a0f53e5", + "maximum": 731, + "minimum": 700, + "name": "group0-shared", + "providernet_id": "c496c429-cb52-4d4b-9171-b4b31fa91a80", + "providernet_name": "group0-data0", + "shared": true, + "tenant_id": null + }, + { + "description": "External network access", + "id": "35ef3460-700a-48a3-8df9-145eb68fcd31", + "maximum": 10, + "minimum": 10, + "name": "group0-external", + "providernet_id": "c496c429-cb52-4d4b-9171-b4b31fa91a80", + "providernet_name": "group0-data0", + "shared": true, + "tenant_id": null + }, + { + "description": "tenant1 reserved networks", + "id": "736b0c0d-945b-4a17-9fe4-cf02a5327132", + "maximum": 615, + "minimum": 600, + "name": "group0-tenant1", + "providernet_id": "c496c429-cb52-4d4b-9171-b4b31fa91a80", + "providernet_name": "group0-data0", + "shared": false, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "description": "tenant2 reserved networks", + "id": "a8184bf7-b683-4bc1-a70c-dae34391344c", + "maximum": 631, + "minimum": 616, + "name": "group0-tenant2", + "providernet_id": "b67d40aa-3651-4dd6-886f-4bff5caa266e", + "providernet_name": "group0-data1", + "shared": false, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + }, + { + "description": "A sample provider network segmentation range", + "id": "bdf07406-a867-42e5-9533-5100c4a3f2ba", + "maximum": 100, + "minimum": 1, + "name": "test-range-0", + "providernet_id": "239ffb19-bad8-4b05-9194-aa8399816a36", + "providernet_name": "test", + "shared": true, + "tenant_id": null + } + ] + } + +This operation does not accept a request body. + +********************************************************************* +Shows detailed information about a specific provider network range +********************************************************************* + +.. rest_method:: GET /v2.0/wrs-provider/providernet-ranges/​{providernet-range_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernetrange_id", "URI", "csapi:UUID", "The ID for a provider network segmentation range." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network segmentation range." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network segmentation range." + "maximum (Optional)", "plain", "xsd:integer", "The upper bound of the segmentation range (inclusive)." + "minimum (Optional)", "plain", "xsd:integer", "The lower bound of the segmentation range (inclusive)." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network segmentation range." + "providernet_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the parent provider network." + "providernet_name (Optional)", "plain", "xsd:string", "The user defined name of the parent provider network." + "shared (Optional)", "plain", "xsd:bool", "The shared attribute indicates that the range is available to any tenant." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the range. Only valid if the shared attribute is False." + +:: + + { + "providernet_range": { + "description": "A sample provider network segmentation range", + "id": "bdf07406-a867-42e5-9533-5100c4a3f2ba", + "maximum": 100, + "minimum": 1, + "name": "test-range-0", + "providernet_id": "239ffb19-bad8-4b05-9194-aa8399816a36", + "providernet_name": "test", + "shared": true, + "tenant_id": null + } + } + +This operation does not accept a request body. + +********************************** +Creates a provider network range +********************************** + +.. rest_method:: POST /v2.0/wrs-provider/providernet-ranges + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network segmentation range." + "maximum (Optional)", "plain", "xsd:integer", "The upper bound of the segmentation range (inclusive)." + "minimum (Optional)", "plain", "xsd:integer", "The lower bound of the segmentation range (inclusive)." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network segmentation range." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network segmentation range." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network segmentation range." + "maximum (Optional)", "plain", "xsd:integer", "The upper bound of the segmentation range (inclusive)." + "minimum (Optional)", "plain", "xsd:integer", "The lower bound of the segmentation range (inclusive)." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network segmentation range." + "providernet_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the parent provider network." + "providernet_name (Optional)", "plain", "xsd:string", "The user defined name of the parent provider network." + "shared (Optional)", "plain", "xsd:bool", "The shared attribute indicates that the range is available to any tenant." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the range. Only valid if the shared attribute is False." + +:: + + { + "providernet_range": { + "description": "A sample provider network segmentation range", + "maximum": "100", + "minimum": "1", + "name": "test-range-0", + "providernet_id": "239ffb19-bad8-4b05-9194-aa8399816a36", + "shared": true + } + } + +:: + + { + "providernet_range": { + "description": "A sample provider network segmentation range", + "id": "bdf07406-a867-42e5-9533-5100c4a3f2ba", + "maximum": "100", + "minimum": "1", + "name": "test-range-0", + "providernet_id": "239ffb19-bad8-4b05-9194-aa8399816a36", + "providernet_name": "test", + "shared": true, + "tenant_id": null + } + } + +********************************************* +Modifies a specific provider network range +********************************************* + +.. rest_method:: PUT /v2.0/wrs-provider/providernet-ranges/​{providernet-range_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernetrange_id", "URI", "csapi:UUID", "The ID for a provider network segmentation range." + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network segmentation range." + "maximum (Optional)", "plain", "xsd:integer", "The upper bound of the segmentation range (inclusive)." + "minimum (Optional)", "plain", "xsd:integer", "The lower bound of the segmentation range (inclusive)." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "User defined description of the provider network segmentation range." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the provider network segmentation range." + "maximum (Optional)", "plain", "xsd:integer", "The upper bound of the segmentation range (inclusive)." + "minimum (Optional)", "plain", "xsd:integer", "The lower bound of the segmentation range (inclusive)." + "name (Optional)", "plain", "xsd:string", "The user defined name of the provider network segmentation range." + "providernet_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the parent provider network." + "providernet_name (Optional)", "plain", "xsd:string", "The user defined name of the parent provider network." + "shared (Optional)", "plain", "xsd:bool", "The shared attribute indicates that the range is available to any tenant." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the range. Only valid if the shared attribute is False." + +:: + + { + "providernet_range": { + "maximum": "1099", + "minimum": "1000", + "description": "VLAN identifiers reserved for tenant1" + } + } + +:: + + { + "providernet_range": { + "description": null, + "id": "fe24481a-303f-4cd9-a0ac-76c2e4a9bcc8", + "maximum": "1099", + "minimum": "1000", + "name": "test-range-0", + "providernet_id": "c496c429-cb52-4d4b-9171-b4b31fa91a80", + "providernet_name": "group0-data0", + "shared": false, + "tenant_id": "206f147dcf72421fa6829e33bfb34637" + } + } + +******************************************** +Deletes a specific provider network range +******************************************** + +.. rest_method:: DELETE /v2.0/wrs-provider/providernet-ranges/​{providernet-range_id}​ + +**Normal response codes** + +204 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernetrange_id", "URI", "csapi:UUID", "The ID for a provider network segmentation range." + +This operation does not accept a request body. + +---------------------- +Provider Network Type +---------------------- + +The Provider Network Type entity is a new entity which was added to the +OpenStack API. It exists simply to allow the end user to query which +provider network types are supported by the system. + +This entity and all of its operations are only available to +administrator level users. + +*************************************** +Lists all supported providernet types +*************************************** + +.. rest_method:: GET /v2.0/wrs-provider/providernet-types + +Insert extra description here, if required. + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernettypes (Optional)", "plain", "xsd:list", "The list of supported providernet types." + "description (Optional)", "plain", "xsd:string", "System description of the provider network type." + "type (Optional)", "plain", "xsd:string", "The encapsulation type of the provider network. Valid values are: ``vlan``, ``flat``" + +:: + + { + "providernet_types": [ + { + "description": "Ethernet network without additional encapsulation", + "type": "flat" + }, + { + "description": "802.1q encapsulated Ethernet network", + "type": "vlan" + } + ] + } + +This operation does not accept a request body. + +----------------------------------- +Provider Network Connectivity Test +----------------------------------- + +The Provider Network Connectivity Test entity is a new entity which was +added to the OpenStack API. It enables the verification of provider +network connectivity between compute nodes. + +This entity and all of its operations are only available to +administrator level users. + +************************************************* +Lists results of providernet connectivity tests +************************************************* + +.. rest_method:: GET /v2.0/wrs-provider/providernet-connectivity-tests + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet_connectivity_tests (Optional)", "plain", "xsd:list", "List of providernet connectivity test results." + +:: + + { + "providernet_connectivity_tests":[ + { + "status":"PASS", + "segmentation_id":"10", + "updated_at":"2016-04-12 17:11:34.515416", + "host_name":"compute-1", + "providernet_id":"fc210630-7bb5-4ad2-a7e3-a4b752a8377b", + "host_id":"da6e8822-49ed-43f7-a5e4-90db837ffb2e", + "providernet_name":"physnet0", + "audit_uuid":"c3278c0b-660b-4152-a756-4eab241c1627", + "type":"vlan", + "message":"" + }, + { + "status":"PASS", + "segmentation_id":"10", + "updated_at":"2016-04-12 17:11:34.511279", + "host_name":"compute-0", + "providernet_id":"fc210630-7bb5-4ad2-a7e3-a4b752a8377b", + "host_id":"3c349ef5-d5f1-4bb1-9742-3538b6e9a352", + "providernet_name":"physnet0", + "audit_uuid":"c3278c0b-660b-4152-a756-4eab241c1627", + "type":"vlan", + "message":"" + } + ] + } + +This operation does not accept a request body. + +***************************************************************************** +Schedule providernet connectivity test to be run, and return scheduled UUID +***************************************************************************** + +.. rest_method:: POST /v2.0/wrs-provider/providernet-connectivity-tests + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "providernet_name (Optional)", "plain", "xsd:string", "Run audit for a given providernet identified by name." + "providernet_id (Optional)", "plain", "xsd:string", "Run audit for a given providernet identified by ID." + "host_name (Optional)", "plain", "xsd:string", "Run audit for all providernets on a given host identified by name." + "host_id (Optional)", "plain", "xsd:string", "Run audit for all providernets on a given host identified by ID." + "segmentation_id (Optional)", "plain", "xsd:string", "Restrict audit to these segmentation IDs." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "audit_uuid (Optional)", "plain", "xsd:string", "Unique ID assigned to the audit." + +:: + + { + "providernet_connectivity_test":{ + "segmentation_id":null, + "host_name":null, + "providernet_id":null + } + } + +:: + + { + "providernet_connectivity_test":{ + "audit_uuid":"12a9f9c2-ca3b-4b56-b463-5755022c8d16" + } + } + +---------------- +Tenant Settings +---------------- + +The Tenant Settings entity is a new entity which was added to the +OpenStack API. It enables management of features or system behaviours on +a per-tenant basis by the administrator. + +This entity and all of its operations are only available to +administrator level users. + +*********************************** +Lists all tenant network settings +*********************************** + +.. rest_method:: GET /v2.0/wrs-tenant/settings + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "settings (Optional)", "plain", "xsd:list", "The list of tenant network settings." + "mac_filtering (Optional)", "plain", "xsd:bool", "The state of the source MAC filtering feature for the specified tenant. The current state of the feature only affects newly launched VM instances." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant." + +:: + + { + "settings": [ + { + "mac_filtering": false, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "mac_filtering": false, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + } + ] + } + +This operation does not accept a request body. + +******************************************************************** +Shows detailed information about a specific tenant network setting +******************************************************************** + +.. rest_method:: GET /v2.0/wrs-tenant/settings/​{tenant_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for a tenant." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "mac_filtering (Optional)", "plain", "xsd:bool", "The state of the source MAC filtering feature for the specified tenant. The current state of the feature only affects newly launched VM instances." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant." + +:: + + { + "setting": { + "mac_filtering": false + } + } + +This operation does not accept a request body. + +******************************************** +Modifies a specific tenant network setting +******************************************** + +.. rest_method:: PUT /v2.0/wrs-tenant/settings/​{tenant_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for a tenant." + "mac_filtering (Optional)", "plain", "xsd:bool", "The state of the source MAC filtering feature for the specified tenant. The current state of the feature only affects newly launched VM instances." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "mac_filtering (Optional)", "plain", "xsd:bool", "The state of the source MAC filtering feature for the specified tenant. The current state of the feature only affects newly launched VM instances." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant." + +:: + + { + "setting": { + "mac_filtering": true + } + } + +:: + + { + "setting": { + "mac_filtering": true + } + } + +******************************************* +Deletes a specific tenant network setting +******************************************* + +.. rest_method:: DELETE /v2.0/wrs-tenant/settings/​{tenant_id}​ + +**Normal response codes** + +204 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "tenant_id", "URI", "csapi:UUID", "The ID for a tenant." + +This operation does not accept a request body. + +------------- +QOS Policies +------------- + +The QOS entity is a new entity which was added to the OpenStack API. It +enables management of Quality of Service policies and profiles via the +RESTful API. QOS policies can be created and maintained by the +administrator. + +************************ +Lists all QOS policies +************************ + +.. rest_method:: GET /v2.0/wrs-tm/qoses + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "Qoses (Optional)", "plain", "xsd:list", "The list of QOS policies." + "description (Optional)", "plain", "xsd:string", "The user defined description of the QoS policy." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the QoS policy." + "name (Optional)", "plain", "xsd:string", "The user defined name of the QoS policy." + "policies (Optional)", "plain", "xsd:dict", "The set of scheduler policies and weights for the QoS policy." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant to which this policy is assigned." + +:: + + { + "qoses": [ + { + "description": "tenant1 Management Network Policy", + "id": "102c64e4-ad26-4610-ae39-f59e15fcb80c", + "name": "tenant1-mgmt-qos", + "policies": { + "scheduler": { + "weight": "8" + } + }, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "description": "tenant2 Management Network Policy", + "id": "62970a9a-b093-4747-92dd-9de25616036a", + "name": "tenant2-mgmt-qos", + "policies": { + "scheduler": { + "weight": "8" + } + }, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + }, + { + "description": "External Network Policy", + "id": "d28e697c-c290-4895-b57c-ac7d38db9003", + "name": "external-qos", + "policies": { + "scheduler": { + "weight": "16" + } + }, + "tenant_id": "206f147dcf72421fa6829e33bfb34637" + } + ] + } + +This operation does not accept a request body. + +******************************************************** +Shows detailed information about a specific QOS policy +******************************************************** + +.. rest_method:: GET /v2.0/wrs-tm/qoses/​{qos_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "qos_id", "URI", "csapi:UUID", "The ID for a QOS Policy." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "The user defined description of the QoS policy." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the QoS policy." + "name (Optional)", "plain", "xsd:string", "The user defined name of the QoS policy." + "policies (Optional)", "plain", "xsd:dict", "The set of scheduler policies and weights for the QoS policy." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant to which this policy is assigned." + +:: + + { + "qos": { + "description": "tenant1 Management Network Policy", + "id": "102c64e4-ad26-4610-ae39-f59e15fcb80c", + "name": "tenant1-mgmt-qos", + "policies": { + "scheduler": { + "weight": "8" + } + }, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + } + +This operation does not accept a request body. + +********************** +Creates a QOS policy +********************** + +.. rest_method:: POST /v2.0/wrs-tm/qoses + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "The user defined description of the QoS policy." + "name (Optional)", "plain", "xsd:string", "The user defined name of the QoS policy." + "policies (Optional)", "plain", "xsd:dict", "The set of scheduler policies and weights for the QoS policy." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant to which this policy is assigned." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "The user defined description of the QoS policy." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the QoS policy." + "name (Optional)", "plain", "xsd:string", "The user defined name of the QoS policy." + "policies (Optional)", "plain", "xsd:dict", "The set of scheduler policies and weights for the QoS policy." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant to which this policy is assigned." + +:: + + { + "qos": { + "description": "A sample QoS profile", + "name": "test-qos-0", + "policies": { + "scheduler": { + "weight": "8" + } + }, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + } + +:: + + { + "qos": { + "description": "A sample QoS profile", + "id": "5e1841fa-c106-47ee-a736-e527478f1239", + "name": "test-qos-0", + "policies": { + "scheduler": { + "weight": "8" + } + }, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + } + +******************************** +Modifies a specific QOS policy +******************************** + +.. rest_method:: PUT /v2.0/wrs-tm/qoses/​{qos_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "qos_id", "URI", "csapi:UUID", "The ID for a QOS Policy." + "description (Optional)", "plain", "xsd:string", "The user defined description of the QoS policy." + "policies (Optional)", "plain", "xsd:dict", "The set of scheduler policies and weights for the QoS policy." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "description (Optional)", "plain", "xsd:string", "The user defined description of the QoS policy." + "id (Optional)", "plain", "csapi:UUID", "The unique UUID value of the QoS policy." + "name (Optional)", "plain", "xsd:string", "The user defined name of the QoS policy." + "policies (Optional)", "plain", "xsd:dict", "The set of scheduler policies and weights for the QoS policy." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant to which this policy is assigned." + +:: + + { + "qos": { + "description": "Another sample QoS profile", + "policies": { + "scheduler": { + "weight": "16" + } + } + } + } + +:: + + { + "qos": { + "description": "Another sample QoS profile", + "id": "5e1841fa-c106-47ee-a736-e527478f1239", + "name": "test-qos-0", + "policies": { + "scheduler": { + "weight": "16" + } + }, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + } + +******************************* +Deletes a specific QOS policy +******************************* + +.. rest_method:: DELETE /v2.0/wrs-tm/qoses/​{qos_id}​ + +**Normal response codes** + +204 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "qos_id", "URI", "csapi:UUID", "The ID for a QOS Policy." + +This operation does not accept a request body. + +-------- +Network +-------- + +The Network entity is an existing OpenStack API. It has been extended to +add the following StarlingX functionality. + +- A QOS policy can optionally be associated to a tenant network + +- The maximum transmit unit (MTU) of each tenant network is inherited + from its associated provider network + +- The status of each tenant network is derived from the state of the + DHCP server which services its subnets + +*************************************************************************** +Lists networks that are accessible to the tenant who submits the reequest +*************************************************************************** + +.. rest_method:: GET /v2.0/networks + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "networks (Optional)", "plain", "xsd:list", "The list of tenant networks." + "wrs-tm:qos (Optional)", "plain", "csapi:UUID", "The unique UUID of the assigned QoS policy." + "status (Optional)", "plain", "xsd:string", "Indicates whether the tenant network is ``ACTIVE`` or ``DOWN``. If the network is DHCP enabled then it can only be active if at least 1 DHCP agent is servicing the network. StarlingX corrected the reporting of this status." + +:: + + { + "networks": [ + { + "admin_state_up": true, + "id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "name": "external-net0", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data0", + "provider:segmentation_id": 10, + "wrs-tm:qos": "d28e697c-c290-4895-b57c-ac7d38db9003", + "router:external": true, + "shared": true, + "status": "ACTIVE", + "subnets": [ + "b282ef86-2584-4a02-9b58-69d6233952a2" + ], + "tenant_id": "206f147dcf72421fa6829e33bfb34637" + }, + { + "admin_state_up": true, + "id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "name": "tenant1-mgmt-net", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data0", + "provider:segmentation_id": 600, + "wrs-tm:qos": "102c64e4-ad26-4610-ae39-f59e15fcb80c", + "router:external": false, + "shared": false, + "status": "ACTIVE", + "subnets": [ + "34efd537-7a72-4fcd-b837-9874caf34117" + ], + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "id": "9472a8ab-9205-43ef-a460-5f01f031791a", + "name": "tenant2-mgmt-net", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data1", + "provider:segmentation_id": 616, + "wrs-tm:qos": "62970a9a-b093-4747-92dd-9de25616036a", + "router:external": false, + "shared": false, + "status": "ACTIVE", + "subnets": [ + "9aa900f4-522b-4b83-ba93-57f7d92da5d5" + ], + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + }, + { + "admin_state_up": true, + "id": "7e5ed852-a990-4fc5-89a2-b17093ca1982", + "name": "internal0-net0", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data0", + "provider:segmentation_id": 700, + "router:external": false, + "shared": true, + "status": "ACTIVE", + "subnets": [ + "ad791a3e-33cf-4d8d-b80f-91c87f97745e" + ], + "tenant_id": "206f147dcf72421fa6829e33bfb34637", + "vlan_transparent": false, + }, + { + "admin_state_up": true, + "id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "name": "tenant1-net0", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data0", + "provider:segmentation_id": 601, + "router:external": false, + "shared": false, + "status": "ACTIVE", + "subnets": [ + "bc269028-1862-4dde-ba2e-62a67d1af4e4", + "837aebc9-6c78-43e9-8124-168ba16adbc7" + ], + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + "vlan_transparent": false, + }, + { + "admin_state_up": true, + "id": "7a77e654-794a-4e19-9679-ac2733e19876", + "name": "tenant2-net0", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data1", + "provider:segmentation_id": 617, + "router:external": false, + "shared": false, + "status": "ACTIVE", + "subnets": [ + "985806f5-9fd7-4d47-9da6-cb0c1316e63d" + ], + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + "vlan_transparent": false, + } + ] + } + +This operation does not accept a request body. + +******************************************* +Shows information for a specified network +******************************************* + +.. rest_method:: GET /v2.0/networks/​{network_id}​ + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401), unauthorized (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "network_id", "URI", "csapi:UUID", "The UUID for a network." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-tm:qos (Optional)", "plain", "csapi:UUID", "The unique UUID of the assigned QoS policy." + "status (Optional)", "plain", "xsd:string", "Indicates whether the tenant network is ``ACTIVE`` or ``DOWN``. If the network is DHCP enabled then it can only be active if at least 1 DHCP agent is servicing the network. StarlingX corrected the reporting of this status." + +:: + + { + "network": { + "admin_state_up": true, + "id": "e87e7438-8a07-4e82-a472-862bb7fa93ac", + "name": "test-net-0", + "mtu": 1500, + "provider:network_type": "vlan", + "provider:physical_network": "group0-data0", + "provider:segmentation_id": 602, + "wrs-tm:qos": "102c64e4-ad26-4610-ae39-f59e15fcb80c", + "router:external": false, + "shared": false, + "status": "ACTIVE", + "subnets": [], + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10", + "vlan_transparent": false, + } + } + +This operation does not accept a request body. + +------- +Subnet +------- + +The Subnet entity is an existing OpenStack API. It has been extended to +add the following StarlingX functionality. + +- A subnet can be configured to allow VLAN tagging by the VM instance. + +************************************************************************* +Lists subnets that are accessible to the tenant who submits the request +************************************************************************* + +.. rest_method:: GET /v2.0/subnets + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "subnets (Optional)", "plain", "xsd:list", "The list of subnets." + "wrs-net:managed (Optional)", "plain", "xsd:bool", "Indicates whether IP address allocation is managed by the system or by the customer. If ``true`` then the system allocates IP addresses when ports are created and attached to VM instances. If ``false`` then the system will not assign any IP addresses automatically. This implies that if the system cannot allocate any IP addresses that it also cannot allocate a DHCP server, manage allocation pools, or server DNS nameservers or static routers." + "wrs-provider:network_type (Optional)", "plain", "xsd:string", "The type of the provider network to which this subnet is assigned. Only visible to admin users." + "wrs-provider:physical_name (Optional)", "plain", "xsd:string", "The name of the provider network to which this subnet is assigned. Only visible to admin users." + "wrs-provider:segmentation_id (Optional)", "plain", "xsd:integer", "The provider network segmentation id to which this subnet is assigned. Only visible to admin users." + "wrs-net:vlan_id (Optional)", "plain", "xsd:integer", "The VLAN ID to be used in the VM instance. If the VLAN ID is 0 then all packets originated from the VM instance are expected to be untagged. If the VLAN ID value is non zero than it is expected that all packets originated by the VM must be tagged with the corresponding VLAN ID value. Any other value will be discarded by the host vswitch." + +:: + + { + "subnets": [ + { + "allocation_pools": [ + { + "end": "192.168.1.254", + "start": "192.168.1.2" + } + ], + "cidr": "192.168.1.0/24", + "dns_nameservers": [], + "enable_dhcp": false, + "gateway_ip": "192.168.1.1", + "host_routes": [], + "id": "b282ef86-2584-4a02-9b58-69d6233952a2", + "ip_version": 4, + "wrs-net:managed": true, + "name": "external-subnet0", + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": 10, + "tenant_id": "206f147dcf72421fa6829e33bfb34637", + "wrs-net:vlan_id": 0 + }, + { + "allocation_pools": [ + { + "end": "192.168.201.50", + "start": "192.168.201.2" + } + ], + "cidr": "192.168.201.0/24", + "dns_nameservers": [], + "enable_dhcp": true, + "gateway_ip": "192.168.201.1", + "host_routes": [], + "id": "9aa900f4-522b-4b83-ba93-57f7d92da5d5", + "ip_version": 4, + "wrs-net:managed": true, + "name": "tenant2-mgmt-subnet", + "network_id": "9472a8ab-9205-43ef-a460-5f01f031791a", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data1", + "wrs-provider:segmentation_id": 616, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3", + "wrs-net:vlan_id": 0 + }, + { + "allocation_pools": [ + { + "end": "192.168.101.50", + "start": "192.168.101.2" + } + ], + "cidr": "192.168.101.0/24", + "dns_nameservers": [], + "enable_dhcp": true, + "gateway_ip": "192.168.101.1", + "host_routes": [], + "id": "34efd537-7a72-4fcd-b837-9874caf34117", + "ip_version": 4, + "wrs-net:managed": true, + "name": "tenant1-mgmt-subnet", + "network_id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": 600, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10", + "wrs-net:vlan_id": 0 + }, + { + "allocation_pools": [], + "cidr": "10.0.0.0/24", + "dns_nameservers": [], + "enable_dhcp": false, + "gateway_ip": null, + "host_routes": [], + "id": "ad791a3e-33cf-4d8d-b80f-91c87f97745e", + "ip_version": 4, + "wrs-net:managed": false, + "name": "internal0-subnet0-0", + "network_id": "7e5ed852-a990-4fc5-89a2-b17093ca1982", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": 700, + "tenant_id": "206f147dcf72421fa6829e33bfb34637", + "wrs-net:vlan_id": 0 + }, + { + "allocation_pools": [], + "cidr": "172.16.0.0/24", + "dns_nameservers": [], + "enable_dhcp": false, + "gateway_ip": null, + "host_routes": [], + "id": "bc269028-1862-4dde-ba2e-62a67d1af4e4", + "ip_version": 4, + "wrs-net:managed": false, + "name": "tenant1-subnet0", + "network_id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": 601, + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10", + "wrs-net:vlan_id": 0 + }, + { + "allocation_pools": [], + "cidr": "172.18.0.0/24", + "dns_nameservers": [], + "enable_dhcp": false, + "gateway_ip": null, + "host_routes": [], + "id": "985806f5-9fd7-4d47-9da6-cb0c1316e63d", + "ip_version": 4, + "wrs-net:managed": false, + "name": "tenant2-subnet0", + "network_id": "7a77e654-794a-4e19-9679-ac2733e19876", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data1", + "wrs-provider:segmentation_id": 617, + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3", + "wrs-net:vlan_id": 0 + } + ] + } + +This operation does not accept a request body. + +****************************************** +Shows information for a specified subnet +****************************************** + +.. rest_method:: GET /v2.0/subnets/​{subnet_id}​ + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +201 + +**Error response codes** + +itemNotFound (401), unauthorized (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "subnet_id", "URI", "csapi:UUID", "The UUID for a subnet." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-net:managed (Optional)", "plain", "xsd:bool", "Indicates whether IP address allocation is managed by the system or by the customer. If ``true`` then the system allocates IP addresses when ports are created and attached to VM instances. If ``false`` then the system will not assign any IP addresses automatically. This implies that if the system cannot allocate any IP addresses that it also cannot allocate a DHCP server, manage allocation pools, or server DNS nameservers or static routers." + "wrs-provider:network_type (Optional)", "plain", "xsd:string", "The type of the provider network to which this subnet is assigned. Only visible to admin users." + "wrs-provider:physical_name (Optional)", "plain", "xsd:string", "The name of the provider network to which this subnet is assigned. Only visible to admin users." + "wrs-provider:segmentation_id (Optional)", "plain", "xsd:integer", "The provider network segmentation id to which this subnet is assigned. Only visible to admin users." + "wrs-net:vlan_id (Optional)", "plain", "xsd:integer", "The VLAN ID to be used in the VM instance. If the VLAN ID is 0 then all packets originated from the VM instance are expected to be untagged. If the VLAN ID value is non zero than it is expected that all packets originated by the VM must be tagged with the corresponding VLAN ID value. Any other value will be discarded by the host vswitch." + +:: + + { + "subnet": { + "allocation_pools": [], + "cidr": "1.2.3.0/24", + "dns_nameservers": [], + "enable_dhcp": false, + "gateway_ip": null, + "host_routes": [], + "id": "837aebc9-6c78-43e9-8124-168ba16adbc7", + "ip_version": 4, + "wrs-net:managed": false, + "name": "test-subnet-0", + "network_id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": 615, + "tenant_id": "206f147dcf72421fa6829e33bfb34637", + "wrs-net:vlan_id": 99 + } + } + +This operation does not accept a request body. + +***************************************** +Creates a subnet on a specified network +***************************************** + +.. rest_method:: POST /v2.0/subnets + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +201 + +**Error response codes** + +badRequest (400), itemNotFound (401), forbidden (403), unauthorized +(404), buildInProgress (409) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-net:managed (Optional)", "plain", "xsd:bool", "Indicates whether IP address allocation is managed by the system or by the customer. If ``true`` then the system allocates IP addresses when ports are created and attached to VM instances. If ``false`` then the system will not assign any IP addresses automatically. This implies that if the system cannot allocate any IP addresses that it also cannot allocate a DHCP server, manage allocation pools, or server DNS nameservers or static routers." + "wrs-net:vlan_id (Optional)", "plain", "xsd:integer", "The VLAN ID to be used in the VM instance. If the VLAN ID is 0 then all packets originated from the VM instance are expected to be untagged. If the VLAN ID value is non zero than it is expected that all packets originated by the VM must be tagged with the corresponding VLAN ID value. Any other value will be discarded by the host vswitch." + "wrs-provider:network_type (Optional)", "plain", "xsd:string", "The type of physical network that maps to this subnet resource. For example, ``flat``, ``vlan``, or ``vxlan``. The value specified must match the equivalent attribute value on the parent network resource. Only available to admin users." + "wrs-provider:physical_network (Optional)", "plain", "xsd:string", "The physical network where this subnet object is implemented. The value specified must match the equivalent attribute value on the parent network resource. Only available to admin users." + "wrs-provider:segmentation_id (Optional)", "plain", "xsd:string", "An isolated segment on the physical network reserved for this subnet resource. The ``network_type`` attribute defines the segmentation model. For example, if the ``network_type`` is vlan, this ID is a vlan identifier. If the ``network_type`` value is vxlan, this ID is a vxlan VNI value. All subnets on a specific network that share the same ``wrs-net:vlan_id`` attribute value must have the same ``segmentation_id`` attribute value. Only available to admin users." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-net:managed (Optional)", "plain", "xsd:bool", "Indicates whether IP address allocation is managed by the system or by the customer. If ``true`` then the system allocates IP addresses when ports are created and attached to VM instances. If ``false`` then the system will not assign any IP addresses automatically. This implies that if the system cannot allocate any IP addresses that it also cannot allocate a DHCP server, manage allocation pools, or server DNS nameservers or static routers." + "wrs-provider:network_type (Optional)", "plain", "xsd:string", "The type of the provider network to which this subnet is assigned. Only visible to admin users." + "wrs-provider:physical_name (Optional)", "plain", "xsd:string", "The name of the provider network to which this subnet is assigned. Only visible to admin users." + "wrs-provider:segmentation_id (Optional)", "plain", "xsd:integer", "The provider network segmentation id to which this subnet is assigned. Only visible to admin users." + "wrs-net:vlan_id (Optional)", "plain", "xsd:integer", "The VLAN ID to be used in the VM instance. If the VLAN ID is 0 then all packets originated from the VM instance are expected to be untagged. If the VLAN ID value is non zero than it is expected that all packets originated by the VM must be tagged with the corresponding VLAN ID value. Any other value will be discarded by the host vswitch." + +:: + + { + "subnet": { + "cidr": "1.2.3.0/24", + "enable_dhcp": false, + "ip_version": 4, + "wrs-net:managed": false, + "name": "test-subnet-0", + "network_id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": "615", + "wrs-net:vlan_id": 99 + } + } + +:: + + { + "subnet": { + "allocation_pools": [], + "cidr": "1.2.3.0/24", + "dns_nameservers": [], + "enable_dhcp": false, + "gateway_ip": null, + "host_routes": [], + "id": "837aebc9-6c78-43e9-8124-168ba16adbc7", + "ip_version": 4, + "wrs-net:managed": false, + "name": "test-subnet-0", + "network_id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "wrs-provider:network_type": "vlan", + "wrs-provider:physical_network": "group0-data0", + "wrs-provider:segmentation_id": 615, + "tenant_id": "206f147dcf72421fa6829e33bfb34637", + "wrs-net:vlan_id": 99 + } + } + +----- +Port +----- + +The Port entity is an existing OpenStack API. It has been extended to +add the following StarlingX functionality. + +- The network interface type (vif_model) is recorded when attached to a + VM instance. + +- Source MAC address filtering is enabled when created for a tenant + which has this feature enabled by the administrator. + +- The MAC address automatically updates to reflect changes to PCI + passthrough devices for VM instances. + +- The maximum transmit unit (MTU) attribute is a reflection of the MTU + value of the attached tenant network. + +******************************************** +Lists ports to which the tenant has access +******************************************** + +.. rest_method:: GET /v2.0/ports + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "ports (Optional)", "plain", "xsd:list", "The list of ports." + "wrs-binding:mac_filtering (Optional)", "plain", "xsd:bool", "The state of source MAC address filtering on the port. If this is ``true`` then the attached vswitch enforces that all ingress packets have a source MAC address that matches the port MAC address." + "wrs-binding:mtu (Optional)", "plain", "xsd:integer", "The maximum transmit unit (MTU). This value is inherited from the tenant network that attaches to this port." + "wrs-binding:vif_model (Optional)", "plain", "xsd:string", "The type of virtual networking device that is presented to the VM instance. This value is only visible if the device_owner is a VM instance port (i.e., device_owner=""compute:nova"")." + +:: + + { + "ports": [ + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-0", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "ce58c529-ba73-47f7-a409-a438ceced112", + "device_owner": "network:router_interface", + "fixed_ips": [ + { + "ip_address": "192.168.201.1", + "subnet_id": "9aa900f4-522b-4b83-ba93-57f7d92da5d5" + } + ], + "id": "e44d4c03-0add-4b1a-bd36-8f6e7ccd48d9", + "mac_address": "fa:16:3e:a6:27:3f", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "9472a8ab-9205-43ef-a460-5f01f031791a", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-0", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "ea2baef7-d84b-44c4-82e7-f274ab5e8b6f", + "device_owner": "network:router_gateway", + "fixed_ips": [ + { + "ip_address": "192.168.1.2", + "subnet_id": "b282ef86-2584-4a02-9b58-69d6233952a2" + } + ], + "id": "0ebefe26-de93-4d9e-b31a-b4620a6743e8", + "mac_address": "fa:16:3e:29:11:9b", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-0", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "ea2baef7-d84b-44c4-82e7-f274ab5e8b6f", + "device_owner": "network:router_interface", + "fixed_ips": [ + { + "ip_address": "192.168.101.1", + "subnet_id": "34efd537-7a72-4fcd-b837-9874caf34117" + } + ], + "id": "cf8c4f0a-f615-4437-a87a-39f2b87b7662", + "mac_address": "fa:16:3e:fb:4b:89", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-0", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "dhcp596d6b96-7696-5200-a782-fa1c60fe4171-f652780a-7a9d-4667-8df4-5c8632728be9", + "device_owner": "network:dhcp", + "fixed_ips": [ + { + "ip_address": "192.168.101.9", + "subnet_id": "34efd537-7a72-4fcd-b837-9874caf34117" + } + ], + "id": "30a92b3d-3353-4c24-9963-d0177b38ad59", + "mac_address": "fa:16:3e:f5:db:a6", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-1", + "wrs-binding:mtu": 1500, + "wrs-binding:vif_model": "virtio", + "binding:vif_type": "bridge", + "device_id": "2e934b37-772e-451a-b64a-cd68d9f8ae42", + "device_owner": "compute:nova", + "fixed_ips": [ + { + "ip_address": "192.168.101.11", + "subnet_id": "34efd537-7a72-4fcd-b837-9874caf34117" + } + ], + "id": "3ec39233-315c-474b-9f08-482e70c264c7", + "mac_address": "fa:16:3e:23:0c:bc", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "2c5c2553-36f2-4db4-8769-6ab71b6e2b1e", + "device_owner": "network:floatingip", + "fixed_ips": [ + { + "ip_address": "192.168.1.4", + "subnet_id": "b282ef86-2584-4a02-9b58-69d6233952a2" + } + ], + "id": "5e5a6728-81af-4b2d-b068-8a8e56847a1e", + "mac_address": "fa:16:3e:67:22:12", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "security_groups": [], + "status": "UNKNOWN", + "tenant_id": "" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-1", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "2e934b37-772e-451a-b64a-cd68d9f8ae42", + "device_owner": "compute:nova", + "fixed_ips": [], + "id": "8c99a79f-212c-45e5-89e6-8aa9ed3b5fcb", + "mac_address": "fa:16:3e:46:47:46", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "2c0896cf-d118-4dca-9760-b4d97e3c7ec3", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-0", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "ce58c529-ba73-47f7-a409-a438ceced112", + "device_owner": "network:router_gateway", + "fixed_ips": [ + { + "ip_address": "192.168.1.3", + "subnet_id": "b282ef86-2584-4a02-9b58-69d6233952a2" + } + ], + "id": "10ce8655-96de-45f4-952c-a830ddf1f0d9", + "mac_address": "fa:16:3e:a4:1d:67", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "f2ade26f-5a16-4fef-b6f7-9bd9769ea1f4", + "device_owner": "network:floatingip", + "fixed_ips": [ + { + "ip_address": "192.168.1.5", + "subnet_id": "b282ef86-2584-4a02-9b58-69d6233952a2" + } + ], + "id": "573e154f-ec13-4e39-afcc-8e79d2089589", + "mac_address": "fa:16:3e:23:37:59", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876", + "security_groups": [], + "status": "UNKNOWN", + "tenant_id": "" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-1", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "2e934b37-772e-451a-b64a-cd68d9f8ae42", + "device_owner": "compute:nova", + "fixed_ips": [], + "id": "9c9b1182-9f7d-4e21-910c-c4441a23d397", + "mac_address": "fa:16:3e:75:5f:61", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "7e5ed852-a990-4fc5-89a2-b17093ca1982", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-0", + "wrs-binding:mtu": 1500, + "binding:vif_type": "bridge", + "device_id": "dhcp596d6b96-7696-5200-a782-fa1c60fe4171-9472a8ab-9205-43ef-a460-5f01f031791a", + "device_owner": "network:dhcp", + "fixed_ips": [ + { + "ip_address": "192.168.201.6", + "subnet_id": "9aa900f4-522b-4b83-ba93-57f7d92da5d5" + } + ], + "id": "62872b6d-3e74-4838-9cf3-99736d0f3919", + "mac_address": "fa:16:3e:92:0b:14", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "9472a8ab-9205-43ef-a460-5f01f031791a", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + } + ] + } + +This operation does not accept a request body. + +**************************************** +Shows information for a specified port +**************************************** + +.. rest_method:: GET /v2.0/ports/​{port_id}​ + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401), unauthorized (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "port_id", "URI", "csapi:UUID", "The UUID for a port." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-binding:mac_filtering (Optional)", "plain", "xsd:bool", "The state of source MAC address filtering on the port. If this is ``true`` then the attached vswitch enforces that all ingress packets have a source MAC address that matches the port MAC address." + "wrs-binding:mtu (Optional)", "plain", "xsd:integer", "The maximum transmit unit (MTU). This value is inherited from the tenant network that attaches to this port." + "wrs-binding:vif_model (Optional)", "plain", "xsd:string", "The type of virtual networking device that is presented to the VM instance. This value is only visible if the device_owner is a VM instance port (i.e., device_owner=""compute:nova"")." + +:: + + { + "port": { + "admin_state_up": true, + "binding:capabilities": { + "port_filter": true + }, + "binding:host_id": "compute-1", + "wrs-binding:mtu": 1500, + "wrs-binding:vif_model": "virtio", + "binding:vif_type": "bridge", + "device_id": "2e934b37-772e-451a-b64a-cd68d9f8ae42", + "device_owner": "compute:nova", + "fixed_ips": [ + { + "ip_address": "192.168.101.11", + "subnet_id": "34efd537-7a72-4fcd-b837-9874caf34117" + } + ], + "id": "3ec39233-315c-474b-9f08-482e70c264c7", + "mac_address": "fa:16:3e:23:0c:bc", + "wrs-binding:mac_filtering": false + "name": "", + "network_id": "f652780a-7a9d-4667-8df4-5c8632728be9", + "security_groups": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + } + +This operation does not accept a request body. + +------- +Router +------- + +The Router entity is an existing OpenStack API. It has been extended to +add the following StarlingX functionality. + +- The host attribute has been added to reflect which compute host + implements the virtual router. + +********************************************************************************* +Lists logical routers that are accessible to the tenant who submits the request +********************************************************************************* + +.. rest_method:: GET /v2.0/routers + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "routers (Optional)", "plain", "xsd:list", "The list of virtual routers." + "wrs-net:host (Optional)", "plain", "xsd:string", "The host node where this virtual router is implemented. Only visible to admin users." + +:: + + { + "routers": [ + { + "admin_state_up": true, + "external_gateway_info": { + "enable_snat": true, + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876" + }, + "wrs-net:host": "compute-0", + "id": "ea2baef7-d84b-44c4-82e7-f274ab5e8b6f", + "name": "tenant1-router", + "routes": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + }, + { + "admin_state_up": true, + "external_gateway_info": { + "enable_snat": true, + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876" + }, + "wrs-net:host": "compute-0", + "id": "ce58c529-ba73-47f7-a409-a438ceced112", + "name": "tenant2-router", + "routes": [], + "status": "ACTIVE", + "tenant_id": "d8753af85cef49a4bf5f95208c4957f3" + } + ] + } + +This operation does not accept a request body. + +************************************** +Shows details for a specified router +************************************** + +.. rest_method:: GET /v2.0/routers/​{router_id}​ + +This is an existing OpenStack API. The documentation that follows lists +only the fields that are new or modified. For a detailed description of +existing and unmodified fields please refer to the standard OpenStack +API documentation. + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (401), forbidden (403), unauthorized (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "router_id", "URI", "csapi:UUID", "The UUID for a router." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "wrs-net:host (Optional)", "plain", "xsd:string", "The host node where this virtual router is implemented. Only visible to admin users." + +:: + + { + "router": { + "admin_state_up": true, + "external_gateway_info": { + "enable_snat": true, + "network_id": "b9475152-11d3-4bda-95c7-fb26a3ad3876" + }, + "wrs-net:host": "compute-0", + "id": "ea2baef7-d84b-44c4-82e7-f274ab5e8b6f", + "name": "tenant1-router", + "routes": [], + "status": "ACTIVE", + "tenant_id": "0590d9fa3dd74bfe9bdf7ed4e5331a10" + } + } + +This operation does not accept a request body. + +---------------- +Port Forwarding +---------------- + +The portfowarding entity is an upstream subproject that is not yet part +of the existing OpenStack API. It provides virtual router port +forwarding functionality. It has been included to add the functionality +to the StarlingX. + +************************************************ +Lists all virtual router port forwarding rules +************************************************ + +.. rest_method:: GET /v2.0/portforwardings + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "portforwardings (Optional)", "plain", "xsd:list", "The list of virtual router port forwarding rules." + "router_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the router to which the rule is associated." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the rule." + "inside_addr (Optional)", "plain", "xsd:string", "The internal (private) address which is the final destination of the forwarding rule." + "inside_port (Optional)", "plain", "xsd:integer", "The internal (private) layer4 protocol port number." + "outside_port (Optional)", "plain", "xsd:integer", "The external (public) address which is the initial destination of the forwarding rule." + "protocol (Optional)", "plain", "xsd:string", "The layer4 protocol name; valid values are: ``udp``, ``tcp``, ``udp-lite``, ``sctp``, ``dccp``." + "description (Optional)", "plain", "xsd:string", "A user defined description string." + +:: + + { + "portforwardings": [{ + "router_id": "3303b254-404c-47eb-b02c-81bf0d602682", + "inside_addr": "192.168.101.63", + "protocol": "tcp", + "outside_port": 1234, + "tenant_id": "6d8ff9303a45465492566fb936fe3b1d", + "description": "sample port forwarding rule", + "id": "66ebb891-f883-4fbd-9daf-15b367429d39", + "inside_port": 80 + }, + { + "router_id": "3303b254-404c-47eb-b02c-81bf0d602682", + "inside_addr": "192.168.101.62", + "protocol": "tcp", + "outside_port": 1235, + "tenant_id": "6d8ff9303a45465492566fb936fe3b1d", + "description": "another sample port forwarding rule", + "id": "f8e22185-07f2-43e7-9213-abf84ef0eb58", + "inside_port": 80 + }] + } + +This operation does not accept a request body. + +************************************************************ +Creates a record for a virtual router port forwarding rule +************************************************************ + +.. rest_method:: POST /v2.0/portforwardings + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "router_id (Optional)", "plain", "xsd:string", "The virtual router on which to create the port forwarding rule" + "inside_addr (Optional)", "plain", "xsd:string", "The internal (private) address which is the final destination of the forwarding rule." + "inside_port (Optional)", "plain", "xsd:integer", "The internal (private) layer4 protocol port number." + "outside_port (Optional)", "plain", "xsd:integer", "The external (public) address which is the initial destination of the forwarding rule." + "protocol (Optional)", "plain", "xsd:string", "The layer4 protocol name; valid values are: ``udp``, ``tcp``, ``udp-lite``, ``sctp``, ``dccp``." + "description (Optional)", "plain", "xsd:string", "A user defined description string." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "router_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the router to which the rule is associated." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the rule." + "inside_addr (Optional)", "plain", "xsd:string", "The internal (private) address which is the final destination of the forwarding rule." + "inside_port (Optional)", "plain", "xsd:integer", "The internal (private) layer4 protocol port number." + "outside_port (Optional)", "plain", "xsd:integer", "The external (public) address which is the initial destination of the forwarding rule." + "protocol (Optional)", "plain", "xsd:string", "The layer4 protocol name; valid values are: ``udp``, ``tcp``, ``udp-lite``, ``sctp``, ``dccp``." + "description (Optional)", "plain", "xsd:string", "A user defined description string." + +:: + + { + "portforwarding": { + "router_id": "3303b254-404c-47eb-b02c-81bf0d602682", + "inside_addr": "192.168.101.63", + "protocol": "tcp", + "outside_port": "1234", + "inside_port": "80", + "description": "sample port forwarding rule" + } + } + +:: + + { + "portforwarding": { + "router_id": "3303b254-404c-47eb-b02c-81bf0d602682", + "inside_addr": "192.168.101.63", + "protocol": "tcp", + "outside_port": "1234", + "tenant_id": "6d8ff9303a45465492566fb936fe3b1d", + "description": "sample port forwarding rule", + "id": "66ebb891-f883-4fbd-9daf-15b367429d39", + "inside_port": "80" + } + } + +********************************************************************************* +Shows detailed information about a specific virtual router port forwarding rule +********************************************************************************* + +.. rest_method:: GET /v2.0/portforwardings/​{portforwarding_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), +unauthorized (401), forbidden (403), badMethod (405), overLimit (413), +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "portforwarding_id", "URI", "csapi:UUID", "The ID for a virtual router port forwarding rule." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "router_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the router to which the rule is associated." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the rule." + "inside_addr (Optional)", "plain", "xsd:string", "The internal (private) address which is the final destination of the forwarding rule." + "inside_port (Optional)", "plain", "xsd:integer", "The internal (private) layer4 protocol port number." + "outside_port (Optional)", "plain", "xsd:integer", "The external (public) address which is the initial destination of the forwarding rule." + "protocol (Optional)", "plain", "xsd:string", "The layer4 protocol name; valid values are: ``udp``, ``tcp``, ``udp-lite``, ``sctp``, ``dccp``." + "description (Optional)", "plain", "xsd:string", "A user defined description string." + +:: + + { + "portforwarding": { + "router_id": "3303b254-404c-47eb-b02c-81bf0d602682", + "inside_addr": "192.168.101.63", + "protocol": "tcp", + "outside_port": 1234, + "tenant_id": "6d8ff9303a45465492566fb936fe3b1d", + "description": "sample port forwarding rule", + "id": "66ebb891-f883-4fbd-9daf-15b367429d39", + "inside_port": 80 + } + } + +This operation does not accept a request body. + +*********************************************** +Updates a virtual router port forwarding rule +*********************************************** + +.. rest_method:: PUT /v2.0/portforwardings/​{portforwarding_id}​ + +**Normal response codes** + +200 + +**Error response codes** + +badMediaType (415), NetworkNotFound (400) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "portforwarding_id", "URI", "csapi:UUID", "The ID for a virtual router port forwarding rule." + "inside_addr (Optional)", "plain", "xsd:string", "The internal (private) address which is the final destination of the forwarding rule." + "inside_port (Optional)", "plain", "xsd:integer", "The internal (private) layer4 protocol port number." + "outside_port (Optional)", "plain", "xsd:integer", "The external (public) address which is the initial destination of the forwarding rule." + "protocol (Optional)", "plain", "xsd:string", "The layer4 protocol name; valid values are: ``udp``, ``tcp``, ``udp-lite``, ``sctp``, ``dccp``." + "description (Optional)", "plain", "xsd:string", "A user defined description string." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "router_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the router to which the rule is associated." + "tenant_id (Optional)", "plain", "csapi:UUID", "The unique UUID of the tenant which owns the rule." + "inside_addr (Optional)", "plain", "xsd:string", "The internal (private) address which is the final destination of the forwarding rule." + "inside_port (Optional)", "plain", "xsd:integer", "The internal (private) layer4 protocol port number." + "outside_port (Optional)", "plain", "xsd:integer", "The external (public) address which is the initial destination of the forwarding rule." + "protocol (Optional)", "plain", "xsd:string", "The layer4 protocol name; valid values are: ``udp``, ``tcp``, ``udp-lite``, ``sctp``, ``dccp``." + "description (Optional)", "plain", "xsd:string", "A user defined description string." + +:: + + { + "portforwarding": { + "description": "updated sample port forwarding rule" + } + } + +:: + + { + "portforwarding": { + "router_id": "3303b254-404c-47eb-b02c-81bf0d602682", + "inside_addr": "192.168.101.63", + "protocol": "tcp", + "outside_port": 1234, + "tenant_id": "6d8ff9303a45465492566fb936fe3b1d", + "description": "updated sample port forwarding rule", + "id": "66ebb891-f883-4fbd-9daf-15b367429d39", + "inside_port": 80 + } + } + +******************************************************** +Deletes a specific virtual router port forwarding rule +******************************************************** + +.. rest_method:: DELETE /v2.0/portforwardings/​{portforwarding_id}​ + +**Normal response codes** + +204 + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "portforwarding_id", "URI", "csapi:UUID", "The ID for a virtual router port forwarding rule." + +This operation does not accept a request body. + + + + diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 3d9b7c704..0b9b69b76 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -6,3 +6,9 @@ StarlingX Documentation .. toctree:: :maxdepth: 2 + + api-ref-blockstorage-v2-cgcs-ext + api-ref-compute-v2-cgcs-ext + api-ref-image-v2-cgcs-ext + api-ref-networking-v2-cgcs-ext +