.. -*- rst -*- ======= Subnets ======= Lists, shows details for, creates, updates, and deletes subnet resources. Default subnetpool extension ============================ The default subnetpool extension (``default-subnetpools``) allows administrative users to specify default subnetpools (one per IP version). Then users can specify the ``use_default_subnetpool`` attribute when creating a subnet, instead of having to specify the ``subnetpool_id`` attribute referencing the default subnetpool. Subnet service types extension ============================== Subnet service types extension (``subnet-service-types``) allows administrative users to set the desired port types for a subnet by adding the ``service_types`` attributes to ``subnets``. (For example, the ``network:floatingip_agent_gateway`` service type enables DVR floating IP agent gateway ports to use the subnet to minimize public IP address consumption). List subnets ============ .. rest_method:: GET /v2.0/subnets Lists subnets that the project has access to. Default policy settings return only subnets owned by the project of the user submitting the request, unless the user has administrative role. You can control which attributes are returned by using the fields query parameter. You can filter results by using query string parameters. Use the ``fields`` query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see `Filtering and Column Selection `__. Normal response codes: 200 Error response codes: 401 Request ------- .. rest_parameters:: parameters.yaml - id: id-query - tenant_id: project_id-query - project_id: project_id-query - name: name-query - enable_dhcp: subnet-enable_dhcp-query - network_id: subnet-network_id-query - ip_version: subnet-ip_version-query - gateway_ip: subnet-gateway_ip-query - cidr: cidr-query - description: description-query - ipv6_address_mode: subnet-ipv6_address_mode-query - ipv6_ra_mode: subnet-ipv6_ra_mode-query - revision_number: revision_number-query - segment_id: subnet-segment_id-query - subnetpool_id: subnet-subnetpool_id-query - tags: tags-query - tags-any: tags-any-query - not-tags: not-tags-query - not-tags-any: not-tags-any-query - fields: fields Response Parameters ------------------- .. rest_parameters:: parameters.yaml - subnets: subnets-obj - id: subnet-id-body - tenant_id: project_id - project_id: project_id - name: subnet-name - enable_dhcp: subnet-enable_dhcp - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers - allocation_pools: subnet-allocation_pools - host_routes: subnet-host_routes - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip - cidr: cidr - created_at: subnet-created_at - description: description - ipv6_address_mode: subnet-ipv6_address_mode - ipv6_ra_mode: subnet-ipv6_ra_mode - revision_number: revision_number - segment_id: subnet-segment_id - service_types: subnet-service_types - subnetpool_id: subnet-subnetpool_id - updated_at: subnet-updated_at Response Example ---------------- .. literalinclude:: samples/subnets/subnets-list-response.json :language: javascript Create subnet ============= .. rest_method:: POST /v2.0/subnets Creates a subnet on a network. OpenStack Networking does not try to derive the correct IP version from the CIDR. If you do not specify the ``gateway_ip`` attribute, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet. To specify a subnet without a gateway, set the ``gateway_ip`` attribute to ``null`` in the request body. If you do not specify the ``allocation_pools`` attribute, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise, you can explicitly specify allocation pools as shown in the following example. When you specify both the ``allocation_pools`` and ``gateway_ip`` attributes, you must ensure that the gateway IP does not overlap with the allocation pools; otherwise, the call returns the ``Conflict (409)`` response code. A subnet can have one or more name servers and host routes. Hosts in this subnet use the name servers. Devices with IP addresses from this subnet, not including the local subnet route, use the host routes. Specify the ``ipv6_ra_mode`` and ``ipv6_address_mode`` attributes to create subnets that support IPv6 configurations, such as stateless address autoconfiguration (SLAAC), DHCPv6 stateful, and DHCPv6 stateless configurations. A subnet can optionally be associated with a network segment when it is created by specifying the ``segment_id`` of a valid segment on the specified network. A network with subnets associated in this way is called a routed network. On any given network, all of the subnets must be associated with segments or none of them can be. Neutron enforces this invariant. Currently, routed networks are only supported for provider networks. Normal response codes: 201 Error response codes: 400, 401, 403, 404, 409 Request ------- .. rest_parameters:: parameters.yaml - subnet: subnet-obj - tenant_id: project_id-request - project_id: project_id-request - name: subnet-name-request - enable_dhcp: subnet-enable_dhcp-request - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers-request - allocation_pools: subnet-allocation_pools-request - host_routes: subnet-host_routes-request - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip-request - cidr: cidr - description: description-request - ipv6_address_mode: subnet-ipv6_address_mode-request - ipv6_ra_mode: subnet-ipv6_ra_mode-request - segment_id: subnet-segment_id-request - subnetpool_id: subnet-subnetpool_id-request - use_default_subnetpool: use_default_subnetpool - service_types: subnet-service_types-optional Request Example --------------- .. literalinclude:: samples/subnets/subnet-create-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - subnet: subnet-obj - id: subnet-id-body - tenant_id: project_id - project_id: project_id - name: subnet-name - enable_dhcp: subnet-enable_dhcp - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers - allocation_pools: subnet-allocation_pools - host_routes: subnet-host_routes - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip - cidr: cidr - created_at: subnet-created_at - description: description - ipv6_address_mode: subnet-ipv6_address_mode - ipv6_ra_mode: subnet-ipv6_ra_mode - revision_number: revision_number - service_types: subnet-service_types - subnetpool_id: subnet-subnetpool_id - segment_id: subnet-segment_id - updated_at: subnet-updated_at Response Example ---------------- .. literalinclude:: samples/subnets/subnet-create-response.json :language: javascript Bulk create subnet ================== .. rest_method:: POST /v2.0/subnets Creates multiple subnets in a single request. Specify a list of subnets in the request body. The bulk create operation is always atomic. Either all or no subnets in the request body are created. Normal response codes: 201 Error response codes: 400, 401, 403, 404, 409 Request ------- .. rest_parameters:: parameters.yaml - subnets: subnets-obj - tenant_id: project_id-request - project_id: project_id-request - name: subnet-name-request - enable_dhcp: subnet-enable_dhcp-request - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers-request - allocation_pools: subnet-allocation_pools-request - host_routes: subnet-host_routes-request - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip-request - cidr: cidr - description: description-request - ipv6_address_mode: subnet-ipv6_address_mode-request - ipv6_ra_mode: subnet-ipv6_ra_mode-request - segment_id: subnet-segment_id-request - subnetpool_id: subnet-subnetpool_id-request - use_default_subnetpool: use_default_subnetpool - service_types: subnet-service_types-optional Request Example --------------- .. literalinclude:: samples/subnets/subnets-create-bulk-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - subnets: subnets-obj - id: subnet-id-body - tenant_id: project_id - project_id: project_id - name: subnet-name - enable_dhcp: subnet-enable_dhcp - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers - allocation_pools: subnet-allocation_pools - host_routes: subnet-host_routes - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip - cidr: cidr - created_at: subnet-created_at - description: description - ipv6_address_mode: subnet-ipv6_address_mode - ipv6_ra_mode: subnet-ipv6_ra_mode - revision_number: revision_number - segment_id: subnet-segment_id - service_types: subnet-service_types - subnetpool_id: subnet-subnetpool_id - updated_at: subnet-updated_at Response Example ---------------- .. literalinclude:: samples/subnets/subnets-create-bulk-response.json :language: javascript Show subnet details =================== .. rest_method:: GET /v2.0/subnets/{subnet_id} Shows details for a subnet. Use the fields query parameter to filter the results. Normal response codes: 200 Error response codes: 401, 404 Request ------- .. rest_parameters:: parameters.yaml - subnet_id: subnet_id-path Response Parameters ------------------- .. rest_parameters:: parameters.yaml - subnet: subnet-obj - id: subnet-id-body - tenant_id: project_id - project_id: project_id - created_at: subnet-created_at - name: subnet-name - enable_dhcp: subnet-enable_dhcp - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers - allocation_pools: subnet-allocation_pools - host_routes: subnet-host_routes - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip - cidr: cidr - updated_at: subnet-updated_at - description: description - ipv6_address_mode: subnet-ipv6_address_mode - ipv6_ra_mode: subnet-ipv6_ra_mode - revision_number: revision_number - segment_id: subnet-segment_id - service_types: subnet-service_types - subnetpool_id: subnet-subnetpool_id Response Example ---------------- .. literalinclude:: samples/subnets/subnet-show-response.json :language: javascript Update subnet ============= .. rest_method:: PUT /v2.0/subnets/{subnet_id} Updates a subnet. Some attributes, such as IP version (ip_version), CIDR (cidr), and segment (segment_id) cannot be updated. Attempting to update these attributes results in a ``400 Bad Request`` error. Normal response codes: 200 Error response codes: 400, 401, 403, 404, 412 Request ------- .. rest_parameters:: parameters.yaml - subnet_id: subnet_id-path - name: subnet-name-update-request - enable_dhcp: subnet-enable_dhcp-request - dns_nameservers: subnet-dns_nameservers-request - allocation_pools: subnet-allocation_pools-request - host_routes: subnet-host_routes-request - gateway_ip: subnet-gateway_ip-request - description: description-request - service_types: subnet-service_types-optional Request Example --------------- .. literalinclude:: samples/subnets/subnet-update-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - subnet: subnet-obj - id: subnet-id-body - tenant_id: project_id - project_id: project_id - name: subnet-name - enable_dhcp: subnet-enable_dhcp - network_id: subnet-network_id - dns_nameservers: subnet-dns_nameservers - allocation_pools: subnet-allocation_pools - host_routes: subnet-host_routes - ip_version: subnet-ip_version - gateway_ip: subnet-gateway_ip - cidr: cidr - created_at: subnet-created_at - description: description - ipv6_address_mode: subnet-ipv6_address_mode - ipv6_ra_mode: subnet-ipv6_ra_mode - revision_number: revision_number - segment_id: subnet-segment_id - service_types: subnet-service_types - subnetpool_id: subnet-subnetpool_id - updated_at: subnet-updated_at Response Example ---------------- .. literalinclude:: samples/subnets/subnet-update-response.json :language: javascript Delete subnet ============= .. rest_method:: DELETE /v2.0/subnets/{subnet_id} Deletes a subnet. The operation fails if subnet IP addresses are still allocated. Normal response codes: 204 Error response codes: 401, 404, 412 Request ------- .. rest_parameters:: parameters.yaml - subnet_id: subnet_id-path Response -------- There is no body content for the response of a successful DELETE request.