Flink Ops

Flink Ops

Give a host agent shared Apache Flink operations capability.

MANDATORY EXECUTION RULE: When this skill is triggered, use only this skill's bundled Java CLI:

com.skill.flinkops.FlinkOpsCli

Never use kubectl, flink run-application, Flink shell scripts, hand-written Kubernetes manifests, Flink Operator CRDs, cloud CLIs, or ad hoc scripts as substitutes for skill execution. This rule applies to discovery, preflight, submission, verification, logs, status, and troubleshooting. If the bundled CLI cannot answer or perform an action, report the missing capability instead of switching tools.

The key boundary is:

• Common operations use Flink REST and work for Kubernetes, YARN, standalone, or

any deployment target that exposes a JobManager REST URL.

• Deployment operations are provider-specific. The MVP implements

--deployment-target kubernetes with Flink native Kubernetes application mode.

Resolve Runtime Paths

Before running any command, resolve SKILL_DIR as the directory that contains this SKILL.md. Do not assume the current working directory is the skill directory.

Examples:

• Codex global install: $HOME/.codex/skills/flink-intelligent-ops
• Claude Code global install: $HOME/.claude/skills/flink-intelligent-ops
• Project-local install: /skills/flink-intelligent-ops

Resolve runtime dependencies from the user's input, environment, or the selected deployment provider reference. Do not assume a provider-specific runtime rule applies to every deployment target.

Common Flink REST reads use the bundled jar directly:

"$JAVA_HOME/bin/java" -jar "$SKILL_DIR/scripts/target/flink-intelligent-ops.jar"  [args]

Provider-specific start operations may require extra classpath entries or environment variables. Load the provider reference before running a provider start command. Kubernetes start includes the Flink runtime jars on the JVM classpath.

"$JAVA_HOME/bin/java" -cp "$SKILL_DIR/scripts/target/flink-intelligent-ops.jar:" \
  com.skill.flinkops.FlinkOpsCli  [provider args]

Kubernetes start must use:

"$JAVA_HOME/bin/java" -cp "$SKILL_DIR/scripts/target/flink-intelligent-ops.jar:$FLINK_HOME/lib/*" \
  com.skill.flinkops.FlinkOpsCli k8s_start_job [args]

Scope

Common operations:

• inspect_cluster --job-manager-url [--deployment-target kubernetes --namespace "$K8S_NAMESPACE"] [--job-id ] [--http-host-header ] [--report]
• get_job_status --job-manager-url [--job-id ] [--http-host-header ]
• diagnose_job --job-manager-url [--job-id ] [--http-host-header ] [--report]
• diagnose_backpressure --job-manager-url --job-id [--vertex-id ] [--http-host-header ] [--report]
• get_exceptions --job-manager-url --job-id [--http-host-header ]
• get_checkpoints --job-manager-url --job-id [--http-host-header ]

Kubernetes provider operations use explicit k8s_* commands and do not require --deployment-target:

• k8s_preflight_start --namespace "$K8S_NAMESPACE" --service-account "$K8S_SERVICE_ACCOUNT" --flink-home "$FLINK_HOME" --kubeconfig-path "$KUBECONFIG_PATH" [--enable-ingress ]
• k8s_check_connectivity --namespace "$K8S_NAMESPACE" --service-account "$K8S_SERVICE_ACCOUNT" --kubeconfig-path "$KUBECONFIG_PATH" [--enable-ingress ]
• yarn_check_connectivity [--hadoop-conf-dir ] [--yarn-queue ] [--yarn-provided-lib-dirs ] [--flink-dist-jar ]
• "$JAVA_HOME/bin/java" -jar "$SKILL_DIR/scripts/target/flink-intelligent-ops.jar" check_cli_environment --deployment-target --flink-home "$FLINK_HOME"
• k8s_check_ingress_controller --namespace "$K8S_NAMESPACE"

returns namespace-scoped Ingress Controller readiness, IngressClass status, and the Controller Service NodePort values when the service is present.

• k8s_get_node_ips returns Kubernetes node

InternalIP, ExternalIP, and Hostname values for constructing agent-side NodePort URLs.

• k8s_render_ingress_controller_yaml --namespace "$K8S_NAMESPACE"

Packaging operations:

• k8s_build_image --base-image --local-jar --target-image [--target-jar-path ]

Deployment operations:

• k8s_start_job ...
• stop_job --job-manager-url --job-id ...
• Stop uses common Flink REST semantics after the JobManager URL is known and

does not require a deployment target.

• Add --verify to k8s_start_job or stop_job when the user asks for read-back

verification. The CLI reads the target REST endpoint after mutation and returns readBackVerification.

• Mutating operations return targetLock.targetFingerprint. Use

--expected-target-lock on execution after a preview when the user wants strict target locking.

For Kubernetes k8s_start_job, startup includes mandatory environment preflight and Ingress creation. Do not ask for all start parameters at once. The CLI checks the namespace, service account, namespace-scoped Ingress Controller, and namespace-specific IngressClass before submitting Flink. After submission, it creates or updates an Ingress for .flink.k8s.com.

Kubernetes credentials are path-only. The agent may pass --kubeconfig-path when the user provides a kubeconfig file path; otherwise the CLI defaults to ~/.kube/config. The agent must not read or ask the user to paste kubeconfig content. The CLI loads the file directly into the Kubernetes SDK client and has no serialization path for kubeconfig content in stdout, stderr, JSON responses, errors, debug logs, reports, or exception messages.

Ingress can be disabled only when the user explicitly chooses not to expose the Flink REST/Web UI externally:

--enable-ingress false

When disabled, k8s_start_job skips Ingress Controller and IngressClass checks, does not create an Ingress, and returns the internal JobManager REST Service URL instead.

Out of scope for this version:

• YARN deployment implementation.
• Flink SQL Gateway operations.
• Installing Kubernetes or the Flink operator.
• Deleting Kubernetes resources.
• Auto remediation.

Execution Modes

• Real Ops Mode: default for real operations. Do not use placeholder IDs,

namespaces, REST URLs, images, providers, or jar values. Collect missing parameters by category. Mutations require explicit confirmation of the final FlinkOpsCli command before adding --confirm.

• Boundary Mode: for out-of-scope requests. Return boundary guidance only and

do not execute a command.

Execution Rules

• Execute the bundled Java CLI for read operations and approved mutations. For

mutations, never execute the real command before parameter collection and user confirmation are complete.

• For k8s_start_job, the final command must use

"$JAVA_HOME/bin/java" -cp "$SKILL_DIR/scripts/target/flink-intelligent-ops.jar:$FLINK_HOME/lib/*" with com.skill.flinkops.FlinkOpsCli.

• When required parameters are missing, never ask with bare flag names only.

Explain every requested parameter before asking the user to provide it. Use this format for each parameter: flag name, what it means, where the user can get it, an example value, and any important caveat. The user should not have to infer domain meaning from English CLI flag names.

• Ask for only one category of parameters per user turn. Do not mix readiness

checks, Ingress remediation choices, image packaging, start configuration, and mutation confirmation in the same question. For a fresh deployment request, the first question should not ask for injected Kubernetes readiness inputs. Use --namespace "$K8S_NAMESPACE", --service-account "$K8S_SERVICE_ACCOUNT", optional --kubeconfig-path "$KUBECONFIG_PATH", and --flink-home "$FLINK_HOME" as runtime placeholders. Do not ask for --name, --parallelism, --flink-image, --main-class, build image choices, or confirmation in the first question.

• For provider starts, first identify the target provider, then load the

matching provider reference. Kubernetes uses k8s_* commands. YARN will use yarn_* commands when implemented.

• Do not treat provider commands as common commands. k8s_get_node_ips,

k8s_check_ingress_controller, k8s_render_ingress_controller_yaml, k8s_preflight_start, k8s_build_image, and k8s_start_job are Kubernetes-provider commands and must not include --deployment-target. Common Flink REST commands use --job-manager-url and do not require a deployment target.

• Classify the user's intent before selecting a command. Requests such as

deploy, start, submit, run, 启动, 部署, 提交, or 运行 with a jar/application are deployment intents. For Kubernetes, a new deployment intent maps first to the readiness flow when readiness is not visible: k8s_check_ingress_controller, then k8s_preflight_start with the derived --enable-ingress value, then optionally k8s_build_image, then k8s_start_job.

• Use get_job_status only for inspection of an existing JobManager REST URL:

the user must provide the URL, or the URL must come from a visible successful k8s_start_job result in the current conversation. Do not infer a REST URL from a local jar path, --flink-home, examples, or common defaults.

• Use inspect_cluster for one-shot inspection requests such as 巡检, health

check, pre-event check, or "give me a report" when a JobManager REST URL is known. With Kubernetes namespace context, it also checks the namespace-scoped Ingress Controller and node addresses. With --report, summarize collected evidence into health status, risk level, findings, root cause candidates, and recommendations. The inspection evidence set follows Flink 1.19 focused REST paths: /overview, /config, /taskmanagers, /jobs, and when a job ID is provided, job status/config/plan, restart metrics, exceptions, and checkpoints.

• Use diagnose_job --report when the user wants a diagnosis report instead of

raw REST evidence. The report flags failed states, root exceptions, checkpoint timeouts/failures, exhausted slots, blocked TaskManagers, and restart metrics. Use diagnose_backpressure for suspected backpressure. It follows Flink 1.19 REST paths: /jobs/:jobid for vertex discovery, /jobs/:jobid/vertices/:vertexid/backpressure, vertex subtask metrics for backpressured/busy/idle time, exceptions, and checkpoints. If no direct vertex or metric-level evidence is available, report unknown instead of guessing.

• Do not rely on stale conversation memory for environment readiness. If the

current visible context does not include a recent successful check result for the same namespace, service account, Ingress setting, and runtime path, run the relevant FlinkOpsCli check again before mutation. Long conversations may drop earlier check results.

• For a new deployment request, environment readiness comes before final start

parameter collection. If the current visible context has no recent successful readiness result, do not collect Kubernetes readiness fields from the user. Use --namespace "$K8S_NAMESPACE", --service-account "$K8S_SERVICE_ACCOUNT", optional --kubeconfig-path "$KUBECONFIG_PATH", and --flink-home "$FLINK_HOME" because these environment variables will be injected later. Do not ask for --enable-ingress up front; derive it from the Ingress Controller check. Run k8s_check_ingress_controller --namespace "$K8S_NAMESPACE" first. If a controller exists, run k8s_check_connectivity and check_cli_environment, then k8s_preflight_start with --enable-ingress true. If it is missing, show both CLI-provided remediation options when present: helmCommands and the kubectl path (kubectlTemplatePath, kubectlManualRenderCommands, and kubectlManualApplyCommands). The YAML template is built into the skill under assets/kubernetes/ingress-controller.yaml.tpl; do not run Helm or kubectl. Ask whether the user wants to create the namespace-scoped Ingress Controller. If the user chooses the kubectl path, do not execute the render command, do not write the YAML file, and do not execute kubectl apply. Recommend the displayed manual render/apply commands for the user or platform administrator to run, then wait. The next agent step after the user says they applied it is rerunning k8s_check_ingress_controller. If the user declines, continue with --enable-ingress false. After readiness is known, collect the remaining k8s_start_job parameters.

• For start/stop execution after a dry-run preview, preserve the returned

targetLock.targetFingerprint and pass it as --expected-target-lock when the user wants target drift protection. A mismatch means the namespace, job URL, job id, host header, or operation target changed and the CLI must not proceed.

• Use check_cli_environment for the local CLI, Java, and Flink runtime

checks needed by the submit chain. k8s_preflight_start includes those checks in its combined Kubernetes start readiness output.

• Do not use any external CLI for preflight or verification. In particular,

kubectl is prohibited in all scenarios, including harmless-looking commands such as kubectl config current-context, kubectl get ns, kubectl logs, and kubectl get events.

• Do not fallback to an unrelated deployment mechanism when the selected

provider path fails. Report the exact error and the missing skill capability or missing parameter.

• Do not fabricate Kubernetes, Flink, checkpoint, exception, or savepoint state.
• Use --dry-run when the user asks for a preview or when no real cluster

should be touched.

• Read operations do not require confirmation.
• Mutating operations require an explicit pre-execution confirmation in the

current turn. Direct user intent is not enough by itself. First show the final command that will run, then wait for the user to confirm, then execute with --confirm.

• Never print kubeconfig, tokens, certificates, or cloud credentials.

Command Quick Reference

| User intent | Command | Type | |-------------|---------|------| | Check namespace Ingress Controller and NodePort | k8s_check_ingress_controller --namespace "$K8S_NAMESPACE" | Read | | Check Kubernetes deployment target connectivity | k8s_check_connectivity --namespace "$K8S_NAMESPACE" --service-account "$K8S_SERVICE_ACCOUNT" --kubeconfig-path "$KUBECONFIG_PATH" --enable-ingress | Read | | Check YARN deployment target connectivity | yarn_check_connectivity [--hadoop-conf-dir ] [--yarn-queue ] [--yarn-provided-lib-dirs ] [--flink-dist-jar ] | Read | | Check CLI execution environment | "$JAVA_HOME/bin/java" -jar "$SKILL_DIR/scripts/target/flink-intelligent-ops.jar" check_cli_environment --deployment-target --flink-home "$FLINK_HOME" | Read | | Get Kubernetes node IPs | k8s_get_node_ips | Read | | Render namespace Ingress Controller YAML | k8s_render_ingress_controller_yaml --namespace "$K8S_NAMESPACE" | Read | | Check combined Kubernetes start readiness | k8s_preflight_start --namespace "$K8S_NAMESPACE" --service-account "$K8S_SERVICE_ACCOUNT" --flink-home "$FLINK_HOME" --kubeconfig-path "$KUBECONFIG_PATH" --enable-ingress | Read | | Build Flink image with local jar | k8s_build_image --base-image --local-jar --target-image [--target-jar-path ] | Mutation | | Start Flink job on Kubernetes | k8s_start_job ... | Mutation | | Stop Flink job | stop_job --job-manager-url --job-id --stop-mode cancel [--http-host-header ] | Mutation | | Stop with savepoint | stop_job --job-manager-url --job-id --stop-mode savepoint --savepoint-dir [--http-host-header ] | Mutation | | Get status | get_job_status --job-manager-url [--job-id ] [--http-host-header ] | Read | | Diagnose job | diagnose_job --job-manager-url [--job-id ] [--http-host-header ] | Read | | Get exceptions | get_exceptions --job-manager-url --job-id [--http-host-header ] | Read | | Get checkpoints | get_checkpoints --job-manager-url --job-id [--http-host-header ] | Read |

Common deployment parameters:

--deploym

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TKilome](https://github.com/TKilome)
- **Source:** [TKilome/skillbound-skills](https://github.com/TKilome/skillbound-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.