Every Flokoa resource — Agents, Models, ModelProviders, and AgentTools — is a standard Kubernetes object, which means the full power of kubectl is available to you out of the box. This page collects the most useful commands in one place so you can quickly find what you need without digging through kubectl --help. Commands are grouped by resource type, with a dedicated section for day-to-day debugging workflows.
Agents
Agents are the primary resource in Flokoa. Use the following commands to manage their full lifecycle.
# List agents in the current namespace
kubectl get agents
# List agents in a specific namespace
kubectl get agents -n my-namespace
# List agents across all namespaces
kubectl get agents --all-namespaces
# Show full details including status conditions
kubectl describe agent my-agent
# Print the full manifest as YAML
kubectl get agent my-agent -o yaml
# Stream status changes in real time
kubectl get agents -w
# Check the agent's current lifecycle phase (Pending / Running / Failed)
kubectl get agent my-agent -o jsonpath='{.status.phase}'
# Retrieve the stable in-cluster URL for the agent
kubectl get agent my-agent -o jsonpath='{.status.url}'
# Scale the number of replicas
kubectl patch agent my-agent --type='json' \
-p='[{"op": "replace", "path": "/spec/runtime/spec/replicas", "value": 3}]'
# Update the container image
kubectl patch agent my-agent --type='json' \
-p='[{"op": "replace", "path": "/spec/runtime/spec/container/image", "value": "new-image:v2.0.0"}]'
# Open the manifest in your default editor
kubectl edit agent my-agent
# Delete an agent (also removes the managed Deployment and Service)
kubectl delete agent my-agent
Models and ModelProviders
Models and ModelProviders define how agents connect to large language models. Check their readiness before troubleshooting agent behaviour.
# List all ModelProviders
kubectl get modelproviders
# List all Models
kubectl get models
# Check whether a ModelProvider has successfully loaded its credentials
kubectl get modelprovider openai-provider -o jsonpath='{.status.ready}'
# Check whether a Model has been resolved and is ready for use
kubectl get model gpt-4o -o jsonpath='{.status.ready}'
# Show full details and conditions for a provider
kubectl describe modelprovider openai-provider
# Show full details and conditions for a model
kubectl describe model gpt-4o
# Adjust a model parameter (e.g. raise temperature)
kubectl patch model gpt-4o --type='json' \
-p='[{"op": "replace", "path": "/spec/parameters/temperature", "value": "0.8"}]'
# Rotate an API key by updating the underlying Secret in place
kubectl create secret generic openai-credentials \
--from-literal=api-key=sk-proj-new-key \
--dry-run=client -o yaml | kubectl apply -f -
After rotating a secret, the operator automatically detects the change and marks the ModelProvider ready (or not ready) based on the new value. You do not need to restart any pods manually.
AgentTools are reusable, OpenAPI-backed integrations that agents call at runtime. Use these commands to inspect and update them.
# List all AgentTools in the current namespace
kubectl get agenttools
# Show full details including status conditions
kubectl describe agenttool weather-api
# List the tool references configured on a specific agent
kubectl get agent my-agent -o jsonpath='{.spec.tools[*].toolRef.name}'
# Increase the HTTP timeout for a tool (in seconds)
kubectl patch agenttool weather-api --type='json' \
-p='[{"op": "replace", "path": "/spec/openApi/timeoutSeconds", "value": 60}]'
# Delete a tool (agents referencing it will log resolution warnings)
kubectl delete agenttool weather-api
Debugging
When something goes wrong with an agent, work through these commands to locate the problem quickly.
# Find the pods backing a specific agent
kubectl get pods -l flokoa.ai/agent=my-agent
# Print logs from the most recent pod
kubectl logs -l flokoa.ai/agent=my-agent
# Follow logs from all replicas in real time
kubectl logs -l flokoa.ai/agent=my-agent -f --all-containers
# Open a shell in a running agent pod
kubectl exec -it <pod-name> -- /bin/sh
# Forward the agent's service port to your local machine for ad-hoc testing
kubectl port-forward svc/my-agent 8080:8080
# List Kubernetes events related to a specific agent resource
kubectl get events --field-selector involvedObject.name=my-agent
# View recent events sorted by time (useful for spotting ImagePullBackOff, etc.)
kubectl get events --sort-by='.lastTimestamp'
# Inspect the operator's own logs for reconciliation errors
kubectl logs -n flokoa-system -l control-plane=controller-manager
# Follow operator logs in real time
kubectl logs -n flokoa-system -l control-plane=controller-manager -f
# Check live CPU and memory consumption for agent pods
kubectl top pods -l flokoa.ai/agent=my-agent
Resource status quick reference
The table below lists the most commonly queried status fields and the jsonpath expressions to retrieve them with kubectl get ... -o jsonpath.
| Resource | Field | jsonpath expression |
|---|
| Agent | Lifecycle phase | {.status.phase} |
| Agent | In-cluster URL | {.status.url} |
| Agent | Running replicas | {.status.availableReplicas} |
| Agent | Detected framework | {.status.detectedFramework} |
| Agent | Status conditions | {.status.conditions} |
| ModelProvider | Ready | {.status.ready} |
| Model | Ready | {.status.ready} |
| AgentTool | Conditions | {.status.conditions} |
kubectl get command, for example:
kubectl get agent my-agent -o jsonpath='{.status.availableReplicas}'
kubectl get agent my-agent -o jsonpath='{.status.conditions[?(@.type=="Ready")].message}'
