aigroup-workflow 2.1.2 → 2.2.1

package/skills/infra/kubernetes-specialist/references/custom-operators.md

@@ -0,0 +1,563 @@
+# Custom Operators
+
+---
+
+## CustomResourceDefinition (CRD)
+
+```yaml
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: databases.mycompany.io
+spec:
+  group: mycompany.io
+  names:
+    kind: Database
+    listKind: DatabaseList
+    plural: databases
+    singular: database
+    shortNames:
+      - db
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+          required:
+            - spec
+          properties:
+            spec:
+              type: object
+              required:
+                - engine
+                - version
+                - storage
+              properties:
+                engine:
+                  type: string
+                  enum: [postgres, mysql, mongodb]
+                version:
+                  type: string
+                storage:
+                  type: string
+                  pattern: '^[0-9]+Gi$'
+                replicas:
+                  type: integer
+                  minimum: 1
+                  maximum: 5
+                  default: 1
+            status:
+              type: object
+              properties:
+                phase:
+                  type: string
+                  enum: [Pending, Creating, Running, Failed, Terminating]
+                ready:
+                  type: boolean
+                message:
+                  type: string
+                endpoint:
+                  type: string
+      subresources:
+        status: {}
+        scale:
+          specReplicasPath: .spec.replicas
+          statusReplicasPath: .status.replicas
+      additionalPrinterColumns:
+        - name: Engine
+          type: string
+          jsonPath: .spec.engine
+        - name: Version
+          type: string
+          jsonPath: .spec.version
+        - name: Status
+          type: string
+          jsonPath: .status.phase
+        - name: Age
+          type: date
+          jsonPath: .metadata.creationTimestamp
+```
+
+## Custom Resource Instance
+
+```yaml
+apiVersion: mycompany.io/v1
+kind: Database
+metadata:
+  name: orders-db
+  namespace: production
+spec:
+  engine: postgres
+  version: "15.4"
+  storage: 100Gi
+  replicas: 3
+```
+
+## Operator SDK Project Structure
+
+```
+my-operator/
+├── Dockerfile
+├── Makefile
+├── PROJECT                     # Kubebuilder project config
+├── config/
+│   ├── crd/                    # CRD manifests
+│   │   └── bases/
+│   │       └── mycompany.io_databases.yaml
+│   ├── manager/                # Operator deployment
+│   │   └── manager.yaml
+│   ├── rbac/                   # RBAC configuration
+│   │   ├── role.yaml
+│   │   ├── role_binding.yaml
+│   │   └── service_account.yaml
+│   └── samples/                # Example CRs
+│       └── mycompany_v1_database.yaml
+├── api/
+│   └── v1/
+│       ├── database_types.go   # API type definitions
+│       ├── groupversion_info.go
+│       └── zz_generated.deepcopy.go
+├── controllers/
+│   └── database_controller.go  # Reconciliation logic
+├── main.go                     # Entry point
+└── go.mod
+```
+
+## API Type Definition (Go)
+
+```go
+// api/v1/database_types.go
+package v1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// DatabaseSpec defines the desired state of Database
+type DatabaseSpec struct {
+	// Engine is the database engine type
+	// +kubebuilder:validation:Enum=postgres;mysql;mongodb
+	Engine string `json:"engine"`
+
+	// Version is the database version
+	Version string `json:"version"`
+
+	// Storage is the size of persistent storage
+	// +kubebuilder:validation:Pattern=`^[0-9]+Gi$`
+	Storage string `json:"storage"`
+
+	// Replicas is the number of database instances
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=5
+	// +kubebuilder:default=1
+	// +optional
+	Replicas int32 `json:"replicas,omitempty"`
+}
+
+// DatabaseStatus defines the observed state of Database
+type DatabaseStatus struct {
+	// Phase represents the current lifecycle phase
+	Phase string `json:"phase,omitempty"`
+
+	// Ready indicates if the database is ready to accept connections
+	Ready bool `json:"ready,omitempty"`
+
+	// Message provides additional status information
+	Message string `json:"message,omitempty"`
+
+	// Endpoint is the connection endpoint
+	Endpoint string `json:"endpoint,omitempty"`
+
+	// Replicas is the current number of running replicas
+	Replicas int32 `json:"replicas,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas
+// +kubebuilder:printcolumn:name="Engine",type=string,JSONPath=`.spec.engine`
+// +kubebuilder:printcolumn:name="Version",type=string,JSONPath=`.spec.version`
+// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.phase`
+// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
+
+// Database is the Schema for the databases API
+type Database struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   DatabaseSpec   `json:"spec,omitempty"`
+	Status DatabaseStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// DatabaseList contains a list of Database
+type DatabaseList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []Database `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&Database{}, &DatabaseList{})
+}
+```
+
+## Controller Implementation
+
+```go
+// controllers/database_controller.go
+package controllers
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/resource"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+	"sigs.k8s.io/controller-runtime/pkg/log"
+
+	mycompanyv1 "github.com/mycompany/database-operator/api/v1"
+)
+
+const databaseFinalizer = "databases.mycompany.io/finalizer"
+
+type DatabaseReconciler struct {
+	client.Client
+	Scheme *runtime.Scheme
+}
+
+// +kubebuilder:rbac:groups=mycompany.io,resources=databases,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=mycompany.io,resources=databases/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=mycompany.io,resources=databases/finalizers,verbs=update
+// +kubebuilder:rbac:groups=apps,resources=statefulsets,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=core,resources=services,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=core,resources=persistentvolumeclaims,verbs=get;list;watch
+
+func (r *DatabaseReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+	logger := log.FromContext(ctx)
+
+	// Fetch the Database instance
+	database := &mycompanyv1.Database{}
+	if err := r.Get(ctx, req.NamespacedName, database); err != nil {
+		if errors.IsNotFound(err) {
+			return ctrl.Result{}, nil
+		}
+		return ctrl.Result{}, err
+	}
+
+	// Handle deletion with finalizer
+	if !database.DeletionTimestamp.IsZero() {
+		if controllerutil.ContainsFinalizer(database, databaseFinalizer) {
+			if err := r.cleanupResources(ctx, database); err != nil {
+				return ctrl.Result{}, err
+			}
+			controllerutil.RemoveFinalizer(database, databaseFinalizer)
+			if err := r.Update(ctx, database); err != nil {
+				return ctrl.Result{}, err
+			}
+		}
+		return ctrl.Result{}, nil
+	}
+
+	// Add finalizer if not present
+	if !controllerutil.ContainsFinalizer(database, databaseFinalizer) {
+		controllerutil.AddFinalizer(database, databaseFinalizer)
+		if err := r.Update(ctx, database); err != nil {
+			return ctrl.Result{}, err
+		}
+	}
+
+	// Reconcile StatefulSet
+	statefulSet := r.buildStatefulSet(database)
+	if err := controllerutil.SetControllerReference(database, statefulSet, r.Scheme); err != nil {
+		return ctrl.Result{}, err
+	}
+
+	found := &appsv1.StatefulSet{}
+	err := r.Get(ctx, types.NamespacedName{Name: statefulSet.Name, Namespace: statefulSet.Namespace}, found)
+	if err != nil && errors.IsNotFound(err) {
+		logger.Info("Creating StatefulSet", "name", statefulSet.Name)
+		if err := r.Create(ctx, statefulSet); err != nil {
+			return ctrl.Result{}, err
+		}
+		return r.updateStatus(ctx, database, "Creating", false, "StatefulSet created")
+	} else if err != nil {
+		return ctrl.Result{}, err
+	}
+
+	// Reconcile Service
+	service := r.buildService(database)
+	if err := controllerutil.SetControllerReference(database, service, r.Scheme); err != nil {
+		return ctrl.Result{}, err
+	}
+
+	foundSvc := &corev1.Service{}
+	err = r.Get(ctx, types.NamespacedName{Name: service.Name, Namespace: service.Namespace}, foundSvc)
+	if err != nil && errors.IsNotFound(err) {
+		if err := r.Create(ctx, service); err != nil {
+			return ctrl.Result{}, err
+		}
+	}
+
+	// Update status based on StatefulSet state
+	if found.Status.ReadyReplicas == *found.Spec.Replicas {
+		return r.updateStatus(ctx, database, "Running", true,
+			fmt.Sprintf("%d/%d replicas ready", found.Status.ReadyReplicas, *found.Spec.Replicas))
+	}
+
+	// Requeue to check status
+	return ctrl.Result{RequeueAfter: 10 * time.Second}, nil
+}
+
+func (r *DatabaseReconciler) buildStatefulSet(db *mycompanyv1.Database) *appsv1.StatefulSet {
+	replicas := db.Spec.Replicas
+	labels := map[string]string{
+		"app":        db.Name,
+		"controller": db.Name,
+	}
+
+	return &appsv1.StatefulSet{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      db.Name,
+			Namespace: db.Namespace,
+		},
+		Spec: appsv1.StatefulSetSpec{
+			Replicas: &replicas,
+			Selector: &metav1.LabelSelector{
+				MatchLabels: labels,
+			},
+			ServiceName: db.Name,
+			Template: corev1.PodTemplateSpec{
+				ObjectMeta: metav1.ObjectMeta{
+					Labels: labels,
+				},
+				Spec: corev1.PodSpec{
+					Containers: []corev1.Container{{
+						Name:  "database",
+						Image: fmt.Sprintf("%s:%s", db.Spec.Engine, db.Spec.Version),
+						Ports: []corev1.ContainerPort{{
+							ContainerPort: 5432,
+							Name:          "db",
+						}},
+					}},
+				},
+			},
+			VolumeClaimTemplates: []corev1.PersistentVolumeClaim{{
+				ObjectMeta: metav1.ObjectMeta{
+					Name: "data",
+				},
+				Spec: corev1.PersistentVolumeClaimSpec{
+					AccessModes: []corev1.PersistentVolumeAccessMode{
+						corev1.ReadWriteOnce,
+					},
+					Resources: corev1.VolumeResourceRequirements{
+						Requests: corev1.ResourceList{
+							corev1.ResourceStorage: resource.MustParse(db.Spec.Storage),
+						},
+					},
+				},
+			}},
+		},
+	}
+}
+
+func (r *DatabaseReconciler) buildService(db *mycompanyv1.Database) *corev1.Service {
+	return &corev1.Service{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      db.Name,
+			Namespace: db.Namespace,
+		},
+		Spec: corev1.ServiceSpec{
+			Selector: map[string]string{"app": db.Name},
+			Ports: []corev1.ServicePort{{
+				Port: 5432,
+				Name: "db",
+			}},
+			ClusterIP: "None", // Headless service for StatefulSet
+		},
+	}
+}
+
+func (r *DatabaseReconciler) updateStatus(ctx context.Context, db *mycompanyv1.Database,
+	phase string, ready bool, message string) (ctrl.Result, error) {
+	db.Status.Phase = phase
+	db.Status.Ready = ready
+	db.Status.Message = message
+	db.Status.Endpoint = fmt.Sprintf("%s.%s.svc.cluster.local:5432", db.Name, db.Namespace)
+	return ctrl.Result{}, r.Status().Update(ctx, db)
+}
+
+func (r *DatabaseReconciler) cleanupResources(ctx context.Context, db *mycompanyv1.Database) error {
+	// Custom cleanup logic (e.g., backup before deletion)
+	return nil
+}
+
+func (r *DatabaseReconciler) SetupWithManager(mgr ctrl.Manager) error {
+	return ctrl.NewControllerManagedBy(mgr).
+		For(&mycompanyv1.Database{}).
+		Owns(&appsv1.StatefulSet{}).
+		Owns(&corev1.Service{}).
+		Complete(r)
+}
+```
+
+## Operator RBAC
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: database-operator
+  namespace: operators
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: database-operator-role
+rules:
+  - apiGroups: ["mycompany.io"]
+    resources: ["databases"]
+    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+  - apiGroups: ["mycompany.io"]
+    resources: ["databases/status"]
+    verbs: ["get", "update", "patch"]
+  - apiGroups: ["mycompany.io"]
+    resources: ["databases/finalizers"]
+    verbs: ["update"]
+  - apiGroups: ["apps"]
+    resources: ["statefulsets"]
+    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+  - apiGroups: [""]
+    resources: ["services", "configmaps", "secrets"]
+    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+  - apiGroups: [""]
+    resources: ["persistentvolumeclaims"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: [""]
+    resources: ["events"]
+    verbs: ["create", "patch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: database-operator-rolebinding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: database-operator-role
+subjects:
+  - kind: ServiceAccount
+    name: database-operator
+    namespace: operators
+```
+
+## Operator Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: database-operator
+  namespace: operators
+  labels:
+    app: database-operator
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: database-operator
+  template:
+    metadata:
+      labels:
+        app: database-operator
+    spec:
+      serviceAccountName: database-operator
+      securityContext:
+        runAsNonRoot: true
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: manager
+          image: myregistry.io/database-operator:v1.0.0
+          args:
+            - --leader-elect
+            - --health-probe-bind-address=:8081
+          securityContext:
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop: ["ALL"]
+            readOnlyRootFilesystem: true
+          ports:
+            - containerPort: 8080
+              name: metrics
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 8081
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 8081
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          resources:
+            limits:
+              cpu: 500m
+              memory: 128Mi
+            requests:
+              cpu: 10m
+              memory: 64Mi
+```
+
+## Operator SDK Commands
+
+```bash
+# Initialize new operator project
+operator-sdk init --domain mycompany.io --repo github.com/mycompany/database-operator
+
+# Create new API (CRD + controller)
+operator-sdk create api --group mycompany --version v1 --kind Database --resource --controller
+
+# Generate manifests (CRD, RBAC)
+make manifests
+
+# Generate deep copy methods
+make generate
+
+# Build operator image
+make docker-build docker-push IMG=myregistry.io/database-operator:v1.0.0
+
+# Deploy to cluster
+make deploy IMG=myregistry.io/database-operator:v1.0.0
+
+# Undeploy
+make undeploy
+```
+
+## Best Practices
+
+1. **Use finalizers** for cleanup of external resources before CR deletion
+2. **Set owner references** so owned resources are garbage collected with the CR
+3. **Implement idempotent reconciliation** - same input should produce same output
+4. **Use status subresource** to separate desired state (spec) from observed state (status)
+5. **Add validation** via OpenAPI schema or webhooks
+6. **Emit events** for significant state changes
+7. **Use leader election** for high availability
+8. **Set resource limits** on the operator deployment
+9. **Follow least privilege** RBAC principles
+10. **Test with envtest** for unit testing controllers