homelab/.claude/skills/add-service/SKILL.md

name, description

name	description
add-service	Add a new service to the homelab cluster end-to-end (manifests, Argo CD Application, DNS, certs/secrets). Use when the user wants to deploy a new app or service to the K3s cluster.

Add a new service to the cluster: $ARGUMENTS

Follow the checklist from argocd/README.md, in order:

1. Manifests or Helm values

• Raw resources: create manifests/<area>/<service>.yaml. Follow the style of existing files (see manifests/portfolio/portfolio.yaml for a full example: Namespace → Deployment → Service → Certificate → IngressRoute, all in one file separated by ---). Start the file with an # Apply: / # Delete: / # Description: comment block matching sibling files.
• Helm chart instead: add values/<service>.yaml with the chart's values.

2. Argo CD Application

Add argocd/apps/<service>.yaml. For a raw manifest directory:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: <service>
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitea.nik4nao.com/nik/homelab.git
    targetRevision: main
    path: manifests/<area>
    directory:
      recurse: true
      include: '*.yaml'
  destination:
    server: https://kubernetes.default.svc
    namespace: <service>
  syncPolicy:
    automated:
      prune: false
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

For a Helm chart, mirror an existing chart-backed Application (e.g. argocd/apps/traefik.yaml) and point it at values/<service>.yaml.

prune: false is deliberate — deleting a manifest from Git will NOT remove the resource from the cluster automatically; say so if the user is removing something, not just adding.

3. DNS (internal services only)

home.arpa has no wildcard DNS. If this service gets a *.home.arpa hostname, add it to both:

• values/pihole.yaml (dnsmasq.customDnsEntries, format address=/<host>.home.arpa/<node-ip>, plus an ingress.hosts entry if the service itself is exposed through Pi-hole's own ingress block — most services don't need that part, just the customDnsEntries line)
• values/pihole-debian.yaml (same entry, kept in sync with the primary)

Public services use nik4nao.com and don't need Pi-hole entries.

4. Certificates and secrets

• Internal (home.arpa): Certificate with issuerRef.name: internal-ca-issuer.
• Public (nik4nao.com): Certificate with issuerRef.name: letsencrypt-prod.
• If the service needs credentials, decide runtime-script vs sealed-secret — see the regen-sealed-secret skill / manifests/README.md for the distinction. Don't hardcode secret values into the manifest.
• If the image is pulled from the private Gitea registry, add an imagePullSecrets reference and reuse/create the matching registry-secret.sh pattern (see manifests/portfolio/registry-secret.sh).

5. Commit

Commit manifests, the Application file, and any DNS/values changes together. Do not commit .env or any plaintext secret values. Let the app-of-apps reconcile — don't kubectl apply the new Application by hand unless the user asks for an immediate manual sync.