home-docker/external-service-template.yaml

# Template for Exposing External Services (Outside K8s)
#
# Use this template when you have services running on your local network
# (e.g., http://192.168.1.4:3031) and want to expose them with:
# - A custom domain (e.g., myapp.junv.cc)
# - Automatic HTTPS certificate from Let's Encrypt
# - Through your existing NGINX Ingress Controller
#
# HOW TO USE:
# 1. Copy this template
# 2. Replace ALL_CAPS placeholders with your values
# 3. Save as home-apps/SERVICENAME.yaml
# 4. Apply: kubectl apply -f home-apps/SERVICENAME.yaml
#
# EXAMPLE:
# Service: http://192.168.1.4:3031 → https://myapp.junv.cc
#
---
# Service without selector (no pods, points to external endpoint)
apiVersion: v1
kind: Service
metadata:
  name: SERVICENAME  # e.g., home-assistant, grafana-external
  namespace: home-apps
spec:
  ports:
  - name: http
    port: 80  # Port exposed within cluster
    targetPort: EXTERNAL_PORT  # e.g., 3031, 8080, 9090
    protocol: TCP
---
# Manual EndpointSlice pointing to external IP
apiVersion: discovery.k8s.io/v1
kind: EndpointSlice
metadata:
  name: SERVICENAME  # MUST match Service name exactly
  namespace: home-apps
  labels:
    kubernetes.io/service-name: SERVICENAME  # Required: links EndpointSlice to Service
addressType: IPv4
endpoints:
  - addresses:
      - EXTERNAL_IP  # e.g., 192.168.1.4
ports:
  - name: http  # Should match Service port name
    port: EXTERNAL_PORT  # e.g., 3031
    protocol: TCP
---
# Ingress with automatic TLS certificate
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: SERVICENAME-ingress
  namespace: home-apps
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    # Optional: Add OAuth2 protection (uncomment to enable)
    # nginx.ingress.kubernetes.io/auth-url: "https://pass.junv.cc/oauth2/auth"
    # nginx.ingress.kubernetes.io/auth-signin: "https://pass.junv.cc/oauth2/start?rd=https://$host$escaped_request_uri"
    # Optional: Proxy settings for specific backends
    # nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    # nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    # nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    # Optional: Websocket support (for apps like Home Assistant)
    # nginx.ingress.kubernetes.io/websocket-services: "SERVICENAME"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - DOMAIN.junv.cc  # e.g., homeassistant.junv.cc, grafana.junv.cc
    secretName: SERVICENAME-tls  # cert-manager will create this automatically
  rules:
  - host: DOMAIN.junv.cc
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: SERVICENAME
            port:
              number: 80

---
# ============================================================================
# REAL WORLD EXAMPLE 1: Home Assistant on 192.168.1.4:8123
# ============================================================================
# apiVersion: v1
# kind: Service
# metadata:
#   name: home-assistant-external
#   namespace: home-apps
# spec:
#   ports:
#   - name: http
#     port: 80
#     targetPort: 8123
#     protocol: TCP
# ---
# apiVersion: discovery.k8s.io/v1
# kind: EndpointSlice
# metadata:
#   name: home-assistant-external
#   namespace: home-apps
#   labels:
#     kubernetes.io/service-name: home-assistant-external
# addressType: IPv4
# endpoints:
#   - addresses:
#       - 192.168.1.4
# ports:
#   - name: http
#     port: 8123
#     protocol: TCP
# ---
# apiVersion: networking.k8s.io/v1
# kind: Ingress
# metadata:
#   name: home-assistant-external-ingress
#   namespace: home-apps
#   annotations:
#     cert-manager.io/cluster-issuer: "letsencrypt-prod"
#     nginx.ingress.kubernetes.io/websocket-services: "home-assistant-external"
# spec:
#   ingressClassName: nginx
#   tls:
#   - hosts:
#     - ha.junv.cc
#     secretName: home-assistant-external-tls
#   rules:
#   - host: ha.junv.cc
#     http:
#       paths:
#       - path: /
#         pathType: Prefix
#         backend:
#           service:
#             name: home-assistant-external
#             port:
#               number: 80

---
# ============================================================================
# REAL WORLD EXAMPLE 2: Proxmox Web UI on 192.168.1.5:8006
# ============================================================================
# apiVersion: v1
# kind: Service
# metadata:
#   name: proxmox-external
#   namespace: home-apps
# spec:
#   ports:
#   - name: https
#     port: 8006
#     targetPort: 8006
#     protocol: TCP
# ---
# apiVersion: discovery.k8s.io/v1
# kind: EndpointSlice
# metadata:
#   name: proxmox-external
#   namespace: home-apps
#   labels:
#     kubernetes.io/service-name: proxmox-external
# addressType: IPv4
# endpoints:
#   - addresses:
#       - 192.168.1.5
# ports:
#   - name: https
#     port: 8006
#     protocol: TCP
# ---
# apiVersion: networking.k8s.io/v1
# kind: Ingress
# metadata:
#   name: proxmox-external-ingress
#   namespace: home-apps
#   annotations:
#     cert-manager.io/cluster-issuer: "letsencrypt-prod"
#     # Backend uses HTTPS, tell NGINX to use it
#     nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
#     # Skip TLS verification (self-signed cert on backend)
#     nginx.ingress.kubernetes.io/proxy-ssl-verify: "false"
# spec:
#   ingressClassName: nginx
#   tls:
#   - hosts:
#     - proxmox.junv.cc
#     secretName: proxmox-external-tls
#   rules:
#   - host: proxmox.junv.cc
#     http:
#       paths:
#       - path: /
#         pathType: Prefix
#         backend:
#           service:
#             name: proxmox-external
#             port:
#               number: 8006

---
# ============================================================================
# COMPARISON: NPM vs Native Kubernetes
# ============================================================================
#
# Nginx Proxy Manager (*.r.junv.cc):
# ✅ Web UI - easy to add services
# ✅ Good for non-technical users
# ❌ Extra hop (NGINX Ingress → NPM → External Service)
# ❌ More resources (NPM pod + database)
# ❌ Not GitOps - config stored in database
#
# Native K8s (this template):
# ✅ GitOps - version controlled YAML
# ✅ Native K8s - no extra components
# ✅ Direct routing (NGINX Ingress → External Service)
# ✅ Automatic cert renewal via cert-manager
# ❌ Must write/copy YAML for each service
# ❌ No web UI
#
# RECOMMENDATION:
# - Use NPM (*.r.junv.cc) for quick ad-hoc services or non-tech users
# - Use this template for permanent services you want in GitOps