This guide covers installing the Antfly Operator in your Kubernetes cluster.

Prerequisites#

Before installing the operator, ensure you have:

• Kubernetes 1.20+ cluster running
• kubectl installed and configured to access your cluster
• Storage class with dynamic provisioning (most cloud providers include this by default)
• Cluster admin permissions to create CRDs and cluster-scoped resources

Optional Prerequisites#

• metrics-server: Required for autoscaling (most managed Kubernetes services include this)
• Service mesh: For mTLS encryption (Istio, Linkerd, or Consul)

Quick Install#

Install the operator with a single command:

kubectl apply -f https://antfly.io/antfly-operator-install.yaml

This installs:

• Custom Resource Definitions (CRDs)
• Operator namespace (antfly-operator-namespace)
• ServiceAccount and RBAC permissions
• Operator Deployment

The operator binary defaults --inference-antfly-image to ghcr.io/antflydb/antfly:omni. If you use spec.inference and that image is not mirrored or available to your cluster, add --inference-antfly-image=<image> to the deployment args. The image must provide the /antfly inference runtime contract.

For production environments that manage CRDs through GitOps or another platform workflow, run the operator with --skip-crd-install=true and remove the customresourcedefinitions verbs from the operator ClusterRole. The default manifest keeps those permissions because startup CRD bootstrap is enabled by default.

If --enable-inference-controllers=false, the operator disables direct InferencePool/InferenceProxy reconciliation and AntflyCluster.spec.inference management. It does not delete previously owned InferencePool objects while the flag is disabled, even if spec.inference is removed during that time.

Verify Installation#

Check that the operator is running:

# Check operator pod status
kubectl get pods -n antfly-operator-namespace

# Expected output:
# NAME                              READY   STATUS    RESTARTS   AGE
# antfly-operator-xxxxxxxxx-xxxxx   1/1     Running   0          30s

Verify CRDs are installed:

kubectl get crd | grep antfly

# Expected output:
# antflybackups.antfly.io     2025-01-15T00:00:00Z
# antflyclusters.antfly.io    2025-01-15T00:00:00Z
# antflyrestores.antfly.io    2025-01-15T00:00:00Z
# inferencepools.antfly.io      2025-01-15T00:00:00Z
# inferenceproxies.antfly.io     2025-01-15T00:00:00Z

What Gets Installed#

The installation creates:

Install with Helm (Coming Soon)#

Helm chart installation will be available in a future release. Track progress in GitHub Issues.

Air-Gapped Installation#

For environments without internet access:

1. Download the install manifest:

   curl -LO https://antfly.io/antfly-operator-install.yaml
   

2. Pull and push the operator image to your private registry:

   # Pull from public registry
   docker pull ghcr.io/antflydb/antfly-operator:latest
   
   # Tag for private registry
   docker tag ghcr.io/antflydb/antfly-operator:latest \
     your-registry.example.com/antfly-operator:latest
   
   # Push to private registry
   docker push your-registry.example.com/antfly-operator:latest
   

3. Update the image in install.yaml:

   # Change image from ghcr.io/antflydb/antfly-operator:latest
   # to your-registry.example.com/antfly-operator:latest
   

4. Apply the manifest:

   kubectl apply -f install.yaml
   

Namespace Configuration#

By default, the operator watches all namespaces. To restrict to specific namespaces, modify the deployment:

# In the operator Deployment spec
env:
  - name: WATCH_NAMESPACE
    value: "namespace1,namespace2"

Resource Requirements#

The operator has minimal resource requirements:

Upgrading#

To upgrade the operator:

# Apply the new version
kubectl apply -f https://antfly.io/antfly-operator-install.yaml

The operator handles CRD upgrades automatically. Existing clusters continue running during the upgrade.

Uninstalling#

To completely remove the operator:

# Delete all Antfly clusters first
kubectl delete antflyclusters --all-namespaces --all
kubectl delete antflybackups --all-namespaces --all
kubectl delete antflyrestores --all-namespaces --all

# Uninstall the operator
kubectl delete -f https://antfly.io/antfly-operator-install.yaml

# Remove CRDs (the operator self-installs these but does not remove them on deletion)
kubectl delete crd antflyclusters.antfly.io antflybackups.antfly.io antflyrestores.antfly.io inferencepools.antfly.io inferenceproxies.antfly.io

# Remove PVCs left behind by StatefulSets (retained by default)
kubectl delete pvc -l app.kubernetes.io/name=antfly-database --all-namespaces

spec:
  storage:
    pvcRetentionPolicy:
      whenDeleted: Delete

See Storage Operations for details.

Troubleshooting Installation#

Operator Pod Not Starting#

Check pod events:

kubectl describe pod -n antfly-operator-namespace -l app.kubernetes.io/name=antfly-operator

Common issues:

• ImagePullBackOff: Registry access issue or incorrect image name
• CrashLoopBackOff: Check operator logs with kubectl logs -n antfly-operator-namespace -l app.kubernetes.io/name=antfly-operator

RBAC Errors#

If you see permission errors:

# Verify ClusterRoleBinding
kubectl get clusterrolebinding antfly-operator-cluster-role-binding -o yaml

# Test permissions
kubectl auth can-i create statefulsets --as=system:serviceaccount:antfly-operator-namespace:antfly-operator-service-account

CRDs Not Installed#

# Check if CRDs exist
kubectl get crd | grep antfly

# Manually apply CRDs if missing
kubectl apply -f https://antfly.io/antfly-operator-install.yaml

Next Steps#

• Quickstart: Deploy your first cluster
• Concepts: Understand the architecture
• Cloud Platforms: Platform-specific guides