Clusters & Agents

Cluster Concept

A cluster in GitOpsHQ represents a registered Kubernetes cluster with an active agent connection. Clusters are the deployment targets for your project deliveries — the delivery generator commits manifests to Git, and the cluster agent ensures those manifests are synced and running.

Clusters also provide runtime visibility: inventory browsing, resource inspection, drift detection, log streaming, and operational commands — all from the GitOpsHQ UI without requiring direct kubectl access.

Cluster Registration

Register a cluster from the Clusters page (/clusters). The backend API is POST /api/v2/clusters.

Cluster Labels

Labels are key-value pairs attached to clusters for organization and filtering:

Labels are used in binding rules and approval policies to target specific cluster groups.

Agent Installation

The agent is a lightweight Go binary that runs as a Kubernetes Deployment in the target cluster.

Installation Methods

helm upgrade --install gitopshq-agent \
  oci://ghcr.io/gitopshq-io/charts/gitopshq-agent \
  --namespace gitopshq-system \
  --create-namespace \
  --set registrationToken="ghqa_reg_a1b2c3d4..." \
  --set hub.address="agent.gitopshq.io:50051" \
  --set capabilities.observe=true \
  --set capabilities.argocdRead=true

kubectl create namespace gitopshq-system

kubectl create secret generic gitopshq-agent-registration \
  --namespace gitopshq-system \
  --from-literal=GITOPSHQ_REGISTRATION_TOKEN="ghqa_reg_a1b2c3d4..."

kubectl create secret generic gitopshq-agent-hub \
  --namespace gitopshq-system \
  --from-literal=GITOPSHQ_HUB_ADDRESS="agent.gitopshq.io:50051"

Agent RBAC Requirements

The Helm chart creates RBAC resources based on the rbac.profile value and enabled capabilities:

readonly profile (default) -- cluster-wide read access for inventory and inspection:

readwrite profile -- adds write verbs for operational commands:

Identity Secret RBAC -- when persistence.type: secret, the chart grants create, get, update, patch on the identity Secret so the agent can persist its token after registration.

Agent Architecture

The agent is designed for security, reliability, and minimal footprint:

Connection Model

Token Lifecycle

Cluster Detail Page

The Cluster Detail page (/clusters/:id) is the operational hub for a registered cluster. It provides real-time visibility into the cluster's state, workloads, and health.

Health Status

The cluster header always shows the current connection health:

Cluster Tabs

Inventory

Browse the cluster's namespaces and resources in real-time.

• Namespace list with resource counts per type (pods, deployments, services, configmaps, secrets)
• Resource table filtered by namespace and type
• Resource summary: name, status, age, labels
• Click any resource to open the Resource Inspection view

The inventory is refreshed periodically by the agent and on-demand when you navigate to the tab.

ArgoCD Applications

If ArgoCD is running in the cluster, this tab shows all ArgoCD Application resources:

Quick actions: Force Sync, Hard Refresh, View in ArgoCD UI (if ArgoCD dashboard URL is configured).

Drift Findings

Drift detection compares the desired state (from Git) with the actual state (from the cluster) for each resource managed by GitOpsHQ deliveries.

• Per-resource drift detail with field-level differences
• Drift severity classification (cosmetic vs. functional)
• "Resolve" action: force sync from Git to cluster
• Drift history: when drift was first detected, how long it persisted

Bindings

Shows which project deliveries target this cluster:

Commands

History of all commands sent to the cluster and their execution results.

Filter by command type, status, or date range to investigate operational history.

Log Streaming

Real-time pod log streaming powered by xterm.js.

1. Select namespace from the dropdown.
2. Select pod from the filtered pod list.
3. Select container (for multi-container pods).
4. Start streaming. Logs appear in real-time in the terminal viewer. Previous logs (tail) are loaded first, then the stream follows new log lines.

Features:

• Search within logs: Ctrl+F to find specific log entries
• Pause/resume: Pause the stream to inspect a specific section
• Download: Export the current log buffer as a text file
• Timestamps: Toggle timestamp display on each log line
• Follow mode: Auto-scroll to latest log entries (enabled by default)

Credential Sync

Status of credential synchronization from GitOpsHQ to the cluster (e.g., image pull secrets, TLS certificates):

Resource Inspection

Deep-dive into any Kubernetes resource:

• YAML view: Full resource YAML with syntax highlighting
• Events: Kubernetes events related to the resource (sorted by timestamp)
• Related resources: Linked resources (e.g., a Deployment's ReplicaSets and Pods)
• Labels and annotations: Searchable label/annotation display
• Conditions: Resource condition table (for Deployments, Nodes, Pods)

Cluster Commands

Commands are operational actions sent to the cluster agent for execution. They provide controlled cluster operations without requiring direct kubectl access.

Available Commands

Command Execution Flow

Command Approval

Commands can require approval based on cluster approval policies:

• Bind an approval policy to a cluster from the Cluster Detail settings
• Configure which command types require approval per cluster
• Production clusters typically require approval for Rollback and Scale
• Development clusters can auto-approve all commands
• Command approval requests appear in the unified Approvals inbox (/approvals)

Cluster Bindings

Bindings connect project deliveries to clusters — they define where generated manifests are deployed.

Binding Types

Binding Configuration

Bindings are configured at the project level under Settings → Targets:

1. Select the cluster to bind
2. Map tenant-environments to the cluster
3. Configure the target namespace pattern (e.g., {{ .tenant }}-{{ .environment }})
4. Optionally set cluster-specific overrides (e.g., region-specific storage class)

Cluster Approval Policies

Approval policies can be bound directly to clusters to control operational actions:

Cluster approval requests appear in the unified Approvals inbox alongside release and promotion approvals.

Agent Health Monitoring

Monitor agent health across all clusters from the Clusters list page:

Error Reference

Best Practices