Skip to main content

zones

Creates, updates, deletes, gets or lists a zones resource.

Overview​

Namezones
TypeResource
Idoci.dns.zones

Fields​

The following fields are returned by SELECT queries:

A response containing a single zone object.

NameDatatypeDescription
idstringThe OCID of the zone.
namestringThe name of the zone.
compartmentIdstringThe OCID of the compartment containing the zone.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
dnssecConfigobjectDNSSEC configuration data. A zone may have a maximum of 10 DnssecKeyVersions, regardless of signing key type.
dnssecStatestringThe state of DNSSEC on the zone. For DNSSEC to function, every parent zone in the DNS tree up to the top-level domain (or an independent trust anchor) must also have DNSSEC correctly set up. After enabling DNSSEC, you must add a DS record to the zone's parent zone containing the KskDnssecKeyVersion data. You can find the DS data in the dsData attribute of the KskDnssecKeyVersion. Then, use the PromoteZoneDnssecKeyVersion operation to promote the KskDnssecKeyVersion. New KskDnssecKeyVersions are generated annually, a week before the existing KskDnssecKeyVersion's expiration. To rollover a KskDnssecKeyVersion, you must replace the parent zone's DS record containing the old KskDnssecKeyVersion data with the data from the new KskDnssecKeyVersion. To remove the old DS record without causing service disruption, wait until the old DS record's TTL has expired, and the new DS record has propagated. After the DS replacement has been completed, then the PromoteZoneDnssecKeyVersion operation must be called. Metrics are emitted in the oci_dns namespace daily for each KskDnssecKeyVersion indicating how many days are left until expiration. We recommend that you set up alarms and notifications for KskDnssecKeyVersion expiration so that the necessary parent zone updates can be made and the PromoteZoneDnssecKeyVersion operation can be called. Enabling DNSSEC results in additional records in DNS responses which increases their size and can cause higher response latency. For more information, see [DNSSEC](/iaas/Content/DNS/Concepts/dnssec.htm). (ENABLED, DISABLED) (default: DISABLED, x-obmcs-top-level-enum: #/definitions/ZoneDnssecState)
externalDownstreamsarrayExternal secondary servers for the zone. This field is currently not supported when zoneType is SECONDARY or scope is PRIVATE.
externalMastersarrayExternal master servers for the zone. externalMasters becomes a required parameter when the zoneType value is SECONDARY.
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
isProtectedbooleanA Boolean flag indicating whether or not parts of the resource are unable to be explicitly managed.
lifecycleStatestringThe current state of the zone resource. (ACTIVE, CREATING, DELETED, DELETING, FAILED, UPDATING)
nameserversarrayThe authoritative nameservers for the zone.
resolutionModestringThe resolution mode of a zone defines behavior related to how query responses can be handled. See [Private DNS Zone Transparency](/Content/DNS/Tasks/privatedns.htm#use-cases__resolution) for more information. (STATIC, TRANSPARENT, RTYPE_TRANSPARENT) (default: STATIC, x-obmcs-top-level-enum: #/definitions/ZoneResolutionMode)
scopestringThe scope of the zone. (GLOBAL, PRIVATE) (x-obmcs-top-level-enum: #/definitions/Scope)
selfstring (url)The canonical absolute URL of the resource.
serialinteger (int64)The current serial of the zone. As seen in the zone's SOA record.
timeCreatedstring (date-time)The date and time the resource was created in "YYYY-MM-ddThh:mm:ssZ" format with a Z offset, as defined by RFC 3339. Example: 2016-07-22T17:23:59:60Z
versionstringVersion is the never-repeating, totally-orderable, version of the zone, from which the serial field of the zone's SOA record is derived.
viewIdstringThe OCID of the private view containing the zone. This value will be null for zones in the global DNS, which are publicly resolvable and not part of a private view.
zoneTransferServersarrayThe OCI nameservers that transfer the zone data with external nameservers.
zoneTypestringThe type of the zone. Must be either PRIMARY or SECONDARY. SECONDARY is only supported for GLOBAL zones. (PRIMARY, SECONDARY)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectzoneNameOrId, regionIf-None-Match, If-Modified-Since, opc-request-id, scope, viewId, compartmentIdGets information about the specified zone, including its creation date, zone type, and serial.<br /><br />When the zone name is provided as a path parameter and PRIVATE is used for the scope query<br />parameter then the viewId query parameter is required.<br />
listselectcompartmentId, regionopc-request-id, limit, page, name, nameContains, zoneType, timeCreatedGreaterThanOrEqualTo, timeCreatedLessThan, lifecycleState, sortBy, sortOrder, scope, viewId, tsigKeyId, dnssecStateGets a list of all zones in the specified compartment.<br /><br />The collection can be filtered by name, time created, scope, associated view, and zone type.<br />Filtering by view is only supported for private zones.<br />
createinsertregion, name, compartmentIdopc-request-id, opc-retry-token, compartmentId, scope, viewIdCreates a new zone in the specified compartment.<br /><br />Private zones must have a zone type of PRIMARY. Creating a private zone at or under oraclevcn.com<br />within the default protected view of a VCN-dedicated resolver is not permitted.<br />
updateupdatezoneNameOrId, regionIf-Match, If-Unmodified-Since, opc-request-id, scope, viewId, compartmentIdUpdates the zone with the specified information.<br /><br />Global secondary zones may have their external masters updated. For more information about secondary<br />zones, see [Manage DNS Service Zone](/iaas/Content/DNS/Tasks/managingdnszones.htm). When the zone name<br />is provided as a path parameter and PRIVATE is used for the scope query parameter then the viewId<br />query parameter is required.<br />
deletedeletezoneNameOrId, regionIf-Match, If-Unmodified-Since, opc-request-id, scope, viewId, compartmentIdDeletes the specified zone and all its steering policy attachments.<br /><br />A 204 response indicates that the zone has been successfully deleted. Protected zones cannot be deleted.<br />When the zone name is provided as a path parameter and PRIVATE is used for the scope query parameter<br />then the viewId query parameter is required.<br />
change_compartmentexeczoneId, region, compartmentIdIf-Match, opc-retry-token, opc-request-id, scopeMoves a zone into a different compartment.<br /><br />Protected zones cannot have their compartment changed. When the zone name is provided as a path<br />parameter and PRIVATE is used for the scope query parameter then the viewId query parameter is<br />required.<br /><br />Note: All SteeringPolicyAttachment objects associated with this zone will also be moved into<br />the provided compartment.<br />
promote_zone_dnssec_key_versionexeczoneId, region, dnssecKeyVersionUuidIf-Match, If-Unmodified-Since, opc-retry-token, opc-request-id, scopePromotes a specified DnssecKeyVersion on the zone.<br /><br />If the DnssecKeyVersion identified in the request body is a key signing key (KSK) that is replacing<br />another DnssecKeyVersion, then the old DnssecKeyVersion is scheduled for removal from the zone.<br /><br />For key signing keys (KSKs), you must create the DS record with the new key information before promoting<br />the new key to establish a chain of trust. To avoid a service disruption, remove the old DS record as soon<br />as its TTL (time to live) expires.<br /><br />For more information, see [DNSSEC](/iaas/Content/DNS/Concepts/dnssec.htm).<br />
stage_zone_dnssec_key_versionexeczoneId, region, predecessorDnssecKeyVersionUuidIf-Match, If-Unmodified-Since, opc-retry-token, opc-request-id, scopeStages a new DnssecKeyVersion on the zone. Staging is a process that generates a new "successor" key version<br />that replaces an existing "predecessor" key version.<br />Note: A new key-signing key (KSK) version is inert until you update the parent zone DS records.<br /><br />For more information, see the [DNSSEC](/iaas/Content/DNS/Concepts/dnssec.htm) documentation.<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe OCID of the compartment the resource belongs to.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
zoneIdstringThe OCID of the target zone.
zoneNameOrIdstringThe name or OCID of the target zone.
If-MatchstringThe If-Match header field makes the request method conditional on the existence of at least one current representation of the target resource, when the field-value is *, or having a current representation of the target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value.
If-Modified-SincestringThe If-Modified-Since header field makes a GET or HEAD request method conditional on the selected representation's modification date being more recent than the date provided in the field-value. Transfer of the selected representation's data is avoided if that data has not changed.
If-None-MatchstringThe If-None-Match header field makes the request method conditional on the absence of any current representation of the target resource, when the field-value is *, or having a selected representation with an entity-tag that does not match any of those listed in the field-value.
If-Unmodified-SincestringThe If-Unmodified-Since header field makes the request method conditional on the selected representation's last modification date being earlier than or equal to the date provided in the field-value. This field accomplishes the same purpose as If-Match for cases where the user agent does not have an entity-tag for the representation.
compartmentIdstringThe OCID of the compartment the zone belongs to. This parameter is deprecated and should be omitted.
dnssecStatestringSearch for zones that have the given DnssecState.
lifecycleStatestringThe state of a resource.
limitinteger (int64)The maximum number of items to return in a page of the collection.
namestringA case-sensitive filter for zone names. Will match any zone with a name that equals the provided value.
nameContainsstringSearch by zone name. Will match any zone whose name (case-insensitive) contains the provided value.
opc-request-idstringUnique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringThe value of the opc-next-page response header from the previous "List" call.
scopestringSpecifies to operate only on resources that have a matching DNS scope.
sortBystringThe field by which to sort zones.
sortOrderstringThe order to sort the resources.
timeCreatedGreaterThanOrEqualTostring (date-time)An [RFC 3339](https:​//www.ietf.org/rfc/rfc3339.txt) timestamp that states all returned resources were created on or after the indicated time.
timeCreatedLessThanstring (date-time)An [RFC 3339](https:​//www.ietf.org/rfc/rfc3339.txt) timestamp that states all returned resources were created before the indicated time.
tsigKeyIdstringSearch for zones that are associated with a TSIG key.
viewIdstringThe OCID of the view the zone is associated with. Required when accessing a private zone by name.
zoneTypestringSearch by zone type, PRIMARY or SECONDARY. Will match any zone whose type equals the provided value.

SELECT examples​

Gets information about the specified zone, including its creation date, zone type, and serial.<br /><br />When the zone name is provided as a path parameter and PRIVATE is used for the scope query<br />parameter then the viewId query parameter is required.<br />

SELECT
id,
name,
compartmentId,
definedTags,
dnssecConfig,
dnssecState,
externalDownstreams,
externalMasters,
freeformTags,
isProtected,
lifecycleState,
nameservers,
resolutionMode,
scope,
self,
serial,
timeCreated,
version,
viewId,
zoneTransferServers,
zoneType
FROM oci.dns.zones
WHERE zoneNameOrId = '{{ zoneNameOrId }}' -- required
AND region = '{{ region }}' -- required
AND If-None-Match = '{{ If-None-Match }}'
AND If-Modified-Since = '{{ If-Modified-Since }}'
AND opc-request-id = '{{ opc-request-id }}'
AND scope = '{{ scope }}'
AND viewId = '{{ viewId }}'
AND compartmentId = '{{ compartmentId }}'
;

INSERT examples​

Creates a new zone in the specified compartment.<br /><br />Private zones must have a zone type of PRIMARY. Creating a private zone at or under oraclevcn.com<br />within the default protected view of a VCN-dedicated resolver is not permitted.<br />

INSERT INTO oci.dns.zones (
compartmentId,
definedTags,
freeformTags,
migrationSource,
name,
region,
opc-request-id,
opc-retry-token,
compartmentId,
scope,
viewId
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ freeformTags }}',
'{{ migrationSource }}',
'{{ name }}' /* required */,
'{{ region }}',
'{{ opc-request-id }}',
'{{ opc-retry-token }}',
'{{ compartmentId }}' /* required */,
'{{ scope }}',
'{{ viewId }}'
RETURNING
id,
name,
compartmentId,
definedTags,
dnssecConfig,
dnssecState,
externalDownstreams,
externalMasters,
freeformTags,
isProtected,
lifecycleState,
nameservers,
resolutionMode,
scope,
self,
serial,
timeCreated,
version,
viewId,
zoneTransferServers,
zoneType
;

UPDATE examples​

Updates the zone with the specified information.<br /><br />Global secondary zones may have their external masters updated. For more information about secondary<br />zones, see [Manage DNS Service Zone](/iaas/Content/DNS/Tasks/managingdnszones.htm). When the zone name<br />is provided as a path parameter and PRIVATE is used for the scope query parameter then the viewId<br />query parameter is required.<br />

UPDATE oci.dns.zones
SET 
definedTags = '{{ definedTags }}',
dnssecState = '{{ dnssecState }}',
externalDownstreams = '{{ externalDownstreams }}',
externalMasters = '{{ externalMasters }}',
freeformTags = '{{ freeformTags }}',
resolutionMode = '{{ resolutionMode }}'
WHERE 
zoneNameOrId = '{{ zoneNameOrId }}' --required
AND region = '{{ region }}' --required
AND If-Match = '{{ If-Match}}'
AND If-Unmodified-Since = '{{ If-Unmodified-Since}}'
AND opc-request-id = '{{ opc-request-id}}'
AND scope = '{{ scope}}'
AND viewId = '{{ viewId}}'
AND compartmentId = '{{ compartmentId}}'
RETURNING
id,
name,
compartmentId,
definedTags,
dnssecConfig,
dnssecState,
externalDownstreams,
externalMasters,
freeformTags,
isProtected,
lifecycleState,
nameservers,
resolutionMode,
scope,
self,
serial,
timeCreated,
version,
viewId,
zoneTransferServers,
zoneType;

DELETE examples​

Deletes the specified zone and all its steering policy attachments.<br /><br />A 204 response indicates that the zone has been successfully deleted. Protected zones cannot be deleted.<br />When the zone name is provided as a path parameter and PRIVATE is used for the scope query parameter<br />then the viewId query parameter is required.<br />

DELETE FROM oci.dns.zones
WHERE zoneNameOrId = '{{ zoneNameOrId }}' --required
AND region = '{{ region }}' --required
AND If-Match = '{{ If-Match }}'
AND If-Unmodified-Since = '{{ If-Unmodified-Since }}'
AND opc-request-id = '{{ opc-request-id }}'
AND scope = '{{ scope }}'
AND viewId = '{{ viewId }}'
AND compartmentId = '{{ compartmentId }}'
;

Lifecycle Methods​

Moves a zone into a different compartment.<br /><br />Protected zones cannot have their compartment changed. When the zone name is provided as a path<br />parameter and PRIVATE is used for the scope query parameter then the viewId query parameter is<br />required.<br /><br />Note: All SteeringPolicyAttachment objects associated with this zone will also be moved into<br />the provided compartment.<br />

EXEC oci.dns.zones.change_compartment 
@zoneId='{{ zoneId }}' --required, 
@region='{{ region }}' --required, 
@If-Match='{{ If-Match }}', 
@opc-retry-token='{{ opc-retry-token }}', 
@opc-request-id='{{ opc-request-id }}', 
@scope='{{ scope }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;