Adds is attribute to manifests.

2025-12-31 08:15:17 +00:00
parent d1304a2630
commit 434769ac7a
19 changed files with 305 additions and 90 deletions
--- a/ADDING-APPS.md
+++ b/ADDING-APPS.md
@@ -14,7 +14,7 @@ Each app directory must contain:
 2. **`kustomization.yaml`** - Kustomize configuration with Wild Cloud labels
 3. **Resource files** - Kubernetes manifests (deployments, services, ingresses, etc.)

-### App Manifest (`manifest.yaml`)
+## App Manifest (`manifest.yaml`)

 The manifest defines the app's metadata, dependencies, configuration schema, and secret requirements.

@@ -22,6 +22,7 @@ This is the contents of an example `manifest.yaml` file for an app named "immich

 ```yaml
 name: immich
+is: immich
 description: Immich is a self-hosted photo and video backup solution that allows you to store, manage, and share your media files securely.
 version: 1.0.0
 icon: https://immich.app/assets/images/logo.png
@@ -54,11 +55,12 @@ requiredSecrets:
  - redis.auth    # References redis app via 'redis' name (no alias)
 ```

-#### Manifest Fields
+### Manifest Fields

 | Field | Required | Description |
 |-------|----------|-------------|
 | `name` | Yes | App identifier (must match directory name) |
+| `is` | Yes | Unique id for this app. Used for `requires` mapping |
 | `description` | Yes | Brief app description shown in listings |
 | `version` | Yes | App version (follow upstream versioning) |
 | `icon` | No | URL to app icon for UI display |
@@ -67,18 +69,156 @@ requiredSecrets:
 | `defaultSecrets` | No | This app's secrets (no 'default' = auto-generated) |
 | `requiredSecrets` | No | List of secrets from dependency apps (format: `<app-ref>.<key>`) |

-**Dependency Configuration:**
+### Dependency Configuration
+
 - Each dependency in `requires` can have:
-  - `name`: The actual app name to depend on
+  - `name`: The app name to depend on (any app with a matching `is` field can satisfy this requirement)
  - `alias`: Optional reference name for templates (defaults to `name`)

-**Manifest Template Variable Sources:**
+### Manifest Template Variables (configuration and secrets)
+
+#### Manifest Template Variable Sources
+
 1. Standard Wild Cloud variables: `{{ .cloud.* }}`, `{{ .cluster.* }}`, `{{ .operator.* }}`
 2. App-specific variables: `{{ .app.* }}` - resolved from current app's config
 3. Dependency variables: `{{ .apps.<ref>.* }}` - resolved using app reference mapping
 4. App-specific secrets (in 'defaultSecrets' ONLY): `{{ secrets.* }}`

-**Manifest App Reference Resolution:**
+#### Available Configuration Variiables
+
+Here's a comprehensive rundown of all config variables that get set during cluster and service setup in config.yaml:
+
+##### operator (Set during initial setup)
+
+  - operator.email - Email for cluster operator/admin
+
+##### cloud (Infrastructure-level settings)
+
+###### DNS Configuration:
+- cloud.dns.ip - IP address of the DNS server (Wild Central)
+- cloud.dns.externalResolver - External DNS resolver (e.g., 1.1.1.1, 8.8.8.8)
+
+###### Network Configuration:
+
+- cloud.router.ip - Router gateway IP
+- cloud.router.dynamicDns - Dynamic DNS hostname (optional)
+- cloud.dhcpRange - DHCP range for the network (e.g., "192.168.8.34,192.168.8.79")
+- cloud.dnsmasq.interface - Network interface for dnsmasq
+
+###### Domain Configuration:
+
+- cloud.baseDomain - Base domain for the cloud (e.g., "payne.io")
+- cloud.domain - Full cloud domain (e.g., "cloud2.payne.io")
+- cloud.internalDomain - Internal cluster domain (e.g., "internal.cloud2.payne.io")
+
+###### Storage Configuration (NFS Service):
+
+- cloud.nfs.host - NFS server hostname/IP
+- cloud.nfs.mediaPath - NFS export path for media storage
+- cloud.nfs.storageCapacity - NFS storage capacity (e.g., "50Gi", "1Ti")
+
+###### Registry Configuration (Docker Registry Service):
+
+- cloud.dockerRegistryHost - Docker registry hostname (e.g., "registry.internal.cloud2.payne.io")
+
+##### SMTP Configuration (SMTP Service):
+
+- cloud.smtp.host - SMTP server hostname
+- cloud.smtp.port - SMTP port (typically "465" or "587")
+- cloud.smtp.user - SMTP username
+- cloud.smtp.from - Default 'from' email address
+- cloud.smtp.tls - Enable TLS (true/false)
+- cloud.smtp.startTls - Enable STARTTLS (true/false)
+
+###### Backup Configuration:
+
+- cloud.backup.root - Root path for backups
+
+##### cluster (Kubernetes cluster settings)
+
+###### Basic Cluster Info:
+
+- cluster.name - Cluster name identifier
+- cluster.hostnamePrefix - Prefix for node hostnames
+
+###### Node Configuration:
+
+- cluster.nodes.talos.version - Talos Linux version (e.g., "v1.11.5")
+- cluster.nodes.talos.schematicId - Talos Image Factory schematic ID
+- cluster.nodes.control.vip - Virtual IP for control plane
+- cluster.nodes.active.* - Individual node configurations with:
+  - role - "controlplane" or "worker"
+  - interface - Network interface name
+  - disk - Disk device path
+  - currentIp - Current IP address
+  - targetIp - Target IP address
+  - configured - Configuration status
+  - applied - Applied status
+  - maintenance - Maintenance mode
+  - schematicId - Node-specific schematic ID
+  - version - Node-specific Talos version
+
+###### MetalLB Service:
+
+- cluster.ipAddressPool - IP range for MetalLB (e.g., "192.168.8.80-192.168.8.89")
+- cluster.loadBalancerIp - Primary load balancer IP (e.g., "192.168.8.80")
+
+###### Cert-Manager Service:
+
+- cluster.certManager.cloudflare.domain - Cloudflare domain for DNS-01 challenge
+- cluster.certManager.cloudflare.zoneID - Cloudflare zone ID
+
+###### ExternalDNS Service:
+
+- cluster.externalDns.ownerId - Unique identifier for this cluster's DNS records
+
+###### Docker Registry Service:
+
+- cluster.dockerRegistry.storage - Storage size for registry (e.g., "10Gi")
+
+##### apps (Application configurations)
+
+Each app added to the cluster gets its own section under apps.<app-name> with app-specific configuration from the app's manifest. Common patterns include:
+
+Standard app fields:
+- apps.<name>.namespace - Kubernetes namespace
+- apps.<name>.domain - App domain (e.g., "ghost.cloud2.payne.io")
+- apps.<name>.externalDnsDomain - Domain for external DNS
+- apps.<name>.tlsSecretName - TLS certificate secret name
+- apps.<name>.image - Container image
+- apps.<name>.port - Service port
+- apps.<name>.storage - Persistent volume size
+- apps.<name>.timezone - Timezone setting
+
+Database-dependent apps:
+- apps.<name>.dbHost / dbHostname - Database hostname
+- apps.<name>.dbPort - Database port
+- apps.<name>.dbName - Database name
+- apps.<name>.dbUser / dbUsername - Database user
+
+SMTP-enabled apps:
+- apps.<name>.smtp.host - SMTP server
+- apps.<name>.smtp.port - SMTP port
+- apps.<name>.smtp.user - SMTP username
+- apps.<name>.smtp.from - From address
+- apps.<name>.smtp.tls - TLS enabled
+- apps.<name>.smtp.startTls - STARTTLS enabled
+
+Configuration Flow
+
+1. Initial Setup: operator.email, basic cloud.* settings
+2. Cluster Bootstrap: cluster.name, cluster.nodes.* settings
+3. Infrastructure Services: Each service prompts for its serviceConfig from its manifest
+   - MetalLB → cluster.ipAddressPool, cluster.loadBalancerIp
+   - Cert-Manager → cluster.certManager.*
+   - ExternalDNS → cluster.externalDns.ownerId
+   - NFS → cloud.nfs.*
+   - Docker Registry → cloud.dockerRegistryHost, cluster.dockerRegistry.storage
+   - SMTP → cloud.smtp.*
+4. Apps: Each app adds its configuration under apps.<name>.* based on its manifest
+
+#### Manifest App Reference Resolution:
+
 When you use `{{ .apps.<ref>.* }}` in templates:
 1. System checks if `<ref>` matches any dependency's `alias` field
 2. If no alias match, checks if `<ref>` matches any dependency's `name` field