.. -*- 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. Resource timestamps =================== The ``standard-attr-timestamp`` extension adds the ``created_at`` and ``updated_at`` attributes to all resources that have standard attributes. Subnet allocation extension =========================== Subnet allocation extension (``subnet_allocation``) enables allocation of subnets from a subnet pool. Subnet DNS publish fixed IP extension ===================================== The ``subnet-dns-publish-fixed-ip`` extension adds the ``dns_publish_fixed_ip`` attribute to subnets. It allows to select per subnet whether DNS records for fixed IPs are to be published in an external DNS service. Segment extension ================= The `Segments`_ (``segment``) extension makes it possible to associate a subnet with a specific L2 segment on the network, instead of spanning all the segments in the network. The association between network and subnet remains, but an optional ``segment_id`` field is added to the subnet so that it can be associated with a particular segment on the network. With multiple subnets on a network the ``segment_id`` is used to determine if the subnets are l2-adjacent or not. Subnets within a network are either all associated to segments, or none of them are associated to segments. Subnet segment_id writable extension ==================================== The subnet segment_id writable (``subnet-segmentid-writable``) extension enhances the `Segments`_ (``segment``) extension in that now the ``segment_id`` attribute is also available for write when a subnet is updated. Segment peer subnet host routes extension ========================================= The segment peer subnet host routes extension ( ``segments-peer-subnet-host-routes``) extension enhances the `Segments`_ (``segment``) extension in that now the ``host_routes`` property of the different `Subnets`_ (``subnets``) in a routed network gets routes to the peer subnets on different segments added automatically. This ensures that traffic within an L3 routed network stays within the network even when the default route is on a different host interface. 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). Tag extension ============= The ``standard-attr-tag`` adds Tag support for resources with standard attributes by adding the ``tags`` attribute allowing consumers to associate tags with resources. 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. .. include:: filtering-list.inc 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 - shared: shared-query - sort_dir: sort_dir - sort_key: subnet-sort_key - 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 - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip-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: created_at_resource - 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: updated_at_resource - tags: tags - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip - router:external: subnet-router:external 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. .. note:: Creating a subnet does not always result in an automatic port update for the ports which are already bound on the network. For details see: https://docs.openstack.org/neutron/latest/admin/config-ipv6.html#address-modes-for-ports 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 - prefixlen: subnet-prefixlen-request - 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 - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip-request 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: created_at_resource - 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: updated_at_resource - tags: tags - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip - router:external: subnet-router:external 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 - prefixlen: subnet-prefixlen-request - 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 - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip-request 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: created_at_resource - 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: updated_at_resource - tags: tags - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip - router:external: subnet-router:external 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. .. include:: filtering-show.inc 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: created_at_resource - 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: updated_at_resource - 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 - tags: tags - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip - router:external: subnet-router:external 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 - segment_id: subnet-segment_id-request - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip-request 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: created_at_resource - 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: updated_at_resource - tags: tags - dns_publish_fixed_ip: subnet-dns_publish_fixed_ip - router:external: subnet-router:external 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.