# VPC Peering Connection with Oracle Cloud

This document describes how to create a VPC peering connection between EMQX Cloud and Oracle Cloud Infrastructure (OCI) by using Local Peering Gateways (LPGs).

In this setup:

- The Virtual Cloud Network (VCN), where your Oracle Cloud resources reside, acts as the requesting side.
- The VCN where the EMQX Cloud deployment resides acts as the accepting side of the peering connection.

## Prerequisites

Before you begin, ensure that:

- Your Oracle Cloud VCN and the EMQX Cloud deployment are located in the same region.
- The CIDR block of your Oracle Cloud VCN does not overlap with the CIDR block of the EMQX Cloud VCN.
- You have sufficient permissions to manage VCNs, Local Peering Gateways, route tables, and security rules in Oracle Cloud.

## Create a VPC Peering Connection

### Step 1: Collect Required OCIDs from Oracle Cloud

Before initiating the peering connection, collect the following OCIDs from your Oracle Cloud account. These are required when submitting the connection request in the EMQX Cloud console.

#### Get the Group OCID

1. In the Oracle Cloud Console, go to **Identity & Security** -> **Identity** -> **Domains**.

2. Open an existing domain (for example, `Default`) or create a new one.

   ![domains](./_assets/vpc_oracle/domains.png)

3. In the domain, go to **User Management** -> **Groups**. Select an existing group or click **Create group** to create a new one.

   Make sure the group includes the user who will establish the peering connection.

   ![user_groups](./_assets/vpc_oracle/user_groups.png)

4. Open the group and copy the **OCID** shown in the group details.

   ![group_ocid](./_assets/vpc_oracle/group_ocid.png)

#### Get the Compartment OCID

1. Go to **Identity & Security** -> **Identity** -> **Compartments**.

2. Select the compartment that contains the VCN you want to peer with EMQX Cloud.

3. Copy the **OCID** from the compartment details page.

   ![compartment_ocid](./_assets/vpc_oracle/compartment_ocid.png)

#### Get the Tenancy OCID

1. Go to **Governance & Administration** -> **Account Management** -> **Tenancy Details**.

2. Copy the **OCID** from the **General Information** section.

   ![tenancy_ocid](./_assets/vpc_oracle/tenancy_ocid.png)

### Step 2: Initiate the Peering Connection in EMQX Cloud

1. Log in to the EMQX Cloud Console and go to the **Deployment Overview** page of the target deployment.

2. From the left navigation menu, click **Network Management**.

3. In the **VPC Peering Connection** section, click **+ VPC Peering Connection**.

   On the dialog page, confirm the **Region of Deployment** and make sure it matches the region of your Oracle Cloud VCN.

   <img src="./_assets/vpc_oracle/region_of_deployment.png" alt="region_of_deployment" style="zoom:67%;" />

4. Enter the **Requestor Tenancy OCID** and **Requestor Group OCID** collected in Step 1, then click **Confirm**.

5. After identity verification, click **Create Local Peering Gateway**.

   EMQX Cloud automatically creates a Local Peering Gateway in its VCN and displays the following information:

   - **Local Peering Gateway OCID**
   - **Acceptor Tenancy OCID**
   - **Region of Deployment**
   - **CIDR of the EMQX Cloud VCN**

   Keep this dialog open, as these values will be used in the next steps.

   <img src="./_assets/vpc_oracle/vpc_guidelines.png" alt="vpc_guidelines" style="zoom:67%;" />

### Step 3: Configure an IAM Policy in Oracle Cloud

You must create an IAM policy in Oracle Cloud to authorize the cross-tenancy peering connection. The policy must be created at the **root compartment (tenancy) level**.

1. In the Oracle Cloud Console, go to **Identity & Security** -> **Policies**.

2. Click **Create Policy**.

3. In the **Policy Builder** section, click **Show manual editor**.

   ![policy_builder](./_assets/vpc_oracle/policy_builder.png)

4. Enter the following policy statements, replacing the placeholders with your actual values:

   ```
   Define tenancy Acceptor as <Acceptor Tenancy OCID>
   Allow group <Requestor Group> to manage local-peering-from in compartment id <Requestor Compartment ID>
   Endorse group <Requestor Group> to manage local-peering-to in tenancy Acceptor
   Endorse group <Requestor Group> to associate local-peering-gateways in compartment id <Requestor Compartment ID> with local-peering-gateways in tenancy Acceptor
   ```

   - `<Acceptor Tenancy OCID>`: the **Acceptor Tenancy OCID** from the EMQX Cloud dialog in Step 2.
   - `<Requestor Group>`: the group name in `'Domain'/'group-name'` format, for example `'Default'/'cloud-test-group'`.
   - `<Requestor Compartment ID>`: the **Compartment OCID** collected in Step 1.

5. Save the policy.

   ![policy_statements](./_assets/vpc_oracle/policy_statements.png)

### Step 4: Create a Local Peering Gateway in Oracle Cloud

1. Log in to the **Oracle Cloud Console**.

2. In the top search bar, search for **Virtual Cloud Networks**, and open the VCN where your Oracle Cloud resources are deployed.

3. In the VCN details page, select **Gateways** from the left navigation.

4. In the **Local Peering Gateways** section, click **Create Local Peering Gateway**.

5. Enter a name (for example, `vpc-peering-lpg`) and select the appropriate compartment.

   ![create_local_peering_gateway](./_assets/vpc_oracle/create_local_peering_gateway.png)

6. Click **Create**.

### Step 5: Establish the Peering Connection

1. In the **Local Peering Gateways** list, locate the newly created LPG.

2. Click the **Actions** menu (⋯) and select **Establish Peering Connection**.

   ![establish_peering_connection](./_assets/vpc_oracle/establish_peering_connection.png)

3. On the **Establish Peering Connection** page:

   - Select **Enter Local Peering Gateway OCID**.
   - Paste the **Local Peering Gateway OCID** obtained from the EMQX Cloud console.

   ![enter_lpg_ocid](./_assets/vpc_oracle/enter_lpg_ocid.png)

4. Click **Establish Peering Connection**.

Wait until the **Peering Status** changes to **Peered**.

### Step 6: Configure Route Tables

After the peering connection is established, you must update the route table to allow traffic to flow to the EMQX Cloud VCN.

1. In the Oracle Cloud Console, go back to the VCN details page.

2. Select the **Routing** tab.

3. Locate the **route table** associated with the subnet where your Oracle Cloud resources reside.

4. Click **Add Route Rules** and configure the following:

   - **Target Type**: `Local Peering Gateway`
   - **Destination CIDR Block**: CIDR of the EMQX Cloud VCN
   - **Target Local Peering Gateway compartment**: Select the compartment where the Local Peering Gateway was created.
   - **Target Local Peering Gateway**: Select the Local Peering Gateway you created for this peering connection.

   ![add_route_rules](./_assets/vpc_oracle/add_route_rules.png)

5. Save the route rule.

### Step 7: Configure Security Rules

Finally, update the security rules to allow traffic from the EMQX Cloud VCN.

1. In the VCN details page, open the **Security** tab.

2. Locate the **Security Lists** or **Network Security Groups (NSGs)** associated with your Oracle Cloud resources.

3. Add **Ingress Rules** to allow traffic from the EMQX Cloud CIDR block.

   - **Source**: EMQX Cloud VCN CIDR
   - **IP Protocol**: TCP (or as required)
   - **Destination Port Range**: As required by your application

4. Save the changes.

   ![ingress_rules](./_assets/vpc_oracle/ingress_rules.png)

## Delete a VPC Peering Connection

To delete a peering connection, you need to ensure that the status of the VPC peering connection is **Running**.

::: tip

Before deleting the peering connection, make sure that there are no associated resources in the deployment; otherwise, there will be unpredictable risks.

:::

1. Go to the VPC Peering Connection area on the Network Management page in your deployment.

2. Click the "delete" icon in the **Actions** column of the peering connection.