oodle-onboarding

Oodle Onboarding — Integration Setup

Integrate infrastructure with the Oodle observability platform using oodle integrations commands. Actively discover the environment to recommend integrations and adapt setup steps. The setup spec is a blueprint — it defines the approach and parameters, but execution adapts based on what the codebase and environment reveal.

Prerequisites

Before starting any onboarding work, verify the Oodle CLI is installed and authenticated. Run these checks at the beginning of every session:

Step 1: Check if the CLI is installed

oodle version

If the command is not found, install it:

brew install oodle-ai/oodle/oodle

If brew is not available, fall back to:

go install github.com/oodle-ai/oodle-cli/cmd/oodle@latest

Step 2: Check if the CLI is authenticated

oodle auth status

If not authenticated or the status shows an error, run interactive login:

oodle auth login

This opens a browser for OAuth login. The user must complete the browser flow — prompt them to do so and wait for confirmation. After login succeeds, verify with oodle auth status.

Note: oodle integrations list-setup-specs and oodle integrations get-setup-spec do NOT require authentication. Use these to discover available integrations and fetch setup instructions even before auth is configured. All other integration commands require valid credentials — complete the auth steps above before proceeding past step 2 in the Command Execution Order.

Command Execution Order

Follow this sequence for every integration onboarding request:

1. Identify the integration type. If the user named one (e.g., "kubernetes", "aws-cloudwatch"), use it. Otherwise, run environment discovery to detect present infrastructure and recommend matching integrations (see references/environment-discovery.md).
2. Fetch available setup specs — run oodle integrations list-setup-specs -o json (no auth required) to confirm the type exists and cross-reference against discovery results.
3. Fetch integration records — run oodle integrations list -o json to extract: (a) the type field (lowercase it for step 4), (b) collectorDomain/logsCollectorDomain for helm values, (c) instance ID from the domain pattern. Then run oodle api-keys list -o json to find an existing API key, or oodle api-keys create --name <name> --scopes <scopes> to create one if none exist. Requires authentication — if not configured, complete Prerequisites steps 1–2 first.
4. Fetch the setup spec — run oodle integrations get-setup-spec <type-lowercase> -o json. This is the blueprint for integration, not a rigid script. It defines the general approach, required tools, and parameters.
5. Discover the environment in depth — probe the codebase, running services, and existing configs. Use findings to resolve parameters and adapt the spec's steps (see references/environment-discovery.md).
6. Collect remaining parameters — after discovery, ask the user for anything that could not be auto-detected. Group questions together.
7. Execute the setup — work through the spec's steps, adapting each one based on discovery results. Confirm with the user before every non-read-only command. Review references/gotchas.md before executing.
8. Validate the integration — run oodle integrations list -o json and check the status.
9. Verify data presence on the Oodle side (see references/post-install-validation.md).

For failure scenarios, consult references/failure-handling.md.

Quick Reference

Aliases: oodle integration, oodle integ

Common Operations

Discovering available integration types

# CORRECT — discover all types with setup specs (no auth required)
oodle integrations list-setup-specs -o json

# CORRECT — table output for display (no auth required)
oodle integrations list-setup-specs

# WRONG — guessing integration types without checking
oodle integrations get-setup-spec some-random-type -o json

Listing configured integrations

# CORRECT — check which integrations are already configured (requires auth)
oodle integrations list -o json

# CORRECT — table output for display
oodle integrations list

Fetching a setup spec

# CORRECT — fetch spec for a known type (no auth required)
oodle integrations get-setup-spec kubernetes -o json

# WRONG — hardcoding setup steps instead of fetching the spec
kubectl apply -f <hardcoded-collector-manifest>   # never hardcode a manifest source; fetch the spec instead

Executing setup steps (adapting the blueprint)

The spec defines what needs to happen. Discover the current state before each step and adapt:

# CORRECT — check existing state, then adapt
kubectl get namespace oodle-system 2>/dev/null && echo "Already exists, skipping" || kubectl create namespace oodle-system

# CORRECT — existing release? upgrade instead of install
helm list -n oodle-system | grep oodle && helm upgrade ... || helm install ...

# CORRECT — show the command and ask for confirmation before running
echo "I will run: kubectl create namespace oodle-system"
# [wait for user confirmation]
kubectl create namespace oodle-system

# WRONG — blindly running spec commands without checking existing state
kubectl create namespace oodle-system  # fails if already exists

# WRONG — running destructive commands without confirmation
kubectl delete namespace oodle-system

Validating the integration

# CORRECT — check integration status after setup
oodle integrations list -o json

# CORRECT — check pods are running (for Kubernetes integrations)
kubectl get pods -n oodle-system

# WRONG — assuming success without verification
echo "Integration complete!"

Best Practices

Always fetch the latest setup spec

Run oodle integrations get-setup-spec <type> -o json at the start of every onboarding session. Never cache or reuse a previously fetched spec — requirements and steps change as the platform evolves. Treat the spec as a blueprint: it defines what needs to happen and what parameters are required, but adapt the exact commands and values based on environment discovery.

Resolve parameters by discovery first, ask second

Collect all required parameters before starting execution. Check these sources in order:

1. Environment discovery — probe actively: kubectl config current-context for cluster name, helm list for existing releases, process lists for running collectors, config files in the codebase for endpoints, env vars for API keys.
2. The user's request — the user may have specified values in the prompt.
3. Ask the user — only for what could not be auto-detected. Group remaining questions together.

Confirm before creating or modifying resources

Show the command to be run and wait for user confirmation before executing any command that creates, modifies, or deletes resources. Read-only commands (list, get, describe) do not need confirmation. Redact secrets in the displayed command — show the redacted version for confirmation, then run the unredacted version internally. For commands that require secret values (e.g., helm install --set apiKey=...), prefer passing secrets via temp files, stdin, or environment variables rather than command-line arguments to avoid shell history exposure.

Handle existing resources gracefully

If a resource already exists (namespace, Helm release, ConfigMap), skip the creation step and note it was already present. Do not fail or attempt to delete and recreate.

Redact secrets in output

Never display full API keys, tokens, or passwords. Show only the first and last 4 characters (e.g., oodl...k9x2). When rendering config templates from the spec, redact secret values before showing to the user.

One step at a time

Execute setup steps sequentially. Verify each step succeeded before moving to the next. If a step fails, diagnose the issue and suggest a fix — do not continue to the next step.

Present a summary when done

After all steps complete and validation passes, present a summary:

• Integration type and name
• What was installed/configured
• Current status
• How to check status later (oodle integrations list)

References

• references/environment-discovery.md — infrastructure detection and setup step adaptation
• references/gotchas.md — critical gotchas to review before executing setup
• references/post-install-validation.md — verifying data presence with query skills
• references/failure-handling.md — troubleshooting common failure scenarios
• Oodle CLI repo — source of the oodle binary
• Oodle docs — product documentation
• oodle-cli skill — core CLI usage, auth, output formats