Organize Flokoa resources across Kubernetes namespaces

All Flokoa Custom Resources are namespace-scoped, which means the way you organize them across namespaces directly affects your team’s ability to share configuration, enforce security boundaries, and isolate environments from one another. A thoughtful namespace layout prevents duplicated secrets, makes RBAC policies easier to write, and keeps production workloads cleanly separated from development. This guide covers the main patterns, from a single-namespace setup for quick starts to a fully multi-tenant shared-resources layout for larger teams.

Cross-namespace references are fully supported in Flokoa. An Agent in one namespace can reference a Model in another, a Model can reference a ModelProvider in yet another, and an Agent can reference AgentTools spread across multiple namespaces — all by adding an optional namespace: field to the reference.

Single namespace

The simplest possible layout puts every resource — Agents, Models, ModelProviders, and AgentTools — in a single namespace. This is ideal for individual developers, proof-of-concept work, and small teams that do not yet need resource isolation. Create the namespace and deploy everything into it:

kubectl create namespace ai-agents

kubectl apply -f modelprovider.yaml -n ai-agents
kubectl apply -f model.yaml -n ai-agents
kubectl apply -f agenttool.yaml -n ai-agents
kubectl apply -f agent.yaml -n ai-agents

All resources are co-located, so no cross-namespace references are needed. The trade-off is that all team members share access to the same secrets and configuration, which becomes a concern as the team or the number of agents grows.

Shared resources pattern

For teams deploying multiple agents or applications, the recommended layout separates resources by their reusability and sensitivity:

shared-resources   →  ModelProviders (API credentials, one per provider)
shared-models      →  Models (tuned model configs for team-wide use)
shared-tools       →  AgentTools (common API integrations)
app-namespace      →  Agents (application-specific deployments)

This structure means provider credentials live in exactly one place, and rotating an API key requires updating a single secret. Applications reference the shared resources without needing copies of the configuration. Create the namespaces:

kubectl create namespace shared-resources
kubectl create namespace shared-models
kubectl create namespace shared-tools
kubectl create namespace my-app

Deploy the shared ModelProvider to shared-resources:

apiVersion: agent.flokoa.ai/v1alpha1
kind: ModelProvider
metadata:
  name: openai-provider
  namespace: shared-resources
spec:
  apiKeySecretRef:
    name: openai-credentials
    key: api-key
  openai: {}

Deploy a shared Model to shared-models, referencing the provider by namespace:

apiVersion: agent.flokoa.ai/v1alpha1
kind: Model
metadata:
  name: shared-gpt-4o
  namespace: shared-models
spec:
  model: "gpt-4o"
  providerRef:
    name: openai-provider
    namespace: shared-resources
  parameters:
    temperature: "0.7"
    maxTokens: 8192

Agents in my-app can now reference these shared resources directly.

Environment isolation

When you need hard boundaries between development, staging, and production workloads, give each environment its own namespace. This approach pairs naturally with namespace-scoped ResourceQuotas, NetworkPolicies, and RBAC rules.

kubectl create namespace development
kubectl create namespace staging
kubectl create namespace production

Apply environment-specific resources to each namespace:

kubectl apply -f modelprovider-dev.yaml -n development
kubectl apply -f modelprovider-prod.yaml -n production

Staging and production may share a ModelProvider if cost and configuration allow, but they should generally use different secrets to prevent a leaked dev credential from affecting production traffic.

Cross-namespace references

Reference any Flokoa resource in a different namespace by adding the namespace: field to the reference. The following Agent spec demonstrates referencing a Model from shared-models and two AgentTools from shared-tools:

apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
  name: my-agent
  namespace: my-app
spec:
  model:
    name: shared-gpt-4o
    namespace: shared-models
  tools:
    - toolRef:
        name: weather-api
        namespace: shared-tools
    - toolRef:
        name: inventory-check
        namespace: shared-tools
  runtime:
    type: standard
    spec:
      container:
        name: agent
        image: ghcr.io/example/my-agent:v1.0.0
        ports:
        - containerPort: 8080
          name: http

When namespace: is omitted from any reference, Flokoa defaults to the same namespace as the referring resource.

RBAC for namespace access

Use Kubernetes RBAC to control which service accounts and users can read resources in shared namespaces. The following Role grants an agent service account the ability to read AgentTool resources in the shared-tools namespace, without giving it broader write access:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: agenttool-reader
  namespace: shared-tools
rules:
- apiGroups: ["agent.flokoa.ai"]
  resources: ["agenttools"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: my-app-agenttool-reader
  namespace: shared-tools
subjects:
- kind: ServiceAccount
  name: my-agent-sa
  namespace: my-app
roleRef:
  kind: Role
  name: agenttool-reader
  apiGroup: rbac.authorization.k8s.io

Apply the same pattern for Model and ModelProvider access in their respective namespaces. Keeping roles narrow — granting only get and list on the specific resource types needed — follows the principle of least privilege.

Best practices

Use this checklist when planning your namespace layout:

Isolate secrets by environment. Never share Kubernetes Secrets containing production API keys with development namespaces.
Centralise provider credentials. One ModelProvider per LLM provider in a shared namespace prevents drift and simplifies key rotation.
Separate reusable tools from app-specific ones. Common integrations belong in shared-tools; one-off tools can live in the application namespace.
Use namespace labels consistently. Labels like environment: production make it easy to apply NetworkPolicies and audit queries across namespaces.
Scope RBAC to the minimum required. Grant get/list on shared resources, not full * verbs.
Document your layout. A short README or architecture diagram in your GitOps repo prevents namespace sprawl as the team grows.
Prefer namespace: references over copying YAML. Duplicating a ModelProvider or AgentTool into every application namespace creates maintenance overhead and inconsistency.

Deploy Your First Agent

Get an Agent running from scratch with a minimal manifest and kubectl.

Connect an LLM Provider

Create ModelProvider and Model resources and attach them to an agent.

Add Tools

Create shareable AgentTool resources backed by OpenAPI specifications.

High Availability

Configure replicas, probes, and anti-affinity for production-grade agents.

Get Started

Core Resources

Guides

Python SDK

Operations

Organize Flokoa resources across Kubernetes namespaces

Single namespace

Shared resources pattern

Environment isolation

Cross-namespace references

RBAC for namespace access

Best practices

Deploy Your First Agent

Connect an LLM Provider

Add Tools

High Availability

​Single namespace

​Shared resources pattern

​Environment isolation

​Cross-namespace references

​RBAC for namespace access

​Best practices

​Related guides

Deploy Your First Agent

Connect an LLM Provider

Add Tools

High Availability

Single namespace

Shared resources pattern

Environment isolation

Cross-namespace references

RBAC for namespace access

Best practices

Related guides