elestio 1.1.0 → 1.2.0

package/README.md

@@ -145,6 +145,11 @@ already started billing its VMs.
 | `elestio clusters resync <clusterID> --force` | Re-sync replicas from the primary |
 | `elestio clusters lock <clusterID>` | Enable termination protection |
 | `elestio clusters unlock <clusterID>` | Disable termination protection |
+| `elestio clusters add-node <clusterID> [--dry-run]` | Add a node, copying the primary's provider, region, size and version |
+| `elestio clusters remove-node <clusterID> <vmID> --force` | Remove a replica node and its VM |
+| `elestio clusters firewall <clusterID>` | Show which IPs each port accepts |
+| `elestio clusters firewall-restrict <clusterID> --port P --ips ip1,ip2` | Only accept a port from these IPs, on every node |
+| `elestio clusters firewall-open <clusterID> --port P` | Open a port to everyone again |
 | `elestio clusters delete <clusterID> --force` | Delete the cluster and all its nodes |
 
 `promote`, `resync` and `delete` require `--force`: promotion demotes the
@@ -152,6 +157,20 @@ current primary, re-sync **erases all data on the replicas** and replaces it
 with a copy of the primary, and delete removes every node. A locked cluster
 must be unlocked before it can be deleted.
 
+**Nodes.** `add-node` copies the primary: same provider, region, size and
+software version (`--size`, `--region`, `--provider` or `--version` to change
+them). It is billed as one more VM, so dry-run it first. It needs remote
+backups on the primary, which seed the new node (`elestio backups auto-enable
+<vmID>`), and is not available on multi-master clusters. After the VM is
+deployed, Elestio still spends a few minutes turning it into a replica: the
+cluster reads `running` meanwhile, and the CLI refuses other node or firewall
+changes until that is done. `remove-node` only removes replicas; to remove the
+primary, `promote` a replica first or delete the whole cluster.
+
+**Firewall.** `firewall-restrict` applies to every node, and the cluster's
+own nodes stay allowed so replication keeps working. Use it rather than
+`elestio firewall` on a single node.
+
 `failover` does not switch the primary itself. It turns on or off the automatic
 failover that promotes a replica when the primary goes down; use `promote` to
 switch by hand. Its state shows in `clusters info`.
@@ -267,6 +286,8 @@ S3 options: `--key`, `--secret`, `--bucket`, `--endpoint`, `--prefix`
 | `elestio ssh <vmID> --direct` | Get direct SSH connection info |
 | `elestio vscode <vmID>` | Get VSCode web URL |
 | `elestio files <vmID>` | Get file explorer URL |
+| `elestio logs <vmID> [--mode app\|install]` | Open a live log view (temporary URL): the app's container logs, or the install log |
+| `elestio audits <vmID> [--days N]` | Audit trail: who did what (default: last 30 days) |
 
 ### Volumes
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "elestio",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Elestio CLI - Deploy and manage services on the Elestio DevOps platform",
   "type": "module",
   "main": "src/cli.js",
   "bin": {
-    "elestio": "./bin/elestio.js"
+    "elestio": "bin/elestio.js"
   },
   "scripts": {
     "start": "node bin/elestio.js",
@@ -36,7 +36,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/elestio/elestio-cli"
+    "url": "git+https://github.com/elestio/elestio-cli.git"
   },
   "homepage": "https://elest.io",
   "bugs": {

package/src/commands/access.js

@@ -1,7 +1,7 @@
 import { apiRequest } from '../api.js';
 import { loadConfig } from '../config.js';
-import { colors, outputJson } from '../utils.js';
-import { getServiceDetails } from './services.js';
+import { colors, outputJson, formatTable, log } from '../utils.js';
+import { getServiceDetails, listServicesRaw } from './services.js';
 
 export async function getCredentials(vmID, projectId = null, json = false) {
   const config = loadConfig();
@@ -143,3 +143,82 @@ export async function getFileExplorer(vmID, projectId = null, json = false) {
   console.log('');
   return response;
 }
+
+/**
+ * startLogTailView modes, as the backend whitelists them. "syslog" streams the
+ * app's `docker-compose logs` and is what the dashboard's Logs tab uses; an
+ * empty mode is the install log. "docker" is not accepted.
+ */
+export const LOG_MODES = { app: 'syslog', install: '', resync: 'resyncLog', alerts: 'alertLog', 'db-migration': 'db-migration-logs' };
+const RAW_LOG_MODES = Object.values(LOG_MODES);
+
+export function resolveLogMode(mode = 'app') {
+  if (mode in LOG_MODES) return LOG_MODES[mode];
+  if (RAW_LOG_MODES.includes(mode)) return mode;
+  throw new Error(`Unknown log mode "${mode}". Use one of: ${Object.keys(LOG_MODES).join(', ')}`);
+}
+
+/**
+ * Live log view. The API opens a temporary web page streaming the logs rather
+ * than returning them, like the dashboard's "Logs" tab.
+ */
+export async function getLogsView(vmID, projectId = null, mode = 'app', json = false) {
+  const pid = projectId || loadConfig().defaultProject;
+  if (!pid) throw new Error('Project ID required');
+
+  const response = await apiRequest('/api/servers/startLogTailView', 'POST', {
+    vmID: String(vmID), projectID: String(pid), mode: resolveLogMode(mode)
+  });
+  if (!response.url) throw new Error(response.message || 'Failed to open the log view');
+
+  if (json) { outputJson({ url: response.url, user: response.user, password: response.password }); return response; }
+
+  console.log(`\n${colors.bold}Live logs (${mode})${colors.reset}\n`);
+  console.log(`  URL:      ${colors.cyan}${response.url}${colors.reset}`);
+  if (response.user) console.log(`  User:     ${response.user}`);
+  if (response.password) console.log(`  Password: ${response.password}`);
+  console.log(`\n  ${colors.dim}Temporary page. --mode install for the installation log.${colors.reset}\n`);
+  return response;
+}
+
+export function formatAudit(a) {
+  return {
+    when: String(a.time || a.timestamp || 'N/A').replace('T', ' ').slice(0, 19),
+    event: [a.event_category, a.event_type].filter(Boolean).join(' / ') || a.event || 'N/A',
+    user: a.email || a.userEmail || 'N/A',
+    details: String(a.event_details || a.details || '').slice(0, 60)
+  };
+}
+
+/** Audit trail of a service: who did what, over the last N days. */
+export async function getAudits(vmID, projectId = null, days = 30, json = false) {
+  const pid = projectId || loadConfig().defaultProject;
+  if (!pid) throw new Error('Project ID required');
+
+  // getAudits takes serverIDs, not vmIDs.
+  const service = (await listServicesRaw(pid)).find(s => String(s.vmID) === String(vmID) || String(s.id) === String(vmID));
+  if (!service) throw new Error(`Service ${vmID} not found in project ${pid}`);
+
+  const end = new Date();
+  const start = new Date(end.getTime() - Number(days) * 24 * 60 * 60 * 1000);
+  const response = await apiRequest('/api/servers/getAudits', 'POST', {
+    serverIDs: [String(service.id)], projectID: String(pid),
+    startDate: start.toISOString(), endDate: end.toISOString()
+  });
+  if (response.status === 'KO' || response.status === 'error') throw new Error(response.message || 'Failed to fetch audits');
+
+  // Entries come back as a bare array in data: {status, count, data: [...]}.
+  const audits = Array.isArray(response.data) ? response.data : (response.data?.audits || response.audits || []);
+  if (json) { outputJson(audits); return audits; }
+  if (audits.length === 0) { log('info', `No audit entries in the last ${days} days`); return []; }
+
+  console.log(`\n${colors.bold}Audit trail of ${vmID} (last ${days} days)${colors.reset}\n`);
+  console.log(formatTable(audits.map(formatAudit), [
+    { key: 'when', label: 'When' },
+    { key: 'event', label: 'Event' },
+    { key: 'user', label: 'User' },
+    { key: 'details', label: 'Details' }
+  ]));
+  console.log('');
+  return audits;
+}

package/src/commands/clusters.js

@@ -6,7 +6,8 @@ import {
   minClusterNodes, supportsClustering, supportsMultiMaster
 } from '../constants.js';
 import { getTemplates } from './templates.js';
-import { listServicesRaw, deleteService } from './services.js';
+import { doAction } from './actions.js';
+import { listServicesRaw, deleteService, getServiceDetails } from './services.js';
 
 const APPID = 'CloudVM';
 
@@ -277,6 +278,257 @@ export async function promoteNode(clusterId, vmID, projectId, force) {
   return response;
 }
 
+// ── Nodes ──
+//
+// Neither operation has an endpoint of its own. The dashboard adds a node with
+// createServer (serviceType "ClusterNodes" + the primary's serverID), and
+// removes one with deleteServer on the node followed by updateClusterNodes,
+// which only decrements the cluster's node count.
+
+const BUSY_STATUSES = ['deploying', 'deleting', 'creating', 'initializing'];
+
+/**
+ * The status reads "running" while a node is still being turned into a
+ * replica; the work in progress is only visible in jsonConfig
+ * ({"configuring":{"ids":[...]},"type":"add-node"}), as the dashboard reads it.
+ */
+export function clusterConfiguration(info) {
+  try {
+    const config = typeof info.jsonConfig === 'string' ? JSON.parse(info.jsonConfig) : info.jsonConfig;
+    // Once done it stays as {"configuring":{"ids":[]},"type":""}: only a type
+    // or pending IDs mean work in progress.
+    if (!config || !config.configuring) return null;
+    if (config.type) return config.type;
+    return Array.isArray(config.configuring.ids) && config.configuring.ids.length > 0 ? 'configuring' : null;
+  } catch {
+    return null;
+  }
+}
+
+function isClusterBusy(info) {
+  const status = String(info.status || '').toLowerCase();
+  return status.includes('configuring') || status.includes('creating') || status === 'being configured' ||
+    clusterConfiguration(info) !== null;
+}
+
+/** Nodes are named after the cluster: pg-cluster1, pg-cluster2... */
+function nextNodeName(nodes, primary) {
+  const base = String(primary.displayName || primary.serverName || '').replace(/\d+$/, '');
+  const numbers = nodes.map(n => Number((String(n.displayName || '').match(/(\d+)$/) || [])[1] || 0));
+  return `${base}${Math.max(nodes.length, ...numbers) + 1}`;
+}
+
+export function addNodeBlocker(info, primary, nodes) {
+  if (info.replicationMode === 'master') {
+    throw new Error('Nodes cannot be added to a multi-master cluster');
+  }
+  if (isClusterBusy(info) || primary.status !== 'running') {
+    throw new Error(`Cluster ${info.id} is busy (${clusterConfiguration(info) || info.status}); wait until it is running`);
+  }
+  if (!Number(primary.remoteBackupsActivated)) {
+    throw new Error(
+      'A new node is seeded from the primary\'s remote backup, and remote backups are off. ' +
+      `Enable them first: elestio backups auto-enable ${primary.vmID}`
+    );
+  }
+  if (nodes.length >= CLUSTER_MAX_NODES) {
+    throw new Error(`Cluster ${info.id} already has ${nodes.length} nodes; the maximum is ${CLUSTER_MAX_NODES}`);
+  }
+}
+
+/**
+ * The node must run the primary's version. getServices does not carry it; the
+ * primary's details do, as selected_software_tag. Falling back to "latest"
+ * could start a replica on another major version, so a missing one is an error.
+ */
+export function nodeVersion(primary, override) {
+  const version = override || primary.selected_software_tag || primary.version;
+  if (!version) throw new Error('Could not read the primary\'s software version; pass it with --version');
+  return String(version);
+}
+
+export function buildAddNodePayload({ info, primary, nodes, adminEmail, projectId, size, region, provider, version }) {
+  return {
+    templateID: String(info.templateID),
+    serverType: size || primary.serverType,
+    datacenter: region || primary.datacenter,
+    providerName: provider || primary.provider,
+    serverName: nextNodeName(nodes, primary),
+    appid: 'CloudVM',
+    data: '',
+    support: 'level1',
+    projectId: projectId === undefined ? undefined : String(projectId),
+    version: nodeVersion(primary, version),
+    adminEmail,
+    deploymentServiceType: 'normal',
+    serviceType: 'ClusterNodes',
+    isReplica: info.replicationMode === 'replica',
+    primaryServerID: String(info.primaryServerID)
+  };
+}
+
+export async function addClusterNode(clusterId, options = {}) {
+  const config = loadConfig();
+  const pid = requireProject(options.project);
+  const info = await getClusterInfo(clusterId, pid);
+  const nodes = await listNodesRaw(info, pid);
+  const listed = nodes.find(n => String(n.vmID) === String(info.primaryProviderServerID));
+  if (!listed) throw new Error(`Primary of cluster ${clusterId} not found`);
+  const primary = { ...listed, ...(await getServiceDetails(listed.vmID, pid)) };
+
+  addNodeBlocker(info, primary, nodes);
+  const payload = buildAddNodePayload({
+    info, primary, nodes, projectId: pid,
+    adminEmail: options.email || config.email,
+    size: options.size, region: options.region, provider: options.provider, version: options.version
+  });
+
+  if (options.dryRun) {
+    if (options.json) { outputJson({ dryRun: true, payload }); return payload; }
+    console.log(`\n${colors.bold}Add node (--dry-run)${colors.reset}\n`);
+    console.log(`  Cluster:   ${info.id} (${info.templateName || 'N/A'}), ${nodes.length} -> ${nodes.length + 1} nodes`);
+    console.log(`  New node:  ${payload.serverName} (${info.replicationMode === 'replica' ? 'replica' : 'node'})`);
+    console.log(`  VM:        ${payload.providerName} / ${payload.datacenter} / ${payload.serverType}`);
+    console.log(`  Version:   ${payload.version} (same as the primary)`);
+    console.log(`  ${colors.yellow}Billed as one more VM.${colors.reset}\n`);
+    log('info', 'To add it, run the same command without --dry-run');
+    return payload;
+  }
+
+  const response = await apiRequest('/api/servers/createServer', 'POST', payload);
+  if (!response.providerServerID && !response.action) {
+    throw new Error(response.message || 'Failed to add the node');
+  }
+  log('success', `Node ${payload.serverName} is being added to cluster ${clusterId} (vmID ${response.providerServerID})`);
+  log('info', `Follow it with: elestio wait ${response.providerServerID}`);
+  return response;
+}
+
+export function planRemoveNode(info, nodes, vmID, projectId) {
+  const node = nodes.find(n => String(n.vmID) === String(vmID));
+  if (!node) {
+    throw new Error(`vmID ${vmID} is not a node of cluster ${info.id}. Nodes: ${nodes.map(n => n.vmID).join(', ') || 'none'}`);
+  }
+  if (String(node.vmID) === String(info.primaryProviderServerID)) {
+    throw new Error(`vmID ${vmID} is the primary. Promote a replica first, or delete the whole cluster with: elestio clusters delete ${info.id} --force`);
+  }
+  if (BUSY_STATUSES.includes(String(node.status).toLowerCase()) || isClusterBusy(info)) {
+    throw new Error(`Node ${vmID} or its cluster is busy (${node.status} / ${info.status}); try again once it is running`);
+  }
+  if (Number(info.templateID) === 183 && nodes.length <= 3) {
+    throw new Error('A Vault cluster cannot go below 3 nodes');
+  }
+  return {
+    node,
+    update: {
+      projectId: String(projectId),
+      clusterId: String(info.id),
+      templateID: String(node.template ?? info.templateID),
+      vmID: String(node.vmID),
+      labelName: String(node.labelName || node.displayName || ''),
+      appid: 'CloudVM'
+    }
+  };
+}
+
+export async function removeClusterNode(clusterId, vmID, projectId, force) {
+  if (!force) {
+    throw new Error(`Removing node ${vmID} deletes that VM and its data. Re-run with --force.`);
+  }
+  const pid = requireProject(projectId);
+  const info = await getClusterInfo(clusterId, pid);
+  const nodes = await listNodesRaw(info, pid);
+  const { update } = planRemoveNode(info, nodes, vmID, pid);
+
+  await deleteService(vmID, { force: true, project: pid });
+  const response = await apiRequest('/api/clusters/updateClusterNodes', 'POST', update);
+  if (response.status === 'KO') throw new Error(response.message || 'Node deleted, but the cluster node count was not updated');
+  log('success', `Node ${vmID} is being removed from cluster ${clusterId}`);
+  return response;
+}
+
+// ── Firewall ──
+
+const OPEN_TARGETS = ['0.0.0.0/0', '::/0'];
+const IPV4_CIDR = /^(\d{1,3}\.){3}\d{1,3}(\/(3[0-2]|[12]?\d))?$/;
+const IPV6_CIDR = /^[0-9a-fA-F:]+(\/\d{1,3})?$/;
+
+export function parseIpList(value) {
+  return String(value ?? '').split(',').map(ip => ip.trim()).filter(Boolean);
+}
+
+function toCidr(ip) {
+  if (IPV4_CIDR.test(ip)) return ip.includes('/') ? ip : `${ip}/32`;
+  if (ip.includes(':') && IPV6_CIDR.test(ip)) return ip.includes('/') ? ip : `${ip}/128`;
+  throw new Error(`"${ip}" is not an IP address or CIDR range`);
+}
+
+function parseRules(raw) {
+  if (Array.isArray(raw)) return raw;
+  try { return JSON.parse(raw || '[]'); } catch { return []; }
+}
+
+/**
+ * Returns new rules where each port in `ports` accepts only `ips` (or everyone
+ * when `ips` is empty). The other rules are kept as they are.
+ */
+export function setPortTargets(rules, ports, ips) {
+  const known = rules.map(r => String(r.port));
+  for (const port of ports) {
+    if (!known.includes(String(port))) {
+      throw new Error(`Port ${port} has no rule on this cluster. Ports: ${known.join(', ')}`);
+    }
+  }
+  const targets = ips.length > 0 ? ips.map(toCidr) : OPEN_TARGETS;
+  return rules.map(r => ports.map(String).includes(String(r.port)) ? { ...r, targets: [...targets] } : { ...r, targets: [...r.targets] });
+}
+
+export async function showClusterFirewall(clusterId, projectId = null, json = false) {
+  const info = await getClusterInfo(clusterId, projectId);
+  const rules = parseRules(info.firewall_rules);
+  if (json) { outputJson(rules); return rules; }
+
+  console.log(`\n${colors.bold}Firewall of cluster ${clusterId}${colors.reset}\n`);
+  console.log(formatTable(rules.map(r => ({
+    port: r.port, protocol: r.protocol,
+    allowed: r.targets.includes('0.0.0.0/0') ? 'everyone' : r.targets.join(', ')
+  })), [
+    { key: 'port', label: 'Port' },
+    { key: 'protocol', label: 'Protocol' },
+    { key: 'allowed', label: 'Allowed from' }
+  ]));
+  console.log('\n  Other nodes of the cluster are always allowed, so replication keeps working.\n');
+  return rules;
+}
+
+export async function setClusterPortAccess(clusterId, port, ips, projectId = null) {
+  const pid = requireProject(projectId);
+  const info = await getClusterInfo(clusterId, pid);
+  if (isClusterBusy(info)) throw new Error(`Cluster ${clusterId} is busy (${clusterConfiguration(info) || info.status}); try again once it is running`);
+  const nodes = await listNodesRaw(info, pid);
+  const primary = nodes.find(n => String(n.vmID) === String(info.primaryProviderServerID));
+  if (!primary) throw new Error(`Primary of cluster ${clusterId} not found`);
+
+  const ports = [String(port)];
+  const rules = JSON.stringify(setPortTargets(parseRules(info.firewall_rules), ports, ips));
+
+  for (const node of nodes) {
+    log('info', `Updating firewall on ${node.displayName || node.vmID}...`);
+    await doAction(node.vmID, 'updateFirewall', {
+      rules, clusterTemplate: info.templateID, primaryServerID: primary.id, currentPort: ports
+    });
+  }
+
+  const response = await apiRequest('/api/clusters/updateClusterRowFirewall', 'POST', {
+    appid: APPID, projectId: pid, clusterID: String(clusterId), firewall_rules: rules
+  });
+  if (response.status === 'KO') throw new Error(response.message || 'Nodes updated, but the cluster rules were not saved');
+
+  log('success', ips.length > 0
+    ? `Port ${port} of cluster ${clusterId} now only accepts ${ips.join(', ')} (plus the cluster's own nodes)`
+    : `Port ${port} of cluster ${clusterId} is open to everyone`);
+}
+
 /**
  * There is no cluster delete endpoint: deleting the primary service deletes
  * every node with it. The primary changes after a promote, so it is looked up

package/src/registry.js

@@ -347,6 +347,44 @@ export const registry = {
         summary: 'Re-sync replicas from the primary, erasing replica data (--force)', usage: 'resync <clusterID> --force',
         async run({ args }) { await (await load.clusters()).resyncCluster(requireArg(args._[2], 'clusters resync <clusterID> --force'), args.project, !!args.force); }
       },
+      'add-node': {
+        summary: 'Add a node, copying the primary (--size/--region to change; --dry-run)', usage: 'add-node <clusterID>',
+        async run({ args, json }) {
+          await (await load.clusters()).addClusterNode(requireArg(args._[2], 'clusters add-node <clusterID>'), {
+            project: args.project, size: args.size, region: args.region, provider: args.provider,
+            version: args.version, email: args.email, dryRun: !!args['dry-run'], json
+          });
+        }
+      },
+      'remove-node': {
+        summary: 'Remove a replica node and its VM (--force)', usage: 'remove-node <clusterID> <vmID> --force',
+        async run({ args }) {
+          await (await load.clusters()).removeClusterNode(
+            requireArg(args._[2], 'clusters remove-node <clusterID> <vmID> --force'),
+            requireArg(args._[3], 'clusters remove-node <clusterID> <vmID> --force'),
+            args.project, !!args.force
+          );
+        }
+      },
+      firewall: {
+        summary: 'Show which IPs each port of a cluster accepts', usage: 'firewall <clusterID>',
+        async run({ args, json }) { await (await load.clusters()).showClusterFirewall(requireArg(args._[2], 'clusters firewall <clusterID>'), args.project, json); }
+      },
+      'firewall-restrict': {
+        summary: 'Only accept a port from given IPs, on every node', usage: 'firewall-restrict <clusterID> --port P --ips ip1,ip2',
+        async run({ args }) {
+          const { setClusterPortAccess, parseIpList } = await load.clusters();
+          const ips = parseIpList(args.ips);
+          if (ips.length === 0) throw new Error('--ips is required (comma-separated IPs or CIDR ranges). To reopen a port use firewall-open.');
+          await setClusterPortAccess(requireArg(args._[2], 'clusters firewall-restrict <clusterID> --port P --ips ...'), requireArg(args.port, '--port <port>'), ips, args.project);
+        }
+      },
+      'firewall-open': {
+        summary: 'Open a port of a cluster to everyone again', usage: 'firewall-open <clusterID> --port P',
+        async run({ args }) {
+          await (await load.clusters()).setClusterPortAccess(requireArg(args._[2], 'clusters firewall-open <clusterID> --port P'), requireArg(args.port, '--port <port>'), [], args.project);
+        }
+      },
       delete: {
         summary: 'Delete a cluster and all its nodes (--force)', usage: 'delete <clusterID> --force',
         async run({ args }) { await (await load.clusters()).deleteCluster(requireArg(args._[2], 'clusters delete <clusterID> --force'), args.project, !!args.force); }
@@ -507,6 +545,20 @@ export const registry = {
 
   // ── Access ──
 
+  logs: {
+    group: 'Access',
+    summary: 'Open a live log view of a service (--mode install for the install log)',
+    usage: 'logs <vmID> [--mode app|install]',
+    async run({ args, json }) { await (await load.access()).getLogsView(requireArg(args._[1], 'logs <vmID>'), args.project, args.mode || 'app', json); }
+  },
+
+  audits: {
+    group: 'Access',
+    summary: 'Show the audit trail of a service (--days, default 30)',
+    usage: 'audits <vmID> [--days N]',
+    async run({ args, json }) { await (await load.access()).getAudits(requireArg(args._[1], 'audits <vmID>'), args.project, args.days ? Number(args.days) : 30, json); }
+  },
+
   credentials: {
     group: 'Access',
     summary: 'Show the application credentials of a service',