oci_virtual_circuit – Create, update and delete OCI Virtual Circuit

New in version 2.5.

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.

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_OCID 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
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:
1200
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.

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:
{'lifecycle_state': 'PROVISIONED', 'customer_bgp_asn': 5, 'time_created': '2018-12-15T12:09:34.999000+00:00', 'bgp_management': 'CUSTOMER_MANAGED', 'region': None, 'id': 'ocid1.virtualcircuit.oc1..xxxxxEXAMPLExxxxx', 'gateway_id': None, 'cross_connect_mappings': [{'cross_connect_or_cross_connect_group_id': 'ocid1.crossconnectgroup.xxxxxEXAMPLExxxxx', 'bgp_md5_auth_key': None, 'vlan': 105, 'customer_bgp_peering_ip': '169.254.203.202/30', 'oracle_bgp_peering_ip': '169.254.203.201/30'}], 'display_name': 'sample-virtual-circuit', 'oracle_bgp_asn': 31898, 'compartment_id': 'ocid1.compartment.oc1..xxxxxEXAMPLExxxxx', 'reference_comment': None, 'provider_service_id': None, 'bandwidth_shape_name': '10 Gbps', 'provider_service_name': None, 'bgp_session_state': 'DOWN', 'provider_state': None, 'service_type': 'COLOCATED', 'provider_name': None, 'type': 'PUBLIC', 'public_prefixes': None}
  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:
[{'cross_connect_or_cross_connect_group_id': None, 'bgp_md5_auth_key': None, 'vlan': None, 'customer_bgp_peering_ip': '10.0.0.18/31', 'oracle_bgp_peering_ip': '10.0.0.19/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
  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.