Skip to main content

vcns

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

Overview​

Namevcns
TypeResource
Idoci.network.vcns

Fields​

The following fields are returned by SELECT queries:

The VCN was retrieved.

NameDatatypeDescription
idstringThe VCN's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
byoipv6CidrBlocksarrayThe list of BYOIPv6 prefixes required to create a VCN that uses BYOIPv6 ranges.
cidrBlockstringDeprecated. The first CIDR IP address from cidrBlocks. Example: 172.16.0.0/16
cidrBlocksarrayThe list of IPv4 CIDR blocks the VCN will use.
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the VCN.
defaultDhcpOptionsIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) for the VCN's default set of DHCP options.
defaultRouteTableIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) for the VCN's default route table.
defaultSecurityListIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) for the VCN's default security list.
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"}}
displayNamestringA user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
dnsLabelstringA DNS label for the VCN, used in conjunction with the VNIC's hostname and subnet'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. The value cannot be changed. The absence of this parameter means the Internet and VCN Resolver will not work for this VCN. For more information, see [DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm). Example: vcn1
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"}
ipv6CidrBlockstringFor an IPv6-enabled VCN, this is the IPv6 prefix for the VCN's private IP address space. The VCN size is always /56. Oracle provides the IPv6 prefix to use as the same CIDR for the ipv6PublicCidrBlock. When creating a subnet, specify the last 8 bits, 00 to FF. See [IPv6 Addresses](/iaas/Content/Network/Concepts/ipv6.htm). Example: 2001:0db8:0123::/56
ipv6PrivateCidrBlocksarrayFor an IPv6-enabled VCN, this is the list of Private IPv6 prefixes for the VCN's IP address space.
ipv6PublicCidrBlockstringFor an IPv6-enabled VCN, this is the IPv6 prefix for the VCN's public IP address space. The VCN size is always /56. This prefix is always provided by Oracle. If you don't provide a custom prefix for the ipv6CidrBlock when creating the VCN, Oracle assigns that value and also uses it for ipv6PublicCidrBlock. Oracle uses addresses from this block for the publicIpAddress attribute of an [Ipv6](#/en/iaas/latest/Ipv6/) that has internet access allowed. Example: 2001:0db8:0123::/48
isEncryptedbooleanIndicates whether traffic within the VCN is encrypted. For more information, see [VN Encryption](/iaas/Content/gov-cloud/govinfo.htm#govinfo_topic_LAN-encryption).
isZprOnlybooleanIndicates whether ZPR Only mode is enforced.
lifecycleStatestringThe VCN's current state. (PROVISIONING, AVAILABLE, TERMINATING, TERMINATED, UPDATING)
securityAttributesobject[Security attributes](/iaas/Content/zero-trust-packet-routing/zpr-artifacts.htm#security-attributes) are labels for a resource that can be referenced in a [Zero Trust Packet Routing](/iaas/Content/zero-trust-packet-routing/overview.htm) (ZPR) policy to control access to ZPR-supported resources. Example: {"Oracle-DataSecurity-ZPR": {"MaxEgressCount": {"value":"42","mode":"audit"}}}
timeCreatedstring (date-time)The date and time the VCN was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z
vcnDomainNamestringThe VCN's domain name, which consists of 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: vcn1.oraclevcn.com

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectvcnId, regionGets the specified VCN's information.
listselectcompartmentId, regionlimit, page, displayName, sortBy, sortOrder, lifecycleStateLists the virtual cloud networks (VCNs) in the specified compartment.<br />
createinsertregion, compartmentIdopc-retry-tokenCreates a new virtual cloud network (VCN). For more information, see<br />[VCNs and Subnets](/iaas/Content/Network/Tasks/managingVCNs.htm).<br /><br />For the VCN, you specify a list of one or more IPv4 CIDR blocks that meet the following criteria:<br /><br />- The CIDR blocks must be valid.<br />- They must not overlap with each other or with the on-premises network CIDR block.<br />- The number of CIDR blocks does not exceed the limit of CIDR blocks allowed per VCN.<br /><br />For a CIDR block, Oracle recommends that you use one of the private IP address ranges specified in [RFC 1918](https:​//tools.ietf.org/html/rfc1918) (10.0.0.0/8, 172.16/12, and 192.168/16). Example:<br />172.16.0.0/16. The CIDR blocks can range from /16 to /30.<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 VCN to<br />reside. Consult an Oracle Cloud Infrastructure administrator in your organization if you're not sure which<br />compartment to use. Notice that the VCN doesn't have to be in the same compartment as the subnets or other<br />Networking Service components. 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, see<br />[Resource Identifiers](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />You may optionally specify a display name for the VCN, otherwise a default is provided. It does not have to<br />be unique, and you can change it. Avoid entering confidential information.<br /><br />You can also add a DNS label for the VCN, which is required if you want the instances to use the<br />Interent and VCN Resolver option for DNS in the VCN. For more information, see<br />[DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm).<br /><br />The VCN automatically comes with a default route table, default security list, and default set of DHCP options.<br />The [OCID](/iaas/Content/General/Concepts/identifiers.htm) for each is returned in the response. You can't delete these default objects, but you can change their<br />contents (that is, change the route rules, security list rules, and so on).<br /><br />The VCN and subnets you create are not accessible until you attach an internet gateway or set up a Site-to-Site VPN<br />or FastConnect. For more information, see<br />[Overview of the Networking Service](/iaas/Content/Network/Concepts/overview.htm).<br />
updateupdatevcnId, regionif-matchUpdates the specified VCN.<br />
deletedeletevcnId, regionif-matchDeletes the specified VCN. The VCN must be completely empty and have no attached gateways. This is an asynchronous<br />operation.<br /><br />A deleted VCN's lifecycleState changes to TERMINATING and then TERMINATED temporarily until the VCN is completely<br />removed. A completely removed VCN does not appear in the results of a ListVcns operation and can't be used in a<br />GetVcn operation.<br />
add_vcn_cidrexecvcnId, region, cidrBlockopc-request-id, opc-retry-token, if-matchAdds a CIDR block to a VCN. The CIDR block you add:<br /><br />- Must be valid.<br />- Must not overlap with another CIDR block in the VCN, a CIDR block of a peered VCN, or the on-premises network CIDR block.<br />- Must not exceed the limit of CIDR blocks allowed per VCN.<br /><br />Note: Adding a CIDR block places your VCN in an updating state until the changes are complete. You cannot create or update the VCN's subnets, VLANs, LPGs, or route tables during this operation. The time to completion can take a few minutes. You can use the GetWorkRequest operation to check the status of the update.<br />
add_ipv6_vcn_cidrexecvcnId, regionopc-request-id, opc-retry-token, if-matchAdd an IPv6 prefix to a VCN. The VCN size is always /56.<br />AddIpv6VcnCidr supports adding Private IPv6 Prefix i.e. ULA or an IPv6 GUA assigned by Oracle or BYOIPv6 Prefix, only one of these per request.<br />Once added the IPv6 prefix cannot be removed or modified.<br />
change_compartmentexecvcnId, region, compartmentIdopc-request-id, opc-retry-tokenMoves a VCN 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_vcn_cidrexecvcnId, region, originalCidrBlock, newCidrBlockopc-request-id, opc-retry-token, if-matchUpdates the specified CIDR block of a VCN. The new CIDR IP range must meet the following criteria:<br /><br />- Must be valid.<br />- Must not overlap with another CIDR block in the VCN, a CIDR block of a peered VCN, or the on-premises network CIDR block.<br />- Must not exceed the limit of CIDR blocks allowed per VCN.<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 /><br />Note: Modifying a CIDR block places your VCN in an updating state until the changes are complete. You cannot create or update the VCN's subnets, VLANs, LPGs, or route tables during this operation. The time to completion can vary depending on the size of your network. Updating a small network could take about a minute, and updating a large network could take up to an hour. You can use the GetWorkRequest operation to check the status of the update.<br />
remove_vcn_cidrexecvcnId, region, cidrBlockopc-request-id, opc-retry-token, if-matchRemoves a specified CIDR block from a VCN.<br /><br />Notes:<br />- You cannot remove a CIDR block if an IP address in its range is in use.<br />- Removing a CIDR block places your VCN in an updating state until the changes are complete. You cannot create or update the VCN's subnets, VLANs, LPGs, or route tables during this operation. The time to completion can take a few minutes. You can use the GetWorkRequest operation to check the status of the update.<br />
remove_ipv6_vcn_cidrexecvcnId, regionopc-request-id, opc-retry-token, if-matchRemoving an existing IPv6 prefix from a VCN.<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)
vcnIdstringSpecify the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN.
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.

SELECT examples​

Gets the specified VCN's information.

SELECT
id,
byoipv6CidrBlocks,
cidrBlock,
cidrBlocks,
compartmentId,
defaultDhcpOptionsId,
defaultRouteTableId,
defaultSecurityListId,
definedTags,
displayName,
dnsLabel,
freeformTags,
ipv6CidrBlock,
ipv6PrivateCidrBlocks,
ipv6PublicCidrBlock,
isEncrypted,
isZprOnly,
lifecycleState,
securityAttributes,
timeCreated,
vcnDomainName
FROM oci.network.vcns
WHERE vcnId = '{{ vcnId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new virtual cloud network (VCN). For more information, see<br />[VCNs and Subnets](/iaas/Content/Network/Tasks/managingVCNs.htm).<br /><br />For the VCN, you specify a list of one or more IPv4 CIDR blocks that meet the following criteria:<br /><br />- The CIDR blocks must be valid.<br />- They must not overlap with each other or with the on-premises network CIDR block.<br />- The number of CIDR blocks does not exceed the limit of CIDR blocks allowed per VCN.<br /><br />For a CIDR block, Oracle recommends that you use one of the private IP address ranges specified in [RFC 1918](https:​//tools.ietf.org/html/rfc1918) (10.0.0.0/8, 172.16/12, and 192.168/16). Example:<br />172.16.0.0/16. The CIDR blocks can range from /16 to /30.<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 VCN to<br />reside. Consult an Oracle Cloud Infrastructure administrator in your organization if you're not sure which<br />compartment to use. Notice that the VCN doesn't have to be in the same compartment as the subnets or other<br />Networking Service components. 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, see<br />[Resource Identifiers](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />You may optionally specify a display name for the VCN, otherwise a default is provided. It does not have to<br />be unique, and you can change it. Avoid entering confidential information.<br /><br />You can also add a DNS label for the VCN, which is required if you want the instances to use the<br />Interent and VCN Resolver option for DNS in the VCN. For more information, see<br />[DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm).<br /><br />The VCN automatically comes with a default route table, default security list, and default set of DHCP options.<br />The [OCID](/iaas/Content/General/Concepts/identifiers.htm) for each is returned in the response. You can't delete these default objects, but you can change their<br />contents (that is, change the route rules, security list rules, and so on).<br /><br />The VCN and subnets you create are not accessible until you attach an internet gateway or set up a Site-to-Site VPN<br />or FastConnect. For more information, see<br />[Overview of the Networking Service](/iaas/Content/Network/Concepts/overview.htm).<br />

INSERT INTO oci.network.vcns (
byoipv6CidrDetails,
cidrBlock,
cidrBlocks,
compartmentId,
definedTags,
displayName,
dnsLabel,
freeformTags,
ipv6CidrBlock,
ipv6PrivateCidrBlocks,
isEncrypted,
isIpv6Enabled,
isOracleGuaAllocationEnabled,
isZprOnly,
securityAttributes,
region,
opc-retry-token
)
SELECT 
'{{ byoipv6CidrDetails }}',
'{{ cidrBlock }}',
'{{ cidrBlocks }}',
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ dnsLabel }}',
'{{ freeformTags }}',
'{{ ipv6CidrBlock }}',
'{{ ipv6PrivateCidrBlocks }}',
{{ isEncrypted }},
{{ isIpv6Enabled }},
{{ isOracleGuaAllocationEnabled }},
{{ isZprOnly }},
'{{ securityAttributes }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
byoipv6CidrBlocks,
cidrBlock,
cidrBlocks,
compartmentId,
defaultDhcpOptionsId,
defaultRouteTableId,
defaultSecurityListId,
definedTags,
displayName,
dnsLabel,
freeformTags,
ipv6CidrBlock,
ipv6PrivateCidrBlocks,
ipv6PublicCidrBlock,
isEncrypted,
isZprOnly,
lifecycleState,
securityAttributes,
timeCreated,
vcnDomainName
;

UPDATE examples​

Updates the specified VCN.<br />

UPDATE oci.network.vcns
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
isEncrypted = {{ isEncrypted }},
isZprOnly = {{ isZprOnly }},
securityAttributes = '{{ securityAttributes }}'
WHERE 
vcnId = '{{ vcnId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
byoipv6CidrBlocks,
cidrBlock,
cidrBlocks,
compartmentId,
defaultDhcpOptionsId,
defaultRouteTableId,
defaultSecurityListId,
definedTags,
displayName,
dnsLabel,
freeformTags,
ipv6CidrBlock,
ipv6PrivateCidrBlocks,
ipv6PublicCidrBlock,
isEncrypted,
isZprOnly,
lifecycleState,
securityAttributes,
timeCreated,
vcnDomainName;

DELETE examples​

Deletes the specified VCN. The VCN must be completely empty and have no attached gateways. This is an asynchronous<br />operation.<br /><br />A deleted VCN's lifecycleState changes to TERMINATING and then TERMINATED temporarily until the VCN is completely<br />removed. A completely removed VCN does not appear in the results of a ListVcns operation and can't be used in a<br />GetVcn operation.<br />

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

Lifecycle Methods​

Adds a CIDR block to a VCN. The CIDR block you add:<br /><br />- Must be valid.<br />- Must not overlap with another CIDR block in the VCN, a CIDR block of a peered VCN, or the on-premises network CIDR block.<br />- Must not exceed the limit of CIDR blocks allowed per VCN.<br /><br />Note: Adding a CIDR block places your VCN in an updating state until the changes are complete. You cannot create or update the VCN's subnets, VLANs, LPGs, or route tables during this operation. The time to completion can take a few minutes. You can use the GetWorkRequest operation to check the status of the update.<br />

EXEC oci.network.vcns.add_vcn_cidr 
@vcnId='{{ vcnId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}' 
@@json=
'{
"cidrBlock": "{{ cidrBlock }}"
}'
;