Add Zone Tasks, Export and Import API Docs

Adds api-ref docs for:

* Zone Import
* Zone Export
* Zone Tasks
* - XFR
* - Abandon

Change-Id: Id0bfca25969a8def0b5be4969be3ae6e772b0249
This commit is contained in:
Graham Hayes 2016-05-16 16:38:50 +01:00
parent 83d4d031a8
commit 403b6aec7a
14 changed files with 843 additions and 0 deletions

View File

@ -0,0 +1,191 @@
============
Zone Exports
============
Zone imports can be an asynchronous operation,
and there are different endpoints to view the status and progress of an export
Create a Zone Export
====================
.. rest_method:: POST /v2/zones/{zone_id}/tasks/exports
Export a zone.
.. note:: This POST should have no body
Normal response codes: 202
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_id: path_zone_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- id: zone_export_id
- location: zone_export_location
- status: zone_export_status
- zone_id: zone_export_zone_id
- message: zone_export_message
- project_id: project_id
- created_at: created_at
- updated_at: updated_at
- version: version
Response Example
----------------
.. literalinclude:: samples/zones/create-zone-export-response.json
:language: javascript
List all Zone Exports
=====================
.. rest_method:: GET /v2/zones/tasks/exports
Normal response codes: 200
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_id: zone_export_zone_id_filter
- message: zone_export_message_filter
- status: zone_export_status_filter
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- id: zone_export_id
- location: zone_export_location
- status: zone_export_status
- zone_id: zone_export_zone_id
- project_id: project_id
- created_at: created_at
- updated_at: updated_at
- version: version
- links: links
- metadata: metadata
Response Example
----------------
.. literalinclude:: samples/zones/list-zone-export-response.json
:language: javascript
Show a Zone Export Information
==============================
.. rest_method:: GET /v2/zones/tasks/exports/{zone_export_id}
Normal response codes: 200
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_export_id: path_zone_export_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- id: zone_export_id
- location: zone_export_location
- status: zone_export_status
- zone_id: zone_export_zone_id
- project_id: project_id
- created_at: created_at
- updated_at: updated_at
- version: version
- links: links
Response Example
----------------
.. literalinclude:: samples/zones/show-zone-export-response.json
:language: javascript
Retrive a Zone Export from the Designate Datastore
==================================================
.. rest_method:: GET /v2/zones/tasks/exports/{zone_export_id}/export
Normal response codes: 200
Error response codes:405,404,403,401,400,503,
.. note::
This endpoint will send a response with a ``text/dns`` content-type.
If the client does not include a ``Accepts: text/dns`` header the request
will be rejected.
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_export_id: path_zone_export_id
- accepts: zone_export_accepts
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
Response Example
----------------
.. literalinclude:: samples/zones/show-zone-export-content.txt
:language: text

View File

@ -0,0 +1,174 @@
===========
Zone Import
===========
Zone imports are an asynchronous operation, and there are different endpoints
to view the status and progress of an import
Create a Zone Import
====================
.. rest_method:: POST /v2/zones/tasks/imports
Import a zone.
.. note:: This POST should have no body, and the content-type should be text/dns
Normal response codes: 202
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- id: zone_import_id
- status: zone_import_status
- zone_id: zone_import_zone_id
- message: zone_import_message
- project_id: project_id
- created_at: created_at
- updated_at: updated_at
- version: version
Response Example
----------------
.. literalinclude:: samples/zones/create-zone-import-response.json
:language: javascript
List all Zone Imports
=====================
.. rest_method:: GET /v2/zones/tasks/imports
Normal response codes: 200
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_id: zone_import_zone_id_filter
- message: zone_import_message_filter
- status: zone_import_status_filter
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- id: zone_import_id
- status: zone_import_status
- zone_id: zone_import_zone_id
- project_id: project_id
- created_at: created_at
- updated_at: updated_at
- version: version
- links: links
- metadata: metadata
Response Example
----------------
.. literalinclude:: samples/zones/list-zone-import-response.json
:language: javascript
Show a Zone Import
==================
.. rest_method:: GET /v2/zones/tasks/imports/{zone_import_id}
Normal response codes: 200
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_import_id: path_zone_import_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- id: zone_import_id
- status: zone_import_status
- zone_id: zone_import_zone_id
- project_id: project_id
- created_at: created_at
- updated_at: updated_at
- version: version
- links: links
Response Example
----------------
.. literalinclude:: samples/zones/show-zone-import-response.json
:language: javascript
Delete a Zone Import
====================
.. rest_method:: DELETE /v2/zones/tasks/imports/{zone_import_id}
This will just delete the record of the zone import, not the imported zone.
The zone will have to be deleted from the zone delete API
Normal response codes: 204
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_import_id: path_zone_import_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id

View File

@ -0,0 +1,82 @@
==========
Zone Tasks
==========
Zone tasks.
Abandon Zone
============
.. rest_method:: POST /v2/zones/{zone_id}/tasks/abandon
Abandon a zone.
This removes a zone from the designate database without removing it
from the backends.
.. note:: This POST should have no body.
.. warning::
This is a protentially dangerous operation, and should only be used if required
Normal response codes: 204
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_id: path_zone_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
Manually Trigger an Update of a Secondary Zone
==============================================
.. rest_method:: POST /v2/zones/{zone_id}/tasks/xfr
Trigger a new XFR from the upstream DNS servers
This will cause designate to query the name servers and if the version in
Designate is out of date, import the new version.
This is useful if an upstream server failed to send a notify to Designate
.. note:: This POST should have no body.
.. important:: This is only useful on SECONDARY zones.
Normal response codes: 202
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_id: path_zone_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id

View File

@ -71,6 +71,7 @@ Response Example
:language: javascript
List Zones
==========
@ -193,6 +194,48 @@ Response Example
:language: javascript
Get the Name Servers for a Zone
===============================
.. rest_method:: GET /v2/zones/{zone_id}/nameservers
Show the nameservers for a zone
Normal response codes: 200
Error response codes:405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- x-auth-token: x-auth-token
- x-auth-all-projects: x-auth-all-projects
- x-auth-sudo-project-id: x-auth-sudo-project-id
- zone_id: path_zone_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: x-openstack-request-id
- hostname: zone_nameserver_hostname
- priority: zone_nameserver_priority
Response Example
----------------
.. literalinclude:: samples/zones/show-zone-nameservers-response.json
:language: javascript
Update a Zone
=============

View File

@ -7,4 +7,7 @@
.. rest_expand_all::
.. include:: dns-api-v2-zone.inc
.. include:: dns-api-v2-zone-import.inc
.. include:: dns-api-v2-zone-export.inc
.. include:: dns-api-v2-zone-tasks.inc
.. include:: dns-api-v2-recordset.inc

View File

@ -321,6 +321,23 @@ zone_transfered_at:
required: true
type: enum
zone_nameserver_hostname:
description: |
The hostname of the nameserver that the zone should be delegated to
in: body
required: true
type: hostname
zone_nameserver_priority:
description: |
The priority of the nameserver. This is used to determine the order of the
the nameserver listings, and which server is used in the SOA record for the
zone.
in: body
required: true
type: hostname
#############################
# Recordset Variables #
@ -435,6 +452,193 @@ recordset_description:
required: false
type: string
#############################
# Zone Import Variables #
#############################
# Header Variables
###################
# Path Variables
#################
path_zone_import_id:
description: |
ID for this zone import
in: path
required: true
type: uuid
# Query Variables
##################
# Filters
# 'status', 'message', 'zone_id'
zone_import_zone_id_filter:
description: |
Filter results to only show zone_imports that have a ``zone_id`` matching the filter
in: query
required: false
type: uuid
zone_import_status_filter:
description: |
Filter results to only show zone_imports that have a ``status`` matching the filter
in: query
required: false
type: string
zone_import_message_filter:
description: |
Filter results to only show zone_imports that have a ``message`` matching the filter
in: query
required: false
type: string
# Body Variables
#################
zone_import_id:
description: |
ID for this zone import
in: body
required: true
type: uuid
zone_import_zone_id:
description: |
ID for the zone that was created by this import
in: body
required: false
type: uuid
zone_import_status:
description: |
Current status of the zone import
in: body
required: true
type: uuid
zone_import_message:
description: |
Message about the current status of the import
in: body
required: false
type: uuid
#############################
# Zone Export Variables #
#############################
# Header Variables
###################
zone_export_accepts:
description: >
Content-Type that will be accepted by the client.
This endpoint will send a response with a ``text/dns`` content-type.
If the client does not include a ``Accepts: text/dns`` header
in: header
required: true
type: string
# Path Variables
#################
path_zone_export_id:
description: |
ID for this zone export
in: path
required: true
type: uuid
# Query Variables
##################
# Filters
# 'status', 'message', 'zone_id'
zone_export_zone_id_filter:
description: |
Filter results to only show ``zone_exports`` that have a ``zone_id`` matching the filter
in: query
required: false
type: uuid
zone_export_status_filter:
description: |
Filter results to only show ``zone_exports`` that have a ``status`` matching the filter
in: query
required: false
type: string
zone_export_message_filter:
description: |
Filter results to only show ``zone_exports`` that have a ``message`` matching the filter
in: query
required: false
type: string
# Body Variables
#################
zone_export_id:
description: |
ID for this zone export
in: body
required: true
type: uuid
zone_export_zone_id:
description: |
ID for the zone that is being exported
in: body
required: false
type: uuid
zone_export_status:
description: |
Current status of the zone export
in: body
required: true
type: uuid
zone_export_message:
description: |
Message about the current status of the export
in: body
required: false
type: uuid
zone_export_location:
description: >
Where the exported zone is published to.
There are currently one placement option available - designate.
This will be shown by ``designate://<url>``.
As more drivers are added, this will expand to include swift - this will be
indicated by location being set to ``swift://<region>/<container>/<file>``
This is also allowed be a webserver if the operator implements a different
data store, and will be indicted by ``http://<url>``
When a zone export is complete, the location will be updated, and
the exported zone file will be available at the location specified.
in: body
required: false
type: string
#############################
# <ITEM> Variables #
#############################

View File

@ -0,0 +1,14 @@
{
"status": "PENDING",
"zone_id": "074e805e-fe87-4cbb-b10b-21a06e215d41",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720"
},
"created_at": "2015-08-27T20:57:03.000000",
"updated_at": null,
"version": 1,
"location": null,
"message": null,
"project_id": "1",
"id": "8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720"
}

View File

@ -0,0 +1,13 @@
{
"status": "PENDING",
"zone_id": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/imports/074e805e-fe87-4cbb-b10b-21a06e215d41"
},
"created_at": "2015-05-08T15:43:42.000000",
"updated_at": null,
"version": 1,
"message": null,
"project_id": "1",
"id": "074e805e-fe87-4cbb-b10b-21a06e215d41"
}

View File

@ -0,0 +1,26 @@
{
"exports": [
{
"status": "COMPLETE",
"zone_id": "17a8d6b3-6ace-4857-b113-a707c5f975b1",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/exports/204be410-0a9c-44b8-839e-bc4df3bb0d9a",
"export": "http://127.0.0.1:9001/v2/zones/tasks/exports/204be410-0a9c-44b8-839e-bc4df3bb0d9a/export"
},
"created_at": "2016-04-04T01:53:29.000000",
"updated_at": "2016-04-04T01:53:29.000000",
"version": 2,
"location": "designate://v2/zones/tasks/exports/204be410-0a9c-44b8-839e-bc4df3bb0d9a/export",
"message": null,
"project_id": "1de6e2fdc22342d3bef6340c7b70f497",
"id": "204be410-0a9c-44b8-839e-bc4df3bb0d9a"
}
],
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/exports"
},
"metadata": {
"total_count": 1
}
}

View File

@ -0,0 +1,38 @@
{
"imports": [
{
"status": "COMPLETE",
"zone_id": "047888ee-e9dd-4c08-8b44-ab2e879e01bd",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/imports/0436a86e-ffc1-4d38-82a7-d75170fcd2a9",
"href": "http://127.0.0.1:9001/v2/zones/047888ee-e9dd-4c08-8b44-ab2e879e01bd"
},
"created_at": "2016-04-05T06:03:06.000000",
"updated_at": "2016-04-05T06:03:06.000000",
"version": 2,
"message": "example.com. imported",
"project_id": "1de6e2fdc22342d3bef6340c7b70f497",
"id": "0436a86e-ffc1-4d38-82a7-d75170fcd2a9"
},
{
"status": "COMPLETE",
"zone_id": "68a17870-7f81-470a-b5e9-2753460fd6dc",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/imports/f0aa4ac1-f975-46a4-b417-339acd1ea8e3",
"href": "http://127.0.0.1:9001/v2/zones/68a17870-7f81-470a-b5e9-2753460fd6dc"
},
"created_at": "2016-04-05T06:06:26.000000",
"updated_at": "2016-04-05T06:06:26.000000",
"version": 2,
"message": "temp.org. imported",
"project_id": "1de6e2fdc22342d3bef6340c7b70f497",
"id": "f0aa4ac1-f975-46a4-b417-339acd1ea8e3"
}
],
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/imports"
},
"metadata": {
"total_count": 2
}
}

View File

@ -0,0 +1,18 @@
$ORIGIN example.com.
$TTL 42
example.com. IN SOA ns.designate.com. nsadmin.example.com. (
1394213803 ; serial
3600 ; refresh
600 ; retry
86400 ; expire
3600 ; minimum
)
example.com. IN NS ns.designate.com.
example.com. IN MX 10 mail.example.com.
ns.example.com. IN A 10.0.0.1
mail.example.com. IN A 10.0.0.2

View File

@ -0,0 +1,15 @@
{
"status": "COMPLETE",
"zone_id": "6625198b-d67d-47dc-8d29-f90bd60f3ac4",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720",
"export": "http://127.0.0.1:9001/v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720/export"
},
"created_at": "2015-08-27T20:57:03.000000",
"updated_at": "2015-08-27T20:57:03.000000",
"version": 2,
"location": "designate://v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720/export",
"message": null,
"project_id": "noauth-project",
"id": "8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720"
}

View File

@ -0,0 +1,14 @@
{
"status": "COMPLETE",
"zone_id": "6625198b-d67d-47dc-8d29-f90bd60f3ac4",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/imports/074e805e-fe87-4cbb-b10b-21a06e215d41",
"href": "http://127.0.0.1:9001/v2/zones/6625198b-d67d-47dc-8d29-f90bd60f3ac4"
},
"created_at": "2015-05-08T15:43:42.000000",
"updated_at": "2015-05-08T15:43:42.000000",
"version": 2,
"message": "example.com. imported",
"project_id": "noauth-project",
"id": "074e805e-fe87-4cbb-b10b-21a06e215d41"
}

View File

@ -0,0 +1,8 @@
{
"nameservers": [
{
"hostname": "ns1.example.com.",
"priority": 10
}
]
}