gitchegumi/homelab

Watch

Fork 0

Document and satisfy cluster prerequisites for UDS Core #9

New issue

Closed

opened 2026-08-29 00:22:50 -05:00 by portegumi · 2 comments

portegumi commented

2026-08-29 00:22:50 -05:00

Collaborator

Description

Translate UDS Core requirements into explicit homelab prerequisites after the base RKE2 platform is stable. This prevents UDS deployment from obscuring unresolved cluster, networking, or storage problems.

Scope

Record the selected, mutually compatible RKE2, Kubernetes, and UDS versions.
Identify resource, storage, networking, DNS, certificate, and ingress prerequisites.
Document any UDS-specific node placement or security requirements.
Create a readiness checklist and identify gaps without deploying UDS Core.

Acceptance criteria

A versioned UDS prerequisite and compatibility document is committed.
Networking, storage, DNS, certificate, and capacity prerequisites are listed with their status.
Unresolved decisions and blockers are linked to their owning issues.
Secret and credential handling for future UDS operations is defined at a policy level.
The base cluster passes the agreed readiness checklist.

Dependencies / blockers

Base-cluster networking and dynamic storage are satisfied. Remaining readiness work is documented in the UDS Core Prerequisites and Readiness checklist and remains owned by this issue.

UDS deployment is tracked by #10 and must wait for the final readiness item. Secret scanning is tracked by #13. GPU enablement in #8 is optional and is required only for capabilities that need GPU resources.

## Description Translate UDS Core requirements into explicit homelab prerequisites after the base RKE2 platform is stable. This prevents UDS deployment from obscuring unresolved cluster, networking, or storage problems. ## Scope - Record the selected, mutually compatible RKE2, Kubernetes, and UDS versions. - Identify resource, storage, networking, DNS, certificate, and ingress prerequisites. - Document any UDS-specific node placement or security requirements. - Create a readiness checklist and identify gaps without deploying UDS Core. ## Acceptance criteria - [x] A versioned UDS prerequisite and compatibility document is committed. - [x] Networking, storage, DNS, certificate, and capacity prerequisites are listed with their status. - [x] Unresolved decisions and blockers are linked to their owning issues. - [x] Secret and credential handling for future UDS operations is defined at a policy level. - [x] The base cluster passes the agreed readiness checklist. ## Dependencies / blockers Base-cluster networking and dynamic storage are satisfied. Remaining readiness work is documented in the [UDS Core Prerequisites and Readiness](https://git.gitchegumi.com/gitchegumi/homelab/wiki/UDS-Core-Prerequisites-and-Readiness) checklist and remains owned by this issue. UDS deployment is tracked by #10 and must wait for the final readiness item. Secret scanning is tracked by #13. GPU enablement in #8 is optional and is required only for capabilities that need GPU resources.

portegumi added the

uds

documentation

labels

2026-08-29 00:22:50 -05:00

gitchegumi added this to the Homelab k8s Setup project

2026-08-29 01:51:01 -05:00

gitchegumi added this to the UDS install milestone

2026-08-29 01:58:30 -05:00

gitchegumi added a new dependency

2026-08-30 13:54:03 -05:00

#10 Deploy and validate UDS Core on the stable RKE2 platform

gitchegumi commented

2026-08-30 14:46:15 -05:00

Owner

Prerequisite audit update

The versioned UDS Core Prerequisites and Readiness page is now published and linked from the wiki Home page and sidebar. It records compatibility decisions, prerequisite status, placeholders, security policy, and the remaining deployment gate.

Decisions and justification

RKE2 / Kubernetes: retain the current Kubernetes 1.35 platform because UDS Core currently tests RKE2 against Kubernetes 1.35.
UDS Core: select 1.11.1 rather than 1.11.0 because the patch release updates Keycloak to 26.7.2.
UDS CLI: select 0.35.1; installation and registry authentication are still pending.
kubectl: the newer local client is an advisory tooling mismatch, not a cluster-readiness blocker. Align to 1.35.x/1.36.x before deployment or use the kubectl bundled with UDS.
Ingress: use the two UDS-managed Istio LoadBalancer gateways with MetalLB. A separate ingress controller is not required solely for Core.
Storage: use the expandable iSCSI StorageClass as the default for ReadWriteOnce workloads and request NFS explicitly for ReadWriteMany needs.

Evidence completed

Worker capacity provides 20 allocatable vCPU and approximately 91 GiB memory, exceeding the agreed CPU and memory baseline.
All nodes are Ready and the RKE2 CNI is healthy.
MetalLB Layer 2 allocation was validated end-to-end with a disposable LoadBalancer Service.
TrueNAS CSI controller and node components are healthy across the cluster.
Dynamic NFS and iSCSI provisioning were validated.
iSCSI attach, mount, write, read, reattach, and cleanup succeeded.
The expandable iSCSI StorageClass is now the cluster default.
Public-repository secret handling is defined, and the UDS-specific credentials that must remain uncommitted are listed.

Remaining readiness blockers

Confirm at least 100 GiB of backend storage headroom and retention capacity.
Install and verify UDS CLI 0.35.1 and registry read access.
Select tenant/admin domains, allocate gateway addresses, and configure wildcard DNS.
Obtain tenant/admin TLS certificates and define CA trust.
Provision Loki and Velero object-storage buckets.
Select and provision the Keycloak PostgreSQL topology.
Validate and persist the UDS inotify/file-limit baseline on eligible nodes.
Validate time synchronization and external-service reachability from the cluster.
Run the final clean cluster-health audit.

The first four acceptance criteria are satisfied and checked. The final base-cluster readiness criterion remains unchecked until all required pending items in the wiki checklist pass. Issue #10 remains blocked by this final gate.

## Prerequisite audit update The versioned [UDS Core Prerequisites and Readiness](https://git.gitchegumi.com/gitchegumi/homelab/wiki/UDS-Core-Prerequisites-and-Readiness) page is now published and linked from the wiki Home page and sidebar. It records compatibility decisions, prerequisite status, placeholders, security policy, and the remaining deployment gate. ### Decisions and justification - **RKE2 / Kubernetes:** retain the current Kubernetes 1.35 platform because UDS Core currently tests RKE2 against Kubernetes 1.35. - **UDS Core:** select 1.11.1 rather than 1.11.0 because the patch release updates Keycloak to 26.7.2. - **UDS CLI:** select 0.35.1; installation and registry authentication are still pending. - **kubectl:** the newer local client is an advisory tooling mismatch, not a cluster-readiness blocker. Align to 1.35.x/1.36.x before deployment or use the kubectl bundled with UDS. - **Ingress:** use the two UDS-managed Istio LoadBalancer gateways with MetalLB. A separate ingress controller is not required solely for Core. - **Storage:** use the expandable iSCSI StorageClass as the default for ReadWriteOnce workloads and request NFS explicitly for ReadWriteMany needs. ### Evidence completed - Worker capacity provides 20 allocatable vCPU and approximately 91 GiB memory, exceeding the agreed CPU and memory baseline. - All nodes are Ready and the RKE2 CNI is healthy. - MetalLB Layer 2 allocation was validated end-to-end with a disposable LoadBalancer Service. - TrueNAS CSI controller and node components are healthy across the cluster. - Dynamic NFS and iSCSI provisioning were validated. - iSCSI attach, mount, write, read, reattach, and cleanup succeeded. - The expandable iSCSI StorageClass is now the cluster default. - Public-repository secret handling is defined, and the UDS-specific credentials that must remain uncommitted are listed. ### Remaining readiness blockers - Confirm at least 100 GiB of backend storage headroom and retention capacity. - Install and verify UDS CLI 0.35.1 and registry read access. - Select tenant/admin domains, allocate gateway addresses, and configure wildcard DNS. - Obtain tenant/admin TLS certificates and define CA trust. - Provision Loki and Velero object-storage buckets. - Select and provision the Keycloak PostgreSQL topology. - Validate and persist the UDS inotify/file-limit baseline on eligible nodes. - Validate time synchronization and external-service reachability from the cluster. - Run the final clean cluster-health audit. The first four acceptance criteria are satisfied and checked. The final base-cluster readiness criterion remains unchecked until all required pending items in the wiki checklist pass. Issue #10 remains blocked by this final gate.

portegumi commented

2026-08-30 22:29:41 -05:00

Author

Collaborator

Readiness gate passed

Issue #9 acceptance criteria are satisfied.

Completed evidence

UDS Core 1.11.1 and UDS CLI 0.35.1 are pinned; registry authentication passed.
All four RKE2 nodes are Ready, the API-server readiness check passes, and there are no unexplained unhealthy pods or unbound PVCs.
MetalLB Layer 2 service allocation, TrueNAS CSI NFS/iSCSI provisioning, the default expandable StorageClass, and storage headroom are validated.
Required inotify and file-descriptor settings are persistent on every node; time synchronization passed.
Tenant/admin DNS and TLS material is prepared and stored outside version control.
External AIStor buckets for Loki and Velero passed scoped read/write/delete, isolation, and in-cluster TLS connectivity tests.
External PostgreSQL 18 has a dedicated non-superuser Keycloak database role; authentication from the cluster passed.
The control-plane node is at 58% disk use with 94 GiB available and DiskPressure=false.

Deferred non-blocker

DNSConfigForming warnings remain because some nodes advertise more than Kubernetes' three-upstream-nameserver limit. Valid resolvers are retained and the cluster health audit passes.

Handoff

The UDS Core Prerequisites and Readiness runbook now records the final evidence, external-service recovery implications, placeholder-only configuration rules, and the UDS certificate-refresh procedure.

Issue #10 is unblocked.

## Readiness gate passed Issue #9 acceptance criteria are satisfied. ### Completed evidence - UDS Core 1.11.1 and UDS CLI 0.35.1 are pinned; registry authentication passed. - All four RKE2 nodes are Ready, the API-server readiness check passes, and there are no unexplained unhealthy pods or unbound PVCs. - MetalLB Layer 2 service allocation, TrueNAS CSI NFS/iSCSI provisioning, the default expandable StorageClass, and storage headroom are validated. - Required inotify and file-descriptor settings are persistent on every node; time synchronization passed. - Tenant/admin DNS and TLS material is prepared and stored outside version control. - External AIStor buckets for Loki and Velero passed scoped read/write/delete, isolation, and in-cluster TLS connectivity tests. - External PostgreSQL 18 has a dedicated non-superuser Keycloak database role; authentication from the cluster passed. - The control-plane node is at 58% disk use with 94 GiB available and DiskPressure=false. ### Deferred non-blocker - DNSConfigForming warnings remain because some nodes advertise more than Kubernetes' three-upstream-nameserver limit. Valid resolvers are retained and the cluster health audit passes. ### Handoff The [UDS Core Prerequisites and Readiness](https://git.gitchegumi.com/gitchegumi/homelab/wiki/UDS-Core-Prerequisites-and-Readiness) runbook now records the final evidence, external-service recovery implications, placeholder-only configuration rules, and the UDS certificate-refresh procedure. Issue #10 is unblocked.

portegumi closed this issue

2026-08-30 22:29:41 -05:00

portegumi referenced this issue

2026-08-30 22:30:03 -05:00

Deploy and validate UDS Core on the stable RKE2 platform #10