chore: import upstream snapshot with attribution

deploy/kubernetes/README.md

@@ -0,0 +1,31 @@
+# Kubernetes deployment foundation (alpha)
+
+This package is the first opt-in Kubernetes foundation for the Go Micro lifecycle:
+`Service`, `Agent`, and `Flow` resources. It is intentionally experimental and
+additive. Nothing in the Go Micro runtime installs these resources or changes
+production defaults.
+
+## What is included
+
+- Alpha CRD manifests in `config/crd/` for `agents.micro.dev`,
+  `services.micro.dev`, and `flows.micro.dev`.
+- A small dependency-free mapper that turns a desired Go Micro resource into the
+  Kubernetes `Deployment` shape an operator reconciliation loop will own.
+- Unit tests that validate the structural CRD fragments and dry-run the
+  Agent-to-Deployment mapping.
+
+## Local validation
+
+```sh
+go test ./deploy/kubernetes
+```
+
+If you have a Kubernetes cluster and `kubectl` available, you can also perform a
+server-side dry run of the CRDs:
+
+```sh
+kubectl apply --dry-run=server -f deploy/kubernetes/config/crd/
+```
+
+The manifests are `v1alpha1`; expect the API shape to evolve before this becomes
+a production operator.

deploy/kubernetes/config/crd/agent.yaml

@@ -0,0 +1,37 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: agents.micro.dev
+spec:
+  group: micro.dev
+  scope: Namespaced
+  names:
+    plural: agents
+    singular: agent
+    kind: Agent
+    shortNames: [magent]
+  versions:
+  - name: v1alpha1
+    served: true
+    storage: true
+    schema:
+      openAPIV3Schema:
+        type: object
+        required: [spec]
+        properties:
+          spec:
+            type: object
+            required: [image]
+            properties:
+              image: {type: string, minLength: 1}
+              command:
+                type: array
+                items: {type: string}
+              args:
+                type: array
+                items: {type: string}
+              replicas: {type: integer, minimum: 0}
+              registry: {type: string}
+              env:
+                type: object
+                additionalProperties: {type: string}

deploy/kubernetes/config/crd/flow.yaml

@@ -0,0 +1,37 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: flows.micro.dev
+spec:
+  group: micro.dev
+  scope: Namespaced
+  names:
+    plural: flows
+    singular: flow
+    kind: Flow
+    shortNames: [mflow]
+  versions:
+  - name: v1alpha1
+    served: true
+    storage: true
+    schema:
+      openAPIV3Schema:
+        type: object
+        required: [spec]
+        properties:
+          spec:
+            type: object
+            required: [image]
+            properties:
+              image: {type: string, minLength: 1}
+              command:
+                type: array
+                items: {type: string}
+              args:
+                type: array
+                items: {type: string}
+              replicas: {type: integer, minimum: 0}
+              registry: {type: string}
+              env:
+                type: object
+                additionalProperties: {type: string}

deploy/kubernetes/config/crd/service.yaml

@@ -0,0 +1,37 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: services.micro.dev
+spec:
+  group: micro.dev
+  scope: Namespaced
+  names:
+    plural: services
+    singular: service
+    kind: Service
+    shortNames: [mservice]
+  versions:
+  - name: v1alpha1
+    served: true
+    storage: true
+    schema:
+      openAPIV3Schema:
+        type: object
+        required: [spec]
+        properties:
+          spec:
+            type: object
+            required: [image]
+            properties:
+              image: {type: string, minLength: 1}
+              command:
+                type: array
+                items: {type: string}
+              args:
+                type: array
+                items: {type: string}
+              replicas: {type: integer, minimum: 0}
+              registry: {type: string}
+              env:
+                type: object
+                additionalProperties: {type: string}

deploy/kubernetes/doc.go

@@ -0,0 +1,8 @@
+// Package kubernetes contains the experimental Kubernetes deployment foundation
+// for Go Micro services, agents, and flows.
+//
+// The package is intentionally small and additive: it exposes alpha custom
+// resource manifests and a dry-run mapper that turns a resource spec into the
+// Deployment shape an operator would reconcile. It does not install an operator
+// or change any runtime defaults.
+package kubernetes

deploy/kubernetes/kubernetes_test.go

@@ -0,0 +1,87 @@
+package kubernetes
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestCRDManifestsAreStructural(t *testing.T) {
+	for _, kind := range []Kind{KindAgent, KindService, KindFlow} {
+		manifest := CRDManifests[kind]
+		if manifest == "" {
+			t.Fatalf("missing manifest for %s", kind)
+		}
+		checks := []string{
+			"apiVersion: apiextensions.k8s.io/v1",
+			"kind: CustomResourceDefinition",
+			"group: micro.dev",
+			"kind: " + string(kind),
+			"name: v1alpha1",
+			"served: true",
+			"storage: true",
+			"openAPIV3Schema:",
+			"type: object",
+			"required: [image]",
+		}
+		for _, check := range checks {
+			if !strings.Contains(manifest, check) {
+				t.Fatalf("%s manifest missing %q:\n%s", kind, check, manifest)
+			}
+		}
+	}
+}
+
+func TestMapDeploymentForAgent(t *testing.T) {
+	deployment, err := MapDeployment(Resource{
+		Kind:      KindAgent,
+		Name:      "support-agent",
+		Namespace: "agents",
+		Spec: WorkloadSpec{
+			Image:    "ghcr.io/acme/support-agent:v1",
+			Replicas: 2,
+			Registry: "kubernetes",
+			Environment: map[string]string{
+				"MODEL": "gpt-5.5",
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("MapDeployment returned error: %v", err)
+	}
+	if deployment.Name != "support-agent" || deployment.Namespace != "agents" {
+		t.Fatalf("unexpected identity: %+v", deployment)
+	}
+	if deployment.Replicas != 2 {
+		t.Fatalf("replicas = %d, want 2", deployment.Replicas)
+	}
+	if got := deployment.Labels["micro.dev/kind"]; got != "agent" {
+		t.Fatalf("micro.dev/kind label = %q, want agent", got)
+	}
+	container := deployment.Pod.Container
+	if container.Image != "ghcr.io/acme/support-agent:v1" {
+		t.Fatalf("image = %q", container.Image)
+	}
+	if got := container.Environment["MICRO_REGISTRY"]; got != "kubernetes" {
+		t.Fatalf("MICRO_REGISTRY = %q, want kubernetes", got)
+	}
+	if got := container.Environment["MODEL"]; got != "gpt-5.5" {
+		t.Fatalf("MODEL = %q, want gpt-5.5", got)
+	}
+}
+
+func TestMapDeploymentDefaultsAndValidation(t *testing.T) {
+	deployment, err := MapDeployment(Resource{Kind: KindService, Name: "api", Spec: WorkloadSpec{Image: "api:latest"}})
+	if err != nil {
+		t.Fatalf("MapDeployment returned error: %v", err)
+	}
+	if deployment.Namespace != "default" || deployment.Replicas != 1 {
+		t.Fatalf("defaults = namespace %q replicas %d", deployment.Namespace, deployment.Replicas)
+	}
+
+	if _, err := MapDeployment(Resource{Kind: KindFlow, Name: "ingest"}); err == nil {
+		t.Fatal("MapDeployment without image succeeded")
+	}
+	if _, err := MapDeployment(Resource{Kind: "Job", Name: "job", Spec: WorkloadSpec{Image: "job:latest"}}); err == nil {
+		t.Fatal("MapDeployment with unsupported kind succeeded")
+	}
+}

deploy/kubernetes/manifests.go

@@ -0,0 +1,32 @@
+package kubernetes
+
+import (
+	"embed"
+	"fmt"
+)
+
+// crdFS holds the canonical CRD manifests. They live as real YAML under
+// config/crd/ so they can be applied directly (`kubectl apply -f
+// deploy/kubernetes/config/crd/`) and are embedded here so the Go API serves
+// the exact same bytes — one source of truth, no drift.
+//
+//go:embed config/crd/agent.yaml config/crd/service.yaml config/crd/flow.yaml
+var crdFS embed.FS
+
+// CRDManifests contains the alpha CRDs for Go Micro lifecycle resources, loaded
+// from the embedded config/crd/ YAML.
+var CRDManifests = map[Kind]string{
+	KindAgent:   mustCRD("agent"),
+	KindService: mustCRD("service"),
+	KindFlow:    mustCRD("flow"),
+}
+
+// mustCRD reads an embedded CRD manifest. The files are embedded at compile
+// time, so a read error means a build/packaging bug, not a runtime condition.
+func mustCRD(name string) string {
+	b, err := crdFS.ReadFile("config/crd/" + name + ".yaml")
+	if err != nil {
+		panic(fmt.Sprintf("kubernetes: embedded CRD %q missing: %v", name, err))
+	}
+	return string(b)
+}

deploy/kubernetes/types.go

@@ -0,0 +1,138 @@
+package kubernetes
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+const (
+	// Group is the API group for the alpha Go Micro Kubernetes resources.
+	Group = "micro.dev"
+	// Version is the current alpha API version for the CRDs in this package.
+	Version = "v1alpha1"
+)
+
+// Kind identifies a Go Micro lifecycle resource that can be reconciled toward a
+// Kubernetes Deployment.
+type Kind string
+
+const (
+	KindAgent   Kind = "Agent"
+	KindService Kind = "Service"
+	KindFlow    Kind = "Flow"
+)
+
+// WorkloadSpec is the common alpha spec shared by Agent, Service, and Flow CRDs.
+type WorkloadSpec struct {
+	Image       string            `json:"image"`
+	Command     []string          `json:"command,omitempty"`
+	Args        []string          `json:"args,omitempty"`
+	Replicas    int32             `json:"replicas,omitempty"`
+	Registry    string            `json:"registry,omitempty"`
+	Environment map[string]string `json:"env,omitempty"`
+}
+
+// Resource is the minimal desired state for a Go Micro lifecycle resource.
+type Resource struct {
+	Kind      Kind
+	Name      string
+	Namespace string
+	Spec      WorkloadSpec
+}
+
+// Deployment is a small, dependency-free representation of the Kubernetes
+// Deployment fields the alpha reconciler skeleton owns.
+type Deployment struct {
+	Name      string
+	Namespace string
+	Labels    map[string]string
+	Replicas  int32
+	Pod       PodTemplate
+}
+
+// PodTemplate describes the pod fields emitted by MapDeployment.
+type PodTemplate struct {
+	Labels    map[string]string
+	Container Container
+}
+
+// Container describes the single Go Micro workload container.
+type Container struct {
+	Name        string
+	Image       string
+	Command     []string
+	Args        []string
+	Environment map[string]string
+}
+
+// MapDeployment maps a Go Micro alpha resource to the Deployment shape an
+// operator reconciliation loop would apply.
+func MapDeployment(resource Resource) (Deployment, error) {
+	if resource.Kind != KindAgent && resource.Kind != KindService && resource.Kind != KindFlow {
+		return Deployment{}, fmt.Errorf("unsupported kind %q", resource.Kind)
+	}
+	name := strings.TrimSpace(resource.Name)
+	if name == "" {
+		return Deployment{}, fmt.Errorf("name is required")
+	}
+	image := strings.TrimSpace(resource.Spec.Image)
+	if image == "" {
+		return Deployment{}, fmt.Errorf("spec.image is required")
+	}
+
+	namespace := strings.TrimSpace(resource.Namespace)
+	if namespace == "" {
+		namespace = "default"
+	}
+	replicas := resource.Spec.Replicas
+	if replicas == 0 {
+		replicas = 1
+	}
+
+	labels := map[string]string{
+		"app.kubernetes.io/name":       name,
+		"app.kubernetes.io/managed-by": "go-micro",
+		"micro.dev/kind":               strings.ToLower(string(resource.Kind)),
+	}
+	env := copyMap(resource.Spec.Environment)
+	if resource.Spec.Registry != "" {
+		env["MICRO_REGISTRY"] = resource.Spec.Registry
+	}
+
+	return Deployment{
+		Name:      name,
+		Namespace: namespace,
+		Labels:    copyMap(labels),
+		Replicas:  replicas,
+		Pod: PodTemplate{
+			Labels: copyMap(labels),
+			Container: Container{
+				Name:        name,
+				Image:       image,
+				Command:     append([]string(nil), resource.Spec.Command...),
+				Args:        append([]string(nil), resource.Spec.Args...),
+				Environment: env,
+			},
+		},
+	}, nil
+}
+
+// EnvironmentKeys returns stable environment variable keys from a mapped
+// container. It is useful for deterministic validation and rendering.
+func (c Container) EnvironmentKeys() []string {
+	keys := make([]string, 0, len(c.Environment))
+	for key := range c.Environment {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+func copyMap(in map[string]string) map[string]string {
+	out := make(map[string]string, len(in))
+	for k, v := range in {
+		out[k] = v
+	}
+	return out
+}