Skip to main content
Flokoa lets you define AI agents as Kubernetes-native Custom Resources (CRDs) and manage their full lifecycle declaratively. This guide walks you through every step, from confirming your cluster prerequisites all the way to sending your first request to a running agent. By the end, you’ll have a working Agent resource and a solid mental model for the resources that compose it.
1

Verify prerequisites

Before applying any manifests, confirm that your environment meets the minimum requirements. Flokoa requires Kubernetes 1.25 or later, a working kubectl configuration, and the Flokoa operator running in the flokoa-system namespace.Check that the operator pod is healthy:
You should see output similar to this, with the operator pod in a Running state:
If the operator is not installed yet, apply the release manifest:
Wait for the controller pod to reach Running before continuing.
2

Write the Agent manifest

Create a file called my-first-agent.yaml with the following minimal Agent spec. This configuration tells Flokoa to deploy a single container behind a Kubernetes Service, using the standard runtime backend.
Every field in this manifest corresponds to a real spec field in the Flokoa CRD — there is nothing extra required to get an agent running.
Flokoa supports two values for spec.runtime.type:
  • standard — Deploys your own container image using a Kubernetes Deployment and an accompanying ClusterIP Service. You own the image and all runtime behavior.
  • template — Uses a generic runtime image fully managed by the operator. The agent’s behavior is defined entirely in the CR through instructions and an output schema.
The standard type is the right choice for most teams that already have agent code packaged in a container.
Avoid using :latest in production. Pin your images to an explicit version tag such as ghcr.io/example/simple-agent:v1.2.3. The latest tag makes rollbacks and audit trails significantly harder to manage.
3

Apply the manifest

Apply the manifest to your cluster with kubectl:
The Flokoa operator detects the new Agent resource and immediately begins reconciling it — creating a Deployment, Service, and any supporting resources defined in the spec.
4

Watch the agent come up

Use the watch flag to observe the Agent’s lifecycle phases in real time:
You’ll see the agent move from Pending to Running as the operator creates the underlying Deployment and the pod transitions to a ready state:
Press Ctrl+C once the phase shows Running. If the agent stays in Pending for more than a minute, move to the next step to inspect its status conditions.
5

Inspect status

Use kubectl describe to get the full picture of what the operator has recorded about your agent:
Look for the Status section in the output. Two fields are especially useful at this stage:
  • status.url — the in-cluster DNS address of the Service the operator created. This is the stable endpoint other cluster workloads can use to reach your agent.
  • status.conditions — a list of standard Kubernetes conditions. The Ready condition with status: "True" confirms the Deployment is fully available. If anything is wrong, the reason and message fields explain the cause.
6

Test connectivity

Forward the agent’s Service port to your local machine so you can send a test request without configuring external ingress:
With the tunnel open, send an HTTP request from another terminal:
A successful response from your agent confirms end-to-end connectivity through the Kubernetes Service. When you’re done testing, press Ctrl+C to close the port-forward.

​
Next steps

You have a running agent. Now connect it to a language model or give it access to external APIs.

Connect an LLM Provider

Configure OpenAI, Anthropic, Google, or AWS Bedrock credentials and attach a model to your agent.

Add Tools

Create AgentTool resources backed by OpenAPI specs and give your agent access to external APIs.