aigroup-workflow 2.1.1 → 2.2.0

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

@@ -1,563 +0,0 @@
-# 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