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

Prerequisites#

Before installing the operator, ensure you have:

• Kubernetes 1.23+ 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:latest. 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.

The operator generates fully qualified internal Service and StatefulSet pod addresses using Kubernetes' default cluster.local DNS domain. On clusters configured with a different domain, add --cluster-domain=<domain> to the operator deployment args. The value must be a valid DNS subdomain; a trailing root dot is accepted and removed.

For TPU-backed InferencePool resources, the controller downloads the checksum-pinned PJRT libtpu.so plugin into an ephemeral volume before starting the inference container. TPU pods therefore need outbound HTTPS access to storage.googleapis.com. The published Antfly runtime image provides the shell, certificate roots, and download utilities used by that init container; custom InferencePool images must provide the same utilities.

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