feat: add openab-feishu chart

[wangyuyan-agent]

Summary

Adds charts/openab-feishu/ — a standalone Helm chart that deploys OAB + Gateway in a single pod for Feishu (飛書) and Lark, following the same pattern as openab-telegram (#873).

Install

helm install my-bot ./charts/openab-feishu \
  --set feishu.appId="cli_xxx" \
  --set feishu.appSecret="xxx" \
  --namespace openab --create-namespace

Only 2 required flags. Everything else has sane defaults.

Credential Management

Three options from simplest to most secure:

#	Method	Security	Notes
1	--set feishu.appId=X --set feishu.appSecret=Y	⚠️ Stored in Helm release Secret, visible via helm get values	Good for dev/testing
2	kubectl create secret --from-literal + --set existingSecret=name	✅ Out of Helm values, brief shell exposure	Good for production
3	kubectl create secret --from-env-file=<(aws sm ...) + --set existingSecret=name	✅✅ Never touches disk or shell variables	Best for security

Release Channel

channel	Core image tag	Gateway image tag
stable (default)	ghcr.io/openabdev/openab:stable	v0.5.1 (pinned)
beta	ghcr.io/openabdev/openab:beta	v0.5.1 (pinned)

Gateway is pinned independently since it has its own release cadence (gateway-v* tags).

Key Differences from openab-telegram

	openab-telegram	openab-feishu
Default containers	3 (agent + gateway + cloudflared)	2 (agent + gateway)
Public endpoint	Required (webhook)	Not needed (WebSocket)
Tunnel sidecar	Always	Optional (webhook mode only)
Credential count	2 (botToken + tunnelToken)	2 (appId + appSecret)
Domain switch	N/A	feishu (China) / lark (overseas)

What it does

• Colocates 2 containers in one pod: openab (agent) + gateway (Feishu adapter)
• WebSocket mode (default): gateway connects outbound, zero public infra needed
• Optional webhook mode: adds cloudflared sidecar (3 containers)
• Supports both Feishu (feishu.cn) and Lark (larksuite.com) via feishu.domain
• existingSecret support — reference a pre-created K8s Secret, chart skips Secret creation
• Security contexts (non-root, read-only rootfs, drop all caps)
• Post-install NOTES.txt with platform setup and auth instructions
• PVC retained on helm uninstall (auth credentials persist)

Design Decision

Default WebSocket mode — the gateway connects outbound to Feishu, eliminating the need for a public endpoint, Cloudflare account, or tunnel configuration. This makes the Feishu chart the simplest platform chart (fewer containers, fewer dependencies).

This is a standalone chart (not a subchart wrapper) for the same reasons as openab-telegram:

1. Full control over the pod spec
2. Simpler to understand and maintain
3. The config.toml surface is much smaller (gateway-only, no Discord/Slack)

Tested

• helm lint ✅
• helm template (WebSocket mode, 2 containers) ✅
• helm template (webhook mode, 3 containers with cloudflared) ✅
• Required value validation (fails fast with clear error) ✅
• existingSecret mode (skips Secret, references external) ✅
• Channel switching (stable / beta) resolves correct tags ✅
• Live deployment on K3s — installed, gateway connected to Feishu WebSocket, messages received and replied successfully ✅

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1500160821567684660

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: feat: add openab-feishu chart
• Source: feat: add openab-feishu chart #883
• Status: moved to PR-Screening
• Generated at: 2026-05-21T10:04:11.309Z
• Discord thread: not available

Screening report

screened PR #883 and moved the project item to `PR-Screening`.

GitHub comment: #883 (comment)
Project action: PVTI_lADOEFbZWM4BUUALzgtX-bw moved Incoming -> PR-Screening in openabdev/1

Intent

Add a standalone charts/openab-feishu/ Helm chart so OpenAB can be deployed for Feishu/Lark with the OpenAB agent and Feishu gateway in one pod. The operator-visible problem is deployment friction: Feishu can use outbound WebSocket mode, so deployers should not need a public webhook endpoint or Cloudflare tunnel for the default path.

Feat

Feature / release packaging. This PR adds a new Helm chart with values, Secret handling, ConfigMap rendering, Deployment, PVC, install notes, and README docs for Feishu/Lark deployments. Default behavior is two containers (openab + gateway) in WebSocket mode, with optional webhook mode adding cloudflared.

Who It Serves

Primarily deployers and agent runtime operators who want to run OpenAB on Feishu or Lark. Secondarily Feishu/Lark users, because a lower-friction install path makes that adapter easier to adopt and support.

Rewritten Prompt

Implement a standalone Helm chart at charts/openab-feishu/ for deploying OpenAB with the Feishu gateway. The chart must support Feishu and Lark domains, default to WebSocket mode without public ingress, optionally support webhook mode with a tunnel sidecar, allow credentials either through generated chart Secrets or an existingSecret, render a minimal gateway-only config.toml, persist agent state on a PVC, and document install/security tradeoffs. Validate with helm lint, helm template for WebSocket and webhook modes, missing-required-value failures, existingSecret rendering, and stable/beta channel image tag selection.

Merge Pitch

This is worth advancing because it extends OpenAB platform coverage with a deployment path that is materially simpler than webhook-based adapters. The risk profile is moderate but bounded: it is a new chart tree, not a core runtime change. Likely reviewer concerns are chart duplication with openab-telegram, whether credential handling is safe enough for production guidance, whether gateway image pinning is intentional, and whether PVC retention/security contexts are rendered correctly across both WebSocket and webhook modes.

Best-Practice Comparison

OpenClaw and Hermes Agent mostly do not apply directly here because this PR is deployment packaging, not scheduling, durable job execution, retry routing, or session orchestration. The relevant overlap is operational clarity: OpenClaw favors explicit delivery routing and run visibility, while Hermes favors self-contained prompts/state. This chart partially aligns by making Feishu vs Lark routing explicit via feishu.domain, keeping deployment state self-contained through a PVC, and isolating credentials via existingSecret; it does not add new retry/backoff, run logs, gateway scheduling, or durable job semantics, and should not be expected to.

Implementation Options

1. Conservative: merge a standalone Feishu chart after focused Helm review, keeping it intentionally parallel to openab-telegram and avoiding shared abstractions until more platform charts stabilize.
2. Balanced: merge the standalone chart now, but require small hardening before merge: template checks for all modes, clearer existingSecret key expectations, explicit gateway tag rationale, and a follow-up issue for shared chart conventions.
3. Ambitious: pause and extract a reusable platform-chart library or parent chart that covers Telegram/Feishu/Lark-style deployments with adapter-specific values layered on top.

Comparison Table

Option	Speed	Complexity	Reliability	Maintainability	User Impact	Fit for OpenAB now
Conservative standalone merge	High	Low	Medium	Medium	High	Good if chart review is clean
Balanced merge + hardening	Medium	Medium	High	High	High	Best fit
Shared platform chart first	Low	High	Medium initially, high later	High later	Delayed	Too heavy before patterns settle

Recommendation

Take the balanced path. Advance this to review, verify the rendered manifests against both WebSocket and webhook modes, and ask reviewers to focus on Secret behavior, image tags, PVC retention, security contexts, and drift from openab-telegram. Do not block this on a shared chart abstraction yet; open a follow-up once Feishu and Telegram chart differences are better understood.

[wangyuyan-agent]

Thanks for the thorough review! All findings addressed in de5bc86.

Changes Made

🔴 F1 — existingSecret + webhook mode silently dropped verification/encrypt env vars

FEISHU_VERIFICATION_TOKEN and FEISHU_ENCRYPT_KEY are now rendered whenever connectionMode=webhook, regardless of whether the values are set in Helm values. Added optional: true so pods start cleanly even if those keys are absent from the secret (both fields are optional security hardening, not required for gateway startup).

🟡 F2 — Boolean default trap in reactions config

Removed | default true/false pipes from configmap.yaml. Defaults are already declared in values.yaml; the pipes caused false to be treated as empty and substituted with true, making agent.reactions.enabled: false impossible to set.

🔴 BUG1 — tunnel.enabled=true without token caused silent CrashLoop

Added a {{- fail }} guard in deployment.yaml that aborts helm install/helm template with a clear error message when the tunnel is enabled but no tunnel.token is provided and no existingSecret is set. (The existingSecret path is allowed through since the token may live in the external secret.)

🟡 BUG2 — storageClass: "-" rendered as literal "-" storageClassName

Applied the standard Helm convention in pvc.yaml: "-" maps to storageClassName: "" (static PV / empty storage class); any other non-empty value passes through as-is.

🟡 BUG3 — checksum/secret annotation had wrong semantics in existingSecret mode

When existingSecret is set, secret.yaml renders empty and the checksum was a constant hash — meaning external secret rotations would not trigger a rolling restart. The annotation is now skipped when existingSecret is set.

🟡 BUG4 — TOML env map rendered in non-deterministic order

Replaced the manual $first-flag iteration with keys | sortAlpha + index lookup. Env keys now render alphabetically, eliminating spurious checksum/config diffs in GitOps pipelines.

---

All scenarios verified with helm lint and helm template:

• websocket mode (default, 2 containers) ✅
• webhook mode + chart-managed secret ✅
• webhook mode + existingSecret (all 4 secret refs render correctly) ✅
• tunnel.enabled=true without token → fast fail with clear message ✅
• tunnel.enabled=true with existingSecret → passes through ✅
• storageClass: "-" → storageClassName: "" ✅
• agent.reactions.enabled: false → renders false ✅
• env map with multiple keys → stable alphabetical order across runs ✅

[wangyuyan-agent]

One follow-up on BUG3 (94e1bc8): the fix in de5bc86 removed the misleading annotation — a constant hash that falsely implied secret changes would trigger rollouts. That part is resolved.

However, the underlying goal of «external secret rotation automatically triggers a Pod rollout» is not achievable at the Helm chart layer: Helm cannot read external Secret contents at render time, so there is no value to checksum.

The correct closure here is documentation. 94e1bc8 adds a comment to `existingSecret` in `values.yaml` that explicitly states: credential rotation will not trigger a rollout automatically, and users who need that behaviour should use Reloader with `reloader.stakater.com/auto: "true"` on the Deployment.

[chaodu-agent]

LGTM ✅ — All previous findings resolved. Feishu chart is production-ready.

What This PR Does

Adds charts/openab-feishu/ — a standalone Helm chart deploying OAB + Gateway for Feishu/Lark. WebSocket mode by default (no public endpoint needed), optional webhook mode with cloudflared sidecar.

How It Works

• 2-container pod (agent + gateway) for WebSocket; 3-container (+ cloudflared) for webhook
• existingSecret support with documented rotation limitation and Reloader guidance
• Security contexts: non-root, read-only rootfs, drop ALL caps, seccomp RuntimeDefault
• Follows openab-telegram chart pattern with improvements (sorted env keys, no boolean default trap)

Findings

#	Severity	Finding	Location
1	🟢	All 🔴/🟡 from previous review correctly fixed	de5bc86, 94e1bc8
2	🟢	WebSocket-first design eliminates public endpoint requirement	values.yaml
3	🟢	Comprehensive README with credential tiers, troubleshooting	README.md
4	🟢	Proper fail-fast validation (missing credentials, tunnel without token)	secret.yaml, deployment.yaml
5	🟢	Deterministic env rendering with sortAlpha	configmap.yaml:14

Previous Findings — Resolution Status

#	Original Finding	Status
🔴 F1	existingSecret + webhook mode dropped verification/encrypt env vars	✅ Fixed — renders secretKeyRef with optional: true whenever connectionMode=webhook
🔴 BUG1	tunnel.enabled without token → silent CrashLoop	✅ Fixed — fail guard aborts at render time
🟡 F2	Boolean default trap in reactions config	✅ Fixed — removed | default pipes
🟡 BUG2	storageClass "-" rendered as literal string	✅ Fixed — standard Helm convention
🟡 BUG3	checksum/secret misleading in existingSecret mode	✅ Fixed — annotation skipped + Reloader documented
🟡 BUG4	Non-deterministic env map order	✅ Fixed — keys | sortAlpha

Baseline Check

• PR opened: May 21, 2026
• Main has: charts/openab/ (multi-platform) + charts/openab-telegram/ — no Feishu chart
• Net-new: standalone Feishu/Lark chart with WebSocket-first design
• Fix commits: de5bc86 (all findings) + 94e1bc8 (rotation docs)
• Contributor verified all scenarios with helm lint + helm template

What's Good (🟢)

• WebSocket-first is the right default for Feishu — simpler than telegram (fewer containers, no tunnel dependency)
• Excellent documentation: prerequisites, credential tiers, webhook mode, Lark overseas, troubleshooting
• Security hardening: non-root, read-only rootfs, drop ALL caps, seccomp RuntimeDefault
• existingSecret rotation limitation honestly documented with actionable Reloader guidance
• Sorted env keys fix is an improvement the telegram chart should backport
• NOTES.txt provides clear post-install steps for both connection modes

Reviewed by: 超渡法師 · 覺渡法師