Oracle Cloud Search Tutorial: Architecture, Pricing, Use Cases, and Hands-On Guide for Observability and Management

1. Introduction

Oracle Cloud Search (often referred to in documentation and the Console as Resource Search) is an Oracle Cloud Infrastructure (OCI) service that helps you find, filter, and inventory OCI resources across your tenancy using a query language and APIs.

In simple terms: Search lets you ask OCI “what resources do I have?” and get back an accurate list—instances, VCNs, buckets, databases, load balancers, and more—optionally filtered by compartment, tags, lifecycle state, region, and other metadata.

Technically, Search provides a query endpoint and a resource index for OCI resource metadata. You submit queries (via Console, CLI, SDK, or REST API) using Resource Query Language and get structured results. Search is commonly used in operations and governance workflows: inventory, tag compliance, drift detection, incident response, and cleanup.

The problem it solves: in real environments, resources sprawl across compartments and teams. Listing resources service-by-service is slow and error-prone. Search provides a centralized, query-driven inventory that supports day-2 operations across OCI.

Naming note (important): This article is about Oracle Cloud (OCI) Search / Resource Search in the Observability and Management category. It is not log search (OCI Logging Search) and not an application/content search engine.

2. What is Search?

Official purpose (in OCI terms)

Search is a managed OCI service for discovering resources in your tenancy using structured queries over resource metadata. It returns results such as resource OCIDs, display names, compartments, resource types, and other indexed attributes.

Official docs (start here):
https://docs.oracle.com/en-us/iaas/Content/Search/Concepts/overview.htm

Core capabilities

Structured search using Resource Query Language (RQL) to find resources by type and attributes.
Free-text search capabilities (where supported) to find resources by keywords.
Tag-based discovery (defined tags and freeform tags) for governance and cost allocation workflows.
Cross-compartment discovery (bounded by IAM permissions).
API/CLI/SDK automation to integrate resource discovery into scripts and operational tooling.

Major components

Search endpoint (API): REST API to execute structured/free-text searches.
Query language: Resource Query Language expressions (service-specific syntax).
Resource index: An OCI-managed index of resource metadata (not your data plane content).
Console integration: The OCI Console provides an interactive Search experience.

Service type

Managed control-plane service (metadata search and discovery).
Not a customer-managed search cluster and not a document/content indexing service.

Scope (regional/global) and tenancy boundaries

Search operates within an OCI tenancy and returns only resources you are authorized to view.
Many OCI resources are regional, so Search behavior can be region-sensitive. In practice, organizations often run Search queries per region when building a complete inventory.
Exact regional behavior and supported resource types can evolve—verify the current behavior in official docs and test in your target regions.

How it fits into the Oracle Cloud ecosystem

Search sits in the “operability” layer: – Works alongside OCI IAM (authorization boundaries). – Supports governance practices alongside Tagging, Audit, Cloud Guard, and Security Zones. – Often used by platform teams and SREs as an inventory input to tooling, dashboards, and cleanup jobs.

3. Why use Search?

Business reasons

Faster inventory and accountability: Identify what exists and who owns it (via tags).
Cost control: Find unused, oversized, or orphaned resources for cleanup.
Reduced risk: Locate exposed resources quickly (for example, public buckets, internet-facing load balancers) and confirm configuration baselines.

Technical reasons

Single query interface for multi-service inventory.
Automation-ready: works with OCI CLI/SDK/REST for repeatable scripts.
Consistent identifiers: results include OCIDs that can be fed into service-specific APIs.

Operational reasons

Incident response: quickly find affected resources by name patterns, tags, or compartment.
Change validation: confirm that a deployment created/updated resources as expected.
Drift discovery: detect resources that exist outside expected compartments or tag standards.

Security/compliance reasons

Tag compliance and asset inventory: demonstrate that assets are accounted for and labeled.
Access-aware discovery: Search results reflect IAM permissions, supporting least privilege.
Auditability: Search API calls can be captured through OCI Audit (verify in your tenancy).

Scalability/performance reasons

Search avoids manual enumeration across many services/compartments.
Enables centralized inventory at scale (bounded by service limits and indexing behavior).

When teams should choose it

You need resource inventory across compartments and teams.
You want to automate governance (tagging, cleanup, ownership).
You need a control-plane discovery tool for operations.

When teams should not choose it

You need full-text search over application content, documents, logs, or database rows (use services designed for content/log analytics).
You need deep configuration assessment and remediation orchestration by itself (Search helps discover resources; other services/tools handle policy-as-code, posture management, remediation workflows).

4. Where is Search used?

Industries

Financial services: asset inventory, audit preparation, governance enforcement.
Healthcare: compliance inventories, environment separation validation.
SaaS and tech: multi-team cloud platform operations, cost controls.
Public sector: compartment-based segregation and asset reporting.

Team types

Cloud platform/CoE teams
DevOps and SRE teams
Security engineering and GRC teams
FinOps/cost optimization teams
Application teams (for self-service discovery)

Workloads

Multi-compartment environments (dev/test/prod separation)
Multi-region deployments (DR, latency optimization)
Shared services architectures (hub-and-spoke networks, centralized logging)
Regulated environments with strict tagging and inventory needs

Architectures

Landing zone / multi-account-like compartment design
Microservices platforms with many small resources
Data platforms with buckets, streams, DBs, analytics services
Hybrid environments needing cloud inventory synchronization (CMDB)

Real-world deployment contexts

Production: scheduled inventory reports, compliance scanning, incident response tooling.
Dev/Test: cleanup scripts to remove resources after labs, PoCs, and ephemeral testing.

5. Top Use Cases and Scenarios

Below are realistic, common ways Oracle Cloud Search is used in operational environments.

1) Tenancy-wide asset inventory

Problem: You need a complete list of OCI resources for reporting or a CMDB.
Why Search fits: One query surface across many resource types and compartments.
Scenario: A platform team runs nightly structured queries and exports results to an internal inventory system.

2) Tag compliance checks (ownership/cost center)

Problem: Resources are created without required tags.
Why Search fits: Query for resources missing specific defined tags.
Scenario: A FinOps team finds untagged compute instances and asks owners to remediate.

3) Find orphaned resources after CI/CD changes

Problem: Old load balancers, volumes, or IPs remain after deployments.
Why Search fits: Query by tag, name pattern, or compartment to identify leftovers.
Scenario: After a blue/green cutover, Search finds resources with environment=blue still present.

4) Incident response: identify blast radius

Problem: A security incident affects a project compartment; you need a list of assets fast.
Why Search fits: Query by compartment and resource types; pivot using OCIDs.
Scenario: Security queries for all public-facing endpoints in a compromised compartment.

5) Cleanup of Always Free / lab environments

Problem: Students or engineers leave resources running.
Why Search fits: Query for resources with lab tags or naming conventions.
Scenario: A nightly job finds instances tagged owner=training older than X days and flags them for deletion.

6) Migration readiness: verify resource counts pre/post move

Problem: You moved workloads to a new compartment/region; need validation.
Why Search fits: Compare query results before and after migration.
Scenario: An architect validates all required resources exist in the target compartment.

7) Governance: detect resources in wrong compartments

Problem: Teams create resources in the root compartment or shared compartments.
Why Search fits: Query by compartmentId and resource types; report violations.
Scenario: A policy requires all app resources to be under App-Prod; Search finds exceptions.

8) Network operations: locate networking objects by naming patterns

Problem: Troubleshooting depends on finding the right VCN/subnet/NSG quickly.
Why Search fits: Search for network resources by displayName patterns and compartment.
Scenario: An SRE finds a subnet by matching subnet-*prod* in a hub VCN.

9) Cost optimization: find unattached block volumes or reserved public IPs

Problem: Unattached storage and reserved IPs can generate cost (service-dependent).
Why Search fits: Query for resource types/states that indicate “unused.”
Scenario: Monthly report enumerates unattached volumes for approval and cleanup.

10) Audit preparation: evidence of inventory and classification

Problem: Auditors request evidence that assets are inventoried and classified.
Why Search fits: Exportable query-based inventory with tag classification.
Scenario: Compliance produces a report of all databases labeled with data_classification=restricted.

11) Posture checking: locate internet-facing resources

Problem: Security needs to identify potentially exposed resources.
Why Search fits: Query resource types that can be public (for example, public IPs, LBs) and validate attributes.
Scenario: A weekly review finds internet-facing load balancers not in approved compartments.

12) Platform engineering: discover resources for automation targeting

Problem: A script needs to apply configuration to a dynamic set of resources.
Why Search fits: Search provides a dynamic set of OCIDs to feed into automation.
Scenario: A script finds all instances with tag patch_group=linux-prod and triggers patch orchestration.

6. Core Features

Feature availability and exact query syntax can change; validate with the official docs for your region and tenancy.

6.1 Structured search (Resource Query Language)

What it does: Allows precise queries for resources by type and metadata fields.
Why it matters: Structured queries are predictable, automatable, and script-friendly.
Practical benefit: Build repeatable inventory checks like “all instances in prod compartments missing an owner tag.”
Limitations/caveats:
Requires learning the query language.
Results depend on indexing timeliness (there can be delays between creation and discoverability).

6.2 Free-text search (where supported)

What it does: Searches by keywords across certain indexed fields.
Why it matters: Faster for interactive exploration when you don’t know the exact field.
Practical benefit: Find a resource by a partial display name or tag value.
Limitations/caveats:
Typically less precise than structured search.
May not support complex conditions.

6.3 Search across compartments (permission-aware)

What it does: Search can return resources across compartments you can access.
Why it matters: Most organizations use compartments for isolation; operations needs cross-compartment visibility.
Practical benefit: Platform teams can inventory across all application compartments.
Limitations/caveats:
IAM controls what you can see; Search does not bypass authorization.
Some orgs intentionally limit cross-compartment visibility.

6.4 Tag-aware discovery (defined tags and freeform tags)

What it does: Enables queries that filter on tags for ownership, environment, cost center, etc.
Why it matters: Tags are the foundation of governance, cost allocation, and automation targeting.
Practical benefit: Find all resources belonging to “team-a” or “prod”.
Limitations/caveats:
Tag indexing may not be immediate.
Tag key naming and namespaces must be consistent for good results.

6.5 API access (REST) and automation (CLI/SDK)

What it does: Provides API-driven search suitable for scripts and systems integration.
Why it matters: Repeatable governance and operational workflows depend on automation.
Practical benefit: Nightly reports, cleanup scripts, and inventory exports.
Limitations/caveats:
Service limits and rate limits apply.
Authentication requires correct IAM policies and API signing.

API reference (Search):
https://docs.oracle.com/en-us/iaas/api/#/en/search/

6.6 Console experience for interactive operations

What it does: Allows operators to search without writing code.
Why it matters: Useful during incidents and interactive investigations.
Practical benefit: Quickly find a resource by name and jump to its details page.
Limitations/caveats:
Console experience may differ slightly from CLI/SDK options.

6.7 Result metadata: OCIDs and resource identifiers

What it does: Returns resource OCIDs and metadata fields useful for follow-up actions.
Why it matters: OCID is the universal identifier to call service-specific APIs.
Practical benefit: Pipe Search results into automation that modifies or validates resources.
Limitations/caveats:
Returned fields vary by resource type.

6.8 Pagination and sorting behaviors (API-level)

What it does: Supports pagination over large result sets.
Why it matters: Real tenancies can have tens of thousands of resources.
Practical benefit: Build robust inventory pipelines.
Limitations/caveats:
You must implement pagination logic in scripts.
Verify any ordering guarantees in official docs.

7. Architecture and How It Works

High-level architecture

At a high level, Search is a control-plane discovery service:

OCI services (Compute, Networking, Object Storage, etc.) emit/maintain control-plane metadata.
Search maintains a managed index of resource metadata.
Users and automation submit queries to the Search endpoint.
Search returns results (resource identifiers + selected metadata), constrained by IAM authorization.

Request/data/control flow

Control flow: Your identity (user or dynamic group) authenticates via IAM → calls Search API.
Data flow: Query → Search index lookup → results returned.
Follow-up: Use returned OCIDs to call the underlying service APIs (Compute, Network, etc.) for deeper details or actions.

Integrations with related OCI services

IAM: Policies and compartment boundaries determine visibility.
Audit: Search API calls can be audited (verify your Audit configuration and retention).
Tagging: Tags are commonly used as search filters and governance controls.
Events / Functions / DevOps (pattern-based): Use Search to discover targets, then run actions via Functions or pipelines.
Monitoring/Logging: Not a direct metric-heavy service by itself; teams often monitor the automation using Logging/Monitoring around the scripts that call Search.

Dependency services

OCI IAM (authentication and authorization)
Underlying OCI service control planes that publish resource metadata

Security/authentication model

Uses standard OCI request signing (API keys) for users, or instance principal / resource principal for workloads (depending on your environment).
Authorization is enforced via IAM policies at tenancy/compartment scope.

Networking model

Search is accessed via OCI public service endpoints (typical OCI API model).
If you require private access patterns, evaluate OCI networking options (for example, private endpoints where applicable) and verify in official docs whether Search supports specific private access mechanisms in your region.

Monitoring/logging/governance considerations

Track Search usage via Audit for compliance.
For automated inventory jobs, log query executions, result counts, and error codes to OCI Logging.
Apply tag governance so Search results can be sliced reliably by owner/environment/cost center.

Simple architecture diagram (Mermaid)

flowchart LR
  U[Operator / Script] -->|Console / CLI / SDK| API[OCI Search API Endpoint]
  API --> IDX[Managed Resource Metadata Index]
  IDX --> API
  API --> R[Search Results: OCIDs + metadata]
  R --> SVC[Follow-up calls to OCI services\n(Compute, Network, Storage, DB)]

Production-style architecture diagram (Mermaid)

flowchart TB
  subgraph Tenancy[OCI Tenancy]
    subgraph Regions[Multiple OCI Regions]
      API1[Search API (Region A)]
      API2[Search API (Region B)]
    end

    subgraph Ops[Operations & Governance Tooling]
      CRON[Scheduled Inventory Job\n(Functions/Compute/CI Runner)]
      LOG[OCI Logging]
      MON[OCI Monitoring]
      TKT[Ticketing / ChatOps\n(external)]
      CMDB[Inventory DB / CMDB\n(external)]
    end

    IAM[IAM Policies\n& Dynamic Groups]
    AUD[OCI Audit]
    TAG[Tagging Standards\n(Defined Tags)]
  end

  CRON -->|Assume principal\n(API signing)| IAM
  CRON -->|Structured queries| API1
  CRON -->|Structured queries| API2
  CRON -->|Write logs| LOG
  CRON -->|Custom metrics (optional)| MON
  CRON -->|Export inventory| CMDB
  CRON -->|Create issues| TKT
  API1 --> AUD
  API2 --> AUD
  TAG -->|Used as filters| API1
  TAG -->|Used as filters| API2

8. Prerequisites

Tenancy/account requirements

An active Oracle Cloud (OCI) tenancy
Access to the OCI Console
Ability to create/read resources in at least one compartment (for the lab)

Permissions / IAM

You need: – Permission to use Search and to read the resources you intend to find. – In OCI, Search results are constrained by what your identity is authorized to see.

Because IAM policy syntax and required verbs can vary by organization and service evolution, use the official IAM guidance for Search and test with least privilege:

Search documentation (overview and related topics):
https://docs.oracle.com/en-us/iaas/Content/Search/Concepts/overview.htm

If you cannot see expected resources: – Confirm you have read/inspect permissions in the relevant compartments for the resource types. – Confirm no policy denies or restricts access. – Verify required Search permissions in official docs for your tenancy setup.

Billing requirements

Search itself is typically not a separately billed “metered” resource, but always confirm in pricing docs (see Pricing section).
The lab can be designed to use mostly free control-plane resources (like VCN and tags), but always validate cost implications in your region and account.

Tools (choose one)

OCI Console (web UI)
OCI CLI (recommended for the hands-on lab):
https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm
Optional: OCI SDK (Python/Java/Go, etc.) if automating

Region availability

Search is broadly available across OCI regions, but regional feature parity can vary. Verify region support in official docs for any regulated or specialty region.

Quotas/limits

API rate limits and pagination limits apply.
If you plan tenancy-wide inventory at scale, design around pagination and rate limiting.
Verify service limits here (general OCI limits entry point):
https://docs.oracle.com/en-us/iaas/Content/General/Concepts/servicelimits.htm

Prerequisite services (for this tutorial)

IAM (users/groups/policies) to authenticate
One compartment and at least one resource to search for (we’ll create a VCN and tags)

9. Pricing / Cost

Pricing model (what to expect)

Oracle Cloud Search is a control-plane discovery capability. Oracle typically does not list Search as a separately priced, metered service in the way compute/storage are priced. In many OCI setups, using Search does not incur a standalone line-item charge.

However: – Pricing and entitlements can change. – Some costs are indirect (automation runtime, logging, data egress). – Always validate using official Oracle pricing sources.

Start with: – Oracle Cloud Pricing landing page: https://www.oracle.com/cloud/pricing/ – OCI Cost Estimator: https://www.oracle.com/cloud/costestimator.html

If Search has a dedicated pricing page for your tenancy/region, use that as the source of truth. If it is not listed, treat it as “included” but verify in official docs/pricing.

Pricing dimensions to consider

Even when Search is not directly billed, you should plan for: – API call volume: may be limited by rate limits (not cost), but impacts automation reliability. – Automation compute: where your scheduled inventory scripts run (Compute, Functions, containers). – Logging/Monitoring: storing job logs, metrics, and alerts. – Data export/storage: storing inventory snapshots in Object Storage or a database. – Cross-region iteration: querying multiple regions can increase runtime and associated costs.

Free tier

OCI has an Always Free tier for some services, but eligibility and specifics vary by region and program updates. Search usage itself is generally not a “resource” you provision.
Verify Always Free details: https://www.oracle.com/cloud/free/

Main cost drivers (practical)

Running inventory jobs too frequently (every minute instead of daily/hourly).
Exporting large inventories and storing long history without lifecycle policies.
Excessive logging verbosity for scheduled jobs.
Using paid compute shapes to run simple queries.

Hidden or indirect costs

Data transfer: If you export results to systems outside OCI or across regions, network egress may apply.
Downstream API calls: Search results often lead to additional API calls (Compute/Network) for deeper inspection, increasing automation runtime.

How to optimize cost

Use Search as the first-pass filter; only call downstream APIs for resources that match.
Run inventory at a reasonable cadence (daily or a few times per day) unless you truly need near-real-time.
Store inventory snapshots with Object Storage lifecycle rules (archive/delete old data).
Keep logs structured and concise; retain only what you need.

Example low-cost starter estimate (no fabricated prices)

A low-cost approach typically includes: – OCI CLI script run on a small runner (or your workstation) – One daily Search query per region – Export results to a small Object Storage bucket with lifecycle policy

Costs depend on: – Where the script runs (your laptop vs OCI compute) – Storage used for exports – Network egress if exporting off-cloud

Because actual numbers vary by region and pricing updates, use: – OCI Cost Estimator: https://www.oracle.com/cloud/costestimator.html

Example production cost considerations

In production, you might run: – Hourly inventory in multiple regions – Exports to Object Storage + a database – SIEM integration – More detailed downstream API enrichment

Cost focus areas: – Automation runtime – Data retention and storage class – SIEM ingestion fees (often external) – Network egress (if exporting outside OCI)

10. Step-by-Step Hands-On Tutorial

This lab walks you through using Oracle Cloud Search to find resources by type and tags, using both the OCI Console and OCI CLI. The lab is designed to be low-risk and low-cost by using primarily control-plane resources (VCN and tags). Always confirm any cost implications in your tenancy.

Objective

Create a small, identifiable resource (a VCN) and tag it.
Use Search to find the resource: – In the OCI Console – Using the OCI CLI structured search command
Validate results and learn common troubleshooting steps.
Clean up created resources.

Lab Overview

You will: – (Optional) Create a dedicated compartment for the lab – Create a tag namespace and defined tag – Create a VCN (Virtual Cloud Network) and apply the defined tag – Query Search using: – Console Search – CLI structured search – Clean up: delete the VCN and tags/compartment (if created)

If you do not have permission to create compartments or tag namespaces, you can still complete most of the lab by: – Using an existing compartment – Using freeform tags (if allowed), or skipping tag creation and searching by resource type/name

Step 1: Confirm region and select (or create) a compartment

Option A (recommended): Create a lab compartment (requires elevated permissions)

In the OCI Console, open the navigation menu.
Go to Identity & Security → Compartments.
Click Create Compartment.
Name it: lab-search
Description: Lab compartment for Search tutorial
Choose the parent compartment (often the root compartment).
Click Create Compartment.

Expected outcome – A new compartment lab-search exists and is in Active state.

Option B: Use an existing compartment

Pick a compartment where you have permission to create networking resources.

Verification – You can open the compartment and view its OCID (useful later).

Step 2: Create a defined tag (namespace + key)

Defined tags are best practice for governance because they are consistent and centrally managed.

Go to Governance & Administration → Tag Namespaces (wording may vary by Console layout).
Click Create Tag Namespace: – Name: Lab – Description: Lab tags for Search tutorial
Open the Lab namespace and click Create Tag Key: – Tag Key Name: Project – (If there is a choice for value type, pick a simple string type if prompted; exact options may vary—verify in Console.)

Expected outcome – You have a defined tag Lab.Project.

Verification – You can see the namespace and key listed in the Console.

Common issue – If you don’t have permission: you may see authorization errors. In that case: – Skip defined tags and use freeform tags later, or – Ask an admin to create the namespace/key and grant you permission to use it.

Step 3: Create a VCN and apply the tag

A VCN is a good lab resource because it’s common, easy to identify, and typically low cost (confirm pricing in your environment).

Go to Networking → Virtual Cloud Networks.
Ensure you’re in the correct compartment (for example, lab-search).
Click Create VCN.
Choose VCN with Internet Connectivity or VCN with Custom CIDR (either is fine for search purposes).
Name: vcn-search-lab
When prompted for tags: – Defined tags: set Lab.Project = search-tutorial – (Optional) Freeform tags: purpose=search-lab
Create the VCN.

Expected outcome – VCN vcn-search-lab exists.

Verification – Open the VCN details page and confirm: – Display name – Compartment – Tags applied

Step 4: Use Search in the OCI Console

Open Search in the OCI Console navigation menu (Observability & Management category placement can vary by Console).
Use a structured search query to find the VCN.

Example queries (validate syntax in your Console help) Try one of the following patterns:

By resource type (VCN):
query vcn resources
By tag (defined tag):
query vcn resources where definedTags.namespace = 'Lab'
By tag key/value (typical intent):
query vcn resources where definedTags.Lab.Project = 'search-tutorial'

Query syntax can be strict (quoting, field names, capitalization). If a query errors, use the Console’s query hints/help, and cross-check the official docs: https://docs.oracle.com/en-us/iaas/Content/Search/Concepts/overview.htm

Expected outcome – The results list includes vcn-search-lab.

Verification – Click the result and confirm it links to the correct VCN OCID/details.

Step 5: Use Search with OCI CLI (structured search)

5.1 Install and configure OCI CLI (if not already)

Follow the official installation guide:
https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm

After installation, configure:

oci setup config

You’ll need: – Tenancy OCID – User OCID – Region – API key (generated and uploaded to your user)

Expected outcome – ~/.oci/config exists and CLI commands authenticate successfully.

Verification Try:

oci iam region list --output table

5.2 Run a structured search query

The OCI CLI includes Search commands. The exact command group can vary by CLI version, but commonly follows this pattern:

oci search resource structured-search --query-text "query vcn resources"

If you want to narrow by compartment, you can either: – Add a where clause (if supported by your query syntax), and/or – Filter locally after retrieval

Expected outcome – The command returns JSON including matching VCNs.

Verification Look for: – display-name or displayName matching vcn-search-lab – identifier or ocid of the VCN

5.3 Useful CLI output formatting

To view in a table-like form, you can use --query (JMESPath) and --output table:

oci search resource structured-search \
  --query-text "query vcn resources" \
  --query "data.items[].{name:\"display-name\", ocid:identifier, compartment:compartment-id}" \
  --output table

Field names in CLI output can vary (hyphenated vs camelCase). If this query fails, run without --query first and inspect the returned structure.

Step 6 (Optional): Automate with Python SDK (mini example)

If you prefer SDK-based automation, OCI provides SDKs. Python example (verify module names with current SDK docs):

Install SDK:

python3 -m pip install oci

Create search_vcn.py:

import oci
from oci.resource_search import ResourceSearchClient
from oci.resource_search.models import StructuredSearchDetails

config = oci.config.from_file()  # reads ~/.oci/config
client = ResourceSearchClient(config)

query = "query vcn resources"
details = StructuredSearchDetails(query=query)

resp = client.search_resources(details)

for item in resp.data.items:
    # item fields vary by resource type; display_name is commonly present
    print(item.display_name, item.identifier, item.compartment_id)

Run:

python3 search_vcn.py

Expected outcome – Prints VCN display names and OCIDs, including vcn-search-lab.

If imports fail, check the current OCI Python SDK docs and Search API model names. SDK packages evolve—verify in official SDK docs.

Validation

Use this checklist:

VCN exists and has tags: – Console → Networking → VCNs → vcn-search-lab
Console Search finds it: – Search results include vcn-search-lab
CLI Search finds it: – oci search resource structured-search --query-text "query vcn resources" returns it
IAM constraints behave as expected: – If you remove access to the compartment (in a test environment), it should no longer appear

Troubleshooting

Problem: “NotAuthorizedOrNotFound” or empty results

Likely causes: – You don’t have permission to read the target compartment/resources. – You are searching in a region where the resource doesn’t exist (for regional resources). – The resource was created recently and is not yet indexed.

Fixes: – Confirm IAM policies for your group. – Confirm the Console/CLI region setting. – Wait a few minutes and retry (indexing delay), then verify in official docs whether indexing is near-real-time.

Problem: Query syntax errors

Likely causes: – Incorrect field names or quoting. – Using a tag field format not supported in your tenancy/CLI version.

Fixes: – Start with a minimal query: query vcn resources – Then add one filter at a time. – Use official query language references (Search docs):
https://docs.oracle.com/en-us/iaas/Content/Search/Concepts/overview.htm

Problem: CLI `--query` JMESPath errors

Likely causes: – Output field names differ from what you assumed.

Fix: – Run the command without --query, inspect the JSON fields, then adjust.

Problem: You can find the resource in the service page but not via Search

Possible causes: – Index lag – Region mismatch – Resource type not indexed the way you expect (rare but possible)

Fix: – Verify indexing behavior and supported resource types in official docs.

Cleanup

To avoid clutter (and potential costs in broader labs), clean up what you created.

Delete the VCN: – Console → Networking → Virtual Cloud Networks – Select vcn-search-lab → Terminate / Delete (Console wording varies) – If deletion fails due to dependencies, delete dependent resources first (subnets, gateways, route tables, etc.), or use the VCN delete workflow that removes dependencies.
Delete the defined tag key/namespace (optional): – Governance & Administration → Tag Namespaces – Remove tag keys, then the namespace
– Some organizations restrict tag deletion; follow your governance process.
Delete the compartment (optional, if created): – Identity → Compartments → lab-search → Delete – Note: compartment deletion in OCI typically requires all resources inside to be deleted first and may take time.

11. Best Practices

Architecture best practices

Treat Search as your inventory front door, but keep authoritative configuration checks with service-specific APIs or policy tooling.
For multi-region inventories, design a region iteration loop and merge results.
Store inventory snapshots with timestamps for trend analysis and audit evidence.

IAM/security best practices

Use least privilege:
Grant read access only to compartments/resource families needed.
Avoid tenancy-wide read unless the role truly requires it (platform ops, security).
Prefer dynamic groups + instance principals for scheduled inventory jobs running on OCI.
Audit who is running broad queries across the tenancy (Audit + internal controls).

Cost best practices

Don’t run inventory too frequently.
Export only the fields you need (reduce downstream processing).
Apply lifecycle policies to inventory exports in Object Storage.

Performance best practices

Use structured queries that narrow results early (resource type + filters).
Implement pagination and backoff in scripts.
Cache results for interactive tools when appropriate (with clear staleness expectations).

Reliability best practices

Treat Search as a dependency: handle API errors and timeouts gracefully.
Implement retries with exponential backoff.
For scheduled jobs, track last successful run and alert on failures.

Operations best practices

Log every inventory run:
query text (or a hashed identifier if sensitive)
region
result count
duration
errors
Version-control your query set (queries-as-code).
Use consistent naming/tagging standards so queries remain stable.

Governance/tagging/naming best practices

Standardize defined tag namespaces (Owner, CostCenter, Environment, DataClassification).
Require tags via policy/guidance and monitor compliance via Search queries.
Use consistent resource naming conventions; even basic prefixing makes free-text discovery easier.

12. Security Considerations

Identity and access model

Search uses OCI IAM for authentication and authorization.
Users/scripts can only see resources they are allowed to read/inspect.
Broad inventory access can be sensitive; treat it like a privileged capability.

Encryption

Search is a managed control-plane service; transport security is via HTTPS to OCI endpoints.
For any exported inventory data you store (Object Storage, DB), enable encryption (default encryption is typical in OCI storage services; verify settings and requirements).

Network exposure

Search API endpoints are typically accessed over OCI public endpoints.
If you have strict network controls:
Run automation within OCI and restrict outbound access.
Review OCI guidance for private access patterns and verify Search endpoint support in your region.

Secrets handling

Avoid embedding API keys in code repositories.
Use instance principals/dynamic groups where possible for OCI-native automation.
If you must use API keys:
store securely (vault/secret manager)
rotate keys
restrict user permissions

Audit/logging

Use OCI Audit to track Search API usage (verify Audit coverage for Search actions in your tenancy).
Log inventory job operations to OCI Logging with retention rules.
Keep exported inventories protected; inventories can reveal sensitive topology and asset names.

Compliance considerations

Inventory data can be sensitive (asset lists, naming conventions, compartment structure).
Apply access controls and retention policies to exported data.
In regulated environments, treat inventories as part of your security evidence and protect accordingly.

Common security mistakes

Granting tenancy-wide read access to broad groups “for convenience.”
Exporting inventories to public buckets or unsecured external endpoints.
Storing API keys in plaintext on shared servers.
Treating Search results as complete security posture assessment (it’s discovery, not full posture evaluation).

Secure deployment recommendations

Use a dedicated automation identity with least privilege.
Segment compartments and restrict who can run tenancy-wide queries.
Store exports in private buckets with strict IAM and audit logging.
Document and review your inventory queries as part of change control.

13. Limitations and Gotchas

Because OCI services evolve, confirm current specifics in official docs. Common gotchas include:

Indexing delay: New or updated resources might not appear instantly.
Region sensitivity: Some resources are regional; an inventory may require querying multiple regions.
IAM visibility constraints: If you can’t see it, Search won’t return it.
Query language strictness: Field names and quoting must match the query language requirements.
Pagination: Large tenancies require pagination logic; otherwise you will only see a subset.
Resource coverage: Not every attribute of every service is necessarily searchable; Search targets key metadata fields.
Console vs API differences: Console convenience features may not map 1:1 to API parameters.
Unexpected empties: Often caused by compartment scope, region selection, or missing permissions.
Downstream enrichment costs: Using Search to find resources then calling many service APIs can increase runtime and operational overhead.
Tag inconsistencies: Poor tag hygiene makes Search results unreliable for governance.

14. Comparison with Alternatives

Search is best compared to other cloud resource discovery services and to inventory/CMDB approaches.

Alternatives inside Oracle Cloud

OCI Resource Manager (Terraform) state as inventory (only what Terraform manages)
OCI Cloud Guard (security posture, detectors, problems; not a generic inventory query engine)
OCI Logging Search (search within logs; different domain)

Alternatives in other clouds

AWS Resource Explorer (resource discovery)
Azure Resource Graph (query resources with KQL-like experience)
Google Cloud Asset Inventory (asset metadata inventory and export)

Open-source/self-managed alternatives

CMDB + collector scripts (custom)
Terraform state + drift tooling
CloudQuery / Steampipe (SQL-style inventory across clouds)

Comparison table

Option	Best For	Strengths	Weaknesses	When to Choose
Oracle Cloud Search	OCI resource discovery and governance queries	Native, permission-aware, API/CLI-friendly, integrates with tags/compartments	Not a content/log search engine; indexing/coverage constraints; multi-region inventory may require iteration	You need OCI-native inventory and filtering by metadata/tags
OCI Cloud Guard	Security posture and threat detection	Detectors, security findings, posture focus	Not designed as a general-purpose inventory query tool	You want security findings and remediation workflows, and use Search as a supporting discovery tool
OCI Logging Search	Searching log events	Deep log analytics/search	Not for resource inventory	You need to investigate logs, not list resources
AWS Resource Explorer	AWS asset discovery	Centralized resource search across AWS	AWS-only; different query semantics	You are on AWS and need similar inventory
Azure Resource Graph	Azure inventory at scale	Powerful query engine for Azure resources	Azure-only; different permissions model	You need fleet inventory across Azure subscriptions
GCP Cloud Asset Inventory	GCP asset inventory/export	Exportable asset snapshots	GCP-only; different query patterns	You need asset inventory and history in GCP
Steampipe / CloudQuery	Multi-cloud inventory with SQL	Flexible queries, multi-cloud	Requires deployment/ops; not OCI-native	You need a single inventory layer across multiple providers

15. Real-World Example

Enterprise example: regulated multi-compartment governance and audit readiness

Problem
A financial services company has hundreds of OCI compartments across business units. Auditors require evidence of: – asset inventory completeness – ownership tagging – separation of prod vs non-prod resources

Proposed architecture – Scheduled inventory job runs daily per region: – Uses dynamic group + instance principal for authentication – Executes Search structured queries for critical resource types – Exports results to Object Storage (private bucket) – Pushes summarized counts to a governance dashboard – Audit and access reviews: – OCI Audit tracks who runs broad inventory queries – IAM restricts Search usage to platform/security roles

Why Search was chosen – Native OCI integration – Query-based inventory across compartments – Tag-based filtering for ownership and classification

Expected outcomes – Repeatable evidence for audits – Early detection of untagged or mis-scoped resources – Reduced manual inventory effort and faster investigations

Startup/small-team example: cost cleanup and operational clarity

Problem
A startup iterates quickly and frequently creates temporary environments. Resources are left behind, causing confusion and cost.

Proposed architecture – Simple nightly script: – Runs structured-search for resources tagged env=dev or owner=team-x – Flags resources older than a threshold (where metadata supports age checks; otherwise use external tracking) – Posts a summary to Slack/ChatOps – Optional: weekly cleanup approval workflow

Why Search was chosen – Low operational overhead (no inventory database required initially) – Works well with consistent tags and naming – Easy to integrate into scripts via CLI

Expected outcomes – Lower cloud spend from fewer orphaned resources – Faster environment troubleshooting – Better hygiene (tagging discipline improves because it’s measured)

16. FAQ

1) Is Oracle Cloud Search the same as searching logs?

No. Search (Resource Search) is for resource metadata discovery (instances, VCNs, buckets, etc.). Log searching is typically done with OCI Logging search features.

2) Does Search return resources across my whole tenancy?

It can, but only within the scope of your IAM permissions, and behavior can be region-influenced for regional resources. For full inventories, many teams query each region and merge results.

3) Do I need to enable or provision Search?

Typically, no separate provisioning is required; it’s available in the Console and via API/CLI. Confirm in your tenancy and region.

4) Can Search find resources in compartments I can’t access?

No. Search is permission-aware and does not bypass IAM.

5) How accurate is Search?

It is generally reliable for discovery, but expect possible indexing delays and verify edge cases for specific services/resource types.

6) Can I search by tags?

Yes, tag-based discovery is a primary use. Exact query syntax depends on the Search query language and your tagging structure—verify in official docs.

7) Can I use Search to find misconfigured resources (like public buckets)?

Search can help discover candidates (by resource type and metadata fields that are indexed), but you may need service-specific APIs to confirm configuration details.

8) Is Search free?

Oracle does not commonly publish Search as a separately priced service. Treat it as generally “included,” but verify using official pricing resources for your account/region.

9) What’s the difference between structured search and free-text search?

Structured search uses a query language with explicit fields and filters. Free-text search is keyword-based and generally less precise.

10) How do I export Search results?

Use CLI/SDK/REST to retrieve results as JSON, then store them (Object Storage, database, etc.). Implement pagination for large inventories.

11) Why do my CLI results differ from the Console?

Common causes: – Different region selection – Different identity/profile used by CLI – Query syntax differences (Console helpers vs raw CLI)

12) How do I run Search from an OCI instance without API keys?

Use instance principals (dynamic groups + policies) where possible. Verify the required setup in official IAM documentation.

13) Does Search provide historical inventory?

Search is primarily for current discovery. For history, you must store snapshots externally (Object Storage/DB) or use additional governance tooling.

14) Are all OCI resource types supported?

Coverage is broad, but not necessarily universal for every attribute and service. Check official docs and test queries for your required services.

15) What’s the best way to build a multi-region inventory?

Maintain a region list
Run the same query set per region
Normalize results (resource type, OCID, compartment, tags)
Store snapshots with timestamps
Add retry/backoff and pagination

16) How do I avoid returning too many results?

Start with: – A specific resource type (rather than “all resources”) – Compartment filters (if supported) – Tag filters

17) Can I use Search as a CMDB?

Search is not a CMDB by itself, but it can feed a CMDB with periodic exports.

17. Top Online Resources to Learn Search

Resource Type	Name	Why It Is Useful
Official documentation	OCI Search overview	Canonical description of what Search is and how it behaves: https://docs.oracle.com/en-us/iaas/Content/Search/Concepts/overview.htm
Official API reference	OCI Search API (REST)	Endpoint details, request/response models, pagination: https://docs.oracle.com/en-us/iaas/api/#/en/search/
Official CLI documentation	OCI CLI installation	Install and configure CLI for labs and automation: https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm
Official CLI command reference	OCI CLI `search` commands	How to run structured/free-text search via CLI (verify current command syntax): https://docs.oracle.com/en-us/iaas/tools/oci-cli/latest/
Official pricing	Oracle Cloud Pricing	Confirm whether Search has direct pricing and understand indirect costs: https://www.oracle.com/cloud/pricing/
Official cost estimation	OCI Cost Estimator	Estimate costs for automation runtimes, storage exports, and logging: https://www.oracle.com/cloud/costestimator.html
Always Free	Oracle Cloud Free Tier	Understand eligibility and free services (verify current program): https://www.oracle.com/cloud/free/
IAM fundamentals	OCI IAM docs	Required for permissions, dynamic groups, least privilege (entry point): https://docs.oracle.com/en-us/iaas/Content/Identity/home.htm
Service limits	OCI Service Limits	Plan for quotas/rate limits/pagination constraints: https://docs.oracle.com/en-us/iaas/Content/General/Concepts/servicelimits.htm
Architecture patterns	Oracle Architecture Center	Reference architectures for governance/ops patterns (browse and adapt): https://www.oracle.com/cloud/architecture-center/

18. Training and Certification Providers

The following institutes are listed as training providers/resources. Verify current course offerings, delivery modes, and syllabi on their websites.

Institute	Suitable Audience	Likely Learning Focus	Mode	Website URL
DevOpsSchool.com	DevOps engineers, SREs, platform teams	OCI operations, DevOps practices, automation fundamentals	Check website	https://www.devopsschool.com/
ScmGalaxy.com	Beginners to intermediate DevOps learners	SCM/DevOps foundations, cloud operations concepts	Check website	https://www.scmgalaxy.com/
CLoudOpsNow.in	Cloud engineers and operations teams	Cloud ops, monitoring/observability, operational readiness	Check website	https://www.cloudopsnow.in/
SreSchool.com	SREs and reliability-focused engineers	SRE practices, incident response, observability patterns	Check website	https://www.sreschool.com/
AiOpsSchool.com	Ops teams exploring AIOps	AIOps concepts, automation, event correlation	Check website	https://www.aiopsschool.com/

19. Top Trainers

These trainer-related sites can be used as learning resources. Verify current OCI/Search-specific coverage on each site.

Platform/Site	Likely Specialization	Suitable Audience	Website URL
RajeshKumar.xyz	DevOps/cloud training content	Engineers seeking practical training and guidance	https://rajeshkumar.xyz/
devopstrainer.in	DevOps tools and cloud training	Beginners to intermediate DevOps practitioners	https://www.devopstrainer.in/
devopsfreelancer.com	Freelance DevOps consulting/training	Teams needing hands-on support and coaching	https://www.devopsfreelancer.com/
devopssupport.in	DevOps support and mentoring	Ops teams needing troubleshooting-oriented learning	https://www.devopssupport.in/

20. Top Consulting Companies

These organizations may provide consulting services. Validate exact service catalogs, references, and engagement models directly with the providers.

Company	Likely Service Area	Where They May Help	Consulting Use Case Examples	Website URL
cotocus.com	Cloud/DevOps engineering services	Cloud adoption, ops automation, platform reliability	Build inventory automation using OCI Search; implement tagging governance reports	https://cotocus.com/
DevOpsSchool.com	DevOps/cloud consulting and training	DevOps transformation, CI/CD, cloud operations	Design an OCI governance model; implement scheduled Search-based inventory and cleanup	https://www.devopsschool.com/
DEVOPSCONSULTING.IN	DevOps and operations consulting	Tooling integration, automation, operational maturity	Integrate OCI Search outputs with CMDB/ticketing; implement least-privilege IAM for ops automation	https://www.devopsconsulting.in/

21. Career and Learning Roadmap

What to learn before Search

OCI fundamentals:
Tenancy, compartments, regions
OCIDs and resource lifecycle
OCI IAM:
Users, groups, policies
Dynamic groups and principals (for automation)
Tagging strategy:
Defined tags vs freeform tags
Governance and naming conventions
OCI CLI basics:
Authentication config
Output formatting and pagination patterns

What to learn after Search

Governance and security:
OCI Cloud Guard concepts
Security Zones (if applicable)
Audit review patterns
Automation patterns:
OCI Functions and Events (event-driven operations)
CI/CD pipelines for ops scripts
Observability:
OCI Logging, Monitoring, Alarms
Centralized log retention and alerting

Job roles that use Search

Cloud Engineer / Cloud Operations Engineer
DevOps Engineer
Site Reliability Engineer (SRE)
Cloud Security Engineer
FinOps Analyst / Cloud Cost Engineer
Solutions Architect / Platform Architect

Certification path (if available)

Oracle certifications change over time. Search is typically a skill within broader OCI certs rather than a standalone certification topic. Start here and choose role-based paths: – Oracle Cloud Certifications: https://education.oracle.com/oracle-cloud-infrastructure-certification

Project ideas for practice

Daily inventory exporter: run Search queries, store JSON snapshots in Object Storage, and generate a summary report.
Tag compliance checker: alert when resources are missing required tags.
Orphaned resource detector: find resources in “temporary” compartments older than X days.
Multi-region inventory dashboard: merge region results and visualize counts by resource type and compartment.
Incident response helper: a script that takes a compartment OCID and prints all resources and key metadata.

22. Glossary

OCI (Oracle Cloud Infrastructure): Oracle’s public cloud platform.
Search (Resource Search): OCI service for searching resource metadata across a tenancy.
Resource metadata: Control-plane information about resources (name, OCID, compartment, tags, lifecycle state).
OCID: Oracle Cloud Identifier, a unique identifier for OCI resources.
Compartment: A logical container for organizing and isolating OCI resources for access control and billing.
IAM: Identity and Access Management; controls authentication and authorization in OCI.
Defined tag: A centrally managed tag with a namespace and key; used for governance.
Freeform tag: A simple key/value tag without a centrally enforced schema.
Structured search: Query-based search using a specific syntax and fields.
Free-text search: Keyword-based search (less strict, where supported).
Indexing delay: Time between resource creation/update and its appearance in Search results.
Dynamic group: An OCI IAM construct that groups resources (like instances) for granting permissions.
Instance principal: An authentication method allowing an OCI compute instance to call OCI APIs without user API keys.
Pagination: Retrieving large API result sets across multiple requests using page tokens.

23. Summary

Oracle Cloud Search (Resource Search) is a practical, operations-focused service in the Observability and Management domain that helps you discover and inventory OCI resources using structured queries across compartments (bounded by IAM permissions). It matters because real OCI environments grow quickly, and Search provides a centralized way to answer “what do we have?” without manually inspecting every service.

From a cost perspective, Search is typically not a separately metered resource, but your automation runtime, logging, and data exports can drive indirect costs—optimize cadence, retention, and downstream enrichment calls. From a security perspective, Search is powerful because it can expose broad inventories; apply least privilege, protect exported inventories, and review usage via Audit.

Use Search when you need resource discovery, tag compliance checks, governance reporting, incident response inventory, or cleanup automation. Next step: build a small “inventory-as-code” script using OCI CLI/SDK, store snapshots, and integrate with your operational dashboards and governance processes.

rajeshkumar

Category