This is the multi-page printable view of this section. Click here to print.
Faros strives to be the best platform as a service for your remote Kubernetes clusters. Where we can do a lot of things, we will structure our documentation around core features. If you have any questions, please reach out to us at Contacts.
For now Faros is predominantly a CLI tool, so we will focus on the CLI documentation. We will also provide some examples of how to use the CLI tool.
Overall Faros is built, so you can build your own platforms on top of it. While we understand that it is not for everyone, we believe that it can be a great tool for those who want to build their own platforms.
In addition we will be working for some core features “out of the box” that can be used by everyone. And hope with time we will be able to provide more features that can be used by everyone.
Faros is distributes control-plane for Kubernetes-like control planes.
For now we are focusing on the following use-case:
What is it good for?: You have k3s, k0s, k8s, or any other kubernetes cluster and you want to access it from your local machine without exposing it to the internet.
What is it not yet good for?: We will enable more features in the future that will make it more useful for other use-cases. In example 0 trust access to the cluster, or multi-tenancy where we can expose only certain namespaces to certain users. This allows you to share your cluster with others without giving them full access to the cluster.
To get started, check out the following sections:
Faros CLI is a kubectl plugin that provides a modern, user-friendly interface for managing Kubernetes clusters and AI agents through the Faros platform.
kubectl is installed. If not, refer to the official Kubernetes documentation for installation guidance.krew, the kubectl plugin manager, following the official krew documentation.Execute the commands below to add the Faros plugin and install it:
kubectl krew index add faros https://github.com/faroshq/krew-index.git
kubectl krew install faros/faros
To update the plugin, run:
kubectl krew upgrade
Before using any Faros commands, authenticate with the Faros platform:
kubectl faros login
This command will:
~/.kube/config-farosThe Faros CLI provides the following command groups:
Manage your Kubernetes clusters through Faros:
# List all clusters
kubectl faros clusters
kubectl faros clusters list
# Create a new cluster
kubectl faros clusters init <cluster-name>
# Delete a cluster
kubectl faros clusters delete <cluster-name>
# Get MCP server details for a cluster
kubectl faros clusters mcp <cluster-name>
# Open SSH session to a cluster
kubectl faros clusters ssh <cluster-name>
Manage AI agents for cluster analysis and automation:
# List all AI agents
kubectl faros ai-agents
kubectl faros ai-agents list
# Create a new AI agent
kubectl faros ai-agents init \
--name <agent-name> \
--backend openai \
--model gpt-4 \
--api-key <your-api-key>
Users can be invited and granted access via Kubernetes RBAC. Use the following role binding template with GitHub-authenticated emails:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: workspace-admin
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
kind: User
name: faros-sso-{email}
The Faros platform extends Kubernetes with custom APIs. Check the supported APIs using:
kubectl api-resources
Faros allows you to register and manage Kubernetes clusters through a simple CLI interface. Once registered, clusters can be accessed remotely via SSH, monitored by AI agents, and integrated with the Faros platform.
kubectl faros loginView all clusters registered with Faros:
kubectl faros clusters list
# or simply
kubectl faros clusters
This displays:
Initialize a new cluster in the Faros platform:
kubectl faros clusters init <cluster-name>
The initialization process:
Example workflow:
kubectl faros clusters init production-us-east
# Output will include a command like:
# kubectl apply -f - <<EOF
# [Agent deployment manifests with JWT token]
# EOF
#
# Run this command on your target cluster to connect it to Faros
Once a cluster is connected, you can open an interactive SSH session:
kubectl faros clusters ssh <cluster-name>
Features:
Retrieve Model Context Protocol (MCP) server details for AI/LLM integration:
kubectl faros clusters mcp <cluster-name>
This displays:
Remove a cluster from Faros:
kubectl faros clusters delete <cluster-name>
This removes the cluster registration from Faros but does not affect the actual Kubernetes cluster.
Faros integrates AI agents powered by LLMs to provide intelligent cluster analysis, recommendations, and automation capabilities. AI agents can be deployed to analyze your clusters and provide actionable insights.
kubectl faros loginView all AI agents in your namespace:
kubectl faros ai-agents list
# or simply
kubectl faros ai-agents
This displays:
Initialize a new AI agent with specific configuration:
kubectl faros ai-agents init \
--name <agent-name> \
--backend openai \
--model gpt-4 \
--api-key <your-api-key>
--name: Name of the AI agent--backend: AI backend provider (default: openai)--model: Model to use (e.g., gpt-4, gpt-3.5-turbo)--api-key: API key for the backend (creates a Kubernetes secret)--secret-name: Use an existing Kubernetes secret instead of creating one--secret-key: Key within the secret containing the API key--namespace or -n: Kubernetes namespace for the agent (default: current namespace)If you prefer to manage secrets separately:
# First, create a secret with your API key
kubectl create secret generic openai-credentials \
--from-literal=api-key=<your-api-key>
# Then reference it when creating the agent
kubectl faros ai-agents init \
--name my-agent \
--backend openai \
--model gpt-4 \
--secret-name openai-credentials \
--secret-key api-key
When you create an agent, the CLI:
intelligence.faros.sh/v1alpha1 API group# List existing agents
kubectl faros ai-agents list
# Create a new agent for production cluster analysis
kubectl faros ai-agents init \
--name prod-analyzer \
--backend openai \
--model gpt-4 \
--api-key sk-...
# Wait for agent to be ready
# Output: Agent "prod-analyzer" created and is now Ready
# List agents to verify
kubectl faros ai-agents list
Currently supported AI backends:
Additional backends may be supported in future releases.
Understanding Faros concepts will help you effectively use the platform for managing Kubernetes clusters and AI-powered analysis.
Faros is built around two main concepts:
Clusters are registered Kubernetes environments that connect to Faros via lightweight agents. Each cluster maintains its own lifecycle, provides secure remote access, and exposes data for analysis.
AI Agents are intelligent assistants powered by large language models that analyze your clusters, provide recommendations, and help with troubleshooting and optimization.
Faros provides a centralized platform for managing multiple Kubernetes clusters through a unified interface. Clusters are registered with Faros via lightweight agents that provide secure, read-only access for monitoring and analysis.
A Cluster in Faros represents a registered Kubernetes cluster that is connected to the Faros platform. Each cluster:
Clusters in Faros go through the following phases:
When you initialize a cluster in Faros, an Agent resource is created. The agent:
The agent is deployed to your cluster using standard Kubernetes manifests:
apiVersion: core.faros.sh/v1alpha1
kind: Agent
metadata:
name: <cluster-name>
spec:
clusterName: <cluster-name>
token: <jwt-token>
Faros provides secure remote access to your clusters without exposing them to the internet:
kubectl faros clusters ssh <cluster-name>
This opens an interactive terminal session that:
For AI and LLM integration, clusters expose MCP servers:
kubectl faros clusters mcp <cluster-name>
This provides connection details for AI agents to query cluster data and metrics.
Faros is designed for organizations managing multiple clusters:
Faros clusters follow these security principles:
Common scenarios for Faros cluster management:
AI Agents in Faros provide intelligent analysis, recommendations, and automation for your Kubernetes clusters. Powered by large language models, they help identify issues, optimize configurations, and provide actionable insights.
An AI Agent in Faros is a resource that connects a large language model (LLM) to your Kubernetes clusters for intelligent analysis. Each agent:
The backend is the AI service provider:
Different models offer different capabilities:
AI Agents go through these phases:
AI Agents require API keys to connect to backend services. Faros supports two approaches:
When you provide --api-key, the CLI creates a secret:
kubectl faros ai-agents init \
--name my-agent \
--backend openai \
--model gpt-4 \
--api-key sk-...
This creates a Kubernetes secret: <agent-name>-api-key
For better secret management, create secrets separately:
# Create secret
kubectl create secret generic ai-credentials \
--from-literal=openai-key=sk-...
# Reference it in the agent
kubectl faros ai-agents init \
--name my-agent \
--backend openai \
--model gpt-4 \
--secret-name ai-credentials \
--secret-key openai-key
AI Agents connect to clusters through:
Clusters expose MCP servers that agents query for data:
# Get MCP server details
kubectl faros clusters mcp production-cluster
The agent uses these endpoints to:
Agents can target specific clusters:
apiVersion: intelligence.faros.sh/v1alpha1
kind: Agent
metadata:
name: prod-analyzer
spec:
backend: openai
model: gpt-4
clusterSelector:
matchLabels:
environment: production
Common scenarios for AI Agents:
Agents analyze resource usage, pod status, and configurations to identify:
When issues occur, agents help:
Agents review configurations and suggest:
Agents audit clusters for:
AI Agents are defined in the intelligence.faros.sh/v1alpha1 API group:
apiVersion: intelligence.faros.sh/v1alpha1
kind: Agent
metadata:
name: production-analyzer
namespace: default
spec:
backend: openai
model: gpt-4
secretRef:
name: openai-credentials
key: api-key
clusterSelector:
matchLabels:
environment: production
status:
phase: Ready
lastHeartbeat: "2024-06-02T10:30:00Z"
conditions:
- type: Ready
status: "True"
lastTransitionTime: "2024-06-02T10:25:00Z"
prod-cost-analyzer, staging-security-auditThis is a placeholder page that shows you how to use this template site.
Do you have any example applications or code for your users in your repo or elsewhere? Link to your examples here.
Top use Swagger Authentication feature use the following swagger instance: https://api.faros.sh/swagger/
We are working on more smooth integration with the API documentation.
When authenticating, use ClientID: faros and mark all scopes.