Most NL→SQL demos are impressive… right up to the moment you need real guarantees. In finance, healthcare, or regulated ops, “pretty good” isn’t good enough.

This article lays out a two‑lane architecture that answers known questions instantly and routes novel ones to human‑in‑the‑loop (HITL) verification and then learns from every review.

Think of it like airport security:

TSA Pre✓® for vetted passengers (fast, cheap, repeatable) and manual screening for everyone else (slower, safer, documented). Same airport, two speeds, one goal: trust!

Lane 1 - The Fast Lane (Reuse, don’t regenerate)

1) Semantic lookup inside the database. When a user asks, the agent runs a similarity search over a repository of previously approved question⇄SQL pairs stored as embeddings in Oracle Autonomous Database 23ai AI Vector Search. If it finds a true match, it reuses the human‑approved SQL - no new generation, no chance to hallucinate new SQL.

2) LLM‑as‑a‑Judge gate. A lightweight judge agent checks whether the new question is semantically identical to the validated one (e.g., cosine threshold and schema terms align). If yes → execute the approved SQL and return the answer. If not → route to the Quality Lane.

Why this works: you avoid generation entirely for common asks. Over time, your “approved SQL cache” compounds - faster answers, lower cost, higher consistency.

Lane 2 - The Quality Lane (Generate, pause, verify, learn)

For novel/ambiguous asks we generate carefully and verify before execution:

1) Clarify & improve the question (short feedback loop).

2) Generate candidate SQL using Select AI in‑database - keeping data movement minimal and auditability high. Don’t execute yet.

3) HITL checkpoint with interrupts. The agent pauses; an analyst verifies business logic, schema, joins, filters, limits and then will either Approve → execute, or Reject → the agent revises and resubmits.

4) Close the loop. Store the now‑approved question⇄SQL as an embedding for future Fast‑Lane reuse (with lineage + reviewer + timestamp).

Reality check: NL→SQL is powerful but can mis-join, mis-filter or reference non-existent columns/tables. The human checkpoint is your safety valve.

Demo repo & UI

GitHub - shjanjua/fast-or-verify-nl2sql

Contribute to shjanjua/fast-or-verify-nl2sql development by creating an account on GitHub.

GitHubshjanjua

I've published a Gradio demo that shows the main moving parts with a clean UI. What it includes today:

• LLM-as-a-Judge decisioning (the “is this semantically the same?” gate).
• Fast Lane behavior for returning pre-approved SQL when there’s a true match (no execution).
• Quality Lane (partial): up to NL→SQL generation (SQL is produced and displayed, not executed).
• Confidence label: "High/Medium/Low" classification for the generated SQL.

What it does not include:

• Human-in-the-loop review UI (approve/reject/edit) and the asynchronous pause/resume cycle.
• Automatic vectorization & storage of new question⇄SQL approvals (i.e., embedding + metadata write-back).
• SQL execution against a database.

👉 Repo: https://github.com/shjanjua/fast-or-verify-nl2sql - it’s built with Gradio so you can run and share the demo quickly without front-end heavy lifting.

Pre-reqs: Oracle Database with Select AI configured and a vector table containing approved Question, SQL & Embedded-Question for Fast-Lane lookup.

Under the Hood

• Oracle Autonomous Database 23ai – AI Vector Search: semantic lookup of approved Q⇄SQL right where your data lives. Oracle Documentation
• Select AI: in-database NL→SQL + RAG for the Quality Lane. Oracle Documentation
• OCI Generative AI: managed LLMs/embeddings for judging, rewriting and confidence scoring.
• Python + LangGraph: multi-step agent.
• Gradio: lightweight UI to expose the flow and show the SQL being produced.

Guardrails that matter

• Least privilege: read-only roles/views; block DDL/DML by policy.
• Dual thresholds: similarity and judge verdict; escalate to HITL on doubt.
• Query “unit tests” (row-count bounds, KPI validations, time windows) — not in demo.
• “Show your work” UX: SQL preview, tables touched, filter summary (the demo previews SQL only).
• Governance metadata (reviewer, version, glossary tags) — not in demo.

What to measure (once you wire in HITL + execution)

• Fast-Lane hit rate (% answered via reuse).
• Time-to-answer (p50/p95) and review latency.
• HITL approval rate and revision count.
• Escapes (post-hoc corrections) → target near-zero.
• Cost per answer vs BI baseline.

Conclusion

This pattern doesn’t replace experts, it scales them. Every human‑approved query becomes a reusable asset, turning your conversational layer into a trust machine over time

You've had your billion dollar, unicorn start-up idea. Your mind is already racing with the architecture, frontend and backend code you'll need to make it a reality. Your main business logic will be served by the backend code. This will (usually) be accessed through RESP APIs that you've so lovingly and tenderly handcrafted with a sweet kiss on the forehead that only a loving mother could hope to replicate.

Now, time to secure your precious childre- I mean APIs, from potential harm...

This guide will make use of Auth0 as an identity broker for a few reasons

1. It's easy. Offload your identity and principal management to somebody else
2. Auth0 provides rich libraries for handling Users, registrations, SSO, password resets and, most importantly for this post, accessTokens in a straightforward manner

We'll also be using Google Cloud's API Gateway as that's what I've experimented with and written a previous post on for handling CORS preflight checks - read about that here:

CORS in GCP API Gateway

If you’re like me, building an application with Backend APIs protected behind a Google Cloud API Gateway, you’ve probably encountered a common issue: The ability to handle CORS preflight requests from your FrontEnd! This is less of an issue with the self-administered ESP and ESPv2 offerings, but using the Managed

High On CloudUsamah Ali Hussain

You'll need to create an Auth0 application suitable for your Front End. Once that's created, Navigate to Applications > Applications and select your newly created app. In the below screen, you'll see your Domain. Make a note of this!

Under Applications > API, you'll also need to create an API to represent your endpoints. Once done, make a note of the Identifier (Audience) that you will have provided during creation:

You should now have a note of your:

• Auth0 Domain
• Auth0 API Audience

You'll also need your Front End application to handle Auth0 login and send your Auth0 User's accessToken (this is important!) with each request. There is documentation on getting this for a number of frameworks, pick your poison.

Once you've got the pre-requisites, the implementation is rather simple. Using the OpenAPI Spec YAML file, we can setup a security attribute and apply it to all of the endpoints we want to secure.

Here is a full example that we'll break down:

# openapi-spec.yaml
swagger: "2.0"
info:
  title: "Voqu VBaaS Backend API"
  description: "API for the Voicebot-as-a-Service platform"
  version: "1.0.0"
schemes:
  - "https"
produces:
  - "application/json"

host: "${api_gateway_managed_service}"
x-google-endpoints:
  - name: "${api_gateway_managed_service}"
    allowCors: True

securityDefinitions:
  auth0_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://${auth0_domain}/"
    x-google-jwks_uri: "https://${auth0_domain}/.well-known/jwks.json"
    x-google-audiences: "${auth0_api_audience}"

# We are returning to the path-based approach, now with the validator exception.
paths:
  /hello:
    get:
      description: "A sample endpoint to test authentication."
      operationId: "hello"
      x-google-backend:
        address: "my-super-cool-url.highoncloud.co.uk/hello"
      security:
        - auth0_jwt: []
      responses:
        "200":
          description: "A successful response"

Remember, this is YAML so be careful with spacing. The above file uses 2-space indents.

The 2 aspects we're using to secure our endpoints in the above file are:

• securityDefinitions - This block defines how the security will be checked, the JWT token issuer, URI and defined audiences
• security - This block is defined as a parameter in each endpoint method that we wish to secure allowing modular application of security where required

The entire flow works as follows:

1. The request reaches GCP API gateway with a header of Authorization: Bearer {token} as is the standard for Access Tokens
2. GCP API Gateway sees that the endpoint being accessed (GET on /hello) has a security parameter so it expects a Token to be checked before allowing the request to pass through
3. The GCP API gateway takes the provided token and uses the auth0 domain, JWKS URI and audiences to validate that the token belongs to a valid Auth0 user and contains the correct claims.
4. If all checks succeed, the request is forwarded to the backend.
5. If the checks fail i.e. the JWT token has expired or does not contain all of the correct, required claims, an error 401 Unauthorized is returned.

For deployment, this guide uses terraform.

The below snippets creates everything you need. Ensure your API Spec YAML file is in your main terraform directory alongside the below code.

• Enable the API Gateway Service

resource "google_project_service" "apigateway" {
  project            = var.project_id
  service            = "apigateway.googleapis.com"
  disable_on_destroy = false
}

• Create the Gateway API Resource as a container for the YAML configuration

resource "google_api_gateway_api" "vbaas_api" {
  provider = google-beta # API Gateway resources are often updated in the beta provider
  project  = var.project_id
  api_id   = "vbaas-backend-api"
  display_name = "VBaaS Backend API"
  depends_on = [google_project_service.apigateway]
}

• Store the OpenAPI Spec YAML file and pass in the required variables

resource "google_api_gateway_api_config" "vbaas_api_config" {
  provider     = google-beta
  project      = var.project_id
  api          = google_api_gateway_api.vbaas_api.api_id
  api_config_id_prefix = "vbaas-config-"
  display_name = "Voqu VBaaS Config v1.0.0"

  openapi_documents {
    document {
      path     = "openapi-spec.yaml"
      contents = base64encode(templatefile("${path.module}/openapi-spec.yaml", {
        auth0_domain          = var.auth0_domain
        auth0_api_audience    = var.auth0_api_audience
        api_gateway_managed_service  = var.api_gateway_managed_service
      }))
    }
  }

  # This lifecycle rule prevents downtime during updates by creating the new
  # config before destroying the old one.
  lifecycle {
    create_before_destroy = true
  }
}

• Spin up the API Gateway

resource "google_api_gateway_gateway" "vbaas_gateway" {
  provider     = google-beta
  project      = var.project_id
  region       = var.region
  gateway_id   = "vbaas-gateway"
  api_config   = google_api_gateway_api_config.vbaas_api_config.id
  display_name = "Voqu VBaaS Gateway"

  depends_on = [google_api_gateway_api_config.vbaas_api_config]
}

• <Optional> Add an output to easily find your API Gateway URL

output "api_gateway_url" {
  description = "The default hostname of the deployed API Gateway."
  value       = "https://${google_api_gateway_gateway.vbaas_gateway.default_hostname}"
}

Now, you can use Auth0 credentials to manage access to your backend APIs. The flexibility of this approach means that the security requirement can be added to any API endpoints and even specific HTTP Request methods for that endpoint, as and when required.

If you're like me, building an application with Backend APIs protected behind a Google Cloud API Gateway, you've probably encountered a common issue: The ability to handle CORS preflight requests from your FrontEnd!

This is less of an issue with the self-administered ESP and ESPv2 offerings, but using the Managed API Gateway offering, you relinquish control of startup options which require some careful considerations for scenarios such as handling CORS preflight requests.

I'm lazy, so here's Gemini Pro 2.5's explanation of CORS:

CORS (Cross-Origin Resource Sharing) preflight OPTIONS requests are a security mechanism used by web browsers to check with the server if the actual request (e.g., POST, PUT, DELETE, or a GET with custom headers) is safe to send.

Their primary purpose is to ensure that a server explicitly permits cross-origin requests that could have side effects on the server's data. This prevents malicious websites from making requests to an API on another domain without the API's explicit permission, enhancing web security.

Now that we've got that out of the way, let's get into issues with GCP and how to handle this.

I know AI is all the buzz right now, but this is not to be confused with OpenAI!

Configuration of a GCP API gateway required an OpenAPI Spec YAML file: https://cloud.google.com/api-gateway/docs/openapi-overview

An example of a simple OpenAPI Spec file for handling backend routes is:

    swagger: "2.0"
    info:
      title: API_ID optional-string
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    host: DNS_NAME_OF_DEPLOYED_API
    schemes:
      - "https"
    paths:
      "/airportName":
        get:
          description: "Get the airport name for a given IATA code."
          operationId: "airportName"
          parameters:
            -
              name: iataCode
              in: query
              required: true
              type: string
          responses:
            200:
              description: "Success."
              schema:
                type: string
            400:
              description: "The IATA code is invalid or missing."

Here you can see we define a single /airportName path which accepts GET requests, requiring parameters and responding with either 200 for success or 400 for an invalid or missing IATA code.

As is, the above spec will work perfectly fine for direct requests to the Gateway, assuming the backend is properly configured of course. Direct requests through Curl or a tool such as Postman will respond appropriately. The issue arises when attempting to access these endpoints using a Front End application in a Browser such as Google Chrome. As we figured out above, the browser will send a HTTP OPTIONS request to see if the actual request is safe to send and if the origin is accepted.

We need to inform the GCP API Gateway that it should handle these CORS Preflight Options requests otherwise it will result in all requests to this API Gateway from the frontend failing with a CORS error HTTP 503 "No Healthy Upstream".

We have two options:

1. Define an explicit OPTIONS method on every endpoint path that will be accepting requests, which will forward these to the backend on every path.
2. Tell the API Gateway to automatically forward all OPTIONS requests to the backend and handle them there.

The second option makes the most sense and is specifically designed for this use-case, otherwise any change to endpoint paths, adding or removing, will need a duplicated block of code to handle those OPTIONS requests. Not very DRY-Programming.

For this we'll need two aspects.

1. Firstly we'll need to tell the API Gateway to handle all OPTIONS requests for defined endpoints.
2. Secondly, we'll need to ensure our Backend (in this example, a FastAPI Application) can handle all of these.

Let's tackle the first part. For this, you'll need a few variables:

• API Gateway managed service name - You can get this from the GCP Console. It will look something like {api_name}-ID.apigateway.{project-name}.cloud.goog

• Your backend URL - Where the actual defined endpoints are hosted.

The below spec is using the example of :

• demo-gateway-18bxrikyi5dy4.apigateway.project.cloud.goog as the Managed Service name and
• my-cool-host.highoncloud.co.uk as the backend URL

# openapi-spec.yaml
swagger: "2.0"
info:
  title: "Voqu VBaaS Backend API"
  description: "API for the Voicebot-as-a-Service platform"
  version: "1.0.0"
schemes:
  - "https"
produces:
  - "application/json"

host: "demo-gateway-18bxrikyi5dy4.apigateway.project.cloud.goog"
x-google-endpoints:
  - name: "demo-gateway-18bxrikyi5dy4.apigateway.project.cloud.goog"
    allowCors: True


# We are returning to the path-based approach, now with the validator exception.
paths:
  /hello:
    get:
      description: "A sample endpoint to test authentication."
      operationId: "hello"
      x-google-backend:
        address: "my-cool-host.highoncloud.co.uk/hello"
      responses:
        "200":
          description: "A successful response"

The key bit to point out here is:

• allowCors - This is set on the entire API Gateway host so all OPTIONS requests will be forwarded

That's the magical touch. It needs to be defined on the x-google-endpoints where the name parameter is set as your API Gateway Managed Service name.

Now with all of this in place, all requests sent to this API Gateway, from an application running in Chrome, which are preceded with a CORS preflight OPTIONS request, will be forwarded to the x-google-backend.

We also need to ensure the backend can handle these OPTIONS requests. For this scenario, I'm running a FastAPI application in development mode which simplifies things. Simply adding the below block of code to your application main.py or otherwise will allow it to handle these appropriately.

• Note: The below code is only suitable for development where all origins are accepted. This is UNSECURE and should be changed to only accept the appropriate origins in production.

from fastapi import FastAPI

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Allow all origins for testing
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

And there we have it. Handling CORS Preflight requests through a GCP API Gateway is complete.

I've been playing with building an application recently so look out for a blog post on securing your endpoints, through the GPC API Gateway, using JWT tokens and Auth0 as an identity provider.

This blog serves as an example of implementing a Full end-to-end automation for deploying code to a "serverless" function, all hosted within OCI.

It's going to revolutionise the world and how we see technology henceforth... I think.

Background

You have a single or multiple routine jobs that you wish to automate through a script. You want this to be deployed on the cloud, with minimal input required on management of the platform as well as reducing costs. You also want to be able to rapidly develop, test and deploy this in a collaborative fashion.

Solution

What we need is a version controlled, collaborative and managed service that will scale, be maintained, only charge for actual usage and be easy enough to deploy and test.

OCI has the stack to solve all of these issues, you just don't know it yet.

Let's start with the design and work into the details of how we can fit them all together.

Workflow

I'm going to show what it would actually look like for Developers to use this system first, so you get a feel for it..

You, master of coding, write some nice code and commit it to the GIT repository (with a proper Commit message of course... I'm looking at my past self judgingly here)

Once you hit that fateful Commit & Push button, the code, as you'd expect, is pushed to the repository. Aaaaaand, that's your work done.

What happens next... is magic (or just the CD part of CI/CD)

OCI DevOps will trigger a Build Pipeline, which triggers a Deploy Pipeline, which deploys to OCI Functions.

Let's dig into the details of how this works and, more importantly, how you can implement this today

The involved components are:

• OCI DevOps Project - An isolated logical environment hosting our CI/CD Resources
• Code Repository - GIT repository hosted and managed by OCI
• Build Pipeline - Used to build (it's in the name) and test software artifacts
• Deployment Pipeline - Used to (you guessed it) deploy artifacts to target environment(s)
• Container Repository - Since we're deploying Docker Containers in this use case, our artifact repository is the OCI Container Repository
• OCI Functions - The target environment to which the Deploy Pipeline will, you know, deploy artifacts.
• OCI Logging/Notification - Useful for (surprise surprise) logging and alerting of any happenings within the Project

Breakdown

Now let's go into each of the above components and discuss how they fit into our specific use-case

OCI Logging/Notifications

When creating a DevOps Project, OCI needs a place to send all of the related alerts and logs (think Pipeline runs and failures, triggers, merges etc). For this, we'll create an OCI ONS Notification Topic and associate this at Project creation, allowing all the relevant notifications to be sent here.

DevOps Project

This one is pretty simple. An OCI DevOps Project is a logical grouping of all the resources required to implement a CI/CD workflow. All the components we go through henceforth will sit under a single Project umbrella.

The nice thing about having everything hosted within OCI is that you no longer have to manage Identities and Access Control across multiple platforms (or try and integrate different platforms with a central LDAP provider). Everything is in one place with OCI's (quite decent if I do say so myself) Policies for granular access control.

Code Repository

A requirement for the CI part of any CI/CD workflow is a version-control system (usually GIT unless you just love being different).

OCI hosts GIT repositories as PaaS services. This is cool because <insert-usual-PaaS-benefits-here>. As a user, you simply create a repository, and off you go.

Code Repositories retains all of the usual GIT features: commits, pulls, pushes, merge requests etc and make up the first step in our journey to deployment.

Pipelines

A ubiquitous term in DevOps. OCI comes with two types of Pipelines allowing you to separate the stages of deployment.

• Build Pipeline: Used to compile, test and (key is in the name) build artifact(s). Think of creating a Spring Boot jar file with java -jar or using a Dockerfile to create an image.
• Deploy Pipeline: Deploy your artifact to the target environment(s).

Build Pipelines have a "Managed Build" stage which takes in a build_spec.yaml file with instructions on how to build the required artifact(s). You can (should) also use this stage to perform tests, however testing isn't covered as part of this guide (see disclaimer).

Deploy Pipelines require two things:

• Artifact(s): These should already be compiled and stored in an Artifact Repository. In our case, this will be the container image created from our code in the Build Pipeline.
• Environment: The target platform for your software. We'll be deploying directly to our OCI Function.

Trigger

OCI Triggers are used in the same way as any GIT trigger. We'll be waiting for pushes to the main branch (see disclaimer before you send death threats) in our Code Repository and using that to trigger the build Pipeline run.

We'll be using another trigger (but defining this one in the Build Pipeline) to kick off the Deployment Pipeline once the Build Pipeline has completed it's steps.

build_spec.yaml

This is the yaml file stored in the Code Repository which tells the OCI Build Pipeline how to work. You can define any number of steps and stages within this (compile, test, rollback on failures etc.).

By default, the Build Pipeline will attempt to find this in the root of your supplied Code Repository, if it is not named as expected or can be found somewhere else, you'll need to configure the Build Pipeline with this location.

In our case, we'll be using this file, along with a Dockerfile to build our python code into a container image,

Now that we understand all of the individual pieces of the puzzle, let's get them all working together.

A word of warning, the next steps are quite in-depth with some moving parts.

Pre-requisites

You'll need an existing OCI Function to deploy to. If you don't have a function, create one using the QuickStart Guides:

Functions QuickStart Guides

Get set up and running quickly using the OCI Functions QuickStart Guides.

You'll also need an OCI IAM User with the appropriate policies allowing it to Manage (push) OCI Container Repository images. Create an Auth token for this User and store it as a Secret in an OCI Vault in the same compartment as your DevOps project. You'll throw this Secret OCID into your build_spec.yaml file.

Step-by-step

Up to this point, what we have is all of the Building blocks for a streamlined, automated deployment. Let's get to deploying

Terraform

Before deploying, ensure you have appropriately populated the provided variables.tf file. The required variables should be self-explanatory (if not, write a pipeline that, when triggered - like you - will send me a strongly worded email)

The code example assumes an OCI Function already exists and we're referring to its OCID which is stored in a terraform variable.

The code will also create all of the required Policies and the dynamic group to give OCI DevOps the required permissions in the compartment.

Run the provided terraform code to spin up all the resources

OCI-CICD/terraform at prod · usamahuzi/OCI-CICD

All the resources you need to Automatically deploy your code to OCI Functions using OCI DevOps - usamahuzi/OCI-CICD

GitHubusamahuzi

• Dynamic group and associated Policies for OCI DevOps:
  • Allow DevOps resources to manage all resources within the compartment
• DevOps Project with ONS Notification Topic
• Code Repository and Trigger
• Target Deploy Environment and Deployment Artifact
• Build and Deploy Pipelines with Stages

Code Repository contents

Once we have the platform, we'll need to setup the contents of the Code Repository that will allow our OCI Function to be deployed and tested.

Fn project CLI

For this, you'll need the Fn project CLI installed:

• For Windows:

curl -LSs https://raw.githubusercontent.com/fnproject/cli/master/install | sh

• For Mac:

brew update && brew install fn

Confirm installation using:

fn version

which should output something similar to the below (I'm not using the latest version, terrible)

Client version: 0.6.36 is not latest: 0.6.39

Generic Function code

Next you'll need to clone your Code Repository locally following this guide:

DevOps Git clone

You can clone the code repository to create a local copy on your computer, add or remove files, commit changes, and work on different branches by using Git operations.

Once cloned, move into your repository directory

cd repository-name

Initialise the function using:

fn init --runtime [go|java|node|python] my-func

Since this guide is creating a python function, I did:

fn init --runtime python user-report-fn

This will create a new directory with your function name. I'll be referring to my function name as user-report-fn from now on. Make sure to use the name you've given your function.

To keep things simple, we'll move everything to the root of the Code Repository and delete the new folder:

mv  user-report-fn/* ./
rmdir user-report-fn

Your directory should contain the following files for a python function:

func.py
func.yaml
requirements.txt

func.py - Your function code to be executed (put everything under the handler function)

func.yaml - Metadata about your function such as name, version

requirements.txt - A list of dependencies required for your python function to operate

You can find sample functions on the OCI GitHub which will give you an idea on how to get started. This guide won't cover Function development.

GitHub - oracle-samples/oracle-functions-samples: Examples demonstrating how to use Oracle Functions

Examples demonstrating how to use Oracle Functions - oracle-samples/oracle-functions-samples

GitHuboracle-samples

Specific Code for this automation

Once you have your function ready for deployment, you'll need to add 2 more files to the root of the Code Repository.

1. build_spec.yaml - As mentioned previously, this gives the instructions to the Build Pipeline
2. Dockerfile - This is required to create the Container Image that will ultimately be deployed as the OCI Function

Example contents of these files can be found here:

OCI-CICD/code-repository-contents at prod · usamahuzi/OCI-CICD

All the resources you need to Automatically deploy your code to OCI Functions using OCI DevOps - usamahuzi/OCI-CICD

GitHubusamahuzi

Do you care about what's going on in the build_spec.yaml file? If so, you need a hobby, but take a gander at the section below

Your Dockerfile can be identical to the one provided if you're using Python so easy peasy there.

Phew. I think we're ready to get this show on the road!

Push to the Code Repository and sit back to watch the magic happen.

Validation

Log into the OCI Console and you should be able to see your DevOps Project containing a new Code Repository, Build Pipeline, Deploy Pipeline, Trigger, Environment and Artifact.

Any new pushes of code to the Code Repository will kick off your Pipeline process, resulting in a shiny new Function being deployed, ready to wreak havoc on your enemies... or similar.

Conclusion

Wow. You've reached the end. Please get some sunlight.

Here's a nice meme summing up my experience getting the tech for this blog working.

This blog series is a longer format and expansion of my UK Oracle User Group presentation, titled; RAG to Reality: A deep-dive into enhancing AI with Retrieval-Augmented Generation, as well as the Oracle published blog: RAG to reality: Amplify AI and cut costs. A mouthful! But an accurate description.

A brief overview of what we'll cover in this series!

• What is Retrieval-Augmented Generation (Part1) - [This Blog]
  • Use-cases
  • Retrieval-Augmented Generation (RAG) Definition
  • Basic RAG Architecture
  • RAG Enhancements
• Oracle Cloud Infrastructure (OCI) Artificial Intelligence (AI) Services (Part2)
• OCI AI RAG Architectures (Part3)
• Easy Demo Build Guide (Part4)
• Advanced RAG (Part5)

Use-Cases

Before we even get into the details of Retrieval-Augmented Generation (RAG), lets see the type of scenario that brings about the need for RAG.

In the above scenario, HR spend an egregious amount of time dealing with employee queries since; policies are stored across different locations (contracts stored in HCM, benefits stored in a 3rd party site etc) and different parts of the business have entirely different policies (due to mergers & acquisitions). So there is not a one size fits all answer to most given queries!

Other scenarios may include;

• Customer Support: A need to provide real-time, accurate answers based upon policy documents
• Healthcare: Summarise patient records and retrieve relevant clinical guidelines
• Legal Tech: Extracting relevant case laws from large repositories for litigation support
• Financial Analysis: Summarising market trends and retrieving regulatory data
• Academic Research: Providing Summaries of related studies and findings across journals

Solving the problem

The features of GenAI & LLMs seem to be the right fit!

But if we ask ChatGPT 'how many days of annual leave am I entitled to?', it will give you a generic, long-winded answer. It's not trained on our enterprise data and it doesn't have access to our proprietary information such as our policies. Therefore, it can never give a precise and concise answer. So how do we go from a generic response, to a precise response ?

There are 3 main options here, but the most efficient of them all is Retrieval-Augmented Generation. So we finally get to it! So, what is RAG?

RAG is a framework that (1) Retrieves relevant, context-specific data from a knowledge-base in real-time, (2) augments the LLMs input with this retrieved data to (3) generate a response that is informed, contextually accurate and grounded upon up-to-date data. Easy-peasy! This framework addresses some of the key challenges you find with off the shelf LLMs

So now let's look at an actual (basic) RAG architecture!

For ease of understanding, let's split this into 2 sections; Data Ingestion and Query Response.

Data Ingestion

Data Ingestion has 3 main steps.

1. Chunking

Chunking is the process of dividing the corpus of documents into smaller text segments. It is required due to LLMs having a limit on the amount of data, typically measured in tokens, that it can in-take in any given call. So we split large texts into smaller segments, but an issue arrises when a given chunk doesn't capture an entire thought or idea.

In the RAG process, we will retrieve 'chunks' based on a similarity search and it is these chunks that will be passed into the LLM. So if a 'chunk' ends part-way through a thought, it may result in an incorrect conclusion as you are reading only part of an idea and you do not have the context in which to understand the given matching phrase in the chunk. How do we overcome this ? One popular method is overlapping; we overlap chunks such that a given text segment may be included in more than 1 chunk, this increases the chances of an entire thought or idea being captured in a single chunk. A more advanced technique is to use to use context-aware chunking in which an NLP model can be utilised to create semantic coherent chunks.

2. Embedding

Embedding is the process of transforming these text chunks into vectors, using an embedding model.

Embedding models are specially trained algorithms that convert the original data into a vector, whilst encapsulating information, features/properties of the original data in the vector. A vector consists of a list of numbers, each number is referred to as a dimension, and the dimensions capture the semantic meaning of the original word(s)/sentence(s) (when embedding text). The above image is a massive over simplification, but it is illustrating the idea that vectors are indeed a numeric representation of the information & features of the original data. Vectors will be discussed in more detail in 'Semantic Search' section

3. Vector Store

A vector store is just that, a store of all of the vectors. Vector stores are designed for low-latency retrievals and searching, whilst providing scalability and integration with popular ML pipelines for large-scale deployments

Query Response

Interacting with a RAG system (asking a question), and getting a response back, involves 5 key steps;

1. Question to RAG System

We require an entry point into our RAG system which, in the diagram, is the 'Multi-turn Chat Application'. It is worth noting, that both for data ingestion and query response, there several steps required, as such we require an orchestrator or co-ordinator, which isn't depicted in this basic RAG diagram. We'll highlight this further in the 3rd blog in this series.

2. Embed Question

The original question is embedded (converted to a vector), which will allow us to search against our vector store to find semantically similar documents. Embedding has already been covered in Data Ingestion.

3. Semantic Search

We then use the embedded question to execute an semantic search and identify the closest matching document chunks (which in theory will answer our question). The results of the semantic search will be an input into the LLM. But what exactly is semantic search ?

To try and avoid the philosophical debate about semantic search and vector similarity search, I will simply say that vector search is a part of a multi-step process to implement semantic search. Vector search refers to finding closely related data, in terms of semantics or features, by comparing the distance or angle of their vectors.

To understand this better, we'll base our example on Euclidean distance. Lets take the vector representation of a series of words and plot them onto a graph. The position of each word is represented by their respective vectors and through this we can visually see how closely related words are positioned close together. (In reality, the actual vectors would be hundreds of dimensions and the vectors would be plotted in a Euclidean space consisting of n-spaces, with n being the number of dimensions in a given vector. But for visual purposes, we'll represent them in 2 dimensions).

A raspberry is very similar, in terms of semantics and features, to a blackberry and therefore they are positioned close together. A blackberry has quite different properties to a plum, but they are still related in the sense that both are fruits, as such they fall within the vicinity of all fruits. But a plum is very different to an elephant, so their vectors are of great distance.

So if we take a new word, we can find the closest matching words by simply comparing its vectors to the vectors in the series and seeing which is the closest.

So if we insert the word puppy, we can see that dog, cat and wolf are the closest. But how do we do this mathematically ? We simply apply a formula to compare 2 vectors, the output being a single digit which numerically represents the distance between 2 given vectors.

The above example measures the euclidean distance between 2 vectors (derived from Pythagoras theorem), but there are many other formulas we can use. We simply;

• Calculate the difference between our 2 vectors over a given dimension
• Square this number (this way we always work with a positive number and escape the void of imaginary numbers when square-rooting)
• Do the above for all dimensions, and sum all outputs
• Square root the sum to produce a single number which represents the distance of 2 vectors.

Simply by looking at the numbers in the image above, we can tell that the top vector in the embedded data set is most like our vector as they are numerically the most similar!

4. Context

We then augment the input of the LLM with several pieces;

• The question itself
• The semantic search results
• Chat history
• Pre-amble/instructions to the LLM, such as 'You job is to answer the given question based upon the data provided to you'

5. Response

The LLM will then generate a response, and with the augmented input the LLM should give us an accurate, up-to-date and contextually appropriate response

And that's the flow of a basic RAG architecture! We can take a brief look at how we can turn it from basic to advanced, but we'll but we'll save the details for another blog post!

Just a quick overview of functionality we can add to improve the reliability of our basic RAG architecture! We'll cover these in more detail in another blog.

• Query Translation

You can't always trust the user to ask the right question, or ask it in the right way. If the question is too specific, then the semantic search may miss chunks that are relevant, if the question is too broad you may involve less relevant chunks which could skew the answer. There are many ways to address this; below are just 3;

1. Re-write the query
2. Create several alternatives, run several queries simultaneously and combine the results
3. HyDE - Hypothetical Document Embedding: Have GenAI produce a hypothetical document that may address the question, and execute the semantic search for that document

• Hallucination Checker

Use a separate checker (a dedicated LLM/prompt/agent) whose job is to read the draft answer and the retrieved context and flag unsupported claims. The flow is simple: generate → check → (optionally) revise or return "no grounded answer." This keeps the answering model fast while the checker enforces groundedness. In practice you’ll score entailment/faithfulness against the retrieved passages and only ship when confidence is high.

• Re-Ranking

Start broad, then sharpen. Do a fast first-pass retrieval, then apply a cross‑encoder re‑ranker to the top candidates so the best 5–10 rise to the top. On Oracle, you can call Cohere Rerank via OCI Generative AI as a managed re‑rank model. The result is higher precision without slowing down ingestion or indexing.

• Retrieval Fusion

Don’t bet on a single retriever. Combine keyword search (BM25) with vector similarity (AI Vector Search in Oracle Database 23ai) and fuse the ranked lists, e.g., with Reciprocal Rank Fusion (RRF). This gives you the best of both!

• Routing

Not every query needs the same path. Add a lightweight router that decides: which collection to hit, whether to use keyword, vector, or both, whether to expand the query, or to skip retrieval entirely. In Oracle, Select AI with RAG lets you keep this logic close to the data, and OCI Generative AI Agents (RAG) can orchestrate multi‑source workflows across enterprise content.

• GraphRAG

Graphs allow you to connect pieces of data together, so you can take a large document, split it into chunks and then connect the chunks. This connection shows a relationship between elements that may not be semantically similar. For example with Harry Potter novel, you may connect Harry Potter with; Hogwarts, Gryffindor, Orphan etc, The idea here is that you still do a vector search to identify semantically related chunks, but then you include related facts that are highly relevant in formulating a response but are not semantically connected...

• Multi‑modal

Often your documents aren't just text, they may have embedded images, tables, scanned text etc and different modalities (image, audio, text, video). To make them searchable, we need to ensure we can embed, search and 'understand' the various formats by utilising multi-modal LLMS (to do, for example OCR) and allow us to execute the same RAG flow on these documents.

In this article we'll look at setting up SSL Certificates for free on OCI LoadBalancer (LB), as well as automatically renewing the certificates in the LB when they expire. We'll use Terraform to do all of our Infrastructure setup, so we can focus on the Certificates & Automation!

Components

Oracle Cloud Infrastructure Load Balancer

The OCI Load Balancer provides Layer 7 Load Balancing and TLS Support, allowing us to use it for SSL termination, unlike the OCI Network Load Balancer (which does not provide either). This allows us to have a secure connection between End User and the Load Balancer, and then a HTTP call (stripping out SSL) between the Load Balancer and application, which is what we'll be setting up in this Tutorial. You can also do SSL Tunneling & End-2-End SSL.

Oracle Cloud Infrastructure Command Line Interface

The CLI is a small-footprint tool that you can use on its own or with the Console to complete Oracle Cloud Infrastructure tasks. The CLI provides the same core functionality as the Console, plus additional commands. Some of these, such as the ability to run scripts, extend Console functionality.

Let's Encrypt

Let's Encrypt is a free, opensource and automated Certificate Authority. Let's Encrypt offer FREE SSL/TLS Certificates! They are only valid for 90 days, but can simply be renewed.

Certbot

Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS.

Architecture

The architecture shown above is a simplified workflow of the SSL Certificate renewal & deployment. Everything in red pertains to the Certificate obtainment and deployment; Certbot VM is dedicated to this process. The LoadBalancer listens on 2 ports, each of which are connected to a different backend.

The first Listening Port is 443. This is the User TLS traffic that uses the Certificate. SSL Termination occurs on the LB, the traffic is then forwarded to a Compute instance, hosting a Webserver running on port 2839

The second Listening Port is 80. When traffic hits the LoadBalancer on Port 80, the LB forwards this traffic to Certbot VM on port 80, this is required for the Certificate creation

Let's Encrypt functions as an ACME Server and Certbot is an ACME client. In this setup ACME HTTP challenge is used, with this the ACME Server will attempt to access http://<DOMAIN>/.well-known/acme-challenge/<TOKEN> in order to prove ownership of the domain and create the Certificate. This means that the Certbot VM has to be accessible over port 80. Therefore our LB will be listening on port 80 and will direct the traffic to Certbot since the Compute instance is not accessible to Public Internet and has to be accessed via LB.

The high level flow is as follows;

• Certbot stands up Webserver running on port 80, for ACME Challenge
• Certbot fetches certificate from Let's Encrypt
• Let's Encrypt validates domain ownership via ACME HTTP Challenge
• New Certificate created and obtained from Certbot
• Certbot Hook calls custom script
• Custom script uses OCI CLI to upload the new certificate to LB & update LB Listener to use the new certificate

Pre-Requisites

• Oracle Cloud Infrastructure Tenancy so you can access Always Free services
• Domain with DNS Entry (Can be obtained for free via NoIP)

All of the terraform code is found here. Simply run this (don't forget to pass in your environment variables). This section is simply to give you an understanding of what we're doing via these terraform scripts.

GitHub - ShahvaizJanjua/HOC_FREE_SSL_Demo

Contribute to ShahvaizJanjua/HOC_FREE_SSL_Demo development by creating an account on GitHub.

GitHubShahvaizJanjua

Let's take a look at what the Terraform code will deploy.

Lets touch on 3 Components here;

1. LoadBalancer Health Check:
   The Loadbalancer sends traffic to the Certbot VM on port 80, however for the health check we use Port 22.
   The reason for using Port 22 for the healthcheck is because the LoadBalancer will only pass traffic to the Compute instance if there is a service listening on the port and it gives a valid response, it performs this check at regular intervals. However the service that uses Port 80 is only started when the certbot is executed, it then immediately performs the ACME Challenge which will call Port 80. When the webservice starts, the LoadBalancer will get a valid response on its next health check, however the gap between starting webservice on port 80 and issueing the ACME challenge is too short for the LB to detect a valid backend and therefore the LB will not pass on the the ACME challenge to the backend/Compute instance. Port 22 (SSH) is always running and so the backend will always be healthy, ensuring the ACME Challenge traffic is passed to the Compute instance
2. Service Gateway:
   This is required in order to use the Compute agent plugins, namely Bastion plugin, which will allow us to use the Bastion service
3. Bastion Service:
   The LB Subnet is public, therefore accessible via Internet Gateway. However since the App Subnet is private, we'll be using the Bastion service in order to access the private VMs
4. Web Server:
   This tutorial is about configuring Certbot, so we'll do the Web Server setup behind the scenes via terraform. We'll use cloud-init to setup the web server automatically upon the VM first starting so we don't have to spend time on this.

There's a few parts to performing the Infrastructure setup, the terraform scripts are relatively standard and simple, so we'll touch on some of the interesting parts, but this isn't a terraform tutorial so feel free to skip over this section!

Compute.tf

We'll use cloud-init to run a custom script on the Web Server to automatically configure our Web Service. All we want is a simple html page and a HTTP server running on port 8080 (instead of installing a HTTP server, we'll use the http.server python module to standup a basic python HTTP Service, purely for demo purposes). We can define the script by having the following data resource in terraform

data "template_file" "cloud-config" {
  template = <<YAML
#cloud-config
runcmd:
 - echo 'Starting Setup' >> /tmp/setup.log
 - sudo systemctl stop firewalld
 - mkdir -p /var/www/html
 - wget --output-document=/var/www/html/index.html https://github.com/ShahvaizJanjua/HOC_FREE_SSL_Demo/blob/main/index.html
 - cd /var/www/html
 - nohup python -m http.server 8080 &
YAML
}

To have this initialisation script executed, we base64-encode the data resource and assign it to user_data variable under the metadata block of WebServer oci_core_instance

  metadata = {
    ssh_authorized_keys = file(var.public_key_path)
    user_data = "${base64encode(data.template_file.cloud-config.rendered)}"
  }

Since our VMs are in a private subnet, we'll be using the free Bastion service to access the VMs. In order to do this, the Compute instances require to have the Bastion Plugin enabled, which we can do using the optional agent_config parameter

 agent_config {
        plugins_config {
            desired_state = "ENABLED"
            name = "Bastion"
        }
    }

Network.tf

We require to ensure we have the Service Gateway in our route table for the App Subnet, this is to allow us to enable the Bastion Plugin

resource "oci_core_route_table" "app_rt" {
    compartment_id = oci_identity_compartment.demo.id
    vcn_id = oci_core_vcn.lb_demo_vcn.id
    display_name = "APP_RT"
    route_rules {
        network_entity_id = oci_core_service_gateway.service_gateway.id
        destination = "all-fra-services-in-oracle-services-network"
        destination_type = "SERVICE_CIDR_BLOCK"
    }

    route_rules {
        network_entity_id = oci_core_nat_gateway.nat_gateway.id
        destination = "0.0.0.0/0"
        destination_type = "CIDR_BLOCK"
    }
}

NetworkSecurityGroups.tf

We want to allow incoming traffic to the LB on both ports 80 & 443. We can define both ports in a single resource block instead of having multiple. We do this by using for_each with a set of ports, which are then passed into the source_port_range block using each.key

resource "oci_core_network_security_group_security_rule" "lb_nsg_ingress" {
    network_security_group_id = oci_core_network_security_group.lb_nsg.id
    direction = "INGRESS"
    protocol = 6

    description = "Allow Public Access"
    source = "0.0.0.0/0"
    source_type = "CIDR_BLOCK"
    for_each = toset(["80","443"])

    tcp_options {
        source_port_range {
            max = each.key
            min = each.key
        }
    }
}

We want the LB to be able to communicate to the VMs on their respective ports. We use NSGs of each VM as the destination, which gives us flexibility and avoids hard-coding in IPs. We can use key value pairs in for_each in order to pass the port with its associated destination NSG.

resource "oci_core_network_security_group_security_rule" "lb_nsg_egress" {
    depends_on = [
      oci_core_network_security_group.crtbot_nsg,
      oci_core_network_security_group.websrvr_nsg
    ]
    network_security_group_id = oci_core_network_security_group.lb_nsg.id
    direction = "EGRESS"
    protocol = 6

         for_each = {"80" : oci_core_network_security_group.crtbot_nsg.id,
    "22" : oci_core_network_security_group.crtbot_nsg.id,
     "8080" : oci_core_network_security_group.websrvr_nsg.id}

    description = "Access VMs"
    destination = each.value
    destination_type = "NETWORK_SECURITY_GROUP"
    
    tcp_options {
        destination_port_range {
            max = each.key
            min = each.key
        }
    }
}

Bastion.tf

To create a Bastion session, we first require to provision a Bastion service and specify the target subnet & allows IP address range

resource "oci_bastion_bastion" "bastion" {
    bastion_type = "STANDARD"
    compartment_id = oci_identity_compartment.demo.id
    target_subnet_id = oci_core_subnet.vm_sub.id
    client_cidr_block_allow_list = ["0.0.0.0/0"]
}

In order to use the Bastion Service, we need to ensure that the Bastion Plugin is enabled on the Compute Instance. This takes a short time to instantiate and be detected as running, therefore we want a wait/sleep after provisioning the CertBotVM before we provision the Bastion Session, lets setup a wait/sleep resource that will wait for 5 minutes from when the CertBotVM instance is created.

resource "time_sleep" "wait_5_minutes_for_bastion_plugin" {
  depends_on = [oci_core_instance.CertBotVM]
  create_duration = "5m"
}

We then provision a new Bastion Session, it will depend on the wait resource and as such will wait for 5 minutes from CertBotVM creation before provisioning the Bastion Session.

resource "oci_bastion_session" "session" {
    bastion_id = oci_bastion_bastion.bastion.id
    
    key_details {
        public_key_content = file(var.public_key_path)
    }
    
    target_resource_details {
        session_type = "MANAGED_SSH"
        target_resource_id = oci_core_instance.CertBotVM.id
        target_resource_operating_system_user_name = "opc"
        target_resource_port = "22"
    }

    session_ttl_in_seconds = "10800"
    depends_on = [time_sleep.wait_5_minutes_for_bastion_plugin]
}

NoIP

We first grab a free domain from NoIP.com

Ensure you have added an A record to the DNS on NoIP to point your domain to the public IP of the Load Balancer

Install Certbot

When we run the terraform scripts, it will provide us with the SSH string to be able to connect to the certbot VM via bastion.

Now lets install Certbot

sudo dnf config-manager --enable ol8_developer_EPEL

sudo dnf install snapd -y

sudo setenforce 0
sudo systemctl stop firewalld

sudo ln -s /var/lib/snapd/snap /snap

sudo systemctl enable snapd
sudo systemctl start snapd

sudo snap install --classic certbot

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Install OCI CLI

We'll be using OCI CLI to automatically deploy the new certificate once it is generated and every time it is renewed, so let's install OCI CLI.

sudo dnf install python36-oci-cli -y

oci setup config

Automatic Renewal

Before we obtain our free certificate, lets setup our custom script to auto deploy the certificate to the Load Balancer. In older versions of certbot a cronjob would be required, however now certbot automatically schedules a (systemd) Timer to execute the certbot renew service. You can view this via sudo systemctl list-timers

There's 2 ways of having a script invoked via certbot renewal;

1. Pass in --deploy-hook <script> when running certbot command.
   A config file, named <DOMAIN>.conf will be created in /etc/letsencrypt/renewal. This config file will have an entry pointing to our custom script which will be executed whenever a renewal is run.
2. Place a script in /etc/letsencrypt/renewal-hooks/deploy
   All scripts in here will be automatically executed when certbot executes a succesful certificate renewal

We'll go with option 1. Create a simple script like below

oci lb certificate create \
--load-balancer-id ocid1.loadbalancer.oc1.eu-frankfurt-1.aaaaaaaace2yjn77hmilofdqe5qcjqz5qomgoiekiymjuzjokvk5te6kxl2a \
--wait-for-state SUCCEEDED \
--certificate-name "$RENEWED_DOMAINS-"`date +"%Y-%m-%d"` \
--ca-certificate-file "$RENEWED_LINEAGE/fullchain.pem" \
--private-key-file "$RENEWED_LINEAGE/privkey.pem" \
--public-certificate-file "$RENEWED_LINEAGE/cert.pem"

oci lb listener update --force \
--load-balancer-id ocid1.loadbalancer.oc1.eu-frankfurt-1.aaaaaaaace2yjn77hmilofdqe5qcjqz5qomgoiekiymjuzjokvk5te6kxl2a \
--wait-for-state SUCCEEDED \
--listener-name "Web_Listener" \
--default-backend-set-name "WebBackendSet" \
--port 443 --protocol HTTP2 --cipher-suite-name oci-default-http2-ssl-cipher-suite-v1 \
--ssl-certificate-name "$RENEWED_DOMAINS-"`date +"%Y-%m-%d"`

Obtain Certificate & Automatically Deploy

Now we can generate the SSL certificates

[opc@crtbot ~]# sudo certbot certonly --standalone --deploy-hook /home/opc/lbcertupload.sh
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Please enter the domain name(s) you would like on your certificate (comma and/or
space separated) (Enter 'c' to cancel): [lbdemo.ddns.net](http://lbdemo.ddns.net/)
Requesting a certificate for [lbdemo.ddns.net](http://lbdemo.ddns.net/)

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/lbdemo.ddns.net/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/lbdemo.ddns.net/privkey.pem
This certificate expires on 2023-05-03.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

---

If you like Certbot, please consider supporting our work by:

- Donating to ISRG / Let's Encrypt: [https://letsencrypt.org/donate](https://letsencrypt.org/donate)
- Donating to EFF: [https://eff.org/donate-le](https://eff.org/donate-le)

---

This will retrieve the certificate and execute our custom script which will upload it to OCI and update the Listener to use the new certificate

Lets go to our site and checkout the new certificate in action!

In this article you'll find the full terraform script to spin up & configure the end-2-end architecture, a long with a selective walkthrough of the main terraform code through snippets, finished off with a networking explanation pertaining to the main OCI components

We are effectively using the methodology explained in the Using a DRG to route traffic through a centralized network virtial appliance. The referenced documentation explains the entire setup, the concepts involved and the traffic flow & routing. Our architecture is a slight modification for a scenario requested by a customer, in which traffic from 1 destination follows the referenced flow but other traffic bypasses the centralized network firewall and is routed directly to the end target. The entire setup is done in Terraform. The terraform scripts also mimics customer connectivity (via IPSec tunnel) using Libreswan, all of which the terraform scripts configure with the help of Ansible, but more on that later.

GitHub - ShahvaizJanjua/HOC_DRG-NFW-TF-Demo

Contribute to ShahvaizJanjua/HOC_DRG-NFW-TF-Demo development by creating an account on GitHub.

GitHubShahvaizJanjua

We'll cover the following;

1. Architecture
2. OCI Networking Concepts
3. Terraform scripts involved
4. Terraform code walkthrough
5. Traffic Flow & Route Table Explanation (Bonus)

Architecture

Our setup has the following components & requirements;

1. Hub VCN, containing an OCI Network Firewall
2. A Spoke VCN which has the customer OCI workload, represented through a single Compute Instance
3. 2 separate IPSec tunnels, each connecting to a different site
4. All traffic from Workload VM to 'On-Premise" site must pass through the firewall via the DRG and then be routed to the DRG and down the IPSec tunnel for 'On-Premises' and vice versa - represented with the blue highlight
5. All traffic from Workload VM to 'Multicloud' site will go directly to the 'Multicloud' IPSec tunnels via the DRG, bypassing the Network Firewall - represented with the green highlight
6. 'On-Premises' and 'Multicloud' sites are represented by the following setup;
   VCN created for each site, containing 2 subnets. 1 Subnet for the CPE and 1 Subnet to represent customer workload/vm's
   CPE is represented via Libreswan, a free IKE implementation for Linux, which is installed on a Compute Instance
7. Traffic Logging enablement for Network Firewall to confirm the required traffic is passing through the firewall

OCI Networking Concepts

Lets take a look at a couple of OCI Networking Concepts;

DRG Attachment;

Connects the Dynamic Routing Gateway to either a; Virtual Cloud Network, Virtual Circuit, IPSec or Remote Peering Connection. The DRG attachment allows the DRG to send traffic and receive traffic to & fro the given attached resource.

Every DRG attachment has a DRG Route Table associated with it. This DRG Route Tables Rules are used to route traffic incoming to the DRG from the other end of the attachment (e.g. the IPSec in an IPSec Attachment).

VCN attachments can have 2 Route Tables; 1 DRG Route Table for traffic incoming to the DRG from the VCN, 1 VCN Route Table for traffic incoming to the VCN from the DRG (this differs from normal use of VCN Route Tables which route traffic leaving the Subnet)

Dynamic Route Import Distribution

Before understanding Dynamic Route Import Distributions, it is important to note that a DRG Route Table contains both Static Routes and Dynamic Routes. Static Routes Rules are manually added by us; however a Static Route can only have a Virtual Cloud Network, Remote Peering Connection or Cross-Tenancy as its next hop. So in order to route traffic to IPSecs or Virtual Circuits we require to produce the rules dynamically, which is where Dynamic Route Import Distributions comes into play.

An Import Route Distribution is associated with a DRG Route Table. It contains a set of statements which are criteria's from which DRG attachments to use to populate the dynamic route rules in the DRG route table. When an DRG attachment matches the criteria, all routes associated with the attachments are dynamically imported into the DRG Route Table; for example for a Virtual Circuit all routes advertised using BGP will be imported into the DRG Route Table with the next hop as the DRG attachment (i.e. the Virtual Circuit). The match criteria can be;

1. Match All
2. Attachment Type - in which you specify the attachment type such as Virtual Circuit - results in all IPs advertised over BGP in ALL Virtual Circuits being dynamically added to the DRG Route Table
3. Attachment - in which you specify an individual Attachment, such as a single Virtual Circuit - results in only the IPs advertised over BGP for that specific Virtual Circuit to be dynamically added to the DRG Route Table

Terraform Scripts

Before we dive into the code, lets take a very quick high level look at the scripts;

• Variables.tf - Holds all of our variables; Network CIDRs default values set, can be modified as desired
• Terraform.tfvars - To be populated, variables pertaining to terraform OCI authentication and keys
• Compartments.tf - Holds the OCI provider block and creation of compartment under root compartment
• Data.tf - Holds all Data Sources
• Networking.tf - Setups all networking elements except DRG & IPSec tunnels - i.e. VCNs, Subnets, VCN Route tables, Default Security List modification, Internet Gateway
• NetworkFirewall.tf - Creation of OCI Network Firewall Policy & OCI Network Firewall
• Logging.tf - Enable Traffic Logs to be collected from Network Firewall
• Compute.tf - Creation of OnPrem CPE/Librewan, OnPrem Workload VM, Multicloud CPE/Librewan, Multicloud Workload VM, Spoke (OCI Workload) VM
• DRG.tf - Creation of DRG, DRG Route Tables, DRG Route Table Import Distribution & DRG Attachments
• IPSec.tf - Creation of CPEs & IPSecs. Updating; IPSec Tunnels Interface IPs & IPSec Tunnel attachments DRG Route Table
• LibreswanSetup.tf - Ansible integration to execute ansible playbook to setup Libreswan configuration
• Ansible-vars.tf - Dynamically populate .yml file containing all of the values required by Libreswan config files
• /ansible/multicloud-libswan.yml & /ansible/onprem-libreswan.yml - Ansible scripts to; Install Libreswan, upload Libreswan config files, modify kernel parameters, start Libreswan, configure static routing
• /ansible/multicloud-libreswan.j2 & /andible/onprem-libreswan.j2 - Libreswan config file, populated from the file created dynamically by Ansible-vars.tf
• /ansible/multicloud-libreswan_secrets - IPSec tunnels shared secret, populated from the file created dynamically by Ansible-vars.tf
• vpn_vars not needed, add values to ansible-vars.tf, remove reference from .yml and delete

Terraform Code

Lets get into the Code;

Networking.tf

Creation of VCNs, Subnets, Internet Gateway and population of Route Tables and Security Lists are quite straightforward. Ideally we would utilise Network Security Groups, but for the purposes of this Customer Demonstration we simply used the default Security Lists and opened them up to the world.

resource "oci_core_default_security_list" "spoke_default_sl" {
    manage_default_resource_id = oci_core_vcn.spoke_vcn.default_security_list_id
    compartment_id = oci_identity_compartment.demo.id

   ingress_security_rules {
    protocol = "all"
    source = "0.0.0.0/0"
   }

    egress_security_rules {
    protocol = "all"
    destination = "0.0.0.0/0"
   }
}

You can modify the rules for the default security list by using the manage_default_resource_id. The default security list id is an attribute of a VCN resource, so we can obtain it directly from our VCN resource via oci_core_vcn.spoke_vcn.default_security_list_id

Default Route table follows the same premise;

resource "oci_core_default_route_table" "multicloud_default_route_table" {
    manage_default_resource_id = oci_core_vcn.multicloud_vcn.default_route_table_id
    display_name = "Default Route Table"

    route_rules {
        network_entity_id = oci_core_internet_gateway.multicloud_igw.id
        destination = "0.0.0.0/0"
        destination_type = "CIDR_BLOCK"
    }
}

Compute.tf

Compute Resource is also quite straight forward, the only interesting part is obtaining the Image ID which needs to be given in the source_details attribute of Compute resource

  source_details {
    source_type = "image"
    source_id   = data.oci_core_images.os.images[0].id
  }

As you can see the Image ID is obtained from a Data Source, which gives us a list of images and we simply select the first element in the list. So lets take a look at the data source that this references

data "oci_core_images" "os" {
  compartment_id           = oci_identity_compartment.demo.id
  operating_system = "Oracle Linux"
  operating_system_version = "8"

  shape                    = "VM.Standard.E4.Flex"
  sort_by                  = "TIMECREATED"
  sort_order               = "DESC"
}

We use the oci_core_images Data Source and specify the shape of our Compute to ensure we only get images compatible with our shape. We also want Oracle Linux 8 so we populate operating system details and are ordering by the newest created image.

We need to specify Public Key for SSH

  metadata = {
    ssh_authorized_keys = file(var.public_key_path)
  }

We do this by referencing the variable that holds the path to our Public Key file and telling it that it is a file.

DRG.tf

The DRG setup is mostly also straight forward, we require to do the following;

1. Create Dynamic Routing Gateway
2. Create DRG Route Tables
3. Create DRG Route Table Rules (to populate DRG Route Tables)
4. Create Import Route Distribution
5. Create Import Route Distribution Statements (to populate Import Route Distribution)
6. Create DRG VCN attachments

resource "oci_core_drg_route_table_route_rule" "drg_multicloud_ipsec_rt_rule" {
    drg_route_table_id = oci_core_drg_route_table.drg_multicloud_ipsec_rt.id
    destination = oci_core_vcn.spoke_vcn.cidr_block
    destination_type = "CIDR_BLOCK"
    next_hop_drg_attachment_id = oci_core_drg_attachment.spoke_drg_attachment.id
}

For the rule, we specify the DRG Route Table ID for which the Rule is for, and then the Destination Type, followed by the Destination address and what the next hop is. Lets take a look at populating our Import Route Distribution; as with DRG Route Tables, you create the Import Route Distribution via a resource and then populate it via a separate Import Route Distribution Statement resource

resource "oci_core_drg_route_distribution_statement" "drg_hub_route_distribution_statement" {
    drg_route_distribution_id = oci_core_drg_route_distribution.drg_hub_route_distribution.id
    action = "ACCEPT"

    match_criteria {
        match_type = "DRG_ATTACHMENT_TYPE"

        attachment_type = "IPSEC_TUNNEL"
    }
    priority = 1
}

We cannot have overlapping priorities so it is important that each statement has a unique priority number. Here we are specifying DRG_ATTACHMENT_TYPE meaning all the advertised (or static) addresses of that attachment type will be imported, irrespective of how many of those attachments there are (i.e. this will import route rules for ALL IPSec Tunnels). To specify it for only a single tunnel we can use DRG_ATTACHMENT_ID and specify the actual ID, as below;

resource "oci_core_drg_route_distribution_statement" "drg_spoke_route_distribution_statement1" {
    drg_route_distribution_id = oci_core_drg_route_distribution.drg_spoke_route_distribution.id
    action = "ACCEPT"

    match_criteria {
        match_type = "DRG_ATTACHMENT_ID"

        attachment_type = "IPSEC_TUNNEL"
        drg_attachment_id = oci_core_drg_attachment_management.multicloud_ipsec_attachment_tunnel_a.id
    }
    priority = 1
}

Creating a DRG Attachment in order to attach DRG to VCN is straightforward

resource "oci_core_drg_attachment" "hub_drg_attachment" {
  drg_id             = oci_core_drg.drg.id
  display_name       = "Hub-VCN-Attachment"
  drg_route_table_id = oci_core_drg_route_table.drg_hub_rt.id

  network_details {
    id             = oci_core_vcn.hub_vcn.id
    type           = "VCN"
    route_table_id = oci_core_route_table.hub_vcn_ingress_rt.id
  }
}

IPSec.tf

The creation of CPE & IPSec Connection itself is straight forward

resource "oci_core_ipsec" "onprem_ipsec_connection" {
  compartment_id = oci_identity_compartment.demo.id
  cpe_id         = oci_core_cpe.onprem_cpe.id
  drg_id         = oci_core_drg.drg.id
  static_routes  = [oci_core_vcn.onprem_vcn.cidr_block]

  cpe_local_identifier      = oci_core_instance.onprem_libreswan.public_ip
  cpe_local_identifier_type = "IP_ADDRESS"
  display_name = "OnPrem-IPSec"
}

We're using Static Routing for the IPSec connection, as opposed to BGP dynamic routing or policy-based routing. Hence we populate static_routes for each IPSec connection, the value simply being our OnPremise IP address range

In order to update the default tunnel name and specify the tunnel interface IPs, we require to use the oci_core_ipsec_connection_tunnel_management resource

resource "oci_core_ipsec_connection_tunnel_management" "onprem_ipsec_tunnel_management_a" {
  ipsec_id  = oci_core_ipsec.onprem_ipsec_connection.id
  tunnel_id = data.oci_core_ipsec_connection_tunnels.onprem_ipsec_tunnels.ip_sec_connection_tunnels[0].id
  depends_on = [data.oci_core_ipsec_connections.onprem_ipsec_connections]

   bgp_session_info {
        customer_interface_ip = "10.10.10.1/30"
        oracle_interface_ip = "10.10.10.2/30"
    }

  display_name  = "OnPrem-IPSec-tunnel-a"
  routing       = "STATIC"
  ike_version   = "V1"
}

We require a separate resource for each of the 2 tunnels, hence why this resource is called onprem_ipsec_tunnel_management_a, as we have b for the second tunnel

We also need to attach the DRG Route Table to the IPSec DRG attachment

resource "oci_core_drg_attachment_management" "onprem_ipsec_attachment_tunnel_a" {
  attachment_type = "IPSEC_TUNNEL"
  compartment_id = oci_identity_compartment.demo.id
  network_id = data.oci_core_ipsec_connection_tunnels.onprem_ipsec_tunnels.ip_sec_connection_tunnels.0.id
  drg_id = oci_core_drg.drg.id
  display_name = "drg-ipsec-onprem-attachment-tunnel-a"
  drg_route_table_id = oci_core_drg_route_table.drg_onprem_ipsec_rt.id
}

This needs to be done for each tunnel

NetworkFirewall.tf & Logging.tf

In order to create a Network Firewall, we first require to create a Network Firewall Policy

resource "oci_network_firewall_network_firewall_policy" "network_firewall_policy" {
    compartment_id = oci_identity_compartment.demo.id
    display_name = "Demo-Network-Firewall-Policy"
    security_rules {
        action = "ALLOW"
        condition {}
        name = "Allow-All-Traffic"
    }
}

Our policy is very straight forward, it has a Security Rule of Allow with no condition; i.e. unconditionally allow all traffic.

resource "oci_network_firewall_network_firewall" "network_firewall" {
    compartment_id = oci_identity_compartment.demo.id
    network_firewall_policy_id = oci_network_firewall_network_firewall_policy.network_firewall_policy.id
    subnet_id = oci_core_subnet.hub_sub.id
    display_name = "Demo-Network-Firewall"
}

We can then create our Network Firewall and pass it our Network Firewall Policy ID

We want to enable Traffic Logging for our Network Firewall so we can view the traffic flowing through our Network Firewall. First we must create a Log Group which will contain our Traffic Log

resource "oci_logging_log_group" "log_group" {
    compartment_id = oci_identity_compartment.demo.id
    display_name = "DemoLoggingGroup"
}

Now we can create and enable our Traffic logging

resource "oci_logging_log" "NFW_Log" {
    display_name = "Demo_NetworkFirewall_Log"
    log_group_id = oci_logging_log_group.log_group.id
    log_type = "SERVICE"
    configuration {
        source {
            category = "trafficlog"
            resource = oci_network_firewall_network_firewall.network_firewall.id
            service = "ocinetworkfirewall"
            source_type = "OCISERVICE"
        }
        compartment_id = oci_identity_compartment.demo.id
    }
    is_enabled = true
    retention_duration = 90
}

On-Premise & MultiCloud Setup

The On-Premise and MultiCloud sites have the same architecture, which is the one shown below.

The routing is straight forward, the route table for On-Prem CPE/VPN subnet has all traffic going to Internet Gateway (traffic destined for Workload VM will automatically be routed there, no explicit firewall rules are required). The route table for Workload VM however will force all traffic destined to the OCI Site (Spoke VCN) to the CPE/VPN, which in turn will send the traffic through the DRG/Site-to-Site tunnels via the Internet Gateway.

For the VPN/CPE Subnets route table, we simply use the default route table;

resource "oci_core_default_route_table" "onprem_default_route_table" {
    manage_default_resource_id = oci_core_vcn.onprem_vcn.default_route_table_id
    display_name = "Default Route Table"
    route_rules {
        network_entity_id = oci_core_internet_gateway.onprem_igw.id
        destination = "0.0.0.0/0"
        destination_type = "CIDR_BLOCK"
    }
}

For the Workload VMs Subnet we create a new route table and specify a rule to ensure all traffic destined for the Spoke VCN is sent to the CPE/VPN VM

resource "oci_core_route_table" "onprem_wl_rt" {
    compartment_id = oci_identity_compartment.demo.id
    vcn_id = oci_core_vcn.onprem_vcn.id
    display_name = "OnPrem_Priv_RT"
   route_rules {
        network_entity_id = data.oci_core_private_ips.onprem_libreswan_private_ip.private_ips[0].id
        destination = oci_core_vcn.spoke_vcn.cidr_block
        destination_type = "CIDR_BLOCK"
    }
    route_rules {
        network_entity_id = oci_core_internet_gateway.onprem_igw.id
        destination = "0.0.0.0/0"
        destination_type = "CIDR_BLOCK"
    }
}

Now we move onto configuring the VPN/CPE/Libreswan via Ansible

All of the VM and Libreswan configuration is done via Ansible. How do we execute ansible from terraform ? Quite simple, we use the local-exec provisioner to execute the ansible script on the CPE/VPN VM from our terraform host, by giving it the SSH details and the ansible script that needs to be executed. However if we simply do local-exec it will try and execute this before the VM is ready, so we use remote-exec to first ensure we can establish an SSH session

resource "null_resource" "onprem-libreswan-config" {
  depends_on = [local_file.ansible-libreswan-vars]
  provisioner "remote-exec" {
    inline = ["echo About to run Ansible on LIBRESWAN and waiting!"]
    connection {
      host        = "${oci_core_instance.onprem_libreswan.public_ip}"
      type        = "ssh"
      user        = "opc"
      private_key = file(var.private_key_path)
    }
  }
  provisioner "local-exec" {
    command = "sleep 30; ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -u opc -i '${oci_core_instance.onprem_libreswan.public_ip},' --private-key '${var.private_key_path}' ./ansible/onprem-libreswan.yml"
  }
}  

From the above we can gather that the ansible script to be executed is onprem-libreswan.yml and resides in a folder called ansible. Let's take a look at this script one bit at a time

- hosts: all
  become: yes
  vars_files:
    - ./vpn_vars/onprem-tunnel.yml
    - ../ansible-libreswan-vars.yml

  tasks:

We specify the host this is being executed on, any files containing required variables, followed by the series of tasks to be performed on the host

 - name: install libreswan
    yum:
      name: libreswan
      state: installed 

The first task is straight forward, install Libreswan

  - name: write the vpn config file
    template: src=onprem-libreswan.j2 dest=/etc/ipsec.d/oci-vpn-tunnels.conf
    become: yes

  - name: write the vpn secrets file
    template: src=onprem_libreswan_secrets.j2 dest=/etc/ipsec.d/oci-vpn-secrets.secrets
    become: true

Next we copy over the required configuration files for Libreswan, we'll take a look at how we dynamically create this configuration very soon, but first the remaining ansible tasks

- name: Enable Ibr_netfilter IPv4
    copy:
      dest: /etc/sysctl.conf
      content: |
        net.ipv4.ip_forward = 1
        net.ipv4.conf.default.rp_filter = 0
        net.ipv4.conf.all.rp_filter = 0
        net.ipv4.conf.all.send_redirects = 0
        net.ipv4.conf.default.send_redirects = 0
        net.ipv4.icmp_ignore_bogus_error_responses = 1
        net.ipv4.conf.default.log_martians = 0
        net.ipv4.conf.all.log_martians = 0
        net.ipv4.conf.default.accept_source_route = 0
        net.ipv6.conf.default.accept_source_route = 0
        net.ipv4.conf.all.accept_redirects = 0
        net.ipv6.conf.all.accept_redirects = 0
        net.ipv4.conf.default.accept_redirects = 0
        net.ipv6.conf.default.accept_redirects = 0
    
  - name: Apply Persistent IPv4 Forwarding
    shell: sudo sysctl -p

  - name: Disable Selinux
    shell: sudo setenforce 0

  - name: Disable Firewalld
    shell: sudo systemctl stop firewalld

  - name: ensure ipsec is running
    service: name=ipsec state=started
    become: yes

  - name: Apply Persistent IPSEC connection
    shell: systemctl enable ipsec.service
    become: yes

Next we enable IP forwarding, as well as modifying some kerner parameters.

We disable Selinux, firewalld and start libreswan/ipsec

  - name: Configure Hub Static Route
    shell: sudo ip route add {{ oci_hub_cidr }} nexthop dev vti1 nexthop dev vti2

  - name: Configure Spoke Static Route
    shell: sudo ip route add {{ oci_spoke_cidr }} nexthop dev vti1 nexthop dev vti2

We then add static routing such that all traffic destined to OCI (Hub VCN & Spoke VCN) passes through the Virtual Tunnel Interface's

Libreswan has 2 main files, 1 is for the IPSec configuration and the 2nd holds the Shared Secret for the Site-to-Site VPN Tunnels. The ansible yml code we saw previously is copying these 2 files from your terraform host server to the CPE/VPN VMs. Let's take a look at the 2 files;

conn {{ onprem_conn_name_tunnel1 }}
     authby=secret
     pfs=yes
     left={{ onprem_cpe_local_ip }}
     leftid={{ onprem_cpe_public_ip }}
     leftsubnet=0.0.0.0/0
     leftnexthop=%defaultroute
     right={{ onprem_oci_tunnel1_headend }}
     rightid={{ onprem_oci_tunnel1_headend }}    
     rightsubnet=0.0.0.0/0
     mark=5/0xffffffff # Needs to be unique across all tunnels
     vti-interface=vti1
     vti-routing=no
     leftvti={{ onprem_tunnel1_leftvti }}
     ikev2=no # To use IKEv2, change to ikev2=insist
     ike=aes_cbc256-sha2_384;modp1536
     phase2alg=aes_gcm256;modp1536
     encapsulation=yes
     ikelifetime=28800s
     salifetime=3600s
     auto=start
conn {{ onprem_conn_name_tunnel2 }}
     authby=secret
     pfs=yes
     left={{ onprem_cpe_local_ip }}
     leftid={{ onprem_cpe_public_ip }}
     leftsubnet=0.0.0.0/0
     leftnexthop=%defaultroute
     right={{ onprem_oci_tunnel2_headend }}
     rightid={{ onprem_oci_tunnel2_headend }}    
     rightsubnet=0.0.0.0/0
     mark=6/0xffffffff # Needs to be unique across all tunnels
     vti-interface=vti2
     vti-routing=no
     leftvti={{ onprem_tunnel2_leftvti }}
     ikev2=no # To use IKEv2, change to ikev2=insist
     ike=aes_cbc256-sha2_384;modp1536
     phase2alg=aes_gcm256;modp1536
     encapsulation=yes
     ikelifetime=28800s
     salifetime=3600s
     auto=start

This is the basic configuration file for Libreswan. Here we are setting up 2 IPSec tunnels, connecting to 2 Public IPs which connect to a single DRG.

The source secrets file which holds the Shared Secret for each tunnel looks like this

{{ onprem_cpe_public_ip }} {{ onprem_oci_tunnel1_headend }} : PSK "{{ onprem_shared_secret_psk1 }}"
{{ onprem_cpe_public_ip }} {{ onprem_oci_tunnel2_headend }} : PSK "{{ onprem_shared_secret_psk2 }}"

As you can see there are variables for the actual values; this allows us to dynamically create the configuration based on our specific implementation as whenever you run the terraform and provision new resources we'll have a new set of Public IPs, Private IPs, Shared Secret Keys, IPSec Headend IPs etc. So how do we define these variables ?

ansible-vars.tf

We dynamically create a new file containing our variable names and their values. The values are extracted from either the terraform resources we create or the data sources that we define

resource "local_file" "ansible-libreswan-vars" {
  content = <<-DOC
    # Ansible vars_file containing variable values from Terraform.
    # Generated by Terraform mgmt configuration.
    onprem_cpe_local_ip: ${oci_core_instance.onprem_libreswan.private_ip}
    onprem_cpe_public_ip: ${oci_core_instance.onprem_libreswan.public_ip}
    onprem_oci_tunnel1_headend: ${data.oci_core_ipsec_connection_tunnels.onprem_ipsec_tunnels.ip_sec_connection_tunnels[0].vpn_ip}
    onprem_oci_tunnel2_headend: ${data.oci_core_ipsec_connection_tunnels.onprem_ipsec_tunnels.ip_sec_connection_tunnels[1].vpn_ip}
    onprem_shared_secret_psk1: ${data.oci_core_ipsec_config.onprem_ipsec_config.tunnels[0].shared_secret}
    onprem_shared_secret_psk2: ${data.oci_core_ipsec_config.onprem_ipsec_config.tunnels[1].shared_secret}
    multicloud_cpe_local_ip: ${oci_core_instance.multicloud_libreswan.private_ip}
    multicloud_cpe_public_ip: ${oci_core_instance.multicloud_libreswan.public_ip}
    multicloud_oci_tunnel1_headend: ${data.oci_core_ipsec_connection_tunnels.multicloud_ipsec_tunnels.ip_sec_connection_tunnels[0].vpn_ip}
    multicloud_oci_tunnel2_headend: ${data.oci_core_ipsec_connection_tunnels.multicloud_ipsec_tunnels.ip_sec_connection_tunnels[1].vpn_ip}
    multicloud_shared_secret_psk1: ${data.oci_core_ipsec_config.multicloud_ipsec_config.tunnels[0].shared_secret}
    multicloud_shared_secret_psk2: ${data.oci_core_ipsec_config.multicloud_ipsec_config.tunnels[1].shared_secret}
    oci_hub_cidr: ${oci_core_vcn.hub_vcn.cidr_block}
    oci_spoke_cidr: ${oci_core_vcn.spoke_vcn.cidr_block}
    DOC
  filename = "./ansible-libreswan-vars.yml"

We also have another file which contains the tunnels inside IPs a long with some other required information (FYI, we could add these variables to our script above and then have a single file)

---
#Name for the VPN Connetion
onprem_conn_name_tunnel1: oci-tunnel1
onprem_conn_name_tunnel2: oci-tunnel2

#Connection settings
onprem_tunnel1_cidr: "10.10.10.1/30"
onprem_tunnel2_cidr: "10.10.10.5/30"
onprem_left: "{{ onprem_cpe_local_ip }}"
onprem_tunnel1_right: "{{ onprem_oci_tunnel1_headend }}"
onprem_tunnel2_right: "{{ onprem_oci_tunnel2_headend }}"
onprem_vti1: "vti1"
onprem_vti2: "vti2"
onprem_oci_vcn_cidr: "{{ onprem_oci_vcn_cidr }}"
onprem_tunnel1_leftvti: "10.10.10.1/30"
onprem_tunnel2_leftvti: "10.10.10.5/30"
#PSK to be used. 
onprem_vpn_psk1: "{{ onprem_shared_secret_psk1 }}"
onprem_vpn_psk2: "{{ onprem_shared_secret_psk2 }}"

Traffic Flow

With all of that covered, let's now take a look at the actual traffic flow by looking at each hope, the route table involved and the route rule for our traffic.

We'll look at the perspective of traffic coming from our Workload VM and going to our Site-to-Site VPNs.

To On-Premise (via Network Firewall)

On-Premise Network has a CIDR of 172.0.0.0/16

When trying to access On-Premise Site from the Workload VM, the route table in play first is the VCN Route Table associated with the subnet. In here we specify what traffic we want to go where; in this case we want the On-Premise CIDR (Destination) to go to the Demo-DRG, which is the next hop

Now that the traffic is being passed to the DRG, we need to instruct the DRG where to pass the traffic to. The Route Table in play here is the DRG Route Table associated with this specific DRG Attachment.

The next hop in this route tables rule is the Hub VCN which is accessed via a DRG Attachment, which is why the Target Type is VCN and the Target is the Hub VCN DRG Attachment

The traffic is now being passed to the Hub VCN via the DRG Attachment. The Route Table in play is the VCN Route Table associated with the DRG Attachment connecting the Hub VCN and DRG. The Route Rule for our traffic is to the Private IP of the Network Firewall.

The traffic has passed through the Network Firewall, which has hopefully allowed the traffic through, so the Route Table in play now is the VCN Route Table associated with the subnet (in our case, the VCNs default route table). The Route Rule for our traffic sends the traffic to the DRG.

Now that the traffic is being sent to the DRG from the VCN, the Route Table in play is now the DRG Route Table associated with the DRG Attachment which connects the Hub VCN to the DRG.

The Route Rule targeting our traffic sends the traffic to the On-Premise IPSec, which will reach the On-Premise CPE. This Route Rule cannot be created manually (statically), instead it is done dynamically by using the Import Route Distribution associated with the DRG Route Table.

This has been explained in the Dynamic Route Import Distribution section

To Multicloud (bypassing Network Firewall)

The traffic to Multicloud Site follows a much simpler path!

Traffic from our Workload VM in the Spoke VCN, to the Multicloud site, is given its first hop by the VCN Route Table associated with our subnet (in our case, the VCN default route table). The route rule tells all traffic destined for Multicloud to be sent to the DRG.

Once the traffic hits the DRG, the Route Table in play is the DRG Route Table associated with the DRG Attachment which connects the Spoke VCN to the DRG.

The route rule in this table tells the traffic that the next hop is the IPSec tunnel. As mentioned previously, this particular rule for IPSec is dynamically populated using the Import Route Distribution.

In this updated article we'll walkthrough the steps to create a free blog hosted on Oracle Cloud Infrastructure, utilising Oracle's very generous Ampere A1 instance which gives you 4 OCPUs (8 Threads) & 24GB RAM for FREE. We'll be also be using the Always Free Network Load Balancer & Bastion Service. We'll first have a very short introduction into the various components involved in this setup, then look at the process and start getting to work! Feel free to skip the theory and jump to whatever section you're interested in.

Components Involved:

• OCI - Network Load Balancer
• OCI - A1 Ampere Compute Instance
• OCI - Bastion Service
• OCI - Other Core Networking (VCN, Subnet, Internet & NAT Gateway etc)
• Ghost
• Lets Encrypt
• NoIP

Explanation of some Components Involved:

Oracle Cloud Infrastructure

Oracle Cloud Free Tier offers Always Free services, which includes a Compute VM which we'll use to host our free website

OCI - Network Load Balancer

Network Load Balancer provides the benefits of flow high availability, source and destination IP addresses, and port preservation. It is designed to handle volatile traffic patterns and millions of flows, offering high throughput while maintaining ultra low latency. Network load balancers have a default 1 million concurrent connection limit. Network Load Balancer is the ideal load balancing solution for latency sensitive workloads.

Ghost

Ghost is a free, opensource and simple web application from which you can create and manage your blog and contents. It has the combined advantage of automatically configuring nginx as a reverse proxy and for HTTPS, as well as obtaining the SSL Certificate and making a crontab entry to automatically renew these certificates.

Let's Encrypt

Let's Encrypt is a free, opensource and automated Certificate Authority. Let's Encrypt offer FREE SSL/TLS Certificates! They are only valid for 90 days, but can simply be renewed.

NoIP

NoIP offer free hostnames under select few domains, they also provide you with complete control over the DNS records for that hostname, so we can the website address directly to our Free OCI VM

Process

The process itself is quite straight forward. First we'll setup the underlying infrastructure in OCI to support the provisioning of our Free VM. We'll then Create and Configure the domain and DNS and point it to our OCI VM (This must be done before configuring Ghost in order to obtain and configure SSL Certs). We'll then finish up by installing Ghost!

Architecture

The architecture is quite straight forward. We have a Public Subnet and a Private Subnet. The Network Load Balancer, which resides in the Public Subnet and has a Public IP, will receive HTTPS traffic from Public Internet and will direct it to the Private Compute instance, inside the Private Subnet, hosting our blogging software.

The Compute Instance in a Private Subnet is not directly accessible via Public Internet, for security reasons. The Compute Instance can however talk out to the internet via NAT Gateway in order to obtain required software and updates. We'll utilise the free Bastion Service to access the private Compute Instance to perform our admin tasks.

If you don't already have an OCI tenancy then go and grab your Always Free account...

Create Networking

To speed things a long we'll use the Network Wizard; which we can select from the Launch resources window in Get Started tab in the Home Screen

• Ensure "Create VCN with Internet Connectivity" is selected
• Click "Start VCN Wizard"

Fill in all of the information pertaining to our VCN setup

Review the Networking Information, Click "Create"

Networking Resources will be provisioned and can be viewed once Provisioning is completed

Update Security Rules

When viewing the VCN, navigate through the following;

• Click "Security Lists" under "Resources"
• Click on the private subnet security list
• Select first line (with TCP Protocol & Destination Port 22)
• Click Edit

• Append Destination Port Range with ",443,80"
• Click Save changes

Create Compute Instance

Select Create VM from the Launch resources window in Get Started tab in the Home Screen, then fill out the VM configuration information;

• Change the image to Canonical Ubuntu 20.04
• Change the shape VM.Standard.A1.Flex with 4 OCPUs & 24 GB memory
• Ensure you select the private subnet for the Subnet of the Primary VNIC

Create Network Load Balancer

Select "Set up a load balancer" from the Launch resources window in Get Started tab in the Home Screen

Click "Create network load balancer" populate the require information

Create Bastion

Click on the Hamburger symbol on the top left of the console.
Under "Identity & Security", click "Bastion" and then "Create Bastion"

Provide a name and select the VCN and private Subnet, allow 0.0.0.0/0 or your computers public IP/32 in the CIDR allowlist

Once the Bastion service is created, click on the service and click "Create session"

provide a username, select the compute instance we created and upload an SSH key

Once the session is created, copy the SSH command

Save this command

ssh -i <privateKey> -N -L <localPort>:10.0.1.222:22 -p 22 ocid1.bastionsession.oc1.eu-frankfurt-1.amaaaaaaztrrnmqaba365sr2ckqrmedj3gxuazdlprxexfxvtacjhej2dxda@host.bastion.eu-frankfurt-1.oci.oraclecloud.com

Create & Configure Domain

Head over to https://www.noip.com/ and grab your free domain

Create an A record for your domain

Install Ghost

Connect to VM

Let's look at the SSH command we copied

ssh -i <privateKey> -N -L <localPort>:10.0.1.222:22 -p 22 ocid1.bastionsession.oc1.eu-frankfurt-1.amaaaaaaztrrnmqaba365sr2ckqrmedj3gxuazdlprxexfxvtacjhej2dxda@host.bastion.eu-frankfurt-1.oci.oraclecloud.com

All we need to do to setup an SSH tunnel is give it the private key location and a local port. Execute this command

ssh -i sjanjua_rsa.ppk -N -L 9500:10.0.1.222:22 -p 22 ocid1.bastionsession.oc1.eu-frankfurt-1.amaaaaaaztrrnmqaba365sr2ckqrmedj3gxuazdlprxexfxvtacjhej2dxda@host.bastion.eu-frankfurt-1.oci.oraclecloud.com

You can then SSH into them

ssh ubuntu@localhost -p 9500

Ghost Setup

Now let's start with the Ghost setup installation.

sudo apt upgrade
sudo apt update

sudo iptables -I INPUT 5 -p tcp --dport 80 -j ACCEPT
sudo iptables -I INPUT 5 -p tcp --dport 443 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

sudo adduser ghostusr
sudo usermod -aG sudo ghostusr
sudo su - ghostusr

sudo apt install cron
sudo apt-get install nginx
sudo apt-get install mysql-server
sudo apt-get install build-essential

sudo mysql

alter user 'root'@'localhost' identified with mysql_native_password by 'oracle99';
quit;

curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash
sudo apt-get install -y nodejs

sudo npm install ghost-cli@latest -g

sudo mkdir -p /var/www/ghost
sudo chown ghostusr:ghostusr /var/www/ghost
sudo chmod 775 /var/www/ghost
cd /var/www/ghost

Run the Ghost installation. You'll need to provide the URL, mysql details and an email address.

Answer Yes to all responses

ghost install 
✔ Checking system Node.js version - found v14.20.0
✔ Checking logged in user
✔ Checking current folder permissions
✔ Checking system compatibility
✔ Checking for a MySQL installation
✔ Checking memory availability
✔ Checking free space
✔ Checking for latest Ghost version
✔ Setting up install directory
✔ Downloading and installing Ghost v5.12.0
✔ Finishing install process
? Enter your blog URL: https://highoncloud.ddns.net
? Enter your MySQL hostname: localhost
? Enter your MySQL username: root
? Enter your MySQL password: [hidden]
? Enter your Ghost database name: ghostdb
✔ Configuring Ghost
✔ Setting up instance
+ sudo chown -R ghost:ghost /var/www/ghost/content
✔ Setting up "ghost" system user
? Do you wish to set up "ghost" mysql user? Yes
✔ Setting up "ghost" mysql user
? Do you wish to set up Nginx? Yes
+ sudo mv /tmp/highoncloud-ddns-net/highoncloud.ddns.net.conf /etc/nginx/sites-available/highoncloud.ddns.net.conf
+ sudo ln -sf /etc/nginx/sites-available/highoncloud.ddns.net.conf /etc/nginx/sites-enabled/highoncloud.ddns.net.conf
+ sudo nginx -s reload
✔ Setting up Nginx
? Do you wish to set up SSL? Yes
? Enter your email (For SSL Certificate) sjspm1@gmail.com
+ sudo /etc/letsencrypt/acme.sh --upgrade --home /etc/letsencrypt
+ sudo /etc/letsencrypt/acme.sh --issue --home /etc/letsencrypt --server letsencrypt --domain highoncloud.ddns.net --webroot /var/www/ghost/system/nginx-root --reloadcmd "nginx -s reload" --accountemail sjspm1@gmail.com
+ sudo openssl dhparam -dsaparam -out /etc/nginx/snippets/dhparam.pem 2048
+ sudo mv /tmp/ssl-params.conf /etc/nginx/snippets/ssl-params.conf
+ sudo mv /tmp/highoncloud-ddns-net/highoncloud.ddns.net-ssl.conf /etc/nginx/sites-available/highoncloud.ddns.net-ssl.conf
+ sudo ln -sf /etc/nginx/sites-available/highoncloud.ddns.net-ssl.conf /etc/nginx/sites-enabled/highoncloud.ddns.net-ssl.conf
+ sudo nginx -s reload
✔ Setting up SSL
? Do you wish to set up Systemd? Yes
+ sudo mv /tmp/highoncloud-ddns-net/ghost_highoncloud-ddns-net.service /lib/systemd/system/ghost_highoncloud-ddns-net.service
+ sudo systemctl daemon-reload
✔ Setting up Systemd
+ sudo systemctl is-active ghost_highoncloud-ddns-net
? Do you want to start Ghost? Yes
+ sudo systemctl start ghost_highoncloud-ddns-net
+ sudo systemctl is-enabled ghost_highoncloud-ddns-net
+ sudo systemctl enable ghost_highoncloud-ddns-net --quiet
✔ Starting Ghost

Ghost uses direct mail by default. To set up an alternative email method read our docs at https://ghost.org/docs/config/#mail

------------------------------------------------------------------------------

Ghost was installed successfully! To complete setup of your publication, visit:

    https://highoncloud.ddns.net/ghost/

Checkout your new site!

In this article we'll walkthrough the steps to create a free website or blog hosted on Oracle Cloud Infrastructure (FYI, at the time of writing this article this site is hosted on OCI using these very steps). We'll first have a very short introduction into the various components involved in this setup, then look at the process and start getting to work! Feel free to skip the theory and jump to whatever section you're interested in.

Components:

Oracle Cloud Infrastructure

Oracle Cloud Free Tier offers Always Free services, which includes a Compute VM which we'll use to host our free website

Ghost

Ghost is a free, opensource and simple web application from which you can create and manage your blog and contents. It has the combined advantage of automatically configuring nginx as a reverse proxy and for HTTPS, as well as obtaining the SSL Certificate and making a crontab entry to automatically renew these certificates.

Let's Encrypt

Let's Encrypt is a free, opensource and automated Certificate Authority. Let's Encrypt offer FREE SSL/TLS Certificates! They are only valid for 90 days, but can simply be renewed.

NoIP

NoIP offer free hostnames under select few domains, they also provide you with complete control over the DNS records for that hostname, so we can the website address directly to our Free OCI VM

Process

The process itself is quite straight forward. First we'll setup the underlying infrastructure in OCI to support the provisioning of our Free VM. We'll then Create and Configure the domain and DNS and point it to our OCI VM (This must be done before configuring Ghost in order to obtain and configure SSL Certs). We'll then finish up by installing Ghost! Here we go!

Tutorial

If you don't already have an OCI tenancy then go and grab your Always Free account...

Create an Always Free Instance

Once you've logged in, select "Create a VM"
This process will create the underlying network as well as creating the VM

Select the "Always Free Eligable" Shape
Select "Canonical Ubuntu 20.04 Minimal" Image
Minimal image is smaller, faster to boot and lightweight

Scroll Down
Change the VCN & Subnet name to something meaningful
Save the Private Key so you can SSH into the VM
Click Create

You'll be taken to the Instance Information page
Make a note of the Public IP
Click on the Subnet

You'll be taken to the Security List for your subnet
Click on the Default Security List
You'll be taken to the Firewall Rules Rules
Click Add Ingress Rules

Set the Source CIDR as 0.0.0.0/0
Set the Destination Port Range as 80,443

80 is required for SSL Cert setup,
443 is for HTTPS traffic to your site

Create & Configure Domain

Head over to https://www.noip.com/ and grab your free domain

Create an A record in the DNS
Use the IP of your Free VM

Install Ghost

SSH into your Free VM as the ubuntu user using the Public IP & Private Key you downloaded during VM Creation

Now let's start with the Ghost setup installation.

sudo apt upgrade
sudo apt update

sudo iptables -I INPUT 5 -p tcp --dport 80 -j ACCEPT
sudo iptables -I INPUT 5 -p tcp --dport 443 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

sudo adduser ghostusr
sudo usermod -aG sudo ghostusr
sudo su - ghostusr

sudo apt install cron
sudo apt-get install nginx
sudo apt-get install mysql-server

sudo mysql

alter user 'root'@'localhost' identified with mysql_native_password by 'oracle99';
quit;

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash
sudo apt-get install -y nodejs

sudo npm install ghost-cli@latest -g

sudo mkdir -p /var/www/ghost
sudo chown ghostusr:ghostusr /var/www/ghost
sudo chmod 775 /var/www/ghost
cd /var/www/ghost

Run the Ghost installation. You'll need to provide the URL, mysql details and an email address.

Answer Yes to all responses

ghost install 
✔ Checking system Node.js version 
✔ Checking logged in user 
✔ Checking current folder permissions 
✔ Checking system compatibility 
✔ Checking for a MySQL installation 
✔ Checking memory availability 
✔ Checking free space 
✔ Checking for latest Ghost version 
✔ Setting up install directory 
✔ Downloading and installing Ghost v3.40.5 
✔ Finishing install process 
? Enter your blog URL: https://highoncloud.co.uk
? Enter your MySQL hostname: localhost 
? Enter your MySQL username: root 
? Enter your MySQL password: [hidden] 
? Enter your Ghost database name: ghostdb 
✔ Configuring Ghost 
✔ Setting up instance
sudo chown -R ghost:ghost /var/www/ghost/content 
	✔ Setting up "ghost" system user 
	? Do you wish to set up "ghost" mysql user
	? Yes 
	✔ Setting up "ghost" mysql user ? Do you wish to set up Nginx
	? Yes
sudo mv /tmp/highoncloud-co-uk/highoncloud.co.uk.conf /etc/nginx/sites-available/highoncloud.co.uk.conf
sudo ln -sf /etc/nginx/sites-available/highoncloud.co.uk.conf /etc/nginx/sites-enabled/highoncloud.co.uk.conf
sudo nginx -s reload 
	✔ Setting up Nginx 
	? Do you wish to set up SSL? Yes 
	? Enter your email (For SSL Certificate) user@highoncloud.co.uk
sudo mkdir -p /etc/letsencrypt
sudo ./acme.sh --install --home /etc/letsencrypt
sudo /etc/letsencrypt/acme.sh --issue --home /etc/letsencrypt --domain highoncloud.co.uk --webroot /var/www/ghost/system/nginx-root --reloadcmd "nginx -s reload" --accountemail shahvaiz.janjua@hotmail.co.uk
sudo openssl dhparam -dsaparam -out /etc/nginx/snippets/dhparam.pem 2048
sudo mv /tmp/ssl-params.conf /etc/nginx/snippets/ssl-params.conf
sudo mv /tmp/highoncloud-co-uk/highoncloud.co.uk-ssl.conf /etc/nginx/sites-available/highoncloud.co.uk-ssl.conf
sudo ln -sf /etc/nginx/sites-available/highoncloud.co.uk-ssl.conf /etc/nginx/sites-enabled/highoncloud.co.uk-ssl.conf
sudo nginx -s reload 
	✔ Setting up SSL 
	? Do you wish to set up Systemd? Yes
sudo mv /tmp/highoncloud-co-uk/ghost_highoncloud-co-uk.service /lib/systemd/system/ghost_highoncloud-co-uk.service
sudo systemctl daemon-reload 
	✔ Setting up Systemd
sudo systemctl is-active ghost_highoncloud-co-uk 
	? Do you want to start Ghost? Yes
sudo systemctl start ghost_highoncloud-co-uk
sudo systemctl is-enabled ghost_highoncloud-co-uk
sudo systemctl enable ghost_highoncloud-co-uk --quiet ✔ Starting Ghost
Ghost uses direct mail by default. To set up an alternative email method read our docs at https://ghost.org/docs/concepts/config/#mail

Ghost was installed successfully! To complete setup of your publication, visit:
<https://highoncloud.co.uk/ghost/>