Skip to main content

subnets

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

Overview​

Namesubnets
TypeResource
Idoci.network.subnets

Fields​

The following fields are returned by SELECT queries:

The subnet was retrieved.

NameDatatypeDescription
idstringThe subnet's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
availabilityDomainstringThe subnet's availability domain. This attribute will be null if this is a regional subnet instead of an AD-specific subnet. Oracle recommends creating regional subnets. Example: Uocm:PHX-AD-1
cidrBlockstringThe subnet's CIDR block. Example: 10.0.1.0/24
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the subnet.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
dhcpOptionsIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the set of DHCP options that the subnet uses.
displayNamestringA user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
dnsLabelstringA DNS label for the subnet, used in conjunction with the VNIC's hostname and VCN's DNS label to form a fully qualified domain name (FQDN) for each VNIC within this subnet (for example, bminstance1.subnet123.vcn1.oraclevcn.com). Must be an alphanumeric string that begins with a letter and is unique within the VCN. The value cannot be changed. The absence of this parameter means the Internet and VCN Resolver will not resolve hostnames of instances in this subnet. For more information, see [DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm). Example: subnet123
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](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
ipv4CidrBlocksarrayThe list of all IPv4 CIDR blocks for the subnet that meets the following criteria: - Ipv4 CIDR blocks must be valid. - Multiple Ipv4 CIDR blocks must not overlap each other or the on-premises network CIDR block. - The number of prefixes must not exceed the limit of IPv4 prefixes allowed to a subnet.
ipv6CidrBlockstringFor an IPv6-enabled subnet, this is the IPv6 prefix for the subnet's private IP address space. The subnet size is always /64. IPv6 addressing is supported for all commercial and government regions. See [IPv6 Addresses](/iaas/Content/Network/Concepts/ipv6.htm). Example: 2001:0db8:0123:1111::/64
ipv6CidrBlocksarrayThe list of all IPv6 prefixes (Oracle allocated IPv6 GUA, ULA or private IPv6 prefixes, BYOIPv6 prefixes) for the subnet.
ipv6PublicCidrBlockstringFor an IPv6-enabled subnet, this is the IPv6 prefix for the subnet's public IP address space. The subnet size is always /64. The left 48 bits are inherited from the ipv6PublicCidrBlock of the [Vcn](#/en/iaas/latest/Vcn/), and the remaining 16 bits are from the subnet's ipv6CidrBlock. Example: 2001:0db8:0123:1111::/64
ipv6VirtualRouterIpstringFor an IPv6-enabled subnet, this is the IPv6 address of the virtual router. Example: 2001:0db8:0123:1111:89ab:cdef:1234:5678
lifecycleStatestringThe subnet's current state. (PROVISIONING, AVAILABLE, TERMINATING, TERMINATED)
prohibitPublicIpOnVnicbooleanWhether VNICs within this subnet can have public IP addresses. Defaults to false, which means VNICs created in this subnet will automatically be assigned public IP addresses unless specified otherwise during instance launch or VNIC creation (with the assignPublicIp flag in [CreateVnicDetails](#/en/iaas/latest/CreateVnicDetails/)). If prohibitPublicIpOnVnic is set to true, VNICs created in this subnet cannot have public IP addresses (that is, it's a private subnet). Example: true
routeTableIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the route table that the subnet uses.
securityListIdsarrayThe OCIDs of the security list or lists that the subnet uses. Remember that security lists are associated with the subnet, but the rules are applied to the individual VNICs in the subnet.
subnetDomainNamestringThe subnet's domain name, which consists of the subnet's DNS label, the VCN's DNS label, and the oraclevcn.com domain. For more information, see [DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm). Example: subnet123.vcn1.oraclevcn.com
timeCreatedstring (date-time)The date and time the subnet was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z
vcnIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN the subnet is in.
virtualRouterIpstringThe IP address of the virtual router. Example: 10.0.14.1
virtualRouterMacstringThe MAC address of the virtual router. Example: 00:00:00:00:00:01

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectsubnetId, regionGets the specified subnet's information.
listselectcompartmentId, regionlimit, page, vcnId, displayName, sortBy, sortOrder, lifecycleStateLists the subnets in the specified VCN and the specified compartment.<br />If the VCN ID is not provided, then the list includes the subnets from all VCNs in the specified compartment.<br />
createinsertregion, compartmentId, vcnIdopc-retry-tokenCreates a new subnet in the specified VCN. You can't change the size of the subnet after creation,<br />so it's important to think about the size of subnets you need before creating them.<br />For more information, see [VCNs and Subnets](/iaas/Content/Network/Tasks/managingVCNs.htm).<br />For information on the number of subnets you can have in a VCN, see<br />[Service Limits](/iaas/Content/General/Concepts/servicelimits.htm).<br /><br />For the purposes of access control, you must provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment where you want the subnet<br />to reside. Notice that the subnet doesn't have to be in the same compartment as the VCN, route tables, or<br />other Networking Service components. If you're not sure which compartment to use, put the subnet in<br />the same compartment as the VCN. For more information about compartments and access control, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm). For information about OCIDs,<br />see [Resource Identifiers](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />You may optionally associate a route table with the subnet. If you don't, the subnet will use the<br />VCN's default route table. For more information about route tables, see<br />[Route Tables](/iaas/Content/Network/Tasks/managingroutetables.htm).<br /><br />You may optionally associate a security list with the subnet. If you don't, the subnet will use the<br />VCN's default security list. For more information about security lists, see<br />[Security Lists](/iaas/Content/Network/Concepts/securitylists.htm).<br /><br />You may optionally associate a set of DHCP options with the subnet. If you don't, the subnet will use the<br />VCN's default set. For more information about DHCP options, see<br />[DHCP Options](/iaas/Content/Network/Tasks/managingDHCP.htm).<br /><br />You may optionally specify a display name for the subnet, otherwise a default is provided.<br />It does not have to be unique, and you can change it. Avoid entering confidential information.<br /><br />You can also add a DNS label for the subnet, which is required if you want the Internet and<br />VCN Resolver to resolve hostnames for instances in the subnet. For more information, see<br />[DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm).<br />
updateupdatesubnetId, regionif-matchUpdates the specified subnet.<br />
deletedeletesubnetId, regionif-matchDeletes the specified subnet, but only if there are no instances in the subnet. This is an asynchronous<br />operation. The subnet's lifecycleState will change to TERMINATING temporarily. If there are any<br />instances in the subnet, the state will instead change back to AVAILABLE.<br />
add_ipv4_subnet_cidrexecsubnetId, region, ipv4CidrBlockopc-retry-token, if-match, opc-request-idAdd an IPv4 prefix to a subnet.<br />
add_ipv6_subnet_cidrexecsubnetId, region, ipv6CidrBlockopc-retry-token, if-match, opc-request-idAdd an IPv6 prefix to a subnet.<br />
change_compartmentexecsubnetId, region, compartmentIdopc-request-id, opc-retry-tokenMoves a subnet into a different compartment within the same tenancy. For information<br />about moving resources between compartments, see<br />[Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br />
modify_ipv4_subnet_cidrexecsubnetId, region, ipv4CidrBlock, updatedIpv4CidrBlockopc-retry-token, if-match, opc-request-idUpdates the specified Ipv4 CIDR block of a Subnet. The new Ipv4 CIDR IP range must meet the following criteria:<br /><br />- Must be valid.<br />- Must not overlap with another Ipv4 CIDR block in the Subnet or the on-premises network CIDR block.<br />- Must not exceed the limit of Ipv4 CIDR blocks allowed per Subnet.<br />- Must include IP addresses from the original CIDR block that are used in the VCN's existing route rules.<br />- No IP address in an existing subnet should be outside of the new CIDR block range.<br />
remove_ipv4_subnet_cidrexecsubnetId, region, ipv4CidrBlockopc-retry-token, if-match, opc-request-idRemove an IPv4 prefix from a subnet<br />
remove_ipv6_subnet_cidrexecsubnetId, region, ipv6CidrBlockopc-retry-token, if-match, opc-request-idRemove an IPv6 prefix from a subnet. At least one IPv6 CIDR should remain.<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](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
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)
subnetIdstringSpecify the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the subnet.
displayNamestringA filter to return only resources that match the given display name exactly.
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerFor list pagination. The maximum number of results per page, or items to return in a paginated "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine). Example: 50
opc-request-idstringUnique 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).
pagestringFor list pagination. The value of the opc-next-page response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for DISPLAYNAME is ascending. The DISPLAYNAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by availability domain if the scope of the resource type is within a single availability domain. If you call one of these "List" operations without specifying an availability domain, the resources are grouped by availability domain, then sorted.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC). The DISPLAYNAME sort order is case sensitive.
vcnIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN.

SELECT examples​

Gets the specified subnet's information.

SELECT
id,
availabilityDomain,
cidrBlock,
compartmentId,
definedTags,
dhcpOptionsId,
displayName,
dnsLabel,
freeformTags,
ipv4CidrBlocks,
ipv6CidrBlock,
ipv6CidrBlocks,
ipv6PublicCidrBlock,
ipv6VirtualRouterIp,
lifecycleState,
prohibitPublicIpOnVnic,
routeTableId,
securityListIds,
subnetDomainName,
timeCreated,
vcnId,
virtualRouterIp,
virtualRouterMac
FROM oci.network.subnets
WHERE subnetId = '{{ subnetId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new subnet in the specified VCN. You can't change the size of the subnet after creation,<br />so it's important to think about the size of subnets you need before creating them.<br />For more information, see [VCNs and Subnets](/iaas/Content/Network/Tasks/managingVCNs.htm).<br />For information on the number of subnets you can have in a VCN, see<br />[Service Limits](/iaas/Content/General/Concepts/servicelimits.htm).<br /><br />For the purposes of access control, you must provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment where you want the subnet<br />to reside. Notice that the subnet doesn't have to be in the same compartment as the VCN, route tables, or<br />other Networking Service components. If you're not sure which compartment to use, put the subnet in<br />the same compartment as the VCN. For more information about compartments and access control, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm). For information about OCIDs,<br />see [Resource Identifiers](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />You may optionally associate a route table with the subnet. If you don't, the subnet will use the<br />VCN's default route table. For more information about route tables, see<br />[Route Tables](/iaas/Content/Network/Tasks/managingroutetables.htm).<br /><br />You may optionally associate a security list with the subnet. If you don't, the subnet will use the<br />VCN's default security list. For more information about security lists, see<br />[Security Lists](/iaas/Content/Network/Concepts/securitylists.htm).<br /><br />You may optionally associate a set of DHCP options with the subnet. If you don't, the subnet will use the<br />VCN's default set. For more information about DHCP options, see<br />[DHCP Options](/iaas/Content/Network/Tasks/managingDHCP.htm).<br /><br />You may optionally specify a display name for the subnet, otherwise a default is provided.<br />It does not have to be unique, and you can change it. Avoid entering confidential information.<br /><br />You can also add a DNS label for the subnet, which is required if you want the Internet and<br />VCN Resolver to resolve hostnames for instances in the subnet. For more information, see<br />[DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm).<br />

INSERT INTO oci.network.subnets (
availabilityDomain,
cidrBlock,
compartmentId,
definedTags,
dhcpOptionsId,
displayName,
dnsLabel,
freeformTags,
ipv4CidrBlocks,
ipv6CidrBlock,
ipv6CidrBlocks,
prohibitPublicIpOnVnic,
routeTableId,
securityListIds,
vcnId,
region,
opc-retry-token
)
SELECT 
'{{ availabilityDomain }}',
'{{ cidrBlock }}',
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ dhcpOptionsId }}',
'{{ displayName }}',
'{{ dnsLabel }}',
'{{ freeformTags }}',
'{{ ipv4CidrBlocks }}',
'{{ ipv6CidrBlock }}',
'{{ ipv6CidrBlocks }}',
{{ prohibitPublicIpOnVnic }},
'{{ routeTableId }}',
'{{ securityListIds }}',
'{{ vcnId }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
availabilityDomain,
cidrBlock,
compartmentId,
definedTags,
dhcpOptionsId,
displayName,
dnsLabel,
freeformTags,
ipv4CidrBlocks,
ipv6CidrBlock,
ipv6CidrBlocks,
ipv6PublicCidrBlock,
ipv6VirtualRouterIp,
lifecycleState,
prohibitPublicIpOnVnic,
routeTableId,
securityListIds,
subnetDomainName,
timeCreated,
vcnId,
virtualRouterIp,
virtualRouterMac
;

UPDATE examples​

Updates the specified subnet.<br />

UPDATE oci.network.subnets
SET 
definedTags = '{{ definedTags }}',
dhcpOptionsId = '{{ dhcpOptionsId }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
ipv6CidrBlock = '{{ ipv6CidrBlock }}',
ipv6CidrBlocks = '{{ ipv6CidrBlocks }}',
routeTableId = '{{ routeTableId }}',
securityListIds = '{{ securityListIds }}'
WHERE 
subnetId = '{{ subnetId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
availabilityDomain,
cidrBlock,
compartmentId,
definedTags,
dhcpOptionsId,
displayName,
dnsLabel,
freeformTags,
ipv4CidrBlocks,
ipv6CidrBlock,
ipv6CidrBlocks,
ipv6PublicCidrBlock,
ipv6VirtualRouterIp,
lifecycleState,
prohibitPublicIpOnVnic,
routeTableId,
securityListIds,
subnetDomainName,
timeCreated,
vcnId,
virtualRouterIp,
virtualRouterMac;

DELETE examples​

Deletes the specified subnet, but only if there are no instances in the subnet. This is an asynchronous<br />operation. The subnet's lifecycleState will change to TERMINATING temporarily. If there are any<br />instances in the subnet, the state will instead change back to AVAILABLE.<br />

DELETE FROM oci.network.subnets
WHERE subnetId = '{{ subnetId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods​

Add an IPv4 prefix to a subnet.<br />

EXEC oci.network.subnets.add_ipv4_subnet_cidr 
@subnetId='{{ subnetId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"ipv4CidrBlock": "{{ ipv4CidrBlock }}"
}'
;