Getting Started

• 1: Install CLI
• 2: Manage Clusters
• 3: Manage AI Agents

1 - Install CLI

Prerequisites

• Ensure kubectl is installed. If not, refer to the official Kubernetes documentation for installation guidance.
• Install krew, the kubectl plugin manager, following the official krew documentation.

Plugin Installation

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

Authentication

Before using any Faros commands, authenticate with the Faros platform:

kubectl faros login

This command will:

1. Start a local authentication server
2. Open your browser to complete OAuth authentication
3. Save your credentials to ~/.kube/config-faros
4. Display next steps for getting started

Available Commands

The Faros CLI provides the following command groups:

Cluster Management

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>

AI Agent Management

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>

User Management

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}

Explore Kubernetes APIs

The Faros platform extends Kubernetes with custom APIs. Check the supported APIs using:

kubectl api-resources

2 - Manage Clusters

Prerequisites

• Ensure you have installed the Faros CLI. If not, refer to the CLI installation guide.
• Authenticate with Faros: kubectl faros login

Listing Clusters

View all clusters registered with Faros:

kubectl faros clusters list
# or simply
kubectl faros clusters

This displays:

• NAME: Cluster name
• PHASE: Current status (Pending, Initializing, Ready, Failed)
• AGE: Time since cluster creation

Creating a New Cluster

Initialize a new cluster in the Faros platform:

kubectl faros clusters init <cluster-name>

The initialization process:

1. Creates a Cluster resource in Faros
2. Waits for the cluster to be initialized
3. Creates an Agent resource for the cluster
4. Generates a JWT token for agent authentication
5. Provides a kubectl command to run on your target cluster
6. Waits for the agent to become ready and establish connection

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

Accessing Clusters via SSH

Once a cluster is connected, you can open an interactive SSH session:

kubectl faros clusters ssh <cluster-name>

Features:

• WebSocket-based SSH connection
• Full terminal support with resize handling
• Secure authentication via Kubernetes credentials
• Signal handling for graceful shutdown

MCP Server Integration

Retrieve Model Context Protocol (MCP) server details for AI/LLM integration:

kubectl faros clusters mcp <cluster-name>

This displays:

• Server name and type
• Connection URL
• Required authentication headers

Deleting a Cluster

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.

3 - Manage AI Agents

Prerequisites

• Ensure you have installed the Faros CLI. If not, refer to the CLI installation guide.
• Authenticate with Faros: kubectl faros login
• An API key for your chosen AI backend (e.g., OpenAI)

Listing AI Agents

View all AI agents in your namespace:

kubectl faros ai-agents list
# or simply
kubectl faros ai-agents

This displays:

• NAME: Agent name
• BACKEND: AI backend (e.g., openai)
• MODEL: Model being used (e.g., gpt-4)
• PHASE: Current status (Pending, Initializing, Ready, Failed)
• AGE: Time since agent creation

Creating a New AI Agent

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>

Configuration Options

• --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)

Using Existing Secrets

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

Agent Lifecycle

When you create an agent, the CLI:

1. Creates an Agent resource in the intelligence.faros.sh/v1alpha1 API group
2. Creates or references a Kubernetes secret for authentication
3. Waits for the agent to transition to Ready phase
4. Displays status and next steps

Example Workflow

# 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

Backend Support

Currently supported AI backends:

• OpenAI: GPT-4, GPT-3.5-turbo, and other OpenAI models

Additional backends may be supported in future releases.