Skip to main content

virtual_circuits

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

Overview​

Namevirtual_circuits
TypeResource
Idoci.network.virtual_circuits

Fields​

The following fields are returned by SELECT queries:

The virtual circuit was retrieved.

NameDatatypeDescription
idstringThe virtual circuit's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
bandwidthShapeNamestringThe provisioned data rate of the connection. To get a list of the available bandwidth levels (that is, shapes), see [ListFastConnectProviderServiceVirtualCircuitBandwidthShapes](#/en/iaas/latest/FastConnectProviderService/ListFastConnectProviderVirtualCircuitBandwidthShapes). Example: 10 Gbps
bgpAdminStatestringSet to ENABLED (the default) to activate the BGP session of the virtual circuit, set to DISABLED to deactivate the virtual circuit. (ENABLED, DISABLED)
bgpIpv6SessionStatestringThe state of the Ipv6 BGP session associated with the virtual circuit. (UP, DOWN)
bgpManagementstringDeprecated. Instead use the information in [FastConnectProviderService](#/en/iaas/latest/FastConnectProviderService/). (CUSTOMER_MANAGED, PROVIDER_MANAGED, ORACLE_MANAGED)
bgpSessionStatestringThe state of the Ipv4 BGP session associated with the virtual circuit. (UP, DOWN)
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the virtual circuit.
crossConnectMappingsarrayAn array of mappings, each containing properties for a cross-connect or cross-connect group that is associated with this virtual circuit.
customerBgpAsnintegerThe BGP ASN of the network at the other end of the BGP session from Oracle. If the session is between the customer's edge router and Oracle, the value is the customer's ASN. If the BGP session is between the provider's edge router and Oracle, the value is the provider's ASN.
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.
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"}
gatewayIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the customer's [dynamic routing gateway (DRG)](#/en/iaas/latest/Drg) that this virtual circuit uses. Applicable only to private virtual circuits.
ipMtustringThe layer 3 IP MTU to use on this virtual circuit. (MTU_1500, MTU_9000) (x-obmcs-top-level-enum: #/definitions/VirtualCircuitIpMtu)
isBfdEnabledbooleanSet to true to enable BFD for IPv4 BGP peering, or set to false to disable BFD. If this is not set, the default is false.
isTransportModebooleanSet to true for the virtual circuit to carry only encrypted traffic, or set to false for the virtual circuit to carry unencrypted traffic. If this is not set, the default is false.
lifecycleStatestringThe virtual circuit's current state. For information about the different states, see [FastConnect Overview](/iaas/Content/Network/Concepts/fastconnect.htm). (PENDING_PROVIDER, VERIFYING, PROVISIONING, PROVISIONED, FAILED, INACTIVE, TERMINATING, TERMINATED)
oracleBgpAsnintegerThe Oracle BGP ASN.
providerNamestringDeprecated. Instead use providerServiceId.
providerServiceIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the service offered by the provider (if the customer is connecting via a provider).
providerServiceKeyNamestringThe service key name offered by the provider (if the customer is connecting via a provider).
providerServiceNamestringDeprecated. Instead use providerServiceId.
providerStatestringThe provider's state in relation to this virtual circuit (if the customer is connecting via a provider). ACTIVE means the provider has provisioned the virtual circuit from their end. INACTIVE means the provider has not yet provisioned the virtual circuit, or has de-provisioned it. (ACTIVE, INACTIVE)
publicPrefixesarrayFor a public virtual circuit. The public IP prefixes (CIDRs) the customer wants to advertise across the connection. All prefix sizes are allowed.
referenceCommentstringProvider-supplied reference information about this virtual circuit (if the customer is connecting via a provider).
regionstringThe Oracle Cloud Infrastructure region where this virtual circuit is located.
routingPolicyarrayThe routing policy sets how routing information about the Oracle cloud is shared over a public virtual circuit. Policies available are: ORACLE_SERVICE_NETWORK, REGIONAL, MARKET_LEVEL, and GLOBAL. See [Route Filtering](/iaas/Content/Network/Concepts/routingonprem.htm#route_filtering) for details. By default, routing information is shared for all routes in the same market.
serviceTypestringProvider service type. (COLOCATED, LAYER2, LAYER3)
timeCreatedstring (date-time)The date and time the virtual circuit was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z
typestringWhether the virtual circuit supports private or public peering. For more information, see [FastConnect Overview](/iaas/Content/Network/Concepts/fastconnect.htm). (PUBLIC, PRIVATE)
virtualCircuitRedundancyMetadataobjectThis resource provides redundancy level details for the virtual circuit. For more about redundancy, see [FastConnect Redundancy Best Practices](/iaas/Content/Network/Concepts/fastconnectresiliency.htm).

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectvirtualCircuitId, regionGets the specified virtual circuit's information.
listselectcompartmentId, regionlimit, page, displayName, sortBy, sortOrder, lifecycleStateLists the virtual circuits in the specified compartment.<br />
createinsertregion, compartmentId, typeopc-retry-tokenCreates a new virtual circuit to use with Oracle Cloud<br />Infrastructure FastConnect. For more information, see<br />[FastConnect Overview](/iaas/Content/Network/Concepts/fastconnect.htm).<br /><br />For the purposes of access control, you must provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the<br />compartment where you want the virtual circuit to reside. If you're<br />not sure which compartment to use, put the virtual circuit in the<br />same compartment with the DRG it's using. For more information about<br />compartments and access control, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm).<br />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 virtual circuit.<br />It does not have to be unique, and you can change it. Avoid entering confidential information.<br /><br />Important: When creating a virtual circuit, you specify a DRG for<br />the traffic to flow through. Make sure you attach the DRG to your<br />VCN and confirm the VCN's routing sends traffic to the DRG. Otherwise<br />traffic will not flow. For more information, see<br />[Route Tables](/iaas/Content/Network/Tasks/managingroutetables.htm).<br />
updateupdatevirtualCircuitId, regionif-matchUpdates the specified virtual circuit. This can be called by<br />either the customer who owns the virtual circuit, or the<br />provider (when provisioning or de-provisioning the virtual<br />circuit from their end). The documentation for<br />[UpdateVirtualCircuitDetails](#/en/iaas/latest/requests/UpdateVirtualCircuitDetails)<br />indicates who can update each property of the virtual circuit.<br /><br />Important: If the virtual circuit is working and in the<br />PROVISIONED state, updating any of the network-related properties<br />(such as the DRG being used, the BGP ASN, and so on) will cause the virtual<br />circuit's state to switch to PROVISIONING and the related BGP<br />session to go down. After Oracle re-provisions the virtual circuit,<br />its state will return to PROVISIONED. Make sure you confirm that<br />the associated BGP session is back up. For more information<br />about the various states and how to test connectivity, see<br />[FastConnect Overview](/iaas/Content/Network/Concepts/fastconnect.htm).<br /><br />To change the list of public IP prefixes for a public virtual circuit,<br />use [BulkAddVirtualCircuitPublicPrefixes](#/en/iaas/latest/VirtualCircuitPublicPrefix/BulkAddVirtualCircuitPublicPrefixes)<br />and<br />[BulkDeleteVirtualCircuitPublicPrefixes](#/en/iaas/latest/VirtualCircuitPublicPrefix/BulkDeleteVirtualCircuitPublicPrefixes).<br />Updating the list of prefixes does NOT cause the BGP session to go down. However,<br />Oracle must verify the customer's ownership of each added prefix before<br />traffic for that prefix will flow across the virtual circuit.<br />
deletedeletevirtualCircuitId, regionif-matchDeletes the specified virtual circuit.<br /><br />Important: If you're using FastConnect via a provider,<br />make sure to also terminate the connection with<br />the provider, or else the provider may continue to bill you.<br />
bulk_add_virtual_circuit_public_prefixesexecvirtualCircuitId, region, publicPrefixesAdds one or more customer public IP prefixes to the specified public virtual circuit.<br />Use this operation (and not [UpdateVirtualCircuit](#/en/iaas/latest/VirtualCircuit/UpdateVirtualCircuit))<br />to add prefixes to the virtual circuit. Oracle must verify the customer's ownership<br />of each prefix before traffic for that prefix will flow across the virtual circuit.<br />
bulk_delete_virtual_circuit_public_prefixesexecvirtualCircuitId, region, publicPrefixesRemoves one or more customer public IP prefixes from the specified public virtual circuit.<br />Use this operation (and not [UpdateVirtualCircuit](#/en/iaas/latest/VirtualCircuit/UpdateVirtualCircuit))<br />to remove prefixes from the virtual circuit. When the virtual circuit's state switches<br />back to PROVISIONED, Oracle stops advertising the specified prefixes across the connection.<br />
change_compartmentexecvirtualCircuitId, region, compartmentIdopc-request-id, opc-retry-tokenMoves a virtual circuit 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 />

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)
virtualCircuitIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the virtual circuit.
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 return only resources that match the specified lifecycle state. The 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 virtual circuit's information.

SELECT
id,
bandwidthShapeName,
bgpAdminState,
bgpIpv6SessionState,
bgpManagement,
bgpSessionState,
compartmentId,
crossConnectMappings,
customerBgpAsn,
definedTags,
displayName,
freeformTags,
gatewayId,
ipMtu,
isBfdEnabled,
isTransportMode,
lifecycleState,
oracleBgpAsn,
providerName,
providerServiceId,
providerServiceKeyName,
providerServiceName,
providerState,
publicPrefixes,
referenceComment,
region,
routingPolicy,
serviceType,
timeCreated,
type,
virtualCircuitRedundancyMetadata
FROM oci.network.virtual_circuits
WHERE virtualCircuitId = '{{ virtualCircuitId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new virtual circuit to use with Oracle Cloud<br />Infrastructure FastConnect. For more information, see<br />[FastConnect Overview](/iaas/Content/Network/Concepts/fastconnect.htm).<br /><br />For the purposes of access control, you must provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the<br />compartment where you want the virtual circuit to reside. If you're<br />not sure which compartment to use, put the virtual circuit in the<br />same compartment with the DRG it's using. For more information about<br />compartments and access control, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm).<br />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 virtual circuit.<br />It does not have to be unique, and you can change it. Avoid entering confidential information.<br /><br />Important: When creating a virtual circuit, you specify a DRG for<br />the traffic to flow through. Make sure you attach the DRG to your<br />VCN and confirm the VCN's routing sends traffic to the DRG. Otherwise<br />traffic will not flow. For more information, see<br />[Route Tables](/iaas/Content/Network/Tasks/managingroutetables.htm).<br />

INSERT INTO oci.network.virtual_circuits (
bandwidthShapeName,
bgpAdminState,
compartmentId,
crossConnectMappings,
customerBgpAsn,
definedTags,
displayName,
freeformTags,
gatewayId,
ipMtu,
isBfdEnabled,
isTransportMode,
providerName,
providerServiceId,
providerServiceKeyName,
providerServiceName,
publicPrefixes,
region,
routingPolicy,
type,
region,
opc-retry-token
)
SELECT 
'{{ bandwidthShapeName }}',
'{{ bgpAdminState }}',
'{{ compartmentId }}' /* required */,
'{{ crossConnectMappings }}',
{{ customerBgpAsn }},
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ gatewayId }}',
'{{ ipMtu }}',
{{ isBfdEnabled }},
{{ isTransportMode }},
'{{ providerName }}',
'{{ providerServiceId }}',
'{{ providerServiceKeyName }}',
'{{ providerServiceName }}',
'{{ publicPrefixes }}',
'{{ region }}',
'{{ routingPolicy }}',
'{{ type }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
bandwidthShapeName,
bgpAdminState,
bgpIpv6SessionState,
bgpManagement,
bgpSessionState,
compartmentId,
crossConnectMappings,
customerBgpAsn,
definedTags,
displayName,
freeformTags,
gatewayId,
ipMtu,
isBfdEnabled,
isTransportMode,
lifecycleState,
oracleBgpAsn,
providerName,
providerServiceId,
providerServiceKeyName,
providerServiceName,
providerState,
publicPrefixes,
referenceComment,
region,
routingPolicy,
serviceType,
timeCreated,
type,
virtualCircuitRedundancyMetadata
;

UPDATE examples​

Updates the specified virtual circuit. This can be called by<br />either the customer who owns the virtual circuit, or the<br />provider (when provisioning or de-provisioning the virtual<br />circuit from their end). The documentation for<br />[UpdateVirtualCircuitDetails](#/en/iaas/latest/requests/UpdateVirtualCircuitDetails)<br />indicates who can update each property of the virtual circuit.<br /><br />Important: If the virtual circuit is working and in the<br />PROVISIONED state, updating any of the network-related properties<br />(such as the DRG being used, the BGP ASN, and so on) will cause the virtual<br />circuit's state to switch to PROVISIONING and the related BGP<br />session to go down. After Oracle re-provisions the virtual circuit,<br />its state will return to PROVISIONED. Make sure you confirm that<br />the associated BGP session is back up. For more information<br />about the various states and how to test connectivity, see<br />[FastConnect Overview](/iaas/Content/Network/Concepts/fastconnect.htm).<br /><br />To change the list of public IP prefixes for a public virtual circuit,<br />use [BulkAddVirtualCircuitPublicPrefixes](#/en/iaas/latest/VirtualCircuitPublicPrefix/BulkAddVirtualCircuitPublicPrefixes)<br />and<br />[BulkDeleteVirtualCircuitPublicPrefixes](#/en/iaas/latest/VirtualCircuitPublicPrefix/BulkDeleteVirtualCircuitPublicPrefixes).<br />Updating the list of prefixes does NOT cause the BGP session to go down. However,<br />Oracle must verify the customer's ownership of each added prefix before<br />traffic for that prefix will flow across the virtual circuit.<br />

UPDATE oci.network.virtual_circuits
SET 
bandwidthShapeName = '{{ bandwidthShapeName }}',
bgpAdminState = '{{ bgpAdminState }}',
crossConnectMappings = '{{ crossConnectMappings }}',
customerBgpAsn = {{ customerBgpAsn }},
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
gatewayId = '{{ gatewayId }}',
ipMtu = '{{ ipMtu }}',
isBfdEnabled = {{ isBfdEnabled }},
isTransportMode = {{ isTransportMode }},
providerServiceKeyName = '{{ providerServiceKeyName }}',
providerState = '{{ providerState }}',
referenceComment = '{{ referenceComment }}',
routingPolicy = '{{ routingPolicy }}'
WHERE 
virtualCircuitId = '{{ virtualCircuitId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
bandwidthShapeName,
bgpAdminState,
bgpIpv6SessionState,
bgpManagement,
bgpSessionState,
compartmentId,
crossConnectMappings,
customerBgpAsn,
definedTags,
displayName,
freeformTags,
gatewayId,
ipMtu,
isBfdEnabled,
isTransportMode,
lifecycleState,
oracleBgpAsn,
providerName,
providerServiceId,
providerServiceKeyName,
providerServiceName,
providerState,
publicPrefixes,
referenceComment,
region,
routingPolicy,
serviceType,
timeCreated,
type,
virtualCircuitRedundancyMetadata;

DELETE examples​

Deletes the specified virtual circuit.<br /><br />Important: If you're using FastConnect via a provider,<br />make sure to also terminate the connection with<br />the provider, or else the provider may continue to bill you.<br />

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

Lifecycle Methods​

Adds one or more customer public IP prefixes to the specified public virtual circuit.<br />Use this operation (and not [UpdateVirtualCircuit](#/en/iaas/latest/VirtualCircuit/UpdateVirtualCircuit))<br />to add prefixes to the virtual circuit. Oracle must verify the customer's ownership<br />of each prefix before traffic for that prefix will flow across the virtual circuit.<br />

EXEC oci.network.virtual_circuits.bulk_add_virtual_circuit_public_prefixes 
@virtualCircuitId='{{ virtualCircuitId }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"publicPrefixes": "{{ publicPrefixes }}"
}'
;