> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/connect-your-technology/l-p-integrations/oracle-cloud-infrastructure/oracle-cloud-infrastructure-terraform-setup.md).

# Oracle Cloud Infrastructure - Terraform Setup

*If you wish to set up the integration manually, return to the* [*Get Started with Oracle Cloud Infrastructure*](/connect-your-technology/l-p-integrations/oracle-cloud-infrastructure/get-started-with-oracle-cloud-infrastructure-setup-for-workbench.md) *page and choose your manual setup option.*

We use Terraform to automate the OCI functions. The Terraform script provisions the central resources in the home region, as well as all necessary regional resources to allow the forwarding of logs to the central bucket.

## Scope and Limitations

1. We have set the retention lock in the automation to 15 days (360h), because Terraform runs so fast that minor clock differences between your system and OCI's servers can cause a 14-day request to be rejected (OCI requires retention locks to be set at least 14 days in the future). Manual setup is slow enough that this is not an issue.
2. This automation supports complete rollback/teardown, however the central bucket and docker image cannot be removed via Terraform due to known limitations within OCI. 
   * **If you need to perform a rollback (such as to retry the setup process), make sure to use the `./deploy.sh rollback` command to do so.** This ensures all resources are removed in a way that does not create a conflict if you re-create resources of the same name.
   * The **central bucket** must be removed manually, unless you wish to use a different bucket name if/when you retry the setup.
   * The **compartment** can be removed via Terraform, but we recommend you remove it manually because compartment deletion may take several minutes to hours if done via Terraform.
   * We do not recommend you remove the **docker image**.

## Prerequisites

1. Make sure there is a user from your organization with **Admin-level cloud access** to the relevant cloud environment.
   * The account you use could be your own OCI account, or it could be an administrator account.
2. Make sure you have an **email address from your organization** that can be used to associate with the Expel Machine User you will create.
   * This email will be used by you to generate the API credentials for Expel.
   * You should choose an organizational email you can access, like a shared security team mailbox or your work email.

## Before You Begin

1. **Locate all region identifiers** for the regions you wish to onboard. You will need to specify these identifiers when you configure the automation resources. 
2. **Obtain the tenancy OCID and tenancy namespace for the OCI admin user (the one deploying the resources)**, which you will need when you configure the automation resources. You can find these values under Profile > Tenancy > Tenancy details (the namespace is labeled "Object storage namespace").

{% hint style="info" %}
If you need additional help locating any of these values, see the [Troubleshooting](#troubleshooting).
{% endhint %}

## Step 1: Download the Automation Files

{% file src="/files/XadMi5GqjYHt35sWRLr0" %}

The expel\_oci\_automation.zip file contains the Terraform configurations, function code, and deployment scripts you need to complete this guide.

<table><thead><tr><th width="175.11328125">Module</th><th width="241.06640625">Contents</th><th>Purpose</th></tr></thead><tbody><tr><td>terraform/central</td><td>Terraform configuration</td><td>Creates central/global resources (run once per tenant).</td></tr><tr><td>terraform/regional</td><td>Terraform configuration</td><td>Creates regional resources (run once per region).</td></tr><tr><td>function/</td><td>Dockerfile, func.py, func.yaml, requirements.txt</td><td>Function code deployed to each region.</td></tr><tr><td>config.env</td><td>Configuration file</td><td>User-provided values for the automation.</td></tr><tr><td>deploy.sh</td><td>Deployment script</td><td>Executes the setup process.</td></tr></tbody></table>

## Step 2: Configure the Automation Resources

In this step, you will unzip the files you downloaded in the previous step so that you can update the config.env file. After you have finished and saved that update, you must re-zip the folder so that it can be used by the automation script in a later step.

{% hint style="info" %}
Before you begin, make sure you have all **region identifiers** for the regions you wish to onboard, the **admin user's tenancy OCID**, **tenancy namespace**, and the **organization email address** [you decided to associate](#prerequisites) with the Expel Machine User. If you need help locating any of these values, see the [Troubleshooting](#troubleshooting).
{% endhint %}

1. Unzip the file you downloaded in Step 1.
2. In the top-level **expel\_oci\_automation folder**, locate the **config.env file** and open it in the text editor of your choice.
3. First, update the **OCIR\_USERNAME** with an OCI account that has permissions to create all required resources.
   * The account you use here could be your own OCI account, or it could be an administrator account.
   * For **native** users, use the format NAMESPACE/EMAIL. *Example: idhl111labc/example.<user@email.com>*&#x20;
   * For **federated** users, use the format NAMESPACE/oracleidentitycloudservice/EMAIL. *Example: idhl111labc/oracleidentitycloudservice/example.<user@email.com>*
4. Update the remaining values:
   * **TENANCY\_OCID** - enter your **tenancy OCID**. If you need help locating this value, see the [Troubleshooting](#tenancy-ocid).
   * **EXPEL\_AUDIT\_USER\_EMAIL** - enter [the org email you want to use](#prerequisites) for the Expel Machine User.
   * **EXPEL\_AUDIT\_USER\_FIRST\_NAME** - enter "Expel".
   * **EXPEL\_AUDIT\_USER\_LAST\_NAME** - enter "User".
   * **REGIONS** - enter the region identifiers for the regions you wish to onboard, using a csv string (example: “us-ashburn-1,us-chicago-1,us-phoenix-1”). If you need help locating the correct identifiers, see the [Troubleshooting](#region-identifier).
5. Save and close the updated file.
6. Re-zip the **updated expel\_oci\_automation folder** (you will need to use this folder in .zip format when you run the automation script in a later step).

## Step 3: Generate an Auth Token

An auth token is required in order to deploy the automation script later in this guide.

1. [Log in to OCI](https://cloud.oracle.com/).
2. In the top right, select your username/email.<br>

   <div align="left"><figure><img src="/files/Yyu2moKHAnvwUlCysXTp" alt="Use the person icon in the top right to access the menu and select your email." width="375"><figcaption></figcaption></figure></div>
3. Select the **Tokens and keys** tab.
4. In the **Auth tokens** section, select **Generate token**.
5. Enter a description for the token, such as "Expel token".
6. Select **Generate token**.
7. Copy and save the generated token, as you will need it for a future step and it will not be available again.
8. Select **Close**.

## Step 4: Upload the Automation File to OCI

You will use OCI's Cloud Shell to perform this step.

1. Make sure you are in your home region.
2. In the **Developer Tools** menu in the top right, select **Cloud Shell**. Wait for your machine to be created, and then continue to the next step.\
   ![Select the developer tools icon in the top bar, then select Cloud Shell.](/files/fgwNxnn7oNPH9JcxcTUC)
3. In the top right of the Cloud Shell window, select **Settings > Upload**.\
   ![Select the gear icon in the top right of the Cloud Shell window, then select Upload.](/files/THHfEi0aBxXLhhnOFmWp)
4. Drop or select the re-zipped, updated **expel\_oci\_automation.zip** file you configured in [Step 2](#step-2-configure-the-automation-resources).
5. Select **Upload**.

## Step 5: Deploy the Automation Script

{% hint style="info" %}
Before you begin, make sure you have the auth token you generated in [Step 3](#step-3-generate-an-auth-token).
{% endhint %}

1. Still in the Cloud Shell window, use the following command to unzip the file you just uploaded:

```
unzip expel_oci_automation.zip
```

2. Switch to the file's directory:

```
cd expel_oci_automation
```

3. Grant execution permissions to the deployment script:

```
chmod +x ./deploy.sh
```

4. Execute the deployment script:

```
./deploy.sh
```

5. When prompted, enter the **auth token** you generated in Step 3.
6. All global and central resources will now be created, along with the regional resources in the selected regions.&#x20;
7. When the process has finished, copy and save the following two values:
   * Stream OCID (this will be the Stream ID in Workbench)
   * Stream Endpoint (this will be the Stream endpoint in Workbench)

<figure><img src="/files/k61hqcfcjgBTxM9tcCGB" alt="A confirmation screen after successful automation, showing the two values you need to copy."><figcaption></figcaption></figure>

## Step 6: Validate All Resources

Before continuing with the setup process, make sure all resources have been created and that there are no errors.

* You may search for the resources in whatever way is easiest for you. For more details, see [Inspecting Resources](https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Tasks/inspect-resources.htm) in the OCI documentation.
* Search for each resource in the charts by name, as this is the name that was created by Terraform.

If you find any discrepancies or issues, [follow the Troubleshooting steps to perform a correct rollback](#you-need-to-perform-a-rollback-and-retry-the-setup) and try the setup process again or [contact Support](/support/how-to-reach-us.md) for help.

<details>

<summary>Global and Central Resources</summary>

<table><thead><tr><th width="45.01171875" data-type="number">#</th><th width="100.12890625">Type</th><th width="147.68359375">Resource</th><th>Name</th><th>Purpose</th></tr></thead><tbody><tr><td>1</td><td>identity</td><td>compartment</td><td>expel_audit_compartment</td><td>Contains all Expel resources</td></tr><tr><td>2</td><td>identity</td><td>dynamic group</td><td>expel_audit_functions_dg</td><td>Grants permissions to OCI resources</td></tr><tr><td>3</td><td>identity</td><td>user group</td><td>expel_audit_functions_dg</td><td>Group for Expel machine user</td></tr><tr><td>4</td><td>identity</td><td>user</td><td>expel_audit_user</td><td>Expel machine user</td></tr><tr><td>5</td><td>identity</td><td>policy (compartment)</td><td>expel_audit_collection_policy</td><td>Dynamic group permissions</td></tr><tr><td>6</td><td>identity</td><td>policy (tenancy)</td><td>expel_audit_machine_policy</td><td>Machine user permissions</td></tr><tr><td>7</td><td>storage</td><td>bucket</td><td>expel_audit_central_bucket</td><td>Function target bucket (receives forwarded logs)</td></tr><tr><td>8</td><td>storage</td><td>lifecycle policy</td><td>expel_audit_lifecycle_policy</td><td>Set to auto-delete after 14 days</td></tr><tr><td>9</td><td>storage</td><td>retention rule</td><td>expel_audit_retention_rule</td><td>7-day retention lock</td></tr><tr><td>10</td><td>streaming</td><td>stream pool</td><td>expel_audit_stream_pool</td><td>Container for streams</td></tr><tr><td>11</td><td>streaming</td><td>stream</td><td>expel_audit_stream</td><td>Event notification queue</td></tr><tr><td>12</td><td>events</td><td>event rule</td><td>expel_audit_event_rule</td><td>Triggers on object create/update in central bucket</td></tr></tbody></table>

</details>

<details>

<summary> Regional Resources</summary>

These resources are created for each target region you onboard.

<table><thead><tr><th width="45.01171875" data-type="number">#</th><th width="139.6875">Type</th><th width="275.671875">Name</th><th>Purpose</th></tr></thead><tbody><tr><td>1</td><td>service connector</td><td>expel_audit_sch_[RegionIdentifier]</td><td>Audit logs → regional function</td></tr><tr><td>2</td><td>application</td><td>expel_audit_func_app_[RegionIdentifier]</td><td>Container for the function</td></tr><tr><td>3</td><td>function</td><td>expel_audit_function_[RegionIdentifier]</td><td>Payload → central bucket</td></tr><tr><td>4</td><td>VCN</td><td>expel_audit_vcn_[RegionIdentifier]</td><td>Container for network components</td></tr><tr><td>5</td><td>service gateway</td><td>expel_audit_sgw_[RegionIdentifier]</td><td>Facilitate communication between OCI services</td></tr><tr><td>6</td><td>NAT gateway</td><td>expel_audit_natgw_[RegionIdentifier]</td><td>Facilitate communication between OCI services</td></tr><tr><td>7</td><td>security list</td><td>expel_audit_sl_[RegionIdentifier]</td><td>Control network traffic at the subnet level by defining firewall rules</td></tr><tr><td>8</td><td>routing table</td><td>expel_audit_rt_[RegionIdentifier]</td><td>Control where network traffic goes from a subnet</td></tr><tr><td>9</td><td>private subnet</td><td>expel_audit_subnet_[RegionIdentifier]</td><td>Divide a VCN into smaller network segments</td></tr><tr><td>10</td><td>registry repo</td><td>expel_audit_repo_[RegionIdentifier]</td><td>Store and manage container images</td></tr><tr><td>11</td><td>registry docker image</td><td>expel_audit_repo_[RegionIdentifier]/ expel_audit_function_[RegionIdentifier]:&#x3C;version_tag></td><td>Packaged container application stored inside OCIR</td></tr><tr><td>12</td><td>context</td><td>[RegionIdentifier]</td><td>Store and switch between OCI CLI configurations</td></tr></tbody></table>

</details>

## Step 7: Obtain the Expel Credentials

These credentials will be used when you configure the security device in Workbench.&#x20;

{% hint style="warning" %}
Before you begin, make sure you have logged out of OCI and looked for the activation email from Oracle.
{% endhint %}

### Step 1: Generate the Credentials

1. Log in to OCI with the Expel Machine User email address you specified in the automation resources. You should have already received an activation email from Oracle. &#x20;
2. In the top right, select the username/email.\
   ![Select the profile icon in the top right and then select the user email.](/files/Yyu2moKHAnvwUlCysXTp)
3. Select the **Tokens and keys** tab.
4. Select **Add API key**.
5. Choose the **Generate API key pair** option.
6. Download the **private key**. This file will download as a .pem file.
7. Select **Add**.
8. In the Configuration file preview, use the Copy button to quickly copy and save the following values:
   * **User** (this will be the OCI user in Workbench)
   * **Fingerprint** (this will be the OCI key fingerprint in Workbench)
   * **Tenancy** (this will be the OCI user tenancy in Workbench)
   * **Region** (this will be the OCI region in Workbench)

<figure><img src="/files/Fx5gHwWJatViuknOLjTr" alt="A preview of the config file showing the needed values and a copy button."><figcaption></figcaption></figure>

### Step 2: Base64 Encode the API Key

You must now format your private API key as a base64-encoded string, and save the output. This string is what you will use for the API key when you configure the security device in Workbench.

{% hint style="danger" %}
For security reasons, we do NOT recommend using an online Base64 encoding website.
{% endhint %}

{% tabs %}
{% tab title="Windows Systems" %}

1. Open PowerShell.
2. Run the following command (drag your .pem file into the window after entering the first part):

```
[Convert]::ToBase64String([IO.File]::ReadAllBytes("<file location/path>"))
```

3. Copy and save the output as your base64-encoded API key.
   {% endtab %}

{% tab title="Unix-Like Systems" %}

1. Open Terminal.
2. Run the following command (drag your .pem file into the window after entering the first part):

```
base64 -i
```

3. Copy and save the output as your base64-encoded API key.
   {% endtab %}
   {% endtabs %}

{% hint style="warning" %}
You may delete the .pem file after you have successfully set up the security device in Workbench. Please retain it until then. If you need to verify that your API key was encoded correctly, see the [Troubleshooting](#base64-encoding).
{% endhint %}

## Step 8: Add Oracle Cloud Infrastructure as a Security Device in Workbench

{% hint style="info" %}
Before you begin, make sure you have the **stream OCID** and **stream messages endpoint** from [Step 5](#step-5-deploy-the-automation-script), as well as the **user**, **fingerprint**, **tenancy**, **region**, and **base64-encoded API key** from [Step 7](#step-7-obtain-the-expel-credentials).
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select **Add Security Device**.
4. In the search box, type “Oracle” and then select the **Oracle Cloud Infrastructure** integration.
5. Complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName OCI”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Stream ID** - enter the **stream ID** you saved in Step 5.
   * **Stream endpoint** - enter the **stream endpoint** you saved in Step 5.&#x20;
   * **OCI user** - enter the **user value** from the configuration file you saved in Step 7.
   * **OCI key fingerprint** - enter the **fingerprint value** from the configuration file you saved in Step 7.
   * **OCI user tenancy** - enter the **tenancy value** from the configuration file you saved in Step 7.
   * **OCI region** - enter the **region identifier** from the configuration file you saved in Step 7.
   * **OCI user key** - enter the **base64-encoded string for the private API key**, which you created in Step 7.
6. Select **Save**.
7. Select **No thanks, I will not provide console access** from the console access dropdown.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support/how-to-reach-us.md).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work.md#device-tuning).

## Troubleshooting

### Device Connection Issues

<details>

<summary>The device does not connect successfully.</summary>

1. Make sure you selected the correct compartment when you deployed the stacks.
2. Verify that you downloaded the private API key and not the public one.
3. Check to be sure your API key was base64-encoded correctly (see below for help).
4. Make sure you pasted all values into the security device correctly, and that you removed any quotes. These values are case-sensitive.
5. Check your connector to make sure it is active.

</details>

<details>

<summary>You need to perform a rollback and retry the setup.</summary>

* Make sure to use the `./deploy.sh rollback` command. This rollback method ensures all resources are removed in a way that does not create a conflict if you re-create resources of the same name.
* You will have to manually delete the central bucket or choose a different name when you retry the setup (known limitations within OCI prevent us from deleting this bucket via Terraform).
* The compartment can be removed via Terraform, but we recommend you remove it manually because compartment deletion may take several minutes to hours if done via Terraform.

</details>

<details>

<summary>You are having persistent issues after trying both of the above.</summary>

If issues persist after checking the above and/or retrying the setup, [contact Support](/support/how-to-reach-us.md). Make sure to provide:

1. Your tenancy OCID and home region
2. The error message shown in Workbench
3. Screenshots of your central bucket and stream details

</details>

### Region Identifier

When you set up the region-specific policy, you must use the correct region identifier. To determine the region identifier:

1. In the upper right, select Manage regions.\
   ![Select the region in the top right, then select manage regions.](/files/WP1ISPWpBHhMQWrlqywS)
2. Locate your region to find its region identifier.

<figure><img src="/files/hNzp6nY3tUJBz3JgZL6R" alt="A page showing the correct region identifiers for each region."><figcaption></figcaption></figure>

### Tenancy OCID

You can find the tenancy OCID under **Profile > Tenancy > Tenancy details**.

### Tenancy Namespace

You can find it on the same page as the Tenancy OCID, labeled as **Object storage namespace**.

<figure><img src="/files/t9SHqU0OCVlx5BVm5h5S" alt="The object storage namespace is circled."><figcaption></figcaption></figure>

### Base64 Encoding

To verify your API key, you can decode your Base64 string and make sure the key matches the one in your .pem file.

{% tabs %}
{% tab title="Windows Systems" %}
Open PowerShell and run:

```
[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('YOUR-BASE64-STRING'))
```

{% endtab %}

{% tab title="Unix-Like Systems" %}
Open Terminal and run:

```
printf "%s" "YOUR-BASE64-STRING" | base64 -d
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.expel.io/connect-your-technology/l-p-integrations/oracle-cloud-infrastructure/oracle-cloud-infrastructure-terraform-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.