> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# kubectl commands for managing Flokoa resources

> A complete reference of kubectl commands for creating, inspecting, updating, scaling, and debugging every Flokoa resource type.

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.

```bash theme={null}
# 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.

```bash theme={null}
# 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 -
```

<Note>
  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.
</Note>

***

## AgentTools

AgentTools are reusable, OpenAPI-backed integrations that agents call at runtime. Use these commands to inspect and update them.

```bash theme={null}
# 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.

```bash theme={null}
# 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}`        |

Use these expressions by appending them to a `kubectl get` command, for example:

```bash theme={null}
kubectl get agent my-agent -o jsonpath='{.status.availableReplicas}'
kubectl get agent my-agent -o jsonpath='{.status.conditions[?(@.type=="Ready")].message}'
```