Deploying Kubernetes Agents - Complete Guide | Nife Deploy

Agents are services deployed on your cluster that enable monitoring, logging, and enhanced Nife platform features.

What are Agents?#

Agents are lightweight services that run on your Kubernetes cluster and:

  • Monitor cluster health and metrics
  • Collect and stream pod logs
  • Run security scans
  • Report resource usage
  • Enable AI-powered log analysis
  • Maintain real-time communication with Nife

Before Deploying#

Prerequisites:

  • Cluster is connected to Nife
  • You have cluster admin access
  • Enough resources on cluster:
    • 100MB memory
    • 10m CPU
    • 1GB storage

Deploying Your First Agent#

Step 1: Start Agent Deployment#

  1. Go to Clusters page
  2. Click Add Agent button (top right)
  3. Or select cluster and click Add Agent

Step 2: Select Cluster#

Cluster Selection:

  • Choose the cluster where agent will run
  • Cluster name is pre-filled if coming from cluster detail
  • Can only deploy one agent per cluster initially

Step 3: Choose Capabilities#

Select what the agent can do:

Available Capabilities:

CapabilityPurposeRecommended
MonitoringCollect metrics (CPU, memory, disk)Always ✅
LoggingStream pod logsYes ✅
SecurityRun security scansYes ✅
AnalyticsEnable AI analysisYes ✅
Auto-scalingAllow auto-scalingOptional
DeploymentDeploy applicationsYes ✅

Selecting Capabilities:

  1. Check boxes next to desired capabilities
  2. At minimum, enable Monitoring
  3. Most users want Monitoring, Logging, Security

Step 4: Generate Agent Token#

  1. Click Generate Token
  2. Token is created securely
  3. Token appears in the dialog

Important: Save this token securely. You'll need it to authenticate the agent.

Step 5: Deploy Agent#

Two methods to deploy:

Method 1: Automatic Deployment

# Copy the provided command
# Paste into your terminal connected to the cluster
# Agent will deploy automatically

Method 2: Manual Kubeconfig

# Use the provided kubeconfig snippet
# Apply to your cluster manually
# More control over deployment

Step 6: Verify Deployment#

  1. After deployment, wait 1-2 minutes
  2. Go to Agents tab
  3. Find your agent in the list
  4. Status should show Connected or Healthy

Managing Agents#

View Agent Details#

  1. Go to Agents tab
  2. Click Details on any agent
  3. See:
    • Agent status
    • Connected cluster
    • Deployed capabilities
    • Recent metrics
    • Last heartbeat

Agent Status Meanings#

StatusMeaningAction
ConnectedAgent is running and communicatingReady to use
HealthyAgent is functioning normallyNo action needed
DisconnectedAgent lost connectionInvestigate network
ErrorAgent encountered an errorCheck logs

Monitor Agent Metrics#

Each agent shows:

  • CPU Usage: Percentage of CPU being used
  • Memory Usage: RAM consumption
  • Disk Usage: Storage space used
  • Last Heartbeat: When agent last reported

Rotate Agent Token#

Refresh agent's authentication token:

  1. Click Details on agent
  2. Click menu (three dots)
  3. Select Rotate Token
  4. Confirm rotation
  5. Agent continues running with new token

Why rotate tokens:

  • Periodic security refresh
  • If token is compromised
  • After security audit
  • Regular maintenance

Trigger Security Scan#

Run security checks on cluster:

  1. Go to Agents tab
  2. Click menu (three dots) on agent
  3. Select Trigger Security Scan
  4. Scan starts immediately
  5. Results appear in Security Findings

Agent Deployment Troubleshooting#

Issue: Agent Won't Connect#

Symptoms:

  • Agent status shows "Disconnected"
  • Metrics not appearing
  • Last heartbeat is old

Solutions:

  1. Check cluster connectivity
  2. Verify agent pod is running:
    kubectl get pods -n nife-agents
  3. Check agent logs:
    kubectl logs -n nife-agents -l app=nife-agent
  4. Verify firewall allows outbound HTTPS
  5. Check if token has expired

Issue: Deployment Failed#

Symptoms:

  • Agent pod never starts
  • Status shows "Error"

Solutions:

  1. Verify cluster has enough resources
  2. Check kubeconfig is correct
  3. Verify cluster admin access
  4. Check namespace exists
  5. Try re-deploying with new token

Issue: High Resource Usage#

Symptoms:

  • Agent using more CPU/memory than expected
  • Cluster performance affected

Solutions:

  1. Check agent version is current
  2. Review security scan frequency
  3. Limit log streaming tail lines
  4. Disable unnecessary capabilities
  5. Contact support for optimization

Issue: Token Expired#

Symptoms:

  • Agent stops connecting after time period
  • Authentication errors in logs

Solutions:

  1. Generate new token
  2. Update agent with new token
  3. Or rotate token (easier)
  4. Redeploy agent if needed

Agent Capabilities Explained#

Monitoring#

Collects real-time metrics about cluster and nodes:

  • CPU, memory, disk usage
  • Network I/O
  • Pod counts
  • Node status

Use when: Always enable for all clusters

Logging#

Enables pod log collection and streaming:

  • Fetch historical logs
  • Stream logs in real-time
  • Filter and search logs
  • Export logs

Use when: You need to view application logs

Security#

Runs security scans on cluster:

  • Vulnerability scanning
  • Configuration audit
  • Access control review
  • Compliance checking

Use when: Security is important (always recommended)

Analytics#

Enables AI-powered log analysis:

  • Automatically detect issues
  • Identify patterns
  • Suggest fixes
  • Analyze trends

Use when: Want intelligent insights from logs

Auto-scaling#

Allows Nife to auto-scale your applications:

  • Scale up under load
  • Scale down when idle
  • Cost optimization
  • Performance tuning

Use when: Want automatic scaling

Deployment#

Allows deploying applications via Nife:

  • Deploy from dashboard
  • CI/CD integration
  • Version management
  • Rollback capability

Use when: Using Nife for deployments

Removing an Agent#

To remove an agent from a cluster:

  1. Go to Agents tab
  2. Select agent
  3. Click menu (three dots)
  4. Select Remove Agent
  5. Confirm removal
  6. Agent is removed from cluster

Note: Removing doesn't delete cluster, only removes agent service.

Best Practices#

1. Deploy to All Clusters#

Deploy at least one agent per cluster for monitoring and management.

2. Enable Recommended Capabilities#

Always enable: Monitoring, Logging, Security

3. Secure Your Tokens#

  • Don't share agent tokens
  • Store tokens securely
  • Rotate tokens periodically
  • Revoke compromised tokens

4. Monitor Agent Health#

  • Check agent status regularly
  • Monitor resource usage
  • Review error logs
  • Update agent when new versions available

5. Plan Deployment#

  • Deploy during low-traffic periods
  • Test in non-production first
  • Have rollback plan
  • Document deployment

6. Rotate Credentials Regularly#

  • Rotate tokens monthly
  • After team changes
  • After security incidents
  • As part of security policy

Agent Updates#

When agent updates are available:

  1. Notification appears in Nife
  2. New agent version is released
  3. You can update from dashboard
  4. Or manually update via kubectl

Update Process:

  1. New version is pulled
  2. Agent pods are recreated
  3. Zero downtime updates
  4. Capabilities are preserved

Next Steps#

  1. Monitor Resources - Track cluster health
  2. View Pod Logs - Access application logs
  3. Run Security Scans - Check cluster security

Support#

Questions about agents?

Agent not connecting?

  • Follow troubleshooting section above
  • Check cluster connectivity
  • Verify token is valid
  • Review agent pod logs