yandex-cloud

Three rules first, because they are the ones that waste a whole investigation when they are missed.

Read kubernetes_get_events before naming a cause for any pod that is not Running. The pod list shows only that it is stuck. Every reason looks identical there — out of memory, unschedulable, an image that will not pull, a volume that will not mount. The event carries the actual message, and guessing between them produces a confident wrong answer that sends someone to check node capacity when the registry was refusing the pull. Pending with no events about resources is an image or volume problem, not a scheduling one.

A pod is not a Yandex Cloud resource. The Yandex Cloud API knows the Kubernetes cluster — version, health, node groups, read with execute_yc_operation on /managed-kubernetes/ — and nothing about what runs inside it. Neither execute_yc_operation nor find_yc_api can reach a pod, an event or a container log, and no /managed-kubernetes/ path returns one. Read those with kubernetes_list_pods, kubernetes_get_events, kubernetes_get_pod_logs and kubernetes_list_nodes, which talk to the cluster's own API server. If those tools are absent, Managed Kubernetes access was not connected during setup — say so rather than trying the Yandex Cloud API instead.

Never run yc via a shell tool. It is normally not installed, it needs its own separate authentication, and it can mutate. If you catch yourself writing yc ... to answer a question, use execute_yc_operation instead.

Everything else reaches Yandex Cloud over its REST API with the configured credential. There is no CLI step and no shell step.

What a connected yandex_cloud means

yandex_cloud appears once in the connected-integrations list, but it is an umbrella. When it is connected you can already read all of this — do not tell the user a piece of it "is not configured":

Monitoring is configured whenever Yandex Cloud is configured — it shares one credential. Cloud Logging group lists use that same REST credential. Reading log entries needs the optional install extra opensre[yandex_cloud_logs] (gRPC stubs for the log reader host). Without it, read_yc_logs fails closed and tells you to install the extra; do not tell the user logging "is not configured" when the umbrella integration is connected and only the entry-reader extra is missing.

Reading anything

find_yc_api indexes ~940 read endpoints across 68 services, generated from Yandex's own protobuf definitions. It is the answer to "what is the path for X", so use it rather than guessing:

1. find_yc_api with the resource in plain words — security groups, postgresql clusters, node group, certificates.
2. execute_yc_operation with the service and path it returned.
3. A path with a {placeholder} needs an id. Call the list endpoint on the same service first and take the id from there.

Reads only. Every mutating operation uses a different HTTP verb and the client refuses those, so there is no way to change anything here. When the answer is that something should change, give the user the exact yc ... command to run themselves — writing that command out is correct, running it is not.

Kubernetes workloads are not in the Yandex Cloud API

The Yandex Cloud API knows about the cluster — its version, health, node groups, maintenance window. It knows nothing about what runs inside it. There is no endpoint for pods, and searching for one wastes the investigation:

A pod is not a Yandex Cloud resource. execute_yc_operation and find_yc_api cannot reach one, and neither can any /managed-kubernetes/ path.

Workloads are read with the kubernetes_* tools, which talk to the cluster's own API server:

So an incident in a Managed Kubernetes cluster is usually two reads, in this order:

1. execute_yc_operation on /managed-kubernetes/v1/clusters — is the control plane itself healthy? A degraded master explains everything below it, and nothing else needs checking.
2. kubernetes_list_pods and kubernetes_get_events — what is actually wrong with the workload.

These tools appear only when a cluster was connected during setup. If they are absent, say that Managed Kubernetes access is not configured and that opensre integrations setup kubernetes connects it — do not fall back to execute_yc_operation and report that pods cannot be read.

A pod stuck in Pending has no logs at all: the container never started, so the API answers 400, not 403. Read its events instead — that is where the reason is.

Logs live in four different places

There is no single log store, so an empty read_yc_logs is a statement about Cloud Logging and nothing else. Where to look depends on who wrote the log:

So the search order for "why did this break" is: ask the owning service first, then Cloud Logging. Doing it the other way round produces a confident "no logs found" for a database that has been logging all along.

Managed-database logs are not reachable from this tree yet. When a database question needs them, say so plainly and fall back to metrics and to the cluster state read through execute_yc_operation on /managed-<engine>/, rather than reporting Cloud Logging's silence as "no logs".

Export to Cloud Logging is optional and off unless someone enabled it. If a managed service has no log group, that is a configuration fact worth reporting — not evidence the service is silent.

Before saying something cannot be read, ask find_yc_api.

Never answer by telling the user to install or run the yc CLI. If the CLI can read it, so can this agent — the CLI is a client of the same REST API, and the path is in the index.

A past incident needs an explicit window

Every reader defaults to a window ending now. Asked about an incident on a given date, pass that date as the window that reader actually accepts — query_yc_metrics takes from_time and to_time; read_yc_logs takes since and until. window_minutes counts back from the present and will silently return nothing for anything older, which reads as "no evidence" rather than "wrong window".

Retention differs by source, and an empty result means different things:

So for an incident weeks back, metrics are usually the only surviving evidence, and they are worth querying with the exact window before concluding anything. Cluster operation history (/managed-*/v1/clusters/{id}/operations) outlives logs too and shows maintenance and failovers.

Answering well

• Query first, then answer. Infrastructure questions are answered from live reads, never from what you remember about Yandex Cloud in general.
• Say what you actually read. Name the folder, the resource ids, the time window. "CPU on build-vm averaged 140% over the last hour (2 cores)" beats "CPU looks high".
• An empty list is an answer. "No managed database clusters in this folder" is a finding; do not present it as a failure or a missing integration.
• One folder at a time. Every read is scoped to the configured folder. Reading a different one means passing folderId explicitly to execute_yc_operation; the folder list is at /resource-manager/v1/folders with cloudId.
• A bare 404 usually means a wrong parameter, not a missing resource — a single-resource read rejects folderId and pageSize. Re-read the path shape before telling the user the resource does not exist.

Metrics

query_yc_metrics takes a Yandex Monitoring query: "cpu_usage"{service="compute"}, narrowed by labels such as resource_id, device, subcluster_name.

It is not PromQL. sum by (...), rate(x[5m]) and topk(...) come back as parse errors, not empty results. Aggregate with Yandex's own functions:

The folder label is folder_id. Writing folderId is accepted and matches nothing, so it looks like the metric has no data rather than like a mistake.

Metrics the user pushes themselves live under service="custom", and the default metric listing does not include them. So list_yc_metrics returning nothing is not evidence a metric is missing — search again with selectors='service="custom"' before saying it does not exist. The tool says so in its own output when a search comes back empty; believe it rather than repeating the same call with a different name filter.