feat: add Helmfile-managed k8s charts for tasks 10-13

Local charts: kafka-cluster (Strimzi Kafka+KafkaNodePool CRs, 3-replica KRaft
topology, 5Gi memory cap, Longhorn storage, pod anti-affinity), queue-crd
(Queue CRD + queue-operator Deployment/RBAC), management-service
(Deployment/Service/ConfigMap/HPA/Ingress, REST exposed externally via
cert-manager-issued TLS, raw gRPC kept cluster-internal per design.md §7a).

helmfile.yaml.gotmpl + releases.d/*.gotmpl wire strimzi-operator ->
kafka-cluster -> redis -> {queue-crd, management-service} via `needs:`.
Directory is releases.d, not helmfile.d as originally sketched in design.md
section 7b: Helmfile v1 treats a literal "helmfile.d" directory as a special
auto-discovery mode that conflicts with an explicit top-level helmfile.yaml.
Files use .gotmpl (required by Helmfile v1 for {{ }}-templated files) and
each declares its own environments: block, since nested helmfiles don't
inherit the parent's resolved values in this version.

Namespace is sqs throughout. environments/homelab.yaml carries no secrets.
Validated locally via helm lint/helm template (all 3 charts) and
`helmfile -e homelab build` (dependency ordering + value substitution) — no
cluster contact made. Live apply is a separate, explicitly-confirmed step.
This commit is contained in:
riotpiaole
2026-06-22 06:31:41 -07:00
parent fd69e33a98
commit 918ba9393f
24 changed files with 784 additions and 0 deletions
+5
View File
@@ -0,0 +1,5 @@
apiVersion: v2
name: kafka-cluster
description: Strimzi Kafka/KafkaNodePool CRs for the kmsvc Kafka cluster (design.md §7)
type: application
version: 0.1.0
@@ -0,0 +1,30 @@
apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
name: {{ .Values.clusterName }}
namespace: {{ .Values.namespace }}
annotations:
strimzi.io/node-pools: enabled
strimzi.io/kraft: enabled
spec:
kafka:
version: 4.0.0
metadataVersion: 4.0-IV3
listeners:
- name: plain
port: 9092
type: internal
tls: false
- name: tls
port: 9093
type: internal
tls: true
config:
default.replication.factor: {{ .Values.kafka.replicationFactor }}
min.insync.replicas: {{ .Values.kafka.minInsyncReplicas }}
offsets.topic.replication.factor: {{ .Values.kafka.replicationFactor }}
transaction.state.log.replication.factor: {{ .Values.kafka.replicationFactor }}
transaction.state.log.min.isr: {{ .Values.kafka.minInsyncReplicas }}
entityOperator:
topicOperator: {}
userOperator: {}
@@ -0,0 +1,39 @@
apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaNodePool
metadata:
name: {{ .Values.clusterName }}-pool
namespace: {{ .Values.namespace }}
labels:
strimzi.io/cluster: {{ .Values.clusterName }}
spec:
replicas: {{ .Values.nodePool.replicas }}
roles:
- controller
- broker
storage:
type: persistent-claim
size: {{ .Values.nodePool.storage.sizeGi }}Gi
class: {{ .Values.nodePool.storage.class }}
deleteClaim: false
resources:
limits:
memory: {{ .Values.nodePool.resources.memory }}
cpu: {{ .Values.nodePool.resources.cpu | quote }}
requests:
memory: {{ .Values.nodePool.resources.memory }}
cpu: {{ .Values.nodePool.resources.cpu | quote }}
template:
pod:
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
topologyKey: {{ .Values.nodePool.antiAffinityTopologyKey }}
labelSelector:
matchLabels:
strimzi.io/cluster: {{ .Values.clusterName }}
kafkaContainer:
env:
- name: KAFKA_HEAP_OPTS
value: {{ .Values.nodePool.heapOpts | quote }}
+21
View File
@@ -0,0 +1,21 @@
clusterName: kmsvc
namespace: sqs
nodePool:
replicas: 3
storage:
class: longhorn
sizeGi: 50
resources:
memory: 5Gi
cpu: "2"
heapOpts: "-Xms2g -Xmx2g"
# design.md §7: 2 of 3 pods land on talos-cp-1 today; a 3rd physical node
# is planned later. Anti-affinity keeps the scheduler spreading pods as
# evenly as the current node count allows, and will auto-rebalance once
# the new node joins — no replica/quorum change needed at that point.
antiAffinityTopologyKey: kubernetes.io/hostname
kafka:
replicationFactor: 3
minInsyncReplicas: 2
+5
View File
@@ -0,0 +1,5 @@
apiVersion: v2
name: management-service
description: kmsvc message-plane gRPC+REST server (design.md §1, §7a, §9)
type: application
version: 0.1.0
@@ -0,0 +1,12 @@
apiVersion: v1
kind: ConfigMap
metadata:
name: management-service-config
namespace: {{ .Values.namespace }}
data:
KMSVC_KAFKA_BROKERS: {{ .Values.env.kafkaBrokers | quote }}
KMSVC_REDIS_ADDR: {{ .Values.env.redisAddr | quote }}
KMSVC_AUTHENTIK_ISSUER_URL: {{ .Values.env.authentikIssuerURL | quote }}
KMSVC_AUTHENTIK_AUDIENCE: {{ .Values.env.authentikAudience | quote }}
KMSVC_GRPC_LISTEN_ADDR: ":{{ .Values.grpcPort }}"
KMSVC_HTTP_LISTEN_ADDR: ":{{ .Values.httpPort }}"
@@ -0,0 +1,39 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: management-service
namespace: {{ .Values.namespace }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
app: management-service
template:
metadata:
labels:
app: management-service
spec:
containers:
- name: management-service
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: grpc
containerPort: {{ .Values.grpcPort }}
- name: http
containerPort: {{ .Values.httpPort }}
envFrom:
- configMapRef:
name: management-service-config
resources:
{{- toYaml .Values.resources | nindent 12 }}
readinessProbe:
tcpSocket:
port: {{ .Values.httpPort }}
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
tcpSocket:
port: {{ .Values.httpPort }}
initialDelaySeconds: 10
periodSeconds: 20
@@ -0,0 +1,27 @@
{{- if .Values.hpa.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: management-service
namespace: {{ .Values.namespace }}
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: management-service
minReplicas: {{ .Values.hpa.minReplicas }}
maxReplicas: {{ .Values.hpa.maxReplicas }}
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: {{ .Values.hpa.targetCPUUtilizationPercentage }}
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: {{ .Values.hpa.targetMemoryUtilizationPercentage }}
{{- end }}
@@ -0,0 +1,26 @@
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: management-service
namespace: {{ .Values.namespace }}
annotations:
cert-manager.io/cluster-issuer: {{ .Values.ingress.clusterIssuer }}
spec:
ingressClassName: {{ .Values.ingress.className }}
tls:
- hosts:
- {{ .Values.ingress.host }}
secretName: {{ .Values.ingress.tlsSecretName }}
rules:
- host: {{ .Values.ingress.host }}
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: management-service
port:
number: {{ .Values.httpPort }}
{{- end }}
@@ -0,0 +1,16 @@
apiVersion: v1
kind: Service
metadata:
name: management-service
namespace: {{ .Values.namespace }}
spec:
selector:
app: management-service
ports:
- name: grpc
port: {{ .Values.grpcPort }}
targetPort: {{ .Values.grpcPort }}
- name: http
port: {{ .Values.httpPort }}
targetPort: {{ .Values.httpPort }}
type: ClusterIP
+38
View File
@@ -0,0 +1,38 @@
namespace: sqs
replicaCount: 2
image:
repository: forgejo.riotpiao.homelab.com/rock/kafka-management-service
tag: latest
pullPolicy: IfNotPresent
grpcPort: 9090
httpPort: 8080
env:
kafkaBrokers: "kmsvc-kafka-bootstrap.sqs.svc.cluster.local:9092"
redisAddr: "kmsvc-redis-master.sqs.svc.cluster.local:6379"
authentikIssuerURL: ""
authentikAudience: ""
resources:
requests:
cpu: 200m
memory: 256Mi
limits:
cpu: "1"
memory: 512Mi
hpa:
enabled: true
minReplicas: 2
maxReplicas: 6
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 80
ingress:
enabled: true
className: nginx
clusterIssuer: homelab-ca
host: kmsvc.homelab.internal
tlsSecretName: kmsvc-tls
+5
View File
@@ -0,0 +1,5 @@
apiVersion: v2
name: queue-crd
description: Queue CRD definition + queue-operator Deployment/RBAC (design.md §2a)
type: application
version: 0.1.0
+262
View File
@@ -0,0 +1,262 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.21.0
name: queues.kmsvc.io
spec:
group: kmsvc.io
names:
kind: Queue
listKind: QueueList
plural: queues
shortNames:
- queue
- queues
singular: queue
scope: Namespaced
versions:
- additionalPrinterColumns:
- jsonPath: .spec.fifoQueue
name: FIFO
type: boolean
- jsonPath: .status.phase
name: Phase
type: string
name: v1
schema:
openAPIV3Schema:
description: Queue is the Schema for the queues API — see design.md §2a.
properties:
apiVersion:
description: |-
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
type: string
kind:
description: |-
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
type: string
metadata:
type: object
spec:
description: QueueSpec defines the desired state of a Queue (design.md
§2a).
properties:
deadLetterTargetQueue:
description: |-
DeadLetterTargetQueue is the name of another Queue to route exhausted
messages to. Must not point at itself or at another DLQ (design.md §5).
type: string
delaySeconds:
description: DelaySeconds is the default delivery delay applied to
sent messages.
format: int32
maximum: 900
minimum: 0
type: integer
fifoQueue:
default: false
description: FIFOQueue enables per-MessageGroupId ordering and deduplication
semantics.
type: boolean
isDLQ:
description: |-
IsDLQ marks this queue as itself a dead-letter queue, used to enforce
the no-DLQ-chaining validation rule in design.md §5.
type: boolean
maxReceiveCount:
default: 5
description: |-
MaxReceiveCount is how many times a message may be redelivered before
being routed to DeadLetterTargetQueue.
format: int32
minimum: 1
type: integer
maxShards:
default: 8
description: MaxShards is the ceiling on shard count the operator
may split up to (design.md §2c).
format: int32
minimum: 1
type: integer
messageRetentionPeriodSeconds:
default: 345600
description: MessageRetentionPeriodSeconds maps to the underlying
Kafka topic's retention.ms.
format: int32
maximum: 1209600
minimum: 60
type: integer
minShards:
default: 1
description: MinShards is the floor on shard count; the operator never
merges below this.
format: int32
minimum: 1
type: integer
partitionsPerShard:
default: 6
description: PartitionsPerShard is the Kafka partition count on each
shard's topic.
format: int32
minimum: 1
type: integer
shardSplitCooldownSeconds:
default: 300
description: |-
ShardSplitCooldownSeconds is the minimum age a shard must reach before it
is eligible to be split again, preventing rapid re-splitting of a child
that hasn't yet absorbed its share of traffic.
format: int32
minimum: 0
type: integer
shardSplitThresholdBytesPerSec:
default: 5242880
description: |-
ShardSplitThresholdBytesPerSec is the sustained per-shard throughput that
triggers a split into two child shards (design.md §2c).
format: int64
minimum: 1
type: integer
visibilityTimeoutSeconds:
default: 30
description: |-
VisibilityTimeoutSeconds is how long a received-but-unacked message stays
invisible to other consumers before being redelivered.
format: int32
maximum: 43200
minimum: 0
type: integer
type: object
status:
description: QueueStatus defines the observed state of a Queue.
properties:
conditions:
description: Conditions hold detailed status information.
items:
description: Condition contains details for one aspect of the current
state of this API Resource.
properties:
lastTransitionTime:
description: |-
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
format: date-time
type: string
message:
description: |-
message is a human readable message indicating details about the transition.
This may be an empty string.
maxLength: 32768
type: string
observedGeneration:
description: |-
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
format: int64
minimum: 0
type: integer
reason:
description: |-
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.
maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
type: string
status:
description: status of the condition, one of True, False, Unknown.
enum:
- "True"
- "False"
- Unknown
type: string
type:
description: type of condition in CamelCase or in foo.example.com/CamelCase.
maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
type: string
required:
- lastTransitionTime
- message
- reason
- status
- type
type: object
type: array
phase:
description: Phase is the current reconciliation phase.
enum:
- Pending
- Ready
- Failed
type: string
shards:
description: |-
Shards lists every shard backing this queue, active or draining
(design.md §2a/§2c).
items:
description: ShardStatus describes one shard backing a Queue (design.md
§2a/§2c).
properties:
createdAt:
description: |-
CreatedAt timestamps when this shard was created, used to enforce
ShardSplitCooldownSeconds.
format: date-time
type: string
hashRangeEnd:
format: int32
type: integer
hashRangeStart:
description: |-
HashRangeStart/HashRangeEnd define the [start, end) murmur2 hash range
this shard owns over the 32-bit key space.
format: int32
type: integer
id:
description: ID is the shard's identifier, used in its topic
name (kmsvc.{queue}.shard-{id}).
type: string
parentId:
description: |-
ParentID is the shard ID this shard was split from, empty for the
original shard-0.
type: string
phase:
description: Phase is this shard's lifecycle state.
enum:
- Active
- Closing
- Closed
type: string
topic:
description: Topic is the underlying Kafka topic name for this
shard.
type: string
required:
- hashRangeEnd
- hashRangeStart
- id
- phase
- topic
type: object
type: array
type: object
type: object
served: true
storage: true
subresources:
status: {}
@@ -0,0 +1,27 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: queue-operator
namespace: {{ .Values.namespace }}
spec:
replicas: 1
selector:
matchLabels:
app: queue-operator
template:
metadata:
labels:
app: queue-operator
spec:
serviceAccountName: queue-operator
containers:
- name: queue-operator
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
env:
- name: KMSVC_KAFKA_BROKERS
value: {{ .Values.kafkaBrokers | quote }}
- name: KMSVC_REDIS_ADDR
value: {{ .Values.redisAddr | quote }}
resources:
{{- toYaml .Values.resources | nindent 12 }}
+39
View File
@@ -0,0 +1,39 @@
apiVersion: v1
kind: ServiceAccount
metadata:
name: queue-operator
namespace: {{ .Values.namespace }}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: queue-operator
rules:
- apiGroups: ["kmsvc.io"]
resources: ["queues"]
verbs: ["get", "list", "watch", "update", "patch"]
- apiGroups: ["kmsvc.io"]
resources: ["queues/status"]
verbs: ["get", "update", "patch"]
- apiGroups: ["kmsvc.io"]
resources: ["queues/finalizers"]
verbs: ["update"]
- apiGroups: ["coordination.k8s.io"]
resources: ["leases"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
resources: ["events"]
verbs: ["create", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: queue-operator
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: queue-operator
subjects:
- kind: ServiceAccount
name: queue-operator
namespace: {{ .Values.namespace }}
+17
View File
@@ -0,0 +1,17 @@
namespace: sqs
image:
repository: forgejo.riotpiao.homelab.com/rock/kafka-management-service-queue-operator
tag: latest
pullPolicy: IfNotPresent
kafkaBrokers: "kmsvc-kafka-bootstrap.sqs.svc.cluster.local:9092"
redisAddr: "kmsvc-redis-master.sqs.svc.cluster.local:6379"
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 256Mi
+25
View File
@@ -0,0 +1,25 @@
# design.md §7b: cluster-specific values for the homelab environment.
# No secrets here — Authentik client secret etc. flow through the existing
# Vault/talos-cli pattern, referenced at deploy time, not inlined.
namespace: sqs
kafkaCluster:
nodePool:
replicas: 3
storage:
class: longhorn
sizeGi: 50
resources:
memory: 5Gi
cpu: "2"
redis:
storageClass: longhorn
memoryLimit: 1Gi
managementService:
ingress:
host: kmsvc.homelab.internal
clusterIssuer: homelab-ca
authentikIssuerURL: "" # cluster/KMSVC_AUTHENTIK_ISSUER_URL — fill in once task 0 is done
authentikAudience: "" # cluster/KMSVC_AUTHENTIK_AUDIENCE
+15
View File
@@ -0,0 +1,15 @@
environments:
homelab:
values:
- environments/homelab.yaml
helmDefaults:
wait: true
timeout: 600
helmfiles:
- path: releases.d/00-strimzi-operator.yaml.gotmpl
- path: releases.d/01-kafka-cluster.yaml.gotmpl
- path: releases.d/02-redis.yaml.gotmpl
- path: releases.d/03-queue-crd.yaml.gotmpl
- path: releases.d/04-management-service.yaml.gotmpl
+32
View File
@@ -0,0 +1,32 @@
apiVersion: kmsvc.io/v1
kind: Queue
metadata:
name: orders-fifo
namespace: sqs
spec:
fifoQueue: true
visibilityTimeoutSeconds: 30
messageRetentionPeriodSeconds: 345600
maxReceiveCount: 5
deadLetterTargetQueue: orders-fifo-dlq
delaySeconds: 0
partitionsPerShard: 6
minShards: 1
maxShards: 8
shardSplitThresholdBytesPerSec: 5242880
shardSplitCooldownSeconds: 300
---
apiVersion: kmsvc.io/v1
kind: Queue
metadata:
name: orders-fifo-dlq
namespace: sqs
spec:
fifoQueue: true
isDLQ: true
visibilityTimeoutSeconds: 30
messageRetentionPeriodSeconds: 1209600
maxReceiveCount: 5
partitionsPerShard: 6
minShards: 1
maxShards: 1
@@ -0,0 +1,16 @@
environments:
homelab:
values:
- ../environments/homelab.yaml
---
repositories:
- name: strimzi
url: https://strimzi.io/charts/
releases:
- name: strimzi-operator
namespace: {{ .Values.namespace }}
chart: strimzi/strimzi-kafka-operator
version: 0.46.0
values:
- watchNamespaces: ["{{ .Values.namespace }}"]
@@ -0,0 +1,21 @@
environments:
homelab:
values:
- ../environments/homelab.yaml
---
releases:
- name: kafka-cluster
namespace: {{ .Values.namespace }}
chart: ../charts/kafka-cluster
needs:
- {{ .Values.namespace }}/strimzi-operator
values:
- namespace: {{ .Values.namespace }}
nodePool:
replicas: {{ .Values.kafkaCluster.nodePool.replicas }}
storage:
class: {{ .Values.kafkaCluster.nodePool.storage.class }}
sizeGi: {{ .Values.kafkaCluster.nodePool.storage.sizeGi }}
resources:
memory: {{ .Values.kafkaCluster.nodePool.resources.memory }}
cpu: {{ .Values.kafkaCluster.nodePool.resources.cpu | quote }}
+28
View File
@@ -0,0 +1,28 @@
environments:
homelab:
values:
- ../environments/homelab.yaml
---
repositories:
- name: bitnami
url: https://charts.bitnami.com/bitnami
releases:
- name: kmsvc-redis
namespace: {{ .Values.namespace }}
chart: bitnami/redis
version: 20.6.0
values:
- architecture: standalone
auth:
enabled: false
master:
persistence:
enabled: true
storageClass: {{ .Values.redis.storageClass }}
size: 2Gi
resources:
limits:
memory: {{ .Values.redis.memoryLimit }}
requests:
memory: {{ .Values.redis.memoryLimit }}
+16
View File
@@ -0,0 +1,16 @@
environments:
homelab:
values:
- ../environments/homelab.yaml
---
releases:
- name: queue-crd
namespace: {{ .Values.namespace }}
chart: ../charts/queue-crd
needs:
- {{ .Values.namespace }}/kafka-cluster
- {{ .Values.namespace }}/kmsvc-redis
values:
- namespace: {{ .Values.namespace }}
kafkaBrokers: "kmsvc-kafka-bootstrap.{{ .Values.namespace }}.svc.cluster.local:9092"
redisAddr: "kmsvc-redis-master.{{ .Values.namespace }}.svc.cluster.local:6379"
@@ -0,0 +1,23 @@
environments:
homelab:
values:
- ../environments/homelab.yaml
---
releases:
- name: management-service
namespace: {{ .Values.namespace }}
chart: ../charts/management-service
needs:
- {{ .Values.namespace }}/kafka-cluster
- {{ .Values.namespace }}/kmsvc-redis
values:
- namespace: {{ .Values.namespace }}
env:
kafkaBrokers: "kmsvc-kafka-bootstrap.{{ .Values.namespace }}.svc.cluster.local:9092"
redisAddr: "kmsvc-redis-master.{{ .Values.namespace }}.svc.cluster.local:6379"
authentikIssuerURL: {{ .Values.managementService.authentikIssuerURL | quote }}
authentikAudience: {{ .Values.managementService.authentikAudience | quote }}
ingress:
enabled: true
host: {{ .Values.managementService.ingress.host | quote }}
clusterIssuer: {{ .Values.managementService.ingress.clusterIssuer | quote }}