telegram-agent

Full-agent Telegram bot: restart workloads and trigger reruns from a chat message. Runs as a pod in K3s, no public exposure.

How it reaches the outside world (and vice versa)

• Telegram: long polling (getUpdates), not a webhook — the pod only makes outbound HTTPS to api.telegram.org. No Service, no MetalLB IP, no Caddy route. Nothing on the internet can reach this pod directly.
• Kubernetes API: in-cluster, via the auto-mounted ServiceAccount token — no kubeconfig to manage.
• Forgejo: outbound HTTPS to git.yukselcloud.com's API, using a fine-grained token (Actions:write, scoped to lab/homelab only).

Safety model

• Chat-ID allowlist: every incoming update is checked against TELEGRAM_AUTHORIZED_CHAT_ID; anything else is silently ignored.
• Confirm before acting: /restart and /rerun stage the action and wait up to 60s for a plain yes reply from the same chat before doing anything. /status is read-only and doesn't need confirmation.
• Namespace allowlist: hardcoded in app/config.go, kept in sync with which namespaces have a telegram-agent-actions RoleBinding applied. Changing what the bot can touch means a code change through the normal GitOps review, not a live config edit.
• Least-privilege RBAC: a purpose-built ClusterRole (clusterrole-actions.yaml) with only the verbs /restart and /rerun actually need — not the built-in edit role.

Commands

/status <namespace>
/restart <namespace> <deployment|statefulset|daemonset> <name>
/rerun k8s <namespace> <cronjob>
/rerun ci <workflow-file.yaml> [ref, default main]
/fressi <status|check>

Setup

1. Get a bot token from @BotFather, and your numeric chat ID from @userinfobot.

2. Mint a Forgejo fine-grained token scoped to lab/homelab, Actions: Read and Write only.

3. Add workflow_dispatch: to the on: block of any .forgejo/workflows/* file you want /rerun ci able to trigger — the existing push-only workflows can't be dispatched via API as-is.

4. Apply the manifests (or let the GitOps workflow do it after first push):

   kubectl apply -f manifests/namespace.yaml
   kubectl apply -f manifests/serviceaccount.yaml
   kubectl apply -f manifests/clusterrolebinding-view.yaml
   kubectl apply -f manifests/clusterrole-actions.yaml
   kubectl apply -f manifests/rolebinding-media-actions.yaml
   kubectl apply -f manifests/rolebinding-monitoring-actions.yaml
   

5. Create the real Secret (never commit it — see the comment in manifests/secret-bot-config.yaml.example):

   kubectl -n telegram-agent create secret generic telegram-agent-config \
     --from-literal=TELEGRAM_BOT_TOKEN='...' \
     --from-literal=TELEGRAM_AUTHORIZED_CHAT_ID='...' \
     --from-literal=FORGEJO_TOKEN='...' \
     --from-literal=FORGEJO_BASE_URL='https://git.yukselcloud.com' \
     --from-literal=FORGEJO_OWNER='lab' \
     --from-literal=FORGEJO_REPO='homelab'
   

6. kubectl apply -f manifests/deployment.yaml, or push and let .forgejo/workflows/deploy-telegram-agent.yaml do it — check the comment at the top of that workflow first: it assumes the runner can build/push a Docker image directly, which hasn't been verified against how this cluster's runner is actually set up.

Extending it with push notifications later

homelab-event-collector already plans to notify via ntfy once its ingress layer (webhook + K8s watcher) is built. Once that's routing events through Redis/Redpanda, adding Telegram as a second sink is small: a goroutine here subscribing to the same channel and calling SendMessage. Not built yet because the upstream pipeline isn't either — no point guessing its shape before it exists.

Adding a new managed namespace

1. Copy manifests/rolebinding-media-actions.yaml, change the namespace, apply it.
2. Add the namespace to AllowedNamespaces in app/config.go, redeploy.

Both steps are required — RBAC without the app-level allowlist just means the bot tries and gets a 403; the allowlist without RBAC means a confusing in-cluster permission error instead of a clean "not allowed" reply.