oodle-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oodle Onboarding — Integration Setup

Oodle 接入指南——集成设置

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.

使用

oodle integrations

命令将基础设施与Oodle可观测性平台集成。主动探测环境以推荐集成方案并调整设置步骤。设置规范是一份蓝图——它定义了实现方法和参数，但执行过程会根据代码库和环境的实际情况进行调整。

Prerequisites

前置条件

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

开始任何接入工作前，请确认Oodle CLI已安装并完成认证。每次会话开始时都要执行以下检查：

Step 1: Check if the CLI is installed

步骤1：检查CLI是否已安装

bash

oodle version

If the command is not found, install it:

bash

brew install oodle-ai/oodle/oodle

brew

is not available, fall back to:

bash

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

bash

oodle version

如果命令未找到，请安装它：

bash

brew install oodle-ai/oodle/oodle

如果

brew

不可用，改用：

bash

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

Step 2: Check if the CLI is authenticated

步骤2：检查CLI是否已认证

bash

oodle auth status

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

bash

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.

bash

oodle auth status

如果未认证或状态显示错误，请运行交互式登录：

bash

oodle auth login

这会打开浏览器进行OAuth登录。用户必须完成浏览器端流程——请提示用户操作并等待确认。登录成功后，使用

oodle auth status

验证。

注意：

oodle integrations list-setup-specs

和

oodle integrations get-setup-spec

不需要认证。即使在配置认证前，也可以使用这些命令探测可用的集成方案并获取设置说明。所有其他集成命令都需要有效凭据——在执行命令顺序中的步骤2之前，请完成上述前置条件中的步骤1-2。

Command Execution Order

命令执行顺序

Follow this sequence for every integration onboarding request:

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
```
).
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.
Fetch integration records — run
```
oodle integrations list -o json
```
to extract: (a) the
```
type
```
field (lowercase it for step 4), (b)
```
apiKey
```
, (c)
```
collectorDomain
```
/
```
logsCollectorDomain
```
for helm values, (d) instance ID from the domain pattern. Requires authentication — if not configured, complete Prerequisites steps 1–2 first.
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.
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
```
).
Collect remaining parameters — after discovery, ask the user for anything that could not be auto-detected. Group questions together.
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.
Validate the integration — run
```
oodle integrations list -o json
```
and check the status.
Verify data presence on the Oodle side (see
```
references/post-install-validation.md
```
).

For failure scenarios, consult

references/failure-handling.md

对于每个集成接入请求，请遵循以下顺序：

确定集成类型。如果用户指定了类型（例如“kubernetes”“aws-cloudwatch”），直接使用该类型。否则，运行环境探测以检测当前存在的基础设施并推荐匹配的集成方案（参见
```
references/environment-discovery.md
```
）。
获取可用的设置规范——运行
```
oodle integrations list-setup-specs -o json
```
（无需认证）以确认该类型存在，并与探测结果交叉验证。
获取集成记录——运行
```
oodle integrations list -o json
```
以提取：(a)
```
type
```
字段（转为小写用于步骤4），(b)
```
apiKey
```
，(c)用于helm值的
```
collectorDomain
```
/
```
logsCollectorDomain
```
，(d)从域名模式中提取实例ID。需要认证——如果未配置，请先完成前置条件中的步骤1-2。
获取设置规范——运行
```
oodle integrations get-setup-spec <type-lowercase> -o json
```
。这是集成的蓝图，而非严格的脚本。它定义了通用方法、所需工具和参数。
深入探测环境——探查代码库、运行中的服务和现有配置。根据探查结果解析参数并调整规范中的步骤（参见
```
references/environment-discovery.md
```
）。
收集剩余参数——探测完成后，向用户询问任何无法自动检测到的信息。将问题集中提出。
执行设置——逐步执行规范中的步骤，根据探测结果调整每一步。在执行任何非只读命令前，请与用户确认。执行前请查看
```
references/gotchas.md
```
。
验证集成——运行
```
oodle integrations list -o json
```
并检查状态。
在Oodle端验证数据存在性（参见
```
references/post-install-validation.md
```
）。

遇到失败场景，请参考

references/failure-handling.md

。

Quick Reference

快速参考

Task	Command	Auth required?
Discover available setup specs	`oodle integrations list-setup-specs -o json`	No
Discover available setup specs (table)	`oodle integrations list-setup-specs`	No
Get setup spec	`oodle integrations get-setup-spec <type> -o json`	No
Get setup spec (YAML)	`oodle integrations get-setup-spec <type> -o yaml`	No
List configured integrations	`oodle integrations list -o json`	Yes
List configured integrations (table)	`oodle integrations list`	Yes

Aliases:

oodle integration

oodle integ

任务	命令	是否需要认证？
探测可用的设置规范	`oodle integrations list-setup-specs -o json`	否
探测可用的设置规范（表格形式）	`oodle integrations list-setup-specs`	否
获取设置规范	`oodle integrations get-setup-spec <type> -o json`	否
获取设置规范（YAML格式）	`oodle integrations get-setup-spec <type> -o yaml`	否
列出已配置的集成	`oodle integrations list -o json`	是
列出已配置的集成（表格形式）	`oodle integrations list`	是

别名：

oodle integration

oodle integ

Common Operations

常见操作

Discovering available integration types

探测可用的集成类型

bash

undefined

bash

undefined

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

undefined

oodle integrations get-setup-spec some-random-type -o json

undefined

Listing configured integrations

列出已配置的集成

bash

undefined

bash

undefined

CORRECT — check which integrations are already configured (requires auth)

正确做法——检查已配置的集成（需要认证）

oodle integrations list -o json

CORRECT — table output for display

正确做法——表格形式输出用于展示

oodle integrations list

undefined

oodle integrations list

undefined

Fetching a setup spec

获取设置规范

bash

undefined

bash

undefined

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 https://some-hardcoded-url/oodle-collector.yaml

undefined

kubectl apply -f https://some-hardcoded-url/oodle-collector.yaml

undefined

Executing setup steps (adapting the blueprint)

执行设置步骤（调整蓝图）

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

bash

undefined

规范定义了需要完成的操作。在执行每一步前先探测当前状态并调整：

bash

undefined

CORRECT — check existing state, then adapt

正确做法——检查现有状态，然后调整

kubectl get namespace oodle-system 2>/dev/null && echo "Already exists, skipping" || kubectl create namespace oodle-system

kubectl get namespace oodle-system 2>/dev/null && echo "已存在，跳过" || 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"

echo "我将执行：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

kubectl create namespace oodle-system # 如果已存在会失败

WRONG — running destructive commands without confirmation

错误做法——未确认就运行破坏性命令

kubectl delete namespace oodle-system

undefined

kubectl delete namespace oodle-system

undefined

Validating the integration

验证集成

bash

undefined

bash

undefined

CORRECT — check integration status after setup

正确做法——设置完成后检查集成状态

oodle integrations list -o json

CORRECT — check pods are running (for Kubernetes integrations)

正确做法——检查Pod是否运行（针对Kubernetes集成）

kubectl get pods -n oodle-system

WRONG — assuming success without verification

错误做法——未验证就假设成功

echo "Integration complete!"

undefined

echo "集成完成！"

undefined

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.

每次接入会话开始时都要运行

oodle integrations get-setup-spec <type> -o json

。切勿缓存或重用之前获取的规范——随着平台演进，需求和步骤会发生变化。将规范视为蓝图：它定义了需要完成的操作和所需参数，但要根据环境探测结果调整具体命令和值。

Resolve parameters by discovery first, ask second

优先通过探测解析参数，其次询问用户

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

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.
The user's request — the user may have specified values in the prompt.
Ask the user — only for what could not be auto-detected. Group remaining questions together.

开始执行前收集所有必需的参数。按以下顺序检查来源：

环境探测——主动探查：
```
kubectl config current-context
```
获取集群名称，
```
helm list
```
获取现有版本，进程列表查找运行中的采集器，代码库中的配置文件查找端点，环境变量查找API密钥。
用户请求——用户可能在提示中指定了值。
询问用户——仅针对无法自动检测到的信息。将剩余问题集中提出。

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.

在执行任何创建、修改或删除资源的命令前，展示要运行的命令并等待用户确认。只读命令（list、get、describe）无需确认。在展示的命令中隐藏敏感信息——展示脱敏后的版本供确认，然后在内部运行未脱敏的版本。对于需要敏感值的命令（例如

helm install --set apiKey=...

），优先通过临时文件、标准输入或环境变量传递敏感信息，而非命令行参数，以避免暴露在Shell历史中。

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.

如果资源已存在（命名空间、Helm版本、ConfigMap），跳过创建步骤并注明该资源已存在。不要失败或尝试删除后重新创建。

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.

切勿显示完整的API密钥、令牌或密码。仅显示首尾4个字符（例如

oodl...k9x2

）。当从规范中渲染配置模板时，在展示给用户前脱敏敏感值。

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
```
)

所有步骤完成且验证通过后，呈现总结：

集成类型和名称
已安装/配置的内容
当前状态
后续如何检查状态（
```
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

```
references/environment-discovery.md
```
——基础设施检测和设置步骤调整
```
references/gotchas.md
```
——执行设置前需查看的关键注意事项
```
references/post-install-validation.md
```
——使用查询技能验证数据存在性
```
references/failure-handling.md
```
——常见失败场景的故障排除
Oodle CLI仓库——
```
oodle
```
二进制文件的来源
Oodle文档——产品文档
oodle-cli技能——核心CLI用法、认证、输出格式