529 lines
16 KiB
ReStructuredText
529 lines
16 KiB
ReStructuredText
.. -*- 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.
|
|
|
|
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 <https://wiki.openstack.org/wiki/Neutron/APIv2
|
|
-specification#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
|
|
- 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
|
|
|
|
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
|
|
- 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
|
|
|
|
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
|
|
|
|
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: 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
|
|
|
|
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
|
|
|
|
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.
|
|
|