oci_virtual_circuit – Create, update and delete OCI Virtual Circuit¶

New in version 2.5.

Synopsis
Requirements
Parameters
Notes
Examples
Return Values
Status

Synopsis ¶

Create an OCI Virtual Circuit to use with Oracle Cloud Infrastructure FastConnect
Update an OCI Virtual Circuit, if present
Delete an OCI Virtual Circuit, if present.

Requirements ¶

The below requirements are needed on the host that executes this module.

python >= 2.7
Python SDK for Oracle Cloud Infrastructure https://oracle-cloud-infrastructure-python-sdk.readthedocs.io

Parameters ¶

Parameter		Choices/Defaults	Comments
api_user string			The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_ID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See `config_file_location`). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_fingerprint string			Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See `config_file_location`). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_key_file string			Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See `config_file_location`). If the key is encrypted with a pass-phrase, the `api_user_key_pass_phrase` option must also be provided.
api_user_key_pass_phrase string			Passphrase used by the key referenced in `api_user_key_file`, if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See `config_file_location`).
auth_type string		Choices: api_key ← instance_principal instance_obo_user	The type of authentication to use for making API requests. By default `auth_type="api_key"` based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use `auth_type="instance_principal"` to use instance principal based authentication when running ansible` playbooks within an OCI compute instance.
bandwidth_shape_name -			The provisioned data rate of the connection.
compartment_id -			Identifier of the compartment under which this Virtual Circuit would be created. Mandatory for create operation.
config_file_location string			Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
config_profile_name string			The profile to load from the config file referenced by `config_file_location`. If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in `config_file_location`.
cross_connect_mappings -			An array of mappings, each containing properties for a cross-connect or cross-connect group that is associated with this virtual circuit.
	bgp_md5_auth_key -		The key for BGP MD5 authentication. Only applicable if your system requires MD5 authentication. If empty or not set, that means you don't use BGP MD5 authentication.
	cross_connect_or_cross_connect_group_id -		The OCID of the cross-connect or cross-connect group for this mapping. Specified by the owner of the cross-connect or cross-connect group (the customer if the customer is colocated with Oracle, or the provider if the customer is connecting via provider).
	customer_bgp_peering_ip -		The BGP IP address for the router on the other end of the BGP session from Oracle. Specified by the owner of that router. If the session goes from Oracle to a customer, this is the BGP IP address of the customer's edge router. If the session goes from Oracle to a provider, this is the BGP IP address of the provider's edge router. Must use a /30 or /31 subnet mask. There's one exception, for a public virtual circuit, Oracle specifies the BGP IP addresses.
	oracle_bgp_peering_ip -		The IP address for Oracle's end of the BGP session. Must use a /30 or /31 subnet mask. If the session goes from Oracle to a customer's edge router, the customer specifies this information. If the session goes from Oracle to a provider's edge router, the provider specifies this. There's one exception, for a public virtual circuit, Oracle specifies the BGP IP addresses.
	vlan -		The number of the specific VLAN (on the cross-connect or cross-connect group) that is assigned to this virtual circuit. Specified by the owner of the cross-connect or cross-connect group (the customer if the customer is colocated with Oracle, or the provider if the customer is connecting via provider).
customer_bgp_asn -			Your BGP ASN (either public or private). Provide this value only if there's a BGP session that goes from your edge router to Oracle. Otherwise, leave this empty or null.
delete_cross_connect_mappings boolean		Choices: no ← yes	Delete any cross connect mappings in the virtual circuit that is specified in cross_connect_mappings. If delete_cross_connect_mappings=yes, cross connect mappings provided by cross_connect_mappings would be deleted from existing cross connect mappings, if they are part of existing cross connect mappings. If they are not part of existing cross connect mappings, they will be ignored. delete_cross_connect_mappings and purge_cross_connect_mappings are mutually exclusive.
delete_public_prefixes -		Default: "no"	Indicates whether public prefixes associated with a public virtual circuit needs to be deleted. If delete_public_prefixes=false, then input publi prefixes gets added.
display_name -			A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information. aliases: name
force_create boolean		Choices: no ← yes	Whether to attempt non-idempotent creation of a resource. By default, create resource is an idempotent operation, and doesn't create the resource if it already exists. Setting this option to true, forcefully creates a copy of the resource, even if it already exists.This option is mutually exclusive with key_by.
gateway_id -			For private virtual circuits only. The OCID of the dynamic routing gateway (DRG) that this virtual circuit uses.
key_by list			The list of comma-separated attributes of this resource which should be used to uniquely identify an instance of the resource. By default, all the attributes of a resource except freeform_tags are used to uniquely identify a resource.
provider_name -			Deprecated. Instead use provider_service_id.
provider_service_id -			The OCID of the service offered by the provider (if you're connecting via a provider).
provider_service_name -			Deprecated. Instead use provider_service_id.
provider_state -		Choices: ACTIVE INACTIVE	The provider's state in relation to this virtual circuit. Relevant only if the customer is using FastConnect 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.
public_prefixes -			For a public virtual circuit. The public IP prefixes (CIDRs) the customer wants to advertise across the connection.
	cidr_block - / required		An individual public IP prefix (CIDR) to add to the public virtual circuit. Must be /31 or less specific.
purge_cross_connect_mappings boolean		Choices: no yes ←	Purge cross connect mappings from virtual circuit which are not present in the provided cross connect mappings list.If purge_cross_connect_mappings=no, provided cross connect mappings would be appended to existing cross connect mappings. purge_cross_connect_mappings and delete_cross_connect_mappings are mutually exclusive.
reference_comment -			Provider-supplied reference information about this virtual circuit. Relevant only if the customer is using FastConnect via a provider. To be updated only by the provider.
region string			The Oracle Cloud Infrastructure region where this virtual circuit is located.
state -		Choices: present ← absent	Create,update or delete cross-connect group. For state=present, if it does not exists, it gets created. If exists, it gets updated.
tenancy string			OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See `config_file_location`). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm
type -		Choices: PUBLIC PRIVATE	The type of IP addresses used in this virtual circuit. PRIVATE means RFC 1918 addresses (10.0.0.0/8, 172.16/12, and 192.168/16). Only PRIVATE is supported.
virtual_circuit_id -			Identifier of the Virtual Circuit. Mandatory for delete and update. aliases: id
wait boolean		Choices: no yes ←	Whether to wait for create or delete operation to complete.
wait_timeout integer		Default: 2000	Time, in seconds, to wait when wait=yes.
wait_until string			The lifecycle state to wait for the resource to transition into when wait=yes. By default, when wait=yes, we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/ RUNNING applicable lifecycle state during create operation & to get into DELETED/DETACHED/ TERMINATED lifecycle state during delete operation.

Notes ¶

Note

For OCI python sdk configuration, please refer to https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html

Examples ¶

# Note: These examples do not set authentication details.
# Create a new colocated Virtual Circuit
- name: Create a new colocated Virtual Circuit
  oci_virtual_circuit:
      compartment_id: 'ocid1.compartment..xxxxxEXAMPLExxxxx'
      display_name: 'ansible-virtual-circuit'
      cross_connect_mappings:
            - cross_connect_or_cross_connect_group_id: 'ocid1.crossconnectgroup..xxxxxEXAMPLExxxxx'
              vlan: 100
      public_prefixes:
             - 206.209.218.0/24
      customer_bgp_asn: 5
      type: 'PUBLIC'
      port_speed_shape_name: '10 Gbps'
      state: 'present'

# Create a new colocated Virtual Circuit
- name: Create a new colocated Virtual Circuit of private type
  oci_virtual_circuit:
      compartment_id: 'ocid1.compartment..xxxxxEXAMPLExxxxx'
      display_name: 'ansible-virtual-circuit-private'
      cross_connect_mappings:
            - cross_connect_or_cross_connect_group_id: 'ocid1.crossconnectgroup..xxxxxEXAMPLExxxxx'
              customer_bgp_peering_ip: '10.0.0.18/31'
              oracle_bgp_peering_ip: '10.0.0.19/31'
              vlan: 100
      customer_bgp_asn: 5
      type: 'PRIVATE'
      port_speed_shape_name: '10 Gbps'
      state: 'present'

# Create a Virtual Circuit using Provider
- name: Create a Virtual Circuit using Provider
  oci_virtual_circuit:
      compartment_id: 'ocid1.compartment..xxxxxEXAMPLExxxxx'
      display_name: 'ansible-virtual-circuit'
      provider_service_id: 'ocid1.providerservice...xxxxxEXAMPLExxxxx'
      customer_bgp_asn: 5
      type: 'PUBLIC'
      port_speed_shape_name: '10 Gbps'
      state: 'present'

# Update an existing Virtual Circuit's Cross Connect Mappings
- name: Update an existing Virtual Circuit's Cross Connect Mappings
  oci_virtual_circuit:
      virtual_circuit_id: 'ocid1.virtualcircuit..xxxxxEXAMPLExxxxx'
      cross_connect_mappings:
            - cross_connect_or_cross_connect_group_id: 'ocid1.crossconnectgroup..xxxxxEXAMPLExxxxx'
              vlan: 105
      state: 'present'

# Update an existing Virtual Circuit's Cross Connect Mappings by appending new Cross Connect Mappings
- name: Update an existing Virtual Circuit's Cross Connect Mappings by appending new Cross Connect Mappings
  oci_virtual_circuit:
      virtual_circuit_id: 'ocid1.virtualcircuit..xxxxxEXAMPLExxxxx'
      cross_connect_mappings:
            - cross_connect_or_cross_connect_group_id: 'ocid1.crossconnectgroup..xxxxxEXAMPLExxxxx'
              vlan: 100
      purge_cross_connect_mappings: false
      state: 'present'

# Update an existing Virtual Circuit's Cross Connect Mappings by deleting a Cross Connect Mappings
- name: Update an existing Virtual Circuit's Cross Connect Mappings by deleting a Cross Connect Mappings
  oci_virtual_circuit:
      virtual_circuit_id: 'ocid1.virtualcircuit..xxxxxEXAMPLExxxxx'
      cross_connect_mappings:
            - cross_connect_or_cross_connect_group_id: 'ocid1.crossconnectgroup..xxxxxEXAMPLExxxxx'
              vlan: 100
      delete_cross_connect_mappings: false
      state: 'present'

# Update an existing Virtual Circuit by deleting Public Prefixes
- name: Update an existing Virtual Circuit by deleting Public Prefixes
  oci_virtual_circuit:
      virtual_circuit_id: 'ocid1.virtualcircuit..xxxxxEXAMPLExxxxx'
      public_prefixes:
            - '10.0.0.21/31'
      delete_public_prefixes: true
      state: 'present'

# Delete Virtual Circuit
- name: Delete Virtual Circuit
  oci_virtual_circuit:
      virtual_circuit_id: 'ocid1.virtualcircuit..xxxxxEXAMPLExxxxx'
      state: 'absent'

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key		Returned	Description
oci_virtual_circuit complex		success	Attributes of the Virtual Circuit. Sample: {'public_prefixes': None, 'provider_state': None, 'bandwidth_shape_name': '10 Gbps', 'provider_service_id': None, 'service_type': 'COLOCATED', 'region': None, 'cross_connect_mappings': [{'oracle_bgp_peering_ip': '169.254.203.201/30', 'bgp_md5_auth_key': None, 'vlan': 105, 'cross_connect_or_cross_connect_group_id': 'ocid1.crossconnectgroup.xxxxxEXAMPLExxxxx', 'customer_bgp_peering_ip': '169.254.203.202/30'}], 'display_name': 'sample-virtual-circuit', 'time_created': '2018-12-15T12:09:34.999000+00:00', 'lifecycle_state': 'PROVISIONED', 'provider_service_name': None, 'gateway_id': None, 'reference_comment': None, 'oracle_bgp_asn': 31898, 'customer_bgp_asn': 5, 'bgp_session_state': 'DOWN', 'provider_name': None, 'bgp_management': 'CUSTOMER_MANAGED', 'compartment_id': 'ocid1.compartment.oc1..xxxxxEXAMPLExxxxx', 'type': 'PUBLIC', 'id': 'ocid1.virtualcircuit.oc1..xxxxxEXAMPLExxxxx'}
	bgp_management string	always	BGP management option. Sample: CUSTOMER_MANAGED
	bgp_session_state string	always	The state of the BGP session associated with the virtual circuit. Sample: UP
	compartment_id string	always	The OCID of the compartment containing the Virtual Circuit. Sample: ocid1.compartment.oc1.iad.xxxxxEXAMPLExxxxx
	cross_connect_mappings list	always	An array of mappings, each containing properties for a cross-connect or cross-connect group that is associated with this virtual circuit. Sample: [{'oracle_bgp_peering_ip': '10.0.0.19/31', 'bgp_md5_auth_key': None, 'vlan': None, 'cross_connect_or_cross_connect_group_id': None, 'customer_bgp_peering_ip': '10.0.0.18/31'}]
	customer_bgp_asn integer	always	The 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. Sample: 10
	display_name string	always	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information. Sample: ansible-virtual-circuit
	gateway_id string	always	The OCID of the customer's dynamic routing gateway (DRG) that this virtual circuit uses. Applicable only to private virtual circuits. Sample: ocid1.drg..xxxxxEXAMPLExxxxx
	id string	always	Identifier of the Virtual Circuit. Sample: ocid1.virtualcircuit.oc1.iad.xxxxxEXAMPLExxxxx
	lifecycle_state string	always	The current state of the Virtual Circuit. Sample: PROVISIONED
	oracle_bgp_asn integer	always	The Oracle BGP ASN. Sample: 31898
	port_speed_shape_name string	always	The port speed for this cross-connect. Sample: 10 Gbps
	provider_name string	always	Name of the Provider. Sample: Megaport
	provider_service_id string	always	The OCID of the service offered by the provider (if the customer is connecting via a provider). Sample: ocid1.providerservice.oc1..xxxxxEXAMPLExxxxx
	provider_service_name string	always	Name of the Provider Service. Sample: Service
	provider_state string	always	The 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. Sample: INACTIVE
	public_prefixes list	always	For a public virtual circuit. The public IP prefixes (CIDRs) the customer wants to advertise across the connection. Each prefix must be /31 or less specific. Sample: [{'cidr_block': '10.0.0.10/31'}]
	reference_comment string	always	Provider-supplied reference information about this virtual circuit (if the customer is connecting via a provider). Sample: SAMPLE
	region string	always	The Oracle Cloud Infrastructure region where this virtual circuit is located. Sample: phx
	service_type string	always	Provider service type. Sample: COLOCATED
	time_created datetime	always	Date and time when the Virtual Circuit was created, in the format defined by RFC3339 Sample: 2016-08-25 21:10:29.600000+00:00
	type string	always	Whether the virtual circuit supports private or public peering. Sample: PUBLIC

Status ¶

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]

Authors¶

Debayan Gupta(@debayan_gupta)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

oci_virtual_circuit – Create, update and delete OCI Virtual Circuit¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶

Status¶