Document KHI job mode

[Haihan-Jiang]

Summary

• add a setup guide for running KHI in job mode
• document the required job mode flags, supported inspection type IDs, and a basic GKE example
• link the new guide from the README user guide section

Fixes #196

Tests

• go test ./pkg/parameters
• git diff --check

[gemini-code-assist]

Code Review

This pull request introduces documentation for running KHI in job mode. It adds a new guide, docs/en/setup-guide/job-mode.md, which details the required flags, command format, inspection values, and feature selection, and updates README.md to link to this new guide. There are no review comments, and I have no feedback to provide.

[Haihan-Jiang]

This is ready for review from my side. The remaining github-deploy-ondemand check appears to require project-side approval/run permissions; could someone take a look or trigger it when convenient?

[kyasbal]

I think the most difficult part of this feature is building the --job-inspection-values parameter.
The current easiest way is using dev tool on browser to see what is sent from the frontend. It's a little hacky way but worth to be documented.

[Haihan-Jiang]

Addressed in 18e401e. The guide now keeps the browser dev tools /run or /dryrun payload workflow, clarifies that set-form fields must be JSON arrays, and updates the GKE example to use the same field IDs/value shapes that job mode expects. I also added a table of extra fields required when optional GKE features are enabled.

[kyasbal]

It would be better if we can show the example workable job command with the full parameter.
The current example lacks of many parameters and user need to find what are missing. It'll be nicer if we can list keys required for actually running the job mode. Values for the parameters can be placeholder then.

[Haihan-Jiang]

Also addressed in 18e401e. I replaced the ALL example with an explicit default GKE feature list and a payload that uses the full required field set for that selected feature set. The guide now also lists the extra field keys to include when optional GKE features are enabled or when ALL is used.

[Haihan-Jiang]

Thanks, I updated the job mode doc in two places:

• added a practical way to build --job-inspection-values from the browser dev tools request payload for /run or /dryrun
• expanded the GKE example to include concrete common field IDs such as project, location, cluster name, namespaces, and kinds

I kept the wording scoped because the exact required fields still depend on the selected inspection type and enabled features.

[kyasbal]

The current example parameter list is still missing several fields. How about asking your codex to run the job to test?

[Haihan-Jiang]

Thanks, I asked Codex to run the job-mode command and it found two concrete issues in the example.

Fixed in 18e401e:

• set-form values such as cloud.google.com/k8s/input-namespaces and cloud.google.com/k8s/input-kinds must be JSON arrays, not scalar strings. The previous example fails with request parameter cloud.google.com/k8s/input-kinds#default was not given in array.
• ALL enables optional GKE features that are disabled by default in the UI, so the runnable default GKE example now uses an explicit feature ID list. I also added the extra fields needed when optional features such as node, container, control plane, CSM, and serial port logs are selected.

Validation performed locally:

• npx markdownlint-cli2 docs/en/setup-guide/job-mode.md -> 0 errors.
• Re-ran job mode with the corrected payload and explicit default GKE feature list. It now gets past the form parameter parsing and stops at local ADC setup: failed to create monitoring metric client: credentials: could not find default credentials. I do not have ADC configured in this local environment, so I could not complete a Cloud Logging-backed export here, but the prior parameter-shape failure is fixed.

[kyasbal]

I'm sorry to return this back again and again. However, this example query must generate the empty result even if the target project and cluster actually exist because resource names input are missing.

We can find the right parameters from chrome inspector when we fills parameters on the form.

Thus parameters beginning with cloud.google.com/common/input-query-resource-names would be necessary to be filled with projects/<the-proejct-id>. This is not great from user experience perspective but for considering the project forwarding its logs to the other projects, KHI receives target project for each queries. These are usually optional field on the UI and automatically filed from the other project ID field. But it's still required for the job mode. Indeed this behavior must be improved in near future...