> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Organize Flokoa resources across Kubernetes namespaces
> Learn patterns for structuring Flokoa Agents, Models, ModelProviders, and AgentTools across namespaces to support teams and environments.
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:
```bash theme={null}
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:
```bash theme={null}
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`:
```yaml theme={null}
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:
```yaml theme={null}
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.
```bash theme={null}
kubectl create namespace development
kubectl create namespace staging
kubectl create namespace production
```
Apply environment-specific resources to each namespace:
```bash theme={null}
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`:
```yaml theme={null}
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:
```yaml theme={null}
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.
## Related guides
Get an Agent running from scratch with a minimal manifest and kubectl.
Create ModelProvider and Model resources and attach them to an agent.
Create shareable AgentTool resources backed by OpenAPI specifications.
Configure replicas, probes, and anti-affinity for production-grade agents.