Doctor AI · Documentation

OKD/OCP posture analysis governed at every step.

Doctor AI connects to OpenShift and OKD clusters using read-only API access, scans workload posture against policy packs and routes every finding through the governance model. No mutation without an approval record. No recommendation without an audit trail.

Operating Principles
Read-Only Access
All cluster operations use the Kubernetes/OpenShift REST API with a minimally-scoped service account token. No writes to the cluster.
Governance-Integrated Findings
Critical severity findings automatically block the governance gate for the linked asset until resolved or exception-approved.
Encrypted Credentials
Service account tokens and kubeconfigs are encrypted at rest using the application key. They are never exposed after save.
Full Audit Trail
Every scan, finding, exception and remediation approval is recorded with a timestamp, user and organization context.
Cluster Registration

A cluster record is the anchor for all Doctor AI operations. Register it once, test connectivity, configure namespace scope and start scanning.

Required fields

  • Cluster Name — unique identifier inside the tenant.
  • Platform — OCP (Red Hat OpenShift) or OKD (community).
  • Kubernetes API URL — e.g. https://api.cluster.example.com:6443
  • Connection Mode — service-account-token, kubeconfig or in-cluster.
  • Bearer Token or Kubeconfig — credential for the read-only service account.

Optional but recommended

  • Web Console URL — enables direct console links in findings and reports.
  • Custom CA Certificate — required for self-signed cluster TLS certificates.
  • Namespace Scope — limits governance evaluation to specific namespaces.
  • Sync Schedule — cron expression for automated posture collection.
  • Environment — development, staging, production or DR.
Connection Modes
Service Account Token
Recommended
Most granular and auditable. The service account is created in the cluster with minimum read permissions.

Setup

  1. Create the service account
  2. oc create sa tainux-doctor -n tainux-system
  3. Assign cluster-reader role
  4. oc adm policy add-cluster-role-to-user cluster-reader -z tainux-doctor -n tainux-system
  5. Extract the token and paste into the Bearer Token field
Kubeconfig
Flexible
Useful when cluster authentication is already configured in a kubeconfig — ideal for multi-cluster setups with OIDC.

Setup

  1. Obtain the cluster kubeconfig
  2. oc config view --minify --flatten > cluster.kubeconfig
  3. Paste the YAML content into the Kubeconfig field
  4. Set the correct context if the file contains multiple clusters
In-Cluster
Self-hosted
When TAINUX is running inside the cluster itself. Uses the Pod's service account automatically — no external credentials needed.

Setup

  1. Deploy TAINUX into the target cluster
  2. Assign cluster-reader to the Pod's service account
  3. Select "In-Cluster" as the connection mode
  4. No additional credentials required
Scan Pipeline
1 Connectivity

Tests the API endpoint, validates TLS and detects the Kubernetes/OpenShift version. Measures latency and records the result.

2 Collection

Reads /api/v1/nodes, /api/v1/namespaces, /api/v1/pods and additional resources filtered by configured namespace scope. All read-only.

3 Analysis

Claude AI evaluates collected data against active policy packs. Classifies findings by severity (critical, high, medium, low, info).

4 Publication

Findings are saved with a timestamp and linked to the governance asset. Critical findings update the governance gate automatically.

To register a cluster, open Doctor AI → Clusters → Register Cluster inside the platform. For support: support@tainux.io.