@localctl/cli 0.5.0-beta.3 → 0.5.0

package/src/lib/hostGuard.js

@@ -0,0 +1,107 @@
+const { capture } = require('./exec');
+const { DOMAIN } = require('./constants');
+const { firstLine } = require('./kubeErrors');
+
+// Host names are case-insensitive and may carry a trailing dot; compare them in one form.
+const normalise = (host) => String(host).trim().toLowerCase().replace(/\.$/, '');
+
+// A host an existing route serves is in the way of `mine` if it is the same name, or a wildcard
+// (`*.local.test`) that covers it.
+function covers(routeHost, mine) {
+  const route = normalise(routeHost);
+  if (route === mine) return true;
+  return route.startsWith('*.') && mine.endsWith(route.slice(1));
+}
+
+function listObjects(resource, optional) {
+  const res = capture('kubectl', ['get', resource, '-A', '-o', 'json', '--request-timeout=20s']);
+  if (res.status !== 0) {
+    const text = `${res.stderr || ''}${res.stdout || ''}`;
+    // Traefik's own CRDs may not be installed: then there simply are no such routes.
+    if (optional && /the server doesn't have a resource type "ingressroutes"|no matches for kind "IngressRoute"/i.test(text)) return [];
+    throw new Error(`Couldn't check whether the hosts are already served by another app (${resource}): ${firstLine(text || 'kubectl failed')}`);
+  }
+  let items;
+  try {
+    items = JSON.parse(res.stdout).items;
+  } catch (e) {
+    items = null;
+  }
+  if (!Array.isArray(items)) throw new Error(`Couldn't read the list of ${resource} from the cluster.`);
+  return items;
+}
+
+// Reads a Traefik rule such as  Host(`a.local.test`) || HostRegexp(`{sub:.+}.local.test`)  with a
+// single linear pass (no regular expression that could backtrack on hostile input). Returns the
+// literal hosts, and `regexps` for HostRegexp patterns, whose reach can't be worked out here.
+function parseRule(rule) {
+  const text = String(rule || '');
+  const hosts = [];
+  const regexps = [];
+  let i = 0;
+  while (i < text.length) {
+    const m = /^(host|hostregexp)\s*\(/i.exec(text.slice(i, i + 24));
+    const prev = i === 0 ? ' ' : text[i - 1];
+    if (!m || /[A-Za-z0-9_]/.test(prev)) {
+      i += 1;
+      continue;
+    }
+    const target = m[1].toLowerCase() === 'host' ? hosts : regexps;
+    i += m[0].length;
+    // Arguments up to the closing parenthesis, each quoted with ` " or '.
+    while (i < text.length && text[i] !== ')') {
+      const quote = text[i];
+      if (quote === '`' || quote === '"' || quote === "'") {
+        const end = text.indexOf(quote, i + 1);
+        if (end === -1) { i = text.length; break; }
+        target.push(text.slice(i + 1, end));
+        i = end + 1;
+      } else {
+        i += 1;
+      }
+    }
+  }
+  return { hosts, regexps };
+}
+
+// Could a HostRegexp pattern reach `mine`? It names the domain, or is a catch-all (no literal
+// domain at all, like `.*`). Anything else is a pattern for some other domain.
+function regexpMayCover(pattern, mine) {
+  const p = String(pattern).toLowerCase();
+  if (p.includes(DOMAIN.toLowerCase()) || p.includes(mine)) return true;
+  return !/[a-z0-9]\.[a-z]{2,}/.test(p.replace(/\\\./g, '.'));
+}
+
+// Stops an app from taking over a host another app already serves: two routes for the same host
+// would fight over it in Traefik, and a config could use that to shadow another app. Looks at the
+// objects in the cluster (the source of truth, unlike a local registry that can go stale): Ingress
+// objects, including wildcard hosts, and Traefik IngressRoutes. Anything other than a clean answer
+// is an error.
+function assertHostsFree(cfg) {
+  const mine = cfg.hosts.map((h) => normalise(`${h}.${DOMAIN}`));
+  const claims = [];
+  for (const ing of listObjects('ingress', false)) {
+    const meta = ing.metadata || {};
+    for (const rule of (ing.spec && ing.spec.rules) || []) {
+      if (rule && rule.host) claims.push({ host: rule.host, namespace: meta.namespace, name: `ingress ${meta.name}` });
+    }
+  }
+  for (const route of listObjects('ingressroutes.traefik.io', true)) {
+    const meta = route.metadata || {};
+    for (const r of (route.spec && route.spec.routes) || []) {
+      const { hosts, regexps } = parseRule(r && r.match);
+      for (const host of hosts) claims.push({ host, namespace: meta.namespace, name: `ingressroute ${meta.name}` });
+      for (const pattern of regexps) claims.push({ pattern, namespace: meta.namespace, name: `ingressroute ${meta.name}` });
+    }
+  }
+  for (const claim of claims) {
+    if (claim.namespace === cfg.namespace) continue;
+    const clash = mine.find((h) => (claim.pattern !== undefined ? regexpMayCover(claim.pattern, h) : covers(claim.host, h)));
+    if (clash) {
+      const what = claim.pattern !== undefined ? `a HostRegexp pattern (${String(claim.pattern).slice(0, 60)})` : claim.host;
+      throw new Error(`The host "${clash}" may already be served by ${claim.namespace}/${claim.name}: ${what}. Pick another "subdomain" or "ingress.hosts" entry in .local/config.yaml.`);
+    }
+  }
+}
+
+module.exports = { assertHostsFree, parseRule };

package/src/lib/hostsFile.js

@@ -8,15 +8,14 @@ const { DOMAIN } = require('./constants');
 
 const MARK_START = '# >>> localctl managed block >>>';
 const MARK_END = '# <<< localctl managed block <<<';
-// $LOCALCTL_HOSTS_FILE points it at another file - used by the e2e suite so tests never touch
-// (or need sudo for) the real hosts file.
-const HOSTS_PATH = process.env.LOCALCTL_HOSTS_FILE ||
-  (process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts');
+const HOSTS_PATH =
+  process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts';
 
-function registerApp(subdomain) {
+// Records one or more subdomains with a single read and write of the registry.
+function registerApp(subdomains) {
   ensureHomeState();
   const registry = JSON.parse(fs.readFileSync(APPS_REGISTRY_PATH, 'utf8'));
-  registry[subdomain] = true;
+  for (const subdomain of [].concat(subdomains)) registry[subdomain] = true;
   fs.writeFileSync(APPS_REGISTRY_PATH, JSON.stringify(registry, null, 2));
 }
 
@@ -51,8 +50,10 @@ function writeHosts(next, current) {
     logger.success(`Updated ${HOSTS_PATH}`);
   } catch (e) {
     if (e.code !== 'EACCES' && e.code !== 'EPERM') throw e;
-    const tmp = path.join(os.tmpdir(), 'localctl-hosts-new');
-    fs.writeFileSync(tmp, next);
+    // Private directory: a fixed name in /tmp could be swapped by another user between this write
+    // and the `sudo cp` below.
+    const tmp = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'localctl-hosts-')), 'hosts');
+    fs.writeFileSync(tmp, next, { flag: 'wx', mode: 0o600 });
     if (process.platform === 'win32') {
       logger.warn('Need Administrator rights to update the hosts file. Approve the Windows prompt to continue.');
       if (copyElevatedWindows(tmp) && fs.readFileSync(HOSTS_PATH, 'utf8') === next) {

package/src/lib/kubeErrors.js

@@ -0,0 +1,22 @@
+// How to read what kubectl says when a command fails. Matching a loose phrase such as "not found"
+// is dangerous: a Forbidden message naming a missing role, or a missing kubeconfig context, also
+// contains it. These helpers match the exact API error for the exact object.
+
+const escapeRegExp = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// "Error from server (NotFound): namespaces "x" not found" (kind is the plural: namespaces, secrets).
+function isNotFound(text, kind, name) {
+  return new RegExp(`Error from server \\(NotFound\\): ${escapeRegExp(kind)} "${escapeRegExp(name)}" not found`).test(String(text || ''));
+}
+
+// "Error from server (Conflict): ..." / "Error from server (AlreadyExists): ..."
+const isConflict = (text) => /Error from server \((Conflict|AlreadyExists)\)/.test(String(text || ''));
+const isAlreadyExists = (text) => /Error from server \(AlreadyExists\)/.test(String(text || ''));
+
+// First line of a message, cut to a sensible size: a hostile or broken kubectl can print megabytes.
+function firstLine(text, max = 300) {
+  const line = String(text || '').trim().split('\n')[0];
+  return line.length > max ? `${line.slice(0, max)}...` : line;
+}
+
+module.exports = { isNotFound, isConflict, isAlreadyExists, firstLine };

package/src/lib/loadConfig.js

@@ -1,25 +1,187 @@
 const fs = require('fs');
 const path = require('path');
-const { appConfigSchema } = require('./configSchema');
+const { loadYaml } = require('./yamlLoad');
+const { appConfigSchema, describeIssues } = require('./configSchema');
+const { readEnvFile } = require('./envFile');
+const { isReservedNamespace } = require('./namespaces');
+const { readRegularFile } = require('./safeRead');
+const { assertPathsInsideProject } = require('./pathGuard');
 const { CONFIG_PATH } = require('./paths');
 const { resolveProfileName } = require('./projectContext');
 const { getProfile, clusterNameFor, namespaceScopeFor } = require('./profileStore');
 
-function loadConfig(configPath = CONFIG_PATH) {
+// YAML turns `PORT: 3000` or `DEBUG: true` into a number or boolean, but environment variables
+// are always strings. Convert scalars instead of rejecting them. (yamlLoad.js already keeps
+// values such as 1.10, 1e3, 0x10, 0777 and dates as text.)
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function stringifyEnv(env) {
+  if (env === null) return undefined;
+  if (!env || typeof env !== 'object' || Array.isArray(env)) return env;
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key === '__proto__') continue; // would change the object's prototype instead of adding a variable
+    out[key] = value === null ? '' : ['number', 'boolean'].includes(typeof value) ? String(value) : value;
+  }
+  return out;
+}
+
+const MAX_CONFIG_BYTES = 512 * 1024;
+// Counted in nodes, where a string weighs as many as it has characters, so one long string that is
+// aliased thousands of times can't slip past as "one node each".
+const MAX_EXPANDED_NODES = 2000000;
+
+// YAML aliases let a tiny file expand into a huge tree (the "billion laughs" shape), which would
+// make validation burn CPU. Count the size of the tree as it would be expanded, sharing the work
+// for repeated nodes, and refuse documents that are too big or that loop back on themselves.
+function assertReasonableSize(value) {
+  const sizes = new Map();
+  const inProgress = new Set();
+  const size = (node) => {
+    if (typeof node === 'string') return Math.max(1, node.length);
+    if (node === null || typeof node !== 'object') return 1;
+    if (sizes.has(node)) return sizes.get(node);
+    if (inProgress.has(node)) throw new Error('Invalid .local/config.yaml: it contains a YAML anchor that refers to itself.');
+    inProgress.add(node);
+    let total = 1;
+    // Keys count by length too: a long key aliased many times is as costly as a long value.
+    const children = Array.isArray(node) ? node.map((c) => [0, c]) : Object.entries(node).map(([k, c]) => [k.length, c]);
+    for (const [keyWeight, child] of children) {
+      total += keyWeight + size(child);
+      if (total > MAX_EXPANDED_NODES) {
+        throw new Error('Invalid .local/config.yaml: it is far larger than a config should be once YAML anchors/aliases are expanded.');
+      }
+    }
+    inProgress.delete(node);
+    sizes.set(node, total);
+    return total;
+  };
+  try {
+    size(value);
+  } catch (e) {
+    if (e instanceof RangeError) throw new Error('Invalid .local/config.yaml: it is nested too deeply.');
+    throw e;
+  }
+}
+
+// Reads and parses the app's YAML config without validating it. Used by loadConfig and by
+// commands that only need a field or two (like the app name).
+function readRawConfig(configPath = CONFIG_PATH) {
   if (!fs.existsSync(configPath)) {
+    const legacy = path.join(path.dirname(configPath), 'config.json');
+    if (fs.existsSync(legacy)) {
+      throw new Error(
+        `Found ${legacy}, but localctl now reads .local/config.yaml. Convert it (JSON is valid ` +
+        'YAML, so renaming the file to config.yaml works as a first step) and delete the old file.',
+      );
+    }
     throw new Error(`No config found at ${configPath}. Run "localctl app new" first.`);
   }
-  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  // The .local folder itself must be a real folder too, not a link to a config somewhere else.
+  try {
+    if (fs.lstatSync(path.dirname(configPath)).isSymbolicLink()) throw new Error('Invalid .local/config.yaml: the .local folder is a symbolic link; use a real folder.');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  let raw;
+  try {
+    raw = loadYaml(readRegularFile(configPath, MAX_CONFIG_BYTES, '.local/config.yaml'));
+  } catch (e) {
+    if (e.name !== 'YAMLException') throw new Error(`Invalid .local/config.yaml: ${e.message}`);
+    throw new Error(`Invalid .local/config.yaml (not valid YAML):\n  ${e.message.split('\n')[0]}`);
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('Invalid .local/config.yaml: expected a mapping of settings at the top level.');
+  }
+  assertReasonableSize(raw);
+  // A key left empty in YAML (`env:`) is null; treat it as not set so the schema defaults apply.
+  for (const key of Object.keys(raw)) {
+    if (raw[key] === null) delete raw[key];
+  }
+  raw.env = stringifyEnv(raw.env);
+  for (const list of ['sidecars', 'initContainers']) {
+    if (Array.isArray(raw[list])) {
+      raw[list] = raw[list].map((c) => (c && typeof c === 'object' ? { ...c, env: stringifyEnv(c.env) } : c));
+    }
+  }
+  return raw;
+}
+
+// Fields an environment can't override: they identify the app and where it lives, which other
+// commands (down, secrets, status) resolve without knowing about environments.
+const LOCKED_IN_ENVIRONMENT = ['name', 'namespace', 'environments', 'envFile'];
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Objects merge key by key, everything else (lists, scalars) is replaced.
+function mergeConfig(base, overlay) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    out[key] = isPlainObject(value) && isPlainObject(out[key]) ? mergeConfig(out[key], value) : value;
+  }
+  return out;
+}
+
+// Applies the named entry of `environments` over the rest of the file (or none when no name is
+// given) and removes the `environments` block itself. The name comes from `localctl app up --env`
+// via LOCALCTL_ENV and can only pick an entry that the file itself defines.
+function applyEnvironment(raw, envName = process.env.LOCALCTL_ENV) {
+  const { environments, ...base } = raw;
+  const available = isPlainObject(environments) ? Object.keys(environments) : [];
+  // Names are checked even when no environment is selected, so a bad one fails early.
+  const badName = available.find((n) => !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(n) || n.length > 63);
+  if (badName !== undefined) throw new Error(`Environment name "${badName}" must be lowercase letters, digits and dashes (like a Kubernetes name).`);
+  if (!envName) return base;
+  if (!available.includes(envName)) {
+    throw new Error(
+      `Unknown environment ${JSON.stringify(String(envName).slice(0, 80))}. ` +
+      (available.length ? `This app defines: ${available.join(', ')}.` : 'This app\'s config has no "environments" block.'),
+    );
+  }
+  const overlay = environments[envName];
+  if (!isPlainObject(overlay)) throw new Error(`Environment "${envName}" must be a mapping of settings.`);
+  const unsafe = Object.keys(overlay).find((k) => UNSAFE_KEYS.has(k));
+  if (unsafe !== undefined) throw new Error(`Environment "${envName}" uses the reserved key "${unsafe}".`);
+  const locked = LOCKED_IN_ENVIRONMENT.filter((k) => k in overlay);
+  if (locked.length) {
+    throw new Error(`Environment "${envName}" can't override ${locked.map((k) => `"${k}"`).join(', ')}.`);
+  }
+  return mergeConfig(base, readEnvOverlay(overlay));
+}
+
+// Same clean-up readRawConfig does for the base file, applied to the overlay.
+function readEnvOverlay(overlay) {
+  const out = { ...overlay };
+  for (const key of Object.keys(out)) {
+    if (out[key] === null) delete out[key];
+  }
+  if ('env' in out) out.env = stringifyEnv(out.env);
+  for (const list of ['sidecars', 'initContainers']) {
+    if (Array.isArray(out[list])) {
+      out[list] = out[list].map((c) => (c && typeof c === 'object' ? { ...c, env: stringifyEnv(c.env) } : c));
+    }
+  }
+  return out;
+}
+
+function loadConfig(configPath = CONFIG_PATH) {
+  const raw = applyEnvironment(readRawConfig(configPath));
+  // envFile values go under the explicit `env` keys, so the YAML always wins over the file.
+  if (typeof raw.envFile === 'string') {
+    raw.env = { ...readEnvFile(path.dirname(path.dirname(configPath)), raw.envFile), ...(raw.env || {}) };
+  }
   const parsed = appConfigSchema.safeParse(raw);
   if (!parsed.success) {
-    const issues = parsed.error.issues
-      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
-      .join('\n');
-    throw new Error(`Invalid .local/config.json:\n${issues}`);
+    throw new Error(`Invalid .local/config.yaml:\n${describeIssues(parsed.error.issues)}`);
   }
   const cfg = parsed.data;
+  assertPathsInsideProject(cfg, path.dirname(path.dirname(configPath)));
   cfg.namespace = cfg.namespace || cfg.name;
   cfg.subdomain = cfg.subdomain || cfg.name;
+  cfg.hosts = [cfg.subdomain, ...cfg.ingress.hosts];
 
   // Which project this app belongs to - walking up from the app's own directory for the nearest
   // .local/project.json, same lookup as git finding .git (see projectContext.js). No
@@ -40,7 +202,19 @@ function loadConfig(configPath = CONFIG_PATH) {
   const scope = namespaceScopeFor(profileName);
   if (scope) {
     cfg.namespace = `${scope}-${cfg.namespace}`;
-    cfg.subdomain = `${scope}-${cfg.subdomain}`;
+    cfg.hosts = cfg.hosts.map((h) => `${scope}-${h}`);
+    cfg.subdomain = cfg.hosts[0];
+  }
+  // The checks in the schema ran before the project prefix was added, so repeat the ones that
+  // depend on the final names (a prefix could turn `system` into `kube-system`, or push a name
+  // past the 63-character limit).
+  if (isReservedNamespace(cfg.namespace)) {
+    throw new Error(`The namespace "${cfg.namespace}" is reserved for Kubernetes and localctl itself; choose another "namespace" or "name".`);
+  }
+  for (const label of [cfg.namespace, ...cfg.hosts]) {
+    if (label.length > 63) {
+      throw new Error(`"${label}" is longer than 63 characters once the project prefix "${scope}-" is added; shorten the app name, namespace or hosts.`);
+    }
   }
 
   cfg.profile = profileName;
@@ -48,4 +222,4 @@ function loadConfig(configPath = CONFIG_PATH) {
   return cfg;
 }
 
-module.exports = { loadConfig };
+module.exports = { loadConfig, readRawConfig, applyEnvironment };

package/src/lib/manifestGen.js

@@ -5,18 +5,28 @@ const { findAddonDir, listAddonNames } = require('./addonDirs');
 const { secretNameFor } = require('./appSecrets');
 
 function buildNamespace(cfg) {
-  return { apiVersion: 'v1', kind: 'Namespace', metadata: { name: cfg.namespace } };
+  return {
+    apiVersion: 'v1',
+    kind: 'Namespace',
+    metadata: {
+      name: cfg.namespace,
+      labels: { 'localctl.dev/managed': 'true' },
+      annotations: { 'localctl.dev/app': cfg.name },
+    },
+  };
 }
 
 // A sidecar - an extra container sharing the pod's network namespace with the main app container.
 // No Service needed for the app to reach it: same pod means `localhost:<port>` already works.
-function buildSidecarContainer(sidecar) {
+function buildSidecarContainer(sidecar, volumeMounts = []) {
   const container = { name: sidecar.name, image: sidecar.image };
   if (sidecar.command) container.command = sidecar.command;
   if (sidecar.args) container.args = sidecar.args;
-  if (sidecar.port) container.ports = [{ name: sidecar.name, containerPort: sidecar.port }];
+  // No port name: names are limited to 15 characters and must be unique across the pod.
+  if (sidecar.port) container.ports = [{ containerPort: sidecar.port }];
   const envVars = Object.entries(sidecar.env || {}).map(([name, value]) => ({ name, value: String(value) }));
   if (envVars.length) container.env = envVars;
+  if (volumeMounts.length) container.volumeMounts = volumeMounts;
   return container;
 }
 
@@ -25,14 +35,17 @@ function buildSidecarContainer(sidecar) {
 // started," not "it's actually accepting connections." An explicit `path` upgrades it to an HTTP
 // check instead.
 function buildProbe(probeCfg, port, defaults) {
-  const check = probeCfg && probeCfg.path
-    ? { httpGet: { path: probeCfg.path, port } }
-    : { tcpSocket: { port } };
-  return {
+  let check = { tcpSocket: { port } };
+  if (probeCfg && probeCfg.path) check = { httpGet: { path: probeCfg.path, port } };
+  if (probeCfg && probeCfg.command) check = { exec: { command: probeCfg.command } };
+  const probe = {
     ...check,
     initialDelaySeconds: (probeCfg && probeCfg.initialDelaySeconds) ?? defaults.initialDelaySeconds,
     periodSeconds: (probeCfg && probeCfg.periodSeconds) ?? defaults.periodSeconds,
   };
+  if (probeCfg && probeCfg.timeoutSeconds) probe.timeoutSeconds = probeCfg.timeoutSeconds;
+  if (probeCfg && probeCfg.failureThreshold) probe.failureThreshold = probeCfg.failureThreshold;
+  return probe;
 }
 
 // Blocks the main container from starting until a dependency's real Service is actually accepting
@@ -42,13 +55,45 @@ function buildWaitInitContainer(depType, connect) {
   return {
     name: `wait-for-${depType}`,
     image: 'busybox:1.36',
-    command: ['sh', '-c', `until nc -z -w1 ${connect.host} ${connect.port}; do echo "waiting for ${depType} (${connect.host}:${connect.port})..."; sleep 1; done`],
+    // host and port are passed as arguments ($0, $1, $2), never spliced into the script text.
+    command: ['sh', '-c', 'until nc -z -w1 "$0" "$1"; do echo "waiting for $2 ($0:$1)..."; sleep 1; done', String(connect.host), String(connect.port), depType],
   };
 }
 
+// An init container the developer declared (migrations, seeding). Runs in the app's own image
+// unless another is given; Tilt swaps the app image for the freshly built one like it does for the
+// main container.
+function buildUserInitContainer(cfg, init, volumeMounts) {
+  const container = { name: init.name, image: init.image || cfg.name };
+  if (init.command) container.command = init.command;
+  if (init.args) container.args = init.args;
+  const envVars = Object.entries(init.env || {}).map(([name, value]) => ({ name, value: String(value) }));
+  if (envVars.length) container.env = envVars;
+  if (volumeMounts.length) container.volumeMounts = volumeMounts;
+  return container;
+}
+
 function buildDeployment(cfg, envVars, initContainers) {
   const ports = [{ name: 'http', containerPort: cfg.port }];
   if (cfg.debug.enabled && cfg.debug.port) ports.push({ name: 'debug', containerPort: cfg.debug.port });
+  for (const extra of cfg.ports) {
+    ports.push({ name: portName(extra), containerPort: extra.port, protocol: extra.protocol });
+  }
+
+  const volumeMounts = cfg.volumes.map((v) => ({ name: v.name, mountPath: v.mountPath }));
+  const allInitContainers = [
+    ...cfg.initContainers.map((init) => buildUserInitContainer(cfg, init, volumeMounts)),
+    ...initContainers,
+  ];
+  const labels = { ...cfg.labels, app: cfg.name };
+  const probes = {};
+  probes.readinessProbe = buildProbe(cfg.probes.readiness, cfg.port, { initialDelaySeconds: 3, periodSeconds: 10 });
+  probes.livenessProbe = buildProbe(cfg.probes.liveness, cfg.port, { initialDelaySeconds: 10, periodSeconds: 20 });
+  if (cfg.probes.startup) probes.startupProbe = buildProbe(cfg.probes.startup, cfg.port, { initialDelaySeconds: 0, periodSeconds: 5 });
+
+  const podAnnotations = Object.keys(cfg.annotations).length
+    ? Object.fromEntries(Object.entries(cfg.annotations).map(([k, v]) => [k, String(v)]))
+    : undefined;
 
   return {
     apiVersion: 'apps/v1',
@@ -56,29 +101,40 @@ function buildDeployment(cfg, envVars, initContainers) {
     metadata: {
       name: cfg.name,
       namespace: cfg.namespace,
-      labels: { app: cfg.name, 'localctl.dev/managed': 'true' },
+      labels: { ...labels, 'localctl.dev/managed': 'true' },
     },
     spec: {
       replicas: cfg.replicas,
       selector: { matchLabels: { app: cfg.name } },
       template: {
-        metadata: { labels: { app: cfg.name } },
+        metadata: { labels, annotations: podAnnotations },
         spec: {
-          initContainers: initContainers.length ? initContainers : undefined,
+          terminationGracePeriodSeconds: cfg.terminationGracePeriodSeconds,
+          initContainers: allInitContainers.length ? allInitContainers : undefined,
+          volumes: cfg.volumes.length
+            ? cfg.volumes.map((v) => ({
+                name: v.name,
+                emptyDir: v.sizeLimit ? { sizeLimit: v.sizeLimit } : {},
+              }))
+            : undefined,
           containers: [
             {
               name: cfg.name,
               // Rewritten to the local registry by Tilt's default_registry()/docker_build().
               image: cfg.name,
+              imagePullPolicy: cfg.imagePullPolicy,
+              command: cfg.command,
+              args: cfg.args,
               ports,
               env: envVars,
-              readinessProbe: buildProbe(cfg.probes.readiness, cfg.port, { initialDelaySeconds: 3, periodSeconds: 10 }),
-              livenessProbe: buildProbe(cfg.probes.liveness, cfg.port, { initialDelaySeconds: 10, periodSeconds: 20 }),
+              volumeMounts: volumeMounts.length ? volumeMounts : undefined,
+              securityContext: cfg.securityContext,
+              ...probes,
               resources: cfg.resources
                 ? { requests: cfg.resources.requests, limits: cfg.resources.limits }
                 : undefined,
             },
-            ...cfg.sidecars.map(buildSidecarContainer),
+            ...cfg.sidecars.map((s) => buildSidecarContainer(s, volumeMounts)),
           ],
         },
       },
@@ -86,11 +142,19 @@ function buildDeployment(cfg, envVars, initContainers) {
   };
 }
 
+// Port names are limited to 15 characters; unnamed ports get "p<number>".
+function portName(extra) {
+  return extra.name || (extra.protocol === 'UDP' ? `p${extra.port}-udp` : `p${extra.port}`);
+}
+
 function buildService(cfg) {
   const ports = [{ name: 'http', port: cfg.port, targetPort: cfg.port }];
   if (cfg.debug.enabled && cfg.debug.port) {
     ports.push({ name: 'debug', port: cfg.debug.port, targetPort: cfg.debug.port });
   }
+  for (const extra of cfg.ports) {
+    ports.push({ name: portName(extra), port: extra.port, targetPort: extra.port, protocol: extra.protocol });
+  }
   return {
     apiVersion: 'v1',
     kind: 'Service',
@@ -104,7 +168,12 @@ function buildService(cfg) {
 }
 
 function buildIngress(cfg) {
-  const host = `${cfg.subdomain}.${DOMAIN}`;
+  const hosts = (cfg.hosts || [cfg.subdomain]).map((h) => `${h}.${DOMAIN}`);
+  const paths = (cfg.ingress.paths.length ? cfg.ingress.paths : [{ path: '/' }]).map((p) => ({
+    path: p.path,
+    pathType: 'Prefix',
+    backend: { service: { name: cfg.name, port: { number: p.port || cfg.port } } },
+  }));
   const ingress = {
     apiVersion: 'networking.k8s.io/v1',
     kind: 'Ingress',
@@ -113,29 +182,18 @@ function buildIngress(cfg) {
       namespace: cfg.namespace,
       labels: { app: cfg.name, 'localctl.dev/managed': 'true' },
       annotations: {
+        ...Object.fromEntries(Object.entries(cfg.ingress.annotations).map(([k, v]) => [k, String(v)])),
+        // Set last: whether the route is HTTPS follows `tls`, not an annotation.
         'traefik.ingress.kubernetes.io/router.entrypoints': cfg.tls ? 'websecure' : 'web',
       },
     },
     spec: {
-      rules: [
-        {
-          host,
-          http: {
-            paths: [
-              {
-                path: '/',
-                pathType: 'Prefix',
-                backend: { service: { name: cfg.name, port: { number: cfg.port } } },
-              },
-            ],
-          },
-        },
-      ],
+      rules: hosts.map((host) => ({ host, http: { paths } })),
     },
   };
   // Empty secretName: Traefik falls back to the cluster's default TLSStore certificate
   // (the *.local.test cert installed by bin/bootstrap.sh / bootstrap.ps1).
-  if (cfg.tls) ingress.spec.tls = [{ hosts: [host] }];
+  if (cfg.tls) ingress.spec.tls = [{ hosts }];
   return ingress;
 }
 
@@ -170,6 +228,7 @@ function generateManifests(cfg) {
       addonName: dep.type,
       owner: cfg.name,
       chartVersionOverride: dep.version,
+      resources: dep.resources,
       extraVars: {
         database: dep.database || cfg.name,
         storage: dep.storage || '1Gi',
@@ -191,6 +250,11 @@ function generateManifests(cfg) {
     secretEnv[key] = { secret: secretNameFor(cfg), key };
   }
 
+  // One definition per variable name: a value the developer wrote in `env` beats an addon's
+  // secretKeyRef of the same name, and a name declared in `secrets` beats an addon's plain value.
+  for (const key of Object.keys(cfg.env)) delete secretEnv[key];
+  for (const key of cfg.secrets) delete literalEnv[key];
+
   const envVars = [
     ...Object.entries(literalEnv).map(([name, value]) => ({ name, value: String(value) })),
     ...Object.entries(secretEnv).map(([name, ref]) => ({
@@ -200,11 +264,11 @@ function generateManifests(cfg) {
   ];
 
   const docs = [buildNamespace(cfg), buildDeployment(cfg, envVars, initContainers), buildService(cfg), buildIngress(cfg)];
-  const rendered = docs.map((d) => yaml.dump(d)).join('---\n');
+  const rendered = docs.map((d) => yaml.dump(d, { noRefs: true })).join('---\n');
   // trimEnd() before joining: addon YAML doesn't reliably end with a trailing newline (see
   // addonLoader.js), and joining on a bare '---\n' in that case glues the separator directly onto
   // the previous piece's last line with no line break, corrupting the YAML.
   return [rendered, ...addonYamls].map((doc) => doc.trimEnd()).join('\n---\n');
 }
 
-module.exports = { generateManifests, knownAddonTypes };
+module.exports = { generateManifests, knownAddonTypes, buildWaitInitContainer };