feat: implements Activityworker CRD and Controller

Author: Algatux

PROJECT

@@ -18,4 +18,13 @@ resources:
   kind: Activity
   path: algatux.dev/kube-activity-engine/api/v1beta1
   version: v1beta1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: algatux.dev
+  group: kube-activity-engine
+  kind: ActivityWorker
+  path: algatux.dev/kube-activity-engine/api/v1beta1
+  version: v1beta1
 version: "3"

README.md

@@ -4,23 +4,46 @@ A Kubernetes operator for managing Activity resources with distributed worker ex
 
 ## Overview
 
-KubeActivityEngine is a Kubernetes controller that manages custom `Activity` resources. It provides a framework for orchestrating activities with configurable inputs and tracking the status of multiple workers executing those activities. The operator maintains state information for each worker (READY, RUNNING, COMPLETED, FAILED) and provides a declarative way to manage distributed activity execution in Kubernetes clusters.
+KubeActivityEngine is a Kubernetes operator that manages custom `Activity` and `ActivityWorker` resources. It provides a framework for orchestrating activities with configurable inputs and automatically creating workers to execute those activities. When an Activity enters the Initialization state, the controller creates ActivityWorker resources that define job specifications. The operator provides a declarative way to manage distributed activity execution in Kubernetes clusters with full lifecycle tracking.
 
 ## Features
 
-- **Custom Resource Definition (CRD)**: Define activities as Kubernetes resources
+- **Dual Custom Resource Definitions (CRDs)**: Define activities and workers as Kubernetes resources
+  - **Activity CRD**: Orchestrates activity lifecycle with configurable inputs
+  - **ActivityWorker CRD**: Defines job specifications with ActivityJob structure
+- **Automatic Worker Creation**: Controller automatically creates ActivityWorker resources during Activity initialization
+- **Flexible Job Configuration**: ActivityJob spec supports custom images, commands, args, environment variables, and pull policies
 - **Worker Status Tracking**: Monitor the state of multiple workers processing activities
-- **Configurable Inputs**: Pass key-value input parameters to activities
 - **Kubernetes-Native**: Built using the Kubebuilder framework with full Kubernetes API integration
 - **Status Conditions**: Track activity lifecycle with standard Kubernetes condition types
 - **RBAC Support**: Fine-grained access control with admin, editor, and viewer roles
 
 ## Architecture
 
-The operator watches for `Activity` custom resources and manages their lifecycle. Each Activity resource contains:
+The operator manages two custom resource types that work together:
 
-- **Spec**: Desired state including activity name and input parameters
-- **Status**: Observed state with worker statuses and conditions
+### Activity Resource
+
+The `Activity` CRD represents a unit of work to be executed. Each Activity contains:
+
+- **Spec**: Desired state including activity name and input parameters (key-value pairs)
+- **Status**: Observed state with conditions tracking the activity lifecycle
+
+When an Activity is created and reaches the "Initialization" condition state, the controller automatically creates ActivityWorker resources.
+
+### ActivityWorker Resource
+
+The `ActivityWorker` CRD defines the execution specification for workers. Each ActivityWorker contains:
+
+- **Spec**: Job specification using the `ActivityJob` structure
+  - **Name**: Unique identifier for the job
+  - **Image**: Container image to run (e.g., `bash:5.0`)
+  - **Command**: Command array to execute (e.g., `["bash", "-c"]`)
+  - **Args**: Arguments array for the command (e.g., `["echo done!"]`)
+  - **Env**: Environment variables for the container
+  - **ImagePullPolicy**: Pull policy for the container image
+- **Status**: Observed state with conditions tracking the worker lifecycle
+- **Labels**: Automatically labeled with `kube-activity-engine.algatux.dev/activity` to link to parent Activity
 
 ### Activity States
 
@@ -108,6 +131,48 @@ View detailed information:
 kubectl describe activity my-activity
 ```
 
+### Quick Demo
+
+After applying an Activity, the controller automatically creates an **ActivityWorker** resource that defines a job specification. The ActivityWorker uses the new `ActivityJob` CRD structure:
+
+**Default ActivityJob Configuration:**
+- **Image**: `bash:5.0`
+- **Command**: `["bash", "-c"]`
+- **Args**: `["echo done!"]`
+- **Environment**: `TEST=FAKE` (example environment variable)
+- **ImagePullPolicy**: `IfNotPresent`
+
+**Verify the created resources:**
+
+List ActivityWorkers for your activity:
+```sh
+kubectl get activityworkers -l kube-activity-engine.algatux.dev/activity=my-activity
+```
+
+View ActivityWorker details:
+```sh
+kubectl describe activityworker <worker-name>
+```
+
+Check the ActivityWorker spec:
+```sh
+kubectl get activityworker <worker-name> -o yaml
+```
+
+**Expected Output:**
+The ActivityWorker will show the job configuration including the bash command that echoes "done!". The worker's status conditions will track its lifecycle state.
+
+**Troubleshooting the demo:**
+- If no ActivityWorkers are created, check the Activity status conditions:
+  ```sh
+  kubectl get activity my-activity -o jsonpath='{.status.conditions}'
+  ```
+- Check the controller logs for any errors:
+  ```sh
+  kubectl logs -n kubeactivityengine-system deployment/kubeactivityengine-controller-manager
+  ```
+- Verify that the Activity has the "Initialization" condition set to "True"
+
 ### Checking Worker Status
 
 Monitor the status of workers processing your activity:
@@ -196,26 +261,41 @@ The chart will be available in `dist/chart/`. Use `--force` flag when updating i
 ## Project Structure
 
 ```
-├── api/v1beta1/              # API definitions
-│   └── activity_types.go     # Activity CRD types
-├── internal/controller/       # Controller implementations
-│   └── activity_controller.go # Activity reconciler
-├── config/                    # Kubernetes manifests
-│   ├── crd/                  # CRD definitions
-│   ├── rbac/                 # RBAC configurations
-│   ├── samples/              # Example resources
-│   └── manager/              # Controller deployment
-└── cmd/                       # Application entrypoint
+├── api/v1beta1/                      # API definitions
+│   ├── activity_types.go             # Activity CRD types
+│   ├── activityworker_types.go       # ActivityWorker CRD types (includes ActivityJob spec)
+│   └── states/                       # State type definitions
+├── internal/
+│   ├── controller/                   # Controller implementations
+│   │   ├── activity_controller.go    # Activity reconciler
+│   │   └── activityworker_controller.go # ActivityWorker reconciler
+│   └── state_machine/                # State machine logic
+│       ├── activity_state_machine.go # Handler retrieval logic
+│       └── transitions/              # State transition handlers
+│           ├── initialization.go     # Initialization state handler (creates ActivityWorkers)
+│           └── empty_conditions.go   # Initial state handler
+├── config/                           # Kubernetes manifests
+│   ├── crd/                         # CRD definitions
+│   ├── rbac/                        # RBAC configurations
+│   ├── samples/                     # Example resources
+│   └── manager/                     # Controller deployment
+└── cmd/                              # Application entrypoint
 ```
 
 ## RBAC Roles
 
-The operator provides three predefined roles:
+The operator provides predefined roles for both Activity and ActivityWorker resources:
 
+**Activity Roles:**
 - **activity-admin-role**: Full access to Activity resources
 - **activity-editor-role**: Create, update, and delete activities
 - **activity-viewer-role**: Read-only access to activities
 
+**ActivityWorker Roles:**
+- **activityworker-admin-role**: Full access to ActivityWorker resources
+- **activityworker-editor-role**: Create, update, and delete activity workers
+- **activityworker-viewer-role**: Read-only access to activity workers
+
 ## Contributing
 
 We welcome contributions! To contribute:

api/v1beta1/activity_types.go

@@ -24,7 +24,7 @@ import (
 type ActivityInputs map[string]string
 type ActivityWorkersStatus map[string]ActivityWorkerStatus
 
-type ActivityWorkerStatus struct {
+type ActivityWorkerRefs struct {
 	Id     string                     `json:"id"`
 	Status states.ActivityWorkerState `json:"status"`
 }
@@ -70,7 +70,7 @@ type ActivityStatus struct {
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
 	// ActivityWorkerStatuses
-	WorkersStatus ActivityWorkersStatus `json:"workersStatus,omitempty"`
+	WorkersStatus []ActivityWorkerRefs `json:"workersStatus,omitempty"`
 }
 
 // +kubebuilder:object:root=true

api/v1beta1/activityworker_types.go

@@ -0,0 +1,97 @@
+/*
+Copyright 2025.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1beta1
+
+import (
+	v1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
+// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
+
+type ActivityJob struct {
+	Name            string        `json:"name"`
+	Image           string        `json:"image"`
+	Command         []string      `json:"command"`
+	Args            []string      `json:"args"`
+	Env             []v1.EnvVar   `json:"env"`
+	ImagePullPolicy v1.PullPolicy `json:"imagePullPolicy"`
+}
+
+// ActivityWorkerSpec defines the desired state of ActivityWorker
+type ActivityWorkerSpec struct {
+	// More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
+
+	Job *ActivityJob `json:"job"`
+}
+
+// ActivityWorkerStatus defines the observed state of ActivityWorker.
+type ActivityWorkerStatus struct {
+	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// For Kubernetes API conventions, see:
+	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
+
+	// conditions represent the current state of the ActivityWorker resource.
+	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
+	//
+	// Standard condition types include:
+	// - "Available": the resource is fully functional
+	// - "Progressing": the resource is being created or updated
+	// - "Degraded": the resource failed to reach or maintain its desired state
+	//
+	// The status of each condition is one of True, False, or Unknown.
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+
+// ActivityWorker is the Schema for the activityworkers API
+type ActivityWorker struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`
+
+	// spec defines the desired state of ActivityWorker
+	// +required
+	Spec ActivityWorkerSpec `json:"spec"`
+
+	// status defines the observed state of ActivityWorker
+	// +optional
+	Status ActivityWorkerStatus `json:"status,omitempty,omitzero"`
+}
+
+// +kubebuilder:object:root=true
+
+// ActivityWorkerList contains a list of ActivityWorker
+type ActivityWorkerList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []ActivityWorker `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&ActivityWorker{}, &ActivityWorkerList{})
+}