hip-0400

HIP-400: Service CRD. Status Active. Hanzo's own standard — read this before implementing against it.

HIP-0400: Service CRD

Abstract

The Service CRD models a generic stateless workload backed by a container image. It is the default abstraction for any HTTP/gRPC service that does not need persistent storage. The operator materializes a Service CR into a Deployment, a Service, and optionally an Ingress, HorizontalPodAutoscaler, PodDisruptionBudget, NetworkPolicy, and KMSSecret. The Service Kind is the canonical replacement for the legacy HanzoService (v1alpha1) alias.

Specification

Group + version

hanzo.ai/v1 (also lux.cloud/v1, zoo.cloud/v1, osage.cloud/v1 when the operator is installed with --api-group).

Spec fields

| Field | Type | Description | |---|---|---| | image | ImageSpec | repository, tag, pullPolicy | | replicas | int | desired Pod count | | ports | []ServicePort | name, containerPort, servicePort | | env | []EnvVar | environment variables (load-bearing — must be honored) | | envFrom | []EnvFromSource | secret/configmap-derived envs | | volumes | []Volume | Pod volumes (load-bearing) | | volumeMounts | []VolumeMount | container mounts (load-bearing) | | resources | ResourceRequirements | requests/limits | | livenessProbe | ProbeSpec | liveness probe | | readinessProbe | ProbeSpec | readiness probe | | ingress | IngressSpec | optional Ingress | | autoscaling | AutoscalingSpec | optional HPA | | pdb | PodDisruptionBudgetSpec | optional PDB | | networkPolicy | NetworkPolicySpec | optional NetworkPolicy | | serviceMonitor | ServiceMonitorSpec | optional Prometheus scrape | | kmsSecrets | []KMSSecretRef | KMS-sourced secret mounts | | sidecars | []Container | sidecar containers | | initContainers | []Container | init containers | | imagePullSecrets | []LocalObjectReference | registry creds | | serviceAccountName | string | SA name | | strategy | string | RollingUpdate / Recreate | | command, args | []string | entrypoint overrides |

Example CR

apiVersion: hanzo.ai/v1
kind: Service
metadata:
  name: example
  namespace: hanzo
spec:
  image:
    repository: ghcr.io/hanzoai/example
    tag: v1.2.3
  replicas: 2
  ports:
    - name: http
      containerPort: 8080
      servicePort: 80
  env:
    - name: LOG_LEVEL
      value: info
  resources:
    requests: { cpu: 100m, memory: 256Mi }
    limits:   { cpu: 1,    memory: 1Gi }

Generated K8s resources

• Deployment
• Service (ClusterIP)
• Ingress (if spec.ingress)
• HorizontalPodAutoscaler (if spec.autoscaling)
• PodDisruptionBudget (if spec.pdb)
• NetworkPolicy (if spec.networkPolicy)
• KMSSecret cross-references (if spec.kmsSecrets)
• ServiceMonitor (if spec.serviceMonitor)

Operator reconciler

• Rust: ~/work/hanzo/operator/src/controllers/service.rs
• Go parity: deprecated, see legacy/go-impl-before-rust-port.

Invariant: env, envFrom, volumes, volumeMounts must round-trip from CR to Pod template. Asserted by controllers::service::tests.

Related services

Every facade Kind (IAM, KMS, LLM, Indexer, Explorer) delegates to the Service reconciler. The vast majority of CRs in ~/work/hanzo/universe/infra/k8s/hanzo-operator/crs/ are Service-shaped.

Status

Implemented in hanzoai/operator v0.3.0+. Active in cluster do-sfo3-the cluster for 40+ workloads.