| name | homelab |
| description | Operational conventions for the HomeLab repository. Activates for any task that interacts with this repo's OKD or MicroShift clusters, applies manifests, runs Ansible against the fleet, or modifies cluster state. Also indexes other project-local skills. |
HomeLab Skill
Operational conventions for this HomeLab repository. Read this in full before
acting on cluster, manifest, or Ansible changes. The companion file
AGENTS.md expands on directory layout and common tasks.
Related Skills
- Kubernetes (KubeShark) —
production-grade Kubernetes manifest, Helm, and Kustomize guidance with a
failure-mode workflow and Conditional Reference Retrieval. Required for any
Kubernetes resource design, review, or refactor. OKD-specific patterns
(SCCs, Routes, arbitrary UID images) live in its
openshift-patterns CRR
reference.
Cluster Inventory
| Cluster | Distribution | Nodes | Storage | KUBECONFIG |
|---|
| OKD | OKD 4.22 (SCOS 10) | 3 control-plane (server-1/2/3) + workers + gpu-1 | Rook-Ceph | $HOME/.kube/okd |
| MicroShift | MicroShift on RPi 5 | Single edge node (PiHole, edge DNS) | Local | $HOME/.kube/microshift |
GitOps: ArgoCD reconciles kubernetes/ into both clusters via
per-app overlays (overlays/okd, overlays/microshift).
Cluster Authentication
Select the target cluster by exporting KUBECONFIG before any kubectl,
oc, helm, kustomize, or argocd call:
- OKD:
export KUBECONFIG=$HOME/.kube/okd
- MicroShift:
export KUBECONFIG=$HOME/.kube/microshift
Both kubeconfigs grant cluster-admin. Caution rules:
- Prefer read-only commands (
get, describe, --dry-run=client,
kustomize build) when exploring.
- Confirm with the user before any mutating action:
apply, delete,
patch, scale, drain, cordon, rollout restart, evict.
- Never
oc adm or kubectl exec into a production workload without
explicit user confirmation.
- Mutations to ArgoCD-managed resources will be reverted on next sync — the
correct fix is almost always a PR to kubernetes/, not a
live
kubectl change.
Repository Workflow
Adding or editing a Kubernetes app
- Place manifests under
kubernetes/<app>/base/ and per-cluster overlays
under kubernetes/<app>/overlays/{okd,microshift}/.
- Register the app in kubernetes/argocd/applications/
as
<app>.yaml and add it to the local kustomization.yaml.
- Run
./main.bash kustomize_fix --dir kubernetes/<app> to apply
kustomize edit fix, prepend the --- document marker, and
prettier-format.
- Validate with
./main.bash test_overlays (requires VAULT_ADDR and
VAULT_TOKEN; runs argocd-vault-plugin + kubeconform -strict against
a sibling ../kubernetes-json-schema/ checkout).
- Follow the Kubernetes (KubeShark) skill
for resource design (security context, probes, resources, RBAC,
NetworkPolicy, rollout strategy).
Secrets
- Prefer External Secrets Operator
for any new secret: declare an
ExternalSecret (or ClusterExternalSecret)
that pulls from Vault via the configured ClusterSecretStore. This keeps
the secret reconciled, rotatable, and visible as a first-class Kubernetes
resource.
- Fall back to argocd-vault-plugin placeholders (
<path:secret/data/...#key>)
only when ESO cannot express the requirement (e.g., templated values
injected into a non-Secret field, or bootstrap manifests that must render
before ESO is available).
- Never commit plaintext secrets, kubeconfigs, tokens, or
.env files.
gitleaks runs in pre-commit and CI.
Ansible
- Entry playbooks:
ansible/servers.yaml, microshift.yaml, desktop.yaml,
laptop.yaml, vscode-server.yaml.
- Inventory: ansible/inventory.
- Standard invocation:
ansible-playbook -i ansible/inventory --ask-become-pass --ask-pass ansible/<playbook>.yaml
(the ./main.bash ansible helper runs servers.yaml).
ansible-lint must pass; preserve idempotency.
OKD provisioning
- okd/ holds
agent-config.yaml and install-config.yaml for the
OKD agent-based installer.
- machineConfigs/ holds Ignition and preseed configs for
bare-metal OS provisioning.
- Treat both as bootstrap inputs; changes are rare and high-risk — require
explicit user confirmation.
Lint and formatting
pre-commit is authoritative (.pre-commit-config.yaml):
gitleaks, shellcheck, yamllint, markdownlint, prettier,
ansible-lint, checkov_diff- Commit messages must satisfy
conventional-pre-commit
(feat:, fix:, chore:, build(deps):, docs:, ...).
YAML rules: 2-space indent, --- document marker at top, no line-length
limit. Shell scripts: set -o errexit -o nounset -o pipefail and
shopt -s failglob; see main.bash.
Renovate
Pinned versions (shell scripts, pre-commit, manifests, Helm/Kustomize
inputs) are kept current by Renovate. Preserve # renovate: datasource=...
comments directly above the pinned version line.
main.bash Reference
The wrapper script exposes these functions; invoke as ./main.bash <fn>:
| Function | Purpose |
|---|
ansible | Run ansible/servers.yaml |
kustomize_fix --all | Run kustomize edit fix across the whole repo, then prettier |
kustomize_fix --dir <d> | Same, scoped to one directory |
test_overlays | Build all OKD overlays through AVP → kubeconform -strict |
test_overlays_k3s | Same for overlays/k3s (legacy clusters) |
stateful_workload_stop | Suspend CronJobs and scale stateful apps to zero for maintenance |
Out of Scope
- notes/ and sandbox/ are scratch. Read for context;
do not deploy from them and do not treat their YAML as authoritative.
CHANGELOG.md is auto-maintained; do not hand-edit.img/ holds documentation assets only.
