Registering Kubernetes Clusters

Shoehorn discovers Kubernetes workloads through lightweight agents deployed to each cluster. This guide covers registering a cluster and deploying the agent.

Overview

The registration flow:

1. Register the cluster in Shoehorn (creates an agent token)
2. Deploy the K8s agent to the target cluster with the token
3. The agent watches workloads and pushes data to Shoehorn
4. Entities are automatically created in the service catalog

Register via UI

1. Navigate to Admin > K8s Agents
2. Click Register Cluster
3. Fill in the cluster details:
   • Cluster Name: A unique identifier (e.g., prod-us-east-1)
   • Description: Human-readable description
   • Environment: production, staging, or development
   • Provider: aws, gcp, azure, or on-prem
   • Region: Cloud region (e.g., us-east-1)
4. Click Register
5. Copy the generated agent token (shown only once)

Register via API

curl -X POST https://shoehorn.example.com/api/v1/k8s/agents \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_name": "prod-us-east-1",
    "description": "Production cluster in US East",
    "environment": "production",
    "provider": "aws",
    "region": "us-east-1"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cluster_name": "prod-us-east-1",
  "agent_token": "shp_agent_xxxxxxxxxxxx",
  "status": "pending"
}

Deploy the Agent

See Deploying the K8s Agent for full Helm installation instructions.

Quick install:

helm install shoehorn-k8s-agent charts/shoehorn-k8s-agent \
  --namespace shoehorn-agent --create-namespace \
  --set config.apiUrl=https://shoehorn.example.com \
  --set config.clusterName=prod-us-east-1 \
  --set config.agentToken=shp_agent_xxxxxxxxxxxx

Agent Status

Once deployed, the agent reports its status via heartbeats. View agent health in Admin > K8s Agents:

Status	Meaning
Connected	Agent is actively pushing data
Stale	No heartbeat in the last 5 minutes
Disconnected	No heartbeat in the last 15 minutes
Pending	Registered but agent not yet deployed

Namespace Filtering

By default, the agent watches all namespaces. To exclude system namespaces:

config:
  excludeNamespaces:
    - kube-system
    - kube-public
    - kube-node-lease
    - cert-manager

Entity Auto-Creation

When the agent discovers a workload, Shoehorn automatically:

1. Creates a catalog entity (if it does not exist)
2. Sets the entity type based on workload kind
3. Extracts metadata from annotations (see Annotations Reference)
4. Detects lifecycle stage from namespace name
5. Adds cluster, environment, and provider tags
6. Links the entity to the cluster

Lifecycle Detection from Namespace

Namespace Pattern	Lifecycle
production, prod-*	production
staging, stage-*	staging
dev-*, develop*	development
test, qa, sandbox	experimental
kube-system, argocd, flux-system	experimental
All others	experimental

Managing Clusters

Rotate Agent Token

If a token is compromised:

1. Navigate to Admin > K8s Agents
2. Select the cluster
3. Click Rotate Token
4. Update the agent deployment with the new token

Remove a Cluster

1. Uninstall the agent from the cluster
2. Navigate to Admin > K8s Agents
3. Select the cluster and click Delete

Entities discovered from the cluster are not automatically deleted. Remove them manually or via the API if needed.

Multiple Clusters

Register each cluster separately. Use consistent naming conventions:

prod-us-east-1
prod-eu-west-1
staging-us-east-1
dev-local

Each agent pushes independently, and entities are tagged with their source cluster for filtering.