OCI Tenancy Explorer

OCI Tenancy Explorer is a Streamlit application for collecting, browsing, and exporting Oracle Cloud Infrastructure tenancy inventory with the OCI Python SDK.

Current application version: 0.1.1

Default OCI connection conventions:

• Profile: DEFAULT
• Config path: ~/.oci/config

Features

• Fast search mode backed by OCI Resource Search structured queries.
• Optional deep mode that adds slower service-specific SDK sweeps.
• Configurable region-level parallelism.
• Configurable deep-service multithreading within each region for faster deep collections.
• Background collection jobs with live progress and SDK activity logs.
• Local retention of the latest 5 completed collections under report-output/collections.
• Saved snapshot browsing while a new collection runs in the background.
• Global search and sidebar filters for resource type, region, compartment, and state.
• Resource browser with a row-level view action that opens a popup dialog.
• Service limits tab with allotted, used, and available values collected through the OCI Limits SDK.
• Clickable resource headers for in-table sorting.
• Active-resource aging column derived from time_created.
• Excel and PDF export for filtered resources, full reports, and individual resource details.
• Basic local sign-in gate with default username oci.
• Login page and app footer display the running application version.
• Theme support including System.

UI startup

Preferred local startup:

./start.sh

start.sh handles:

• virtualenv creation
• pip, setuptools, and wheel upgrades
• dependency install and repair from requirements.txt
• requirement hash tracking
• auth bootstrap output
• Streamlit launch

Optional overrides:

PYTHON_BIN=/path/to/python3 ./start.sh
VENV_DIR=/custom/venv ./start.sh
REQUIREMENTS_FILE=/custom/requirements.txt ./start.sh

Manual startup remains available:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

Authentication

• Default username: oci
• Environment overrides:
  • OCI_EXPLORER_USERNAME
  • OCI_EXPLORER_PASSWORD
• If no password is supplied, a random password is generated and stored in report-output/auth/basic_auth.json
• start.sh prints the active credential source before the UI starts
• The login page shows the running version (0.1.1) before sign-in

Docker

Build the container:

docker build -t oci-tenancy-explorer .

To bake an app username and password into the image:

docker build \
  --build-arg OCI_EXPLORER_APP_USERNAME=oci \
  --build-arg OCI_EXPLORER_APP_PASSWORD='change-me' \
  -t oci-tenancy-explorer .

If your actual OCI configuration is in ~/.oci, copy that directory into the repo as ./.oci before building. The Docker image copies ./.oci into /root/.oci automatically.

Example:

rm -rf .oci
cp -R ~/.oci ./.oci
docker build -t oci-tenancy-explorer .

After the image is built, you can remove the staged local copy if you do not want OCI credentials left in the repo folder:

rm -rf ./.oci

Run it with the default OCI config mounted into the container:

docker run --rm \
  -p 8501:8501 \
  -v "$HOME/.oci:/root/.oci:ro" \
  -v "$(pwd)/report-output:/app/report-output" \
  -e OCI_EXPLORER_USERNAME=oci \
  -e OCI_EXPLORER_REGION_PARALLELISM=6 \
  -e OCI_EXPLORER_DEEP_SERVICE_PARALLELISM=4 \
  -e OCI_EXPLORER_PASSWORD='change-me' \
  oci-tenancy-explorer

Notes:

• Inside the container, the default OCI config path becomes /root/.oci/config
• The image sets OCI_CLI_CONFIG_FILE=/root/.oci/config
• The Dockerfile cannot read ~/.oci directly from your host unless you stage it into the build context first
• The Dockerfile also accepts OCI_EXPLORER_APP_USERNAME and OCI_EXPLORER_APP_PASSWORD as optional build args
• Runtime -e OCI_EXPLORER_PASSWORD=... is safer than embedding the password at build time
• The image also exposes OCI_EXPLORER_REGION_PARALLELISM and OCI_EXPLORER_DEEP_SERVICE_PARALLELISM for default UI threading values
• Runtime volume mounts are safer than baking secrets into the image
• Persist report-output as a volume if you want saved collections and generated auth files to survive container restarts
• You can still override the config path from the UI if you mount it elsewhere

Kubernetes

Kubernetes deployment artifacts are available under k8s/README.md.

Included artifacts:

• k8s/deployment.yaml
• k8s/service.yaml
• k8s/pvc.yaml
• k8s/kustomization.yaml

Typical flow:

kubectl create namespace oci-tenancy-explorer

kubectl create secret generic oci-tenancy-explorer-auth \
  -n oci-tenancy-explorer \
  --from-literal=OCI_EXPLORER_USERNAME=oci \
  --from-literal=OCI_EXPLORER_PASSWORD='change-me'

kubectl create secret generic oci-tenancy-explorer-oci-config \
  -n oci-tenancy-explorer \
  --from-file=config=$HOME/.oci/config \
  --from-file=oci_api_key.pem=$HOME/.oci/oci_api_key.pem

kubectl apply -k k8s
kubectl port-forward -n oci-tenancy-explorer svc/oci-tenancy-explorer 8501:8501

Update the image reference in k8s/deployment.yaml before applying.

Resource coverage

• Compute instances
• VCNs
• Subnets
• Block volumes
• Boot volumes
• Object Storage buckets
• DB systems
• Load balancers

Fast search mode can also surface other indexed OCI resource types through Resource Search.

Long-running collection behavior

• Create new collection starts a background job
• Parallel regions controls region fan-out
• Deep service workers controls multithreaded service collection inside each region when Deep inventory is selected
• Fast search is the recommended default for large tenancies
• Deep inventory adds slower SDK calls for richer detail, but now runs service collectors in parallel
• Service Limits shows tenancy-wide OCI limits with the same browser and export pattern used by Resources
• Saved collections stay available while a new run executes
• The Activity tab shows the SDK operations running behind the scenes
• The Errors tab keeps partial-failure details visible without blocking the rest of the report

CLI usage

Generate a report without the Streamlit UI:

python generate_report.py --collection-mode search --parallelism 4 --deep-service-parallelism 4 --output report-output/oci-tenancy-report.json

Optional flags:

• --config-file /path/to/config
• --profile SOME_PROFILE
• --collection-mode search|deep
• --parallelism 4
• --deep-service-parallelism 4
• --output -

Documentation

• Architecture: docs/ARCHITECTURE.md
• Kubernetes: k8s/README.md
• UML source: docs/uml/oci_tenancy_explorer_component.puml
• Diagram asset: docs/uml/oci_tenancy_explorer_component.svg

Architecture diagram

flowchart TD
    U[User]
    BOOT[start.sh]
    UI[Streamlit UI\napp.py]
    AUTH[Basic Auth\nauth.py]
    JM[Job Manager\njob_manager.py]
    INV[Inventory Collector\ninventory.py]
    ST[Snapshot Storage\nstorage.py]
    CLI[CLI Generator\ngenerate_report.py]
    DOCKER[Dockerfile]
    SNAP[(report-output/collections)]
    AUTHSTORE[(report-output/auth)]
    SDK[OCI Python SDK]
    SEARCH[OCI Resource Search]
    APIs[OCI Service APIs]

    U --> BOOT
    U --> DOCKER
    U --> UI
    U --> CLI
    BOOT --> UI
    UI --> AUTH
    AUTH --> AUTHSTORE
    UI --> JM
    UI --> ST
    JM --> INV
    JM --> ST
    CLI --> INV
    ST --> SNAP
    INV --> SDK
    SDK --> SEARCH
    SDK --> APIs

Loading

Notes

• The explorer uses the OCI Python SDK directly and does not shell out to the OCI CLI for collection.
• Fast mode should be the default for large tenancies because it minimizes API volume.
• Deep mode is better used selectively when richer per-service detail is worth the runtime cost.
• The report stays usable when individual OCI API calls fail; those failures surface in the UI and exported payloads.
• Inventory quality depends on the permissions granted to the configured OCI principal.
• The built-in sign-in is a lightweight local gate, not a replacement for enterprise SSO or reverse-proxy auth.