OCI: Automate your Oracle Cloud Database software releases deployment (db-home)

As part of a very exciting project around Oracle Exadata Cloud @ Customer (aka. ExaCC) technology, we wanted to rollout in an automated manner the database software aka. ORACLE_HOME on ExaCC database clusters (aka. VM cluster). However, we rapidly identified a small lack of command-line parameters to “mimic” the console behavior.

This post describes briefly how to get rid of this “limitation” and applies to various kind of OCI Database services deployments (ExaCC, ExaCS, DBsystems) except Oracle Autonomous database.

The magic OCI console button “Display all available versions”

Indeed, it sounds obvious that DBAs wanna to deploy Oracle database instances on top of the latest Oracle database software available! However, we do also like to validate/ensure the database Release Update number.

Let’s “mimic” the Console with OCI-cli

According to the oci-cli documentation supplied database versions should be visible using “oci db version list”

jew@dbi-X-Geissberg ~ % oci db version list --compartment-id ${OCI_CLI_TENANCY} --query "data[*].{version: version, \"is-latest-for-major-version\": \"is-latest-for-major-version\"}"
[
{
"is-latest-for-major-version": true,
"version": "11.2.0.4"
},
{
"is-latest-for-major-version": true,
"version": "12.1.0.2"
},
{
"is-latest-for-major-version": true,
"version": "12.2.0.1"
},
{
"is-latest-for-major-version": true,
"version": "18.0.0.0"
},
{
"is-latest-for-major-version": true,
"version": "19.0.0.0"
},
{
"is-latest-for-major-version": true,
"version": "21.0.0.0"
}
]

However, neither the documentation nor the CLI results shows any Release Updates information.

The same, applies to the HashiCorp #Terraform data source and #Ansible modules

• Terraform data source: oci_database_db_versions
• Ansible module: oracle.oci.oci_database_db_version_facts

So, what? Let’s try to to talk to OCI Database RestAPIs directly

Well, let’s give a try to postman to walk though the Database Service API endpoints. Unfortunately, there is no postman OCI collection for the Database service API.

Same result, while walking though the OCI Database Service API “ListDbVersions” endpoint documentation.

However, while looking at the “dbaascli” commands we could reverse engineer the RestAPI calls and extrapolate the correct URI to interact with OCI. Furthermore, a blog from another DBA colleague Peter Prostredny gave us some really worth inputs!

ansible.builtin.uri module to talk with OCI Database RestAPIs

- name: List Oracle supplied database Release Updates available
  ansible.builtin.uri:
    url: "https://{{ host }}{{ rest_api }}"
    method: GET
    return_content: true
    headers:
      date: "{{ date }}"
      Authorization: 'Signature version="1", keyId="{{ key_id }}", algorithm="rsa-sha256",headers="(request-target) date host",signature="{{ signature }}"'
  vars:
    host: "database.{{ oci_region }}.oraclecloud.com"
    rest_api: "/20160918/dbVersions/19.0.0.0/minorVersions?compartmentId={{ oci_tenant_id }}"
    #
    key_id: "{{ oci_tenant_id }}/{{ oci_user_id }}/{{ oci_user_fingerprint }}"
date: "{{ now(utc=True).strftime('%a, %d %b %Y %H:%M:%S') }} GMT"

    date_header: "date: {{ date }}"
    host_header: "host: {{ host }}"
    request_target: "(request-target): get {{ rest_api }}"
    signing_string: "{{ request_target }}\n{{ date_header }}\n{{ host_header }}"
    headers: "(request-target) date host"
    signature: "{{ reg_signature.stdout }}"
  register: reg_call_results

However, the aforementioned solution is not really “easy” to read (and maintain). Furthermore, it requires additional tweaks to publish OCI credentials and manage some “time skew” issues between your client and OCI.

{"code":"NotAuthenticated","message":"Date 'Mon, 07 Aug 2023 20:28:26 UTC' is not within allowed clock skew. Current 'Mon, 07 Aug 2023 20:33:27 UTC', valid datetime range: ['Mon, 07 Aug 2023 20:28:27 UTC', 'Mon, 07 Aug 2023 20:38:28 UTC']"}

Thus, we moved forward looking at the oci-cli command “oci raw-request“.

Talking with OCI Database service API endpoints using oci-cli raw request

Indeed, oci-cli “raw-request” mode seems to a good practice as we can expose credentials through the same mechanism as for the Ansible oracle.oci collection modules without any special treatment.

jew@dbi-X-Geissberg ~ % oci raw-request --http-method GET --target-uri "https://database.eu-zurich-1.oraclecloud.com/20160918/dbVersions/19.0.0.0/minorVersions?compartmentId=${OCI_CLI_TENANCY}" | jq '.data[]' | jq '{ version: .version }'
{
"version": "19.17.0.0"
}
{
"version": "19.18.0.0"
}
{
"version": "19.19.0.0"
}

The end

Really? This is of course only the begin of your Journey 🙂 But now, you should be able to start deploying Oracle Home’s on your VMclusters, DBsystems or creating your own customer Oracle Cloud database software images.

Enjoy!