Governance
The Governance system lets you define and enforce fleet-wide policies, track compliance, run canary deployments with automatic rollback, and synchronize configuration from a Git repository via GitOps.
Fleet Policies
Policies define the expected state of your fleet. Each policy specifies rules that Cloud OS instances must follow. The Control Panel evaluates policies against instance state and flags violations.
Policy Types
| Policy Type | Description | Example |
|---|---|---|
| required_apps | Applications that must be installed on every instance | Require monitoring-agent and log-collector |
| blocked_apps | Applications that must not be installed | Block outdated-db or insecure-tool |
| update_rules | Rules for how and when instances should update | Auto-update within 48 hours of release |
| baseline | A baseline configuration that instances must match | Specific Cloud OS version, security settings |
Creating a Policy
- Navigate to Governance > Policies from the sidebar
- Click Create Policy
- Select the policy type
- Define the rules for the policy
- Choose the scope — all instances, a specific group, or a tag filter
- Click Save
Policy Scope
Policies can target:
- All instances — applies fleet-wide
- Groups — applies to instances in specific groups
- Tags — applies to instances matching a tag filter (e.g.,
env=production)
Policy Violations
When an instance does not meet a policy’s requirements, a violation is recorded. Violations are visible on the Governance dashboard and the individual server detail page.
Each violation includes:
- The policy that was violated
- The specific rule that failed
- The instance that is non-compliant
- When the violation was first detected
- Current resolution status
Violation Severity
Violations are categorized by the policy type:
- Critical — blocked apps found on an instance
- Warning — required apps missing or update rules not followed
- Info — baseline drift detected
Compliance Scoring
Each instance receives a compliance score based on how many policies it satisfies. The score is calculated as a percentage:
Compliance Score = (Policies Met / Total Applicable Policies) x 100The Fleet Dashboard shows the average compliance score across all instances, and you can drill down to see per-instance scores on the Governance page.
A compliance score of 100% means the instance satisfies all applicable policies. Instances with no applicable policies are excluded from scoring.
Canary Deployments
Canary deployments let you roll out changes to a small subset of your fleet first, validate the results, and then proceed to the full fleet or automatically roll back if something goes wrong.
Canary deployments require the canary_deployments license feature (Business+ plan).
How Canary Deployments Work
- Define the change — select the command or update to deploy
- Select canary targets — choose a percentage or specific instances as the canary group
- Set success criteria — define what constitutes a successful deployment (e.g., instance remains online, no new violations, health check passes)
- Set the success threshold — the percentage of canary targets that must succeed before proceeding
- Deploy to canary — the change is applied to the canary group
- Evaluation period — the Control Panel monitors the canary instances for a configured duration
- Proceed or rollback — if the success threshold is met, the change rolls out to the remaining fleet; if not, the canary instances are automatically rolled back
Canary Phases
| Phase | Description |
|---|---|
| Canary | Change applied to the selected subset |
| Evaluation | Monitoring period to validate success criteria |
| Rollout | Change applied to the remaining fleet (if canary succeeds) |
| Rollback | Change reverted on canary instances (if canary fails) |
Health Check Polling
During the evaluation phase, the Control Panel automatically polls a health check endpoint on each canary instance. You can configure the following parameters when creating a canary deployment:
| Parameter | Description | Default |
|---|---|---|
| Health Check URL | The endpoint to poll on each canary instance (e.g., /health or /api/status) | /health |
| Success Threshold | Percentage of canary instances that must return healthy for the deployment to proceed | 100% |
| Check Interval | How often the health check is polled during the evaluation period | 30 seconds |
| Max Duration | Maximum time to wait for the success threshold to be met before triggering a rollback | 10 minutes |
The health check poller runs automatically once the canary phase begins. Each poll result is recorded and visible on the deployment detail page.
Auto-Rollback
If the canary deployment fails to meet the success threshold during the evaluation period, the Control Panel automatically:
- Reverts the change on all canary instances
- Records the failure reason
- Sends a notification to the fleet administrator
- Does not proceed with the fleet-wide rollout
Auto-rollback reverts the specific change that was deployed. It does not roll back other changes that may have been made to the instance independently.
Canary API
| Endpoint | Method | Description |
|---|---|---|
/api/fleet/canary | POST | Create a canary deployment |
/api/fleet/canary | GET | List all canary deployments |
/api/fleet/canary/{id} | GET | Get deployment status with health metrics |
/api/fleet/canary/{id}/promote | POST | Force promote to all instances |
/api/fleet/canary/{id}/rollback | POST | Force rollback |
GitOps Configuration Sync
The Control Panel supports GitOps-style configuration management. You can connect a Git repository containing your fleet configuration, and the Control Panel will sync that configuration to your instances.
GitOps requires the gitops license feature (Enterprise plan).
Setting Up GitOps
- Navigate to Governance > GitOps
- Click Connect Repository
- Enter the repository URL
- Configure authentication (SSH key or deploy key)
- Select the branch to track
- Set the sync interval
- Choose a conflict resolution strategy
How Sync Works
The Control Panel periodically pulls the configured branch, compares the repository state against the current fleet state, and applies any differences. Changes detected in the repository are translated into commands that are pushed to the affected instances.
SSH Authentication
GitOps repositories are accessed via SSH. You can either:
- Generate a new SSH key pair in the Control Panel and add the public key as a deploy key on your repository
- Upload an existing private key if you already have SSH access configured
The SSH private key is stored encrypted in the Control Panel database. It is only used for read-only access to pull configuration from the repository.
Conflict Resolution
When the Git repository and the Control Panel have divergent values for the same configuration key, a conflict occurs. You can configure how conflicts are resolved:
| Strategy | Behavior |
|---|---|
| server_wins | Control Panel configuration overrides Git repository values |
| git_wins | Git repository values override Control Panel configuration |
| manual | Sync pauses and presents the conflict for admin resolution |
When using the manual strategy, unresolved conflicts appear in the GitOps dashboard. An administrator must review each conflict and choose which value to keep before the sync can continue.
GitOps API
| Endpoint | Method | Description |
|---|---|---|
/api/governance/gitops | POST | Create GitOps configuration |
/api/governance/gitops | GET | List all configurations |
/api/governance/gitops/{id}/sync | POST | Force sync from repository |
/api/governance/gitops/{id}/conflicts | GET | List unresolved conflicts |
/api/governance/gitops/conflicts/{id}/resolve | POST | Resolve a conflict |
Next Steps
- Fleet Management — register and organize your fleet
- Fleet Operations — issue commands to instances
- Kubernetes — manage Kubernetes clusters alongside your fleet