Oracle Cloud Infrastructure Documentation

Azure Kubernetes Service (AKS)

This topic converts a legacy standalone Java application into a containerized microservice that runs on Azure Kubernetes Service (AKS) and connects to Oracle Autonomous AI Database by using an mTLS wallet.

Prerequisites

This section describes the requirements of Oracle Database and tables for the Java application to connect to Oracle Autonomous AI Database and access the Product table.

Oracle Autonomous AI Database

Complete the following steps to provision an Oracle Autonomous AI Database and create a user and table:
  • Oracle Autonomous AI Database Wallet for the connection.
  • Oracle Database user credentials to create a database session and run SQL commands.
  • Connectivity from the application server to Oracle Database.
  • A Product table in Oracle Database.
Run the following command to create the Product table and insert a test record:
-- Create the Product table
CREATE TABLE Product (
    id NUMBER PRIMARY KEY,
    name VARCHAR2(100) NOT NULL,
    price NUMBER(10, 2) NOT NULL
);

-- Insert a quick test record (optional, so your UI isn't empty on first load)
INSERT INTO Product (id, name, price) 
VALUES (1, 'Test Migration Item', 99.99);

-- Commit the transaction
COMMIT;

Implementation

  1. Development Machine Setup
    1. Tools and Libraries: Install the following libraries and tools on the development machine:
      1. Java Development Kit (JDK): JDK 25 or higher.
      2. Oracle JDBC Driver: Download the standalone ojdbc17.jar.
      3. Rancher Desktop: Install and select the dockerd (moby) container engine during setup. This gives you the standard docker CLI command.
        1. You can use other applications other application similar to Rancher Desktop like Docker Desktop, Podman Desktop, Colima, OrbStack.
      4. Azure CLI (az): To provision the cloud resources.
      5. Kubernetes CLI (kubectl): To interact with the AKS Cluster.
    2. The Java Source Code (ProductApiApp.java)
      1. Create the ProductApiApp.java file and copy the following content into it.
        import java.io.*;
import java.net.InetSocketAddress;
import java.sql.*;
import com.sun.net.httpserver.*;

public class ProductApiApp {
    // These environment variables are injected by the Kubernetes deployment.yaml
    private static final String DB_URL = System.getenv("DB_URL");
    private static final String DB_USER = System.getenv("DB_USER");
    private static final String DB_PASS = System.getenv("DB_PASS");

    public static void main(String[] args) throws Exception {
        if (DB_URL == null || DB_USER == null || DB_PASS == null) {
            System.err.println("ERROR: Missing DB_URL, DB_USER, or DB_PASS");
            System.exit(1);
        }

        // Bind to 0.0.0.0 (all interfaces) so the Kubernetes LoadBalancer can route traffic to it
        HttpServer server = HttpServer.create(new InetSocketAddress("0.0.0.0", 8080), 0);
        server.createContext("/api/products", new ProductApiHandler());
        server.setExecutor(null); 
        server.start();
        System.out.println("API Microservice running on port 8080...");
        System.out.println("Connecting to database using URL: " + DB_URL);
    }

    static class ProductApiHandler implements HttpHandler {
        @Override
        public void handle(HttpExchange exchange) throws IOException {
            // Enable CORS so the UI microservice and remote callers can fetch data from this API
            exchange.getResponseHeaders().add("Access-Control-Allow-Origin", "*");
            exchange.getResponseHeaders().add("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
            exchange.getResponseHeaders().add("Access-Control-Allow-Headers", "Content-Type");
            
            // Handle preflight requests for CORS
            if ("OPTIONS".equalsIgnoreCase(exchange.getRequestMethod())) {
                exchange.sendResponseHeaders(204, -1);
                return;
            }

            exchange.getResponseHeaders().add("Content-Type", "application/json");
            String method = exchange.getRequestMethod();
            StringBuilder jsonResponse = new StringBuilder();
            
            try (Connection conn = DriverManager.getConnection(DB_URL, DB_USER, DB_PASS)) {
                
                if ("GET".equalsIgnoreCase(method)) {
                    // READ: List all products
                    jsonResponse.append("[");
                    try (Statement stmt = conn.createStatement();
                         ResultSet rs = stmt.executeQuery("SELECT id, name, price FROM Product ORDER BY id")) {
                        boolean first = true;
                        while (rs.next()) {
                            if (!first) jsonResponse.append(",");
                            jsonResponse.append("{")
                                        .append("\"id\":").append(rs.getInt("id")).append(",")
                                        .append("\"name\":\"").append(rs.getString("name")).append("\",")
                                        .append("\"price\":").append(rs.getDouble("price"))
                                        .append("}");
                            first = false;
                        }
                    }
                    jsonResponse.append("]");
                } 
                else if ("POST".equalsIgnoreCase(method) || "PUT".equalsIgnoreCase(method) || "DELETE".equalsIgnoreCase(method)) {
                    // Read the ENTIRE request payload (handles multi-line pretty JSON from Postman)
                    InputStreamReader isr = new InputStreamReader(exchange.getRequestBody(), "utf-8");
                    StringBuilder payloadBuilder = new StringBuilder();
                    int b;
                    while ((b = isr.read()) != -1) {
                        payloadBuilder.append((char) b);
                    }
                    String payload = payloadBuilder.toString();
                    
                    String idStr = extractJsonValue(payload, "id");
                    String name = extractJsonValue(payload, "name");
                    String priceStr = extractJsonValue(payload, "price");

                    int id = idStr.isEmpty() ? 0 : Integer.parseInt(idStr);
                    double price = priceStr.isEmpty() ? 0.0 : Double.parseDouble(priceStr);

                    if ("POST".equalsIgnoreCase(method)) {
                        // CREATE
                        String sql = "INSERT INTO Product (id, name, price) VALUES (?, ?, ?)";
                        try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
                            pstmt.setInt(1, id);
                            pstmt.setString(2, name);
                            pstmt.setDouble(3, price);
                            pstmt.executeUpdate();
                        }
                        jsonResponse.append("{\"status\": \"Product created successfully\"}");
                    } else if ("PUT".equalsIgnoreCase(method)) {
                        // UPDATE
                        String sql = "UPDATE Product SET name=?, price=? WHERE id=?";
                        try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
                            pstmt.setString(1, name);
                            pstmt.setDouble(2, price);
                            pstmt.setInt(3, id);
                            pstmt.executeUpdate();
                        }
                        jsonResponse.append("{\"status\": \"Product updated successfully\"}");
                    } else if ("DELETE".equalsIgnoreCase(method)) {
                        // DELETE
                        String sql = "DELETE FROM Product WHERE id=?";
                        try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
                            pstmt.setInt(1, id);
                            pstmt.executeUpdate();
                        }
                        jsonResponse.append("{\"status\": \"Product deleted successfully\"}");
                    }
                }
                
                byte[] responseBytes = jsonResponse.toString().getBytes("UTF-8");
                exchange.sendResponseHeaders(200, responseBytes.length);
                OutputStream os = exchange.getResponseBody();
                os.write(responseBytes);
                os.close();

            } catch (SQLException e) {
                String errorJson = "{\"error\":\"" + e.getMessage().replace("\"", "\\\"") + "\"}";
                byte[] responseBytes = errorJson.getBytes("UTF-8");
                exchange.sendResponseHeaders(500, responseBytes.length);
                OutputStream os = exchange.getResponseBody();
                os.write(responseBytes);
                os.close();
            }
        }

        // Lightweight JSON parser helper for zero-dependency constraint
        // Updated to handle arbitrary spaces and multi-line structures
        private String extractJsonValue(String json, String key) {
            if (json == null) return "";
            String searchKey = "\"" + key + "\"";
            int start = json.indexOf(searchKey);
            if (start == -1) return "";
            start = json.indexOf(":", start) + 1;
            int end = json.indexOf(",", start);
            if (end == -1) end = json.indexOf("}", start);
            if (end == -1) end = json.length();
            return json.substring(start, end).replace("\"", "").trim();
        }
    }
}
    3. The Containerization (Dockerfile)
      1. Create a file named Dockerfile in the same directory as your Java code and the ojdbc17.jar file. Compile the code inside the container to avoid installing build dependencies on the local machine.
        
# Use Eclipse Temurin as a highly trusted, industry-standard base image for Java
FROM eclipse-temurin:25-jdk-jammy

WORKDIR /app
COPY ProductApiApp.java /app/
COPY ojdbc17.jar /app/

# Compile the Java application
RUN javac -cp ojdbc17.jar ProductApiApp.java

EXPOSE 8080
CMD ["java", "-cp", ".:ojdbc17.jar", "ProductApiApp"]
  2. Deployment Environment - Azure Kubernetes Service (AKS)
    Open PowerShell, Command Prompt, or Zsh, and then sign in to Azure:
    az login
    1. Provision Azure Kubernetes Service and Container Registry
      1. Define the variables, and then create the Azure resource group, Azure Container Registry (ACR), and Azure Kubernetes Service (AKS).
        RESOURCE_GROUP="oracle-aks-rg"
LOCATION="eastus"
ACR_NAME="mycompanyacr123" # Must be globally unique
AKS_NAME="oracle-aks-cluster"

# 1. Create Resource Group
az group create --name $RESOURCE_GROUP --location $LOCATION

# 2. Create Azure Container Registry
az acr create --resource-group $RESOURCE_GROUP --name $ACR_NAME --sku Basic

# 3. Create AKS Cluster and attach the ACR (so AKS can pull your images)
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_NAME \
    --node-count 1 \
    --generate-ssh-keys \
    --attach-acr $ACR_NAME

# 4. Get kubectl credentials to connect to your new cluster
az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME
    2. Build and Push the Container (Using Rancher Desktop)
      1. Ensure that Rancher Desktop is running, and then run the following commands.
        
# 1. Log into Azure ACR
az acr login --name $ACR_NAME

# 2. Build the image 
docker build --platform linux/amd64 -t $ACR_NAME.azurecr.io/product-api:v1 .

# 3. Push the image to ACR
docker push $ACR_NAME.azurecr.io/product-api:v1
    3. Configure Oracle Wallet and Database Secrets
      1. Oracle Autonomous AI Database uses an mTLS wallet. Download the instance wallet zip file from the OCI Console and then extract it to a local folder. For example, ./adb-wallet.
        
# 1. Upload the Wallet files into Kubernetes as a Secret
kubectl create secret generic adb-wallet \
  --from-file=./adb-wallet/cwallet.sso \
  --from-file=./adb-wallet/tnsnames.ora \
  --from-file=./adb-wallet/sqlnet.ora

# 2. Upload your Database Credentials as a Secret
kubectl create secret generic db-credentials \
  --from-literal=username="ADMIN" \
  --from-literal=password="<Your_ADB_Password>"
    4. Deploy to AKS
      1. Create a file named deployment.yaml. The DB_URL value uses the Oracle TNS alias found in the tnsnames.ora file and points to the wallet directory (/app/wallet) that Kubernetes mounts.
        • Replace the container registry endpoint.
        • Replace my_adb_high with the actual TNS name. 
        apiVersion: apps/v1
kind: Deployment
metadata:
  name: product-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: product-api
  template:
    metadata:
      labels:
        app: product-api
    spec:
      containers:
      - name: api
        image: mycompanyacr123.azurecr.io/product-api:v1  # UPDATE THIS to your ACR name
	    imagePullPolicy: Always  # Forces Kubernetes to download the newest image from ACR
        ports:
        - containerPort: 8080
        env:
        - name: DB_URL
          # Replace 'my_adb_high' with the actual alias from your tnsnames.ora
          value: "jdbc:oracle:thin:@my_adb_high?TNS_ADMIN=/app/wallet"
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: username
        - name: DB_PASS
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: password
        volumeMounts:
        - name: wallet-volume
          mountPath: /app/wallet
          readOnly: true
      volumes:
      - name: wallet-volume
        secret:
          secretName: adb-wallet
---
apiVersion: v1
kind: Service
metadata:
  name: api-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 8080
  selector:
    app: product-api
    5. Deploy the Application
      Once the EXTERNAL-IP appears, your API is fully accessible over the internet.
      
kubectl apply -f deployment.yaml

# Monitor the deployment until an EXTERNAL-IP is assigned
kubectl get services --watch
  3. Interacting with the API

    Now that API is separated from the UI and deployed on AKS, you can interact with it using any REST client or a decoupled frontend.

    1. Accessing Your Running Application

      Once the EXTERNAL-IP appears, for example, 20.124.x.x, the API is accessible over the internet.

      Even though your Java application is EXPOSE 8080 in the Dockerfile, the Kubernetes Service (api-service defined above) maps the standard web port 80 to the container's port 8080. Therefore, you do not need to specify a port in your URL.

      Access URL Format: http://<EXTERNAL-IP>/api/products

      1. Test it from your terminal:
        curl http://<EXTERNAL-IP>/api/products
    2. Enable OpenAPI Specifications (Optional)

      You can use openai.yaml in Postman or another REST client to interact with the graphical user interface.

      1. Save the following content as openai.yaml. Import the file into Postman, and replace <your-aks-api-external-ip> with the IP address from the previous step. The AI uses this schema to automatically generate valid JSON payloads and fetch current Oracle data.
        openapi: 3.0.0
info:
  title: Oracle Product API
  version: 1.0.0
  description: Full CRUD API to perform operations on the Product table.
servers:
  - url: http://<your-aks-api-external-ip>
paths:
  /api/products:
    get:
      summary: Read all products
      operationId: getProducts
      responses:
        '200':
          description: A JSON array of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
    post:
      summary: Create a new product
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Product created successfully
    put:
      summary: Update an existing product
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Product updated successfully
    delete:
      summary: Delete a product
      operationId: deleteProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Product deleted successfully
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
  4. Cleanup

    After you finish testing, delete the cloud resources to avoid Azure compute costs. Because the resources are in a single resource group, you can clean up the resources by using a single command.

    1. Run the following command for cleaning up the resource.
      
# Delete pods
kubectl delete pods -l app=product-api

# Delete the entire resource group (AKS, ACR, Disks, Load Balancers, and IPs)
az group delete --name oracle-aks-rg --yes --no-wait

# Optional: Remove the local kubectl context
kubectl config delete-context oracle-aks-cluster