Skip to content

Kubernetes

Uses the kubernetes Python client with server-side apply (field manager multihull). Built-in kinds only: Deployment, Service, HPA (KEDA ScaledObject when installed and concurrency is set) and Secret. No CRDs, no operator. It renders no Ingress and no Gateway API HTTPRoute today; both are planned, see #116.

- provider: gke-prod
type: kubernetes
priority: 1
replicas: {min: 2}
kubernetes: {context: gke_acme_europe-west4_prod, namespace: multihull}

Credentials: the kubeconfig context named in the target. Without context, hull running in a pod with no kubeconfig uses the pod’s service account, as the in-cluster controller does.

hull init writes namespace: multihull, and the Helm chart creates that namespace (workloads.namespace, labelled multihull.dev/managed-by: multihull) so helm install prepares the cluster for hull deploy. hull never creates namespaces: when the target namespace is missing, hull deploy stops before applying anything with namespace multihull not found in context <ctx>; install the multihull chart or run kubectl create namespace multihull. A spec without namespace still deploys to default.

Option Default Effect
serviceType LoadBalancer LoadBalancer, NodePort or ClusterIP
nodePort unset fixed node port, for NodePort or LoadBalancer
endpoint unset URL the router uses, stored as the Service annotation multihull.dev/endpoint

Without endpoint, the URL is the address a LoadBalancer Service reports in status.loadBalancer.ingress (a Service status field, not an Ingress resource), then the first node’s external or internal IP plus the node port, then the in-cluster DNS name. A kind cluster reached from the host uses NodePort with a kind extraPortMappings entry and an explicit endpoint:

kubernetes:
context: kind-multihull-live
namespace: multihull-live
serviceType: NodePort
nodePort: 30080
endpoint: http://127.0.0.1:30080

An empty resources.gpu runs the pod on CPU: no nvidia.com/gpu limit, toleration or GPU node selector.

testing/live/kubernetes-gpu/rbac.yaml is a least-privilege service account for one namespace, used by the Kubernetes GPU live run: server-side apply and delete of the four kinds, deployments/scale, pod logs, get on the namespace and list on nodes for GPU inventory. rediscover lists Deployments in every namespace, which it does not grant.

Spec field Kubernetes
container.image Deployment.spec.template.spec.containers[0].image
container.command, port container command, containerPort
resources.gpu nodeSelector + nvidia.com/gpu limit + tolerations
scaling.replicas Deployment replicas + HPA min/max (KEDA when concurrency set)
scaling.concurrency KEDA trigger target
container.health readiness and liveness probes
container.env container env
container.secrets Secret + envFrom
endpoint kubernetes.endpoint, LoadBalancer Service address, NodePort or cluster DNS

Ref stored in state: namespace plus resource names. Every resource carries the label multihull.dev/service=<name> for rediscover.

Each container.secrets name becomes a Secret key, which the API server limits to 253 letters, digits, -, _ or ., not . and not starting with ... Each container.env name must be non-empty printable ASCII without =, the rule every cluster enforces from 1.34 (RelaxedEnvironmentVariableValidation; older clusters are stricter). hull plan notes a name outside these rules and apply refuses it before calling the API server. From 1.30, envFrom passes every Secret key through; 1.29 and older skip keys that are not environment variable names.