Instruction file imported from kubev2v/forklift-console-plugin (.cursor/rules/backend/operator/operator.mdc). Copyright stays with the author.

Forklift Operator

Analyzed from commit: a976d24b6 on 2026-05-04

Overview

The Forklift operator is an Ansible-based operator (operator-sdk) that watches the ForkliftController CRD and reconciles all Forklift components into the target namespace. It uses a single Ansible role (forkliftcontroller) with Jinja2 templates.

ForkliftController CRD

• Group: forklift.konveyor.io, Version: v1beta1, Kind: ForkliftController
• Single watched resource defined in operator/watches.yaml
• Has a finalizer (forklift.konveyor.io/finalizer) for cleanup on deletion
• The CR's .spec fields map to Ansible variables that override defaults in roles/forkliftcontroller/defaults/main.yml

Key Configurable Fields (CR spec → Ansible var)

Feature Flags

Feature flags flow from the ForkliftController CR through Ansible into environment variables on the controller pod:

ForkliftController CR spec
  → Ansible defaults/main.yml
    → Jinja2 template (deployment-controller.yml.j2)
      → Pod env vars (FEATURE_*)
        → Go pkg/settings/features.go loads them

Feature Flag Environment Variables

Some features are gated by OpenShift version (e.g., VmwareSystemSerialNumber requires OCP ≥ 4.20, InsecureSkipVerify requires OCP ≥ 4.21).

Container Images

Defined in operator/related_images.yaml (referenced via RELATED_IMAGE_* env vars):

Deployment Topology

The operator creates these Deployments (all in the Forklift namespace):

forklift-controller (single pod, two containers)

Both containers share the same image (controller_image_fqin) but run different roles based on the ROLE env var. The Go code (pkg/settings/role.go) loads ROLE to enable main, inventory, or both.

forklift-api

Admission webhooks (validating + mutating) for Plans, Providers, Migrations, Secrets.

forklift-validation (optional, feature_validation)

OPA-based policy agent that validates VMs before migration.

forklift-ui-plugin (optional, feature_ui_plugin, OCP only)

This console plugin. Registers as a ConsolePlugin CR with OpenShift.

forklift-volume-populator-controller (optional, feature_volume_populator)

Watches VolumePopulator CRs and spawns populator pods (oVirt, OpenStack, XCOPY).

forklift-ova-proxy

Proxies inventory requests for OVA-based providers.

forklift-cli-download (optional, feature_cli_download, OCP only)

Serves kubectl-mtv binary downloads. Registered via ConsoleCLIDownload CR.

Ansible Role Structure

operator/roles/forkliftcontroller/
├── defaults/main.yml      # All configurable defaults
├── tasks/main.yml         # Reconciliation logic
├── tasks/cleanup.yml      # Resource cleanup for disabled features
├── tasks/webhooks.yml     # Webhook configuration
├── meta/main.yml          # Role metadata
└── templates/
    ├── controller/        # Controller deployment, configmap, services, routes
    ├── api/               # API deployment, webhooks, certificates
    ├── validation/        # Validation deployment, configmap
    ├── ui-plugin/         # UI plugin deployment, ConsolePlugin CR
    ├── populator/         # Volume populator controller deployment
    ├── ova-proxy/         # OVA proxy deployment, service, route
    ├── cli-download/      # CLI download server
    ├── monitor/           # ServiceMonitor, PrometheusRules, alerts
    └── smb-csi/           # SMB CSI driver (HyperV)

Reconciliation Flow (tasks/main.yml)

1. Evaluate feature flags → set *_state facts (present/absent)
2. Detect cluster type (OpenShift vs plain k8s via route.openshift.io API group)
3. Deploy controller ConfigMap + Deployment (always)
4. Deploy OVA proxy (always)
5. Deploy monitoring resources (OCP only)
6. Deploy volume populator controller (if enabled)
7. Configure TLS certificates (k8s: cert-manager; OCP: service-serving-cert)
8. Deploy API server + webhooks
9. Create default host Provider (if KubeVirt present)
10. Deploy validation (if enabled)
11. Deploy UI plugin + register ConsolePlugin (if enabled, OCP only)
12. Deploy CLI download (if enabled, OCP only)
13. Cleanup disabled features

Environment Variable Propagation

The operator injects configuration into the controller pod via two mechanisms:

1. Direct env vars in the Deployment template (feature flags, image refs, resource limits)
2. ConfigMap (forklift-controller-config) mounted as envFrom

The Go controller loads all settings at startup via pkg/settings.Settings.Load() which reads:

• pkg/settings/role.go — ROLE (main, inventory)
• pkg/settings/features.go — FEATURE_* flags
• pkg/settings/migration.go — Migration tuning (MAX_VM_INFLIGHT, VIRT_V2V_IMAGE, etc.)
• pkg/settings/inventory.go — API server config (port, TLS, auth)
• pkg/settings/policy.go — Validation policy agent URL
• pkg/settings/metrics.go — Metrics port
• pkg/settings/logging.go — Log level
• pkg/settings/profiler.go — CPU/memory profiling
• pkg/settings/providers.go — Provider-specific image refs

Streams (Upstream vs Downstream)

OCP vs K8s Differences

The operator detects OpenShift by checking for route.openshift.io API group:

Key Tuning Parameters