Optral Documentation
Clusters

Cluster Management

Learn how to connect, configure, and manage your Kubernetes clusters with Optral.

Overview

Optral connects to your Kubernetes clusters through a lightweight agent that runs inside each cluster. The agent collects metrics, logs, and resource information, sending it securely to the Optral platform for analysis and visualization.

Cluster Status

Understanding the different cluster states

Connected

The agent is running and actively sending data. All features are available.

Pending

Cluster was created but the agent hasn't connected yet. Install the agent to activate.

Disconnected

No heartbeat received for over 5 minutes. Check agent health and network connectivity.

Disabled

Cluster has been manually disabled. Re-enable from cluster settings.

Adding a Cluster

  1. Go to Clusters > Add Cluster
  2. Enter a unique name for your cluster
  3. Select the environment type (production, staging, development)
  4. Copy the generated Helm installation command
  5. Run the command in your cluster

GitOps Integration

Connect your cluster to a Git repository for automated deployments

Optral supports GitOps workflows by integrating with GitHub and GitLab. When enabled, Optral can automatically create pull requests with remediation changes.

Supported Features:

  • Automatic PR creation for runbook remediations
  • Manifest sync status monitoring
  • Drift detection between Git and cluster state
  • Approval workflows for sensitive changes

Setup:

  1. Navigate to cluster settings
  2. Enable GitOps integration
  3. Connect your GitHub or GitLab account
  4. Select the repository and branch
  5. Specify the path to your Kubernetes manifests

Configuration Options

Name & Environment

Update the cluster display name and environment label. This helps organize clusters in the dashboard.

Agent Settings

Configure what data the agent collects: metrics interval, log retention, resource watch filters.

Notifications

Set up alerts for cluster events, issue detection, and agent health.

Required Permissions

RBAC permissions needed by the Optral agent

The Optral agent requires read access to most cluster resources to provide visibility and analysis. For runbook execution, additional write permissions may be needed.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: optral-agent
rules:
- apiGroups: [""]
  resources: ["pods", "services", "nodes", "events", "configmaps"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "daemonsets", "statefulsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get"]

Removing a Cluster

To remove a cluster from Optral:

  1. Uninstall the agent from your cluster:helm uninstall optral-agent -n optral-system
  2. Delete the cluster from the dashboard via cluster settings