chore: update cloudly dependency stack
Align Cloudly with the current typedserver, smartconfig, smartstate, and Docker tooling releases so builds and Docker output stay compatible with the upgraded stack.
This commit is contained in:
@@ -30,15 +30,17 @@ Cloudly currently coordinates these areas:
|
||||
- **Authentication and identity**: human admin login, JWT identities, machine tokens, and cluster identities.
|
||||
- **Clusters**: desired cluster records and machine users used by Coreflow to authenticate back to Cloudly.
|
||||
- **Services**: workload definitions, image references, domains, ports, scale factors, secret bundles, volumes, and deployment metadata.
|
||||
- **Deployments**: deployment records, node placement metadata, health/resource fields, restart/scale API stubs, and DNS activation/deactivation hooks.
|
||||
- **Images and registries**: image metadata, S3-backed image storage, external registry records, and an embedded OCI registry mounted at `/v2`.
|
||||
- **Secrets**: secret groups and bundles that Coreflow flattens into Docker secrets for workloads.
|
||||
- **Domains and DNS**: domain records, DNS entries, and optional domain sync from a dcrouter external gateway.
|
||||
- **Platform bindings**: first-class `database` and `objectstorage` bindings that Coreflow provisions through Corestore.
|
||||
- **Platform bindings**: capabilities such as `database`, `objectstorage`, `logging`, `backup`, and RPC-style platform services that Coreflow/Corestore can reconcile.
|
||||
- **Backups**: backup records, service backup/restore requests, scheduled backup tasks, and archive replication handshakes with Coreflow/Corestore.
|
||||
- **BaseOS**: managed BaseOS node registration, heartbeat handling, desired-state response, image build tracking, and image download URLs.
|
||||
- **CoreBuild workers**: selection of external build workers for BaseOS ISO/raw-image artifact generation.
|
||||
- **CoreBuild workers**: selection of external build workers for BaseOS ISO and balena raw-image artifact generation.
|
||||
- **Tasks**: TaskBuffer-backed operational tasks with execution history, metrics, logs, manual triggers, cancellation, and cron schedules.
|
||||
- **Node and bare-metal inventory**: Hetzner-backed node creation paths and bare-metal metadata records where configured.
|
||||
- **Dashboard**: a web component UI rendered from `ts_web` with views for clusters, services, images, secrets, domains, DNS, tasks, backups, BaseOS, and settings.
|
||||
- **Dashboard**: a web component UI rendered from `ts_web` with views for overview, settings, secrets, clusters, external registries, images, services, deployments, tasks, domains, DNS, mail/log/storage/database shells, backups, and BaseOS.
|
||||
|
||||
## Runtime Components
|
||||
|
||||
@@ -53,10 +55,12 @@ Cloudly currently coordinates these areas:
|
||||
| `CloudlyRegistryManager` | Embedded OCI registry backed by configured S3 storage, including deploy-on-push metadata updates. |
|
||||
| `CloudlyBaseOsManager` | BaseOS registration, heartbeat, image build orchestration, worker selection, and artifact downloads. |
|
||||
| `CloudlyBackupManager` | Service backup/restore orchestration and remote archive object replication. |
|
||||
| `CloudlyTaskManager` | Registers predefined and runtime tasks, tracks task executions, schedules cron jobs, and exposes task APIs. |
|
||||
| `CloudlySettingsManager` | Stores runtime settings in MongoDB, masks sensitive values for API responses, and refreshes gateway/Coreflow state after relevant changes. |
|
||||
|
||||
## Configuration
|
||||
|
||||
Cloudly uses `@push.rocks/npmextra` app data and environment mappings. Values can be supplied through environment variables, `.nogit` app-data files, or by constructing `new Cloudly(config)` programmatically.
|
||||
Cloudly uses `@push.rocks/smartconfig` `AppData` with environment mappings. The runtime entry point loads `.nogit`/environment values through `@push.rocks/qenv`, and embedded callers can override values by constructing `new Cloudly(config)` programmatically.
|
||||
|
||||
Required runtime configuration:
|
||||
|
||||
@@ -88,6 +92,23 @@ Common optional settings are stored through the Cloudly settings manager rather
|
||||
| `corebuildWorkersJson` | JSON array of CoreBuild worker URLs or `{ "url", "token", "id" }` objects. |
|
||||
| `corebuildWorkerUrl` / `corebuildWorkerToken` | Legacy single-worker CoreBuild settings. |
|
||||
| `dcrouterGatewayUrl` / `dcrouterGatewayApiToken` | Optional external gateway integration for domain and route sync. |
|
||||
| `dcrouterWorkHosterId` | Optional stable external gateway work hoster ID; defaults to the cluster ID. |
|
||||
| `dcrouterTargetHost` / `dcrouterTargetPort` | Optional target address that dcrouter should forward workload traffic to. |
|
||||
|
||||
Optional runtime environment variables:
|
||||
|
||||
| Variable | Purpose |
|
||||
| --- | --- |
|
||||
| `SERVEZONE_INSTALL_DEMO_DATA` | Runs the destructive demo data installer when set to `true`. |
|
||||
| `CLOUDLY_BACKUP_CRON` | Enables the scheduled `backup-all-services` task with the supplied cron expression. |
|
||||
| `CLOUDLY_BACKUP_KEEP_LAST` | Number of completed/failed backups to retain per service; defaults to `24`. |
|
||||
| `CLOUDLY_BACKUP_TARGET_TYPE` | Remote archive replication target, currently `s3` or `smb`. |
|
||||
| `CLOUDLY_BACKUP_TARGET_PREFIX` | Remote backup path prefix; defaults to `serve.zone-backups`. |
|
||||
| `CLOUDLY_BASEOS_IMAGE_CLEANUP_INTERVAL_MS` | BaseOS image artifact cleanup interval; defaults to 12 hours. |
|
||||
|
||||
For backup replication with `CLOUDLY_BACKUP_TARGET_TYPE=s3`, set `CLOUDLY_BACKUP_S3_ENDPOINT`, `CLOUDLY_BACKUP_S3_ACCESS_KEY`, `CLOUDLY_BACKUP_S3_SECRET_KEY`, and `CLOUDLY_BACKUP_S3_BUCKET`. Optional S3 variables are `CLOUDLY_BACKUP_S3_REGION`, `CLOUDLY_BACKUP_S3_PORT`, and `CLOUDLY_BACKUP_S3_USE_SSL`.
|
||||
|
||||
For backup replication with `CLOUDLY_BACKUP_TARGET_TYPE=smb`, set `CLOUDLY_BACKUP_SMB_HOST` and `CLOUDLY_BACKUP_SMB_SHARE`. Optional SMB variables are `CLOUDLY_BACKUP_SMB_PORT`, `CLOUDLY_BACKUP_SMB_USERNAME`, `CLOUDLY_BACKUP_SMB_PASSWORD`, and `CLOUDLY_BACKUP_SMB_DOMAIN`.
|
||||
|
||||
## Starting Cloudly
|
||||
|
||||
@@ -141,6 +162,8 @@ Set `SERVEZONE_INSTALL_DEMO_DATA=true` only when you intentionally want the demo
|
||||
|
||||
Cloudly exposes a single composed TypedRouter. Managers add their own typed handlers to the main router, and `CloudlyServer` exposes that router through the HTTP/WebSocket server.
|
||||
|
||||
On first startup, Cloudly bootstraps the first human admin from `SERVEZONE_ADMINACCOUNT`. Human clients authenticate through `adminLoginWithUsernameAndPassword`; machine clients authenticate through `getIdentityByToken`. Cluster creation creates a machine user and token for Coreflow.
|
||||
|
||||
Typical consumers use `@serve.zone/api`:
|
||||
|
||||
```ts
|
||||
@@ -178,11 +201,13 @@ Cloudly serves an OCI registry under `/v2` through `CloudlyRegistryManager`. The
|
||||
For Cloudly-managed services, `getServiceRegistryTarget()` creates stable registry targets like:
|
||||
|
||||
```text
|
||||
<cloudly-host>/workloads/<service-name>-<service-id>:<tag>
|
||||
<cloudly-host>/workloads/<service-name>-<service-id-prefix>:<tag>
|
||||
```
|
||||
|
||||
Registry push hooks record tag/digest metadata on the linked image and service. Unless `deployOnPush` is explicitly `false`, a successful push updates the service image version and asks connected Coreflow clients to reconcile.
|
||||
|
||||
Registry token requests use HTTP Basic credentials against Cloudly users. User passwords and unexpired user tokens are accepted; push/delete scopes require an admin user or a token with the `admin` assigned role.
|
||||
|
||||
## BaseOS and CoreBuild
|
||||
|
||||
Cloudly can manage BaseOS nodes and image builds:
|
||||
@@ -191,6 +216,8 @@ Cloudly can manage BaseOS nodes and image builds:
|
||||
- A configured `baseosJoinToken` accepts generic device enrollment.
|
||||
- BaseOS image builds create one-time provisioning tokens that are embedded in generated images.
|
||||
- Cloudly selects a CoreBuild worker based on `/corebuild/v1/capabilities` and sends the build to `/corebuild/v1/jobs/baseos-image`.
|
||||
- Supported build kinds are `ubuntu-iso` and `balena-raw`; Raspberry Pi builds use `balena-raw`.
|
||||
- Supported architecture values are `amd64`, `arm64`, and `rpi`.
|
||||
- Completed artifacts are stored in the configured S3 bucket and served through short-lived `/baseos/v1/images/:buildId/download` URLs.
|
||||
|
||||
CoreBuild worker configuration can use `corebuildWorkersJson` for multiple workers or the legacy `corebuildWorkerUrl` and `corebuildWorkerToken` settings for one worker.
|
||||
@@ -207,6 +234,27 @@ The backup path includes:
|
||||
- Optional archive replication through `prepareBackupReplication`, `uploadBackupArchiveObject`, `completeBackupReplication`, `getBackupArchiveManifest`, and `downloadBackupArchiveObject`.
|
||||
- Optional scheduled `backup-all-services` task when `CLOUDLY_BACKUP_CRON` is set.
|
||||
|
||||
Manual `createServiceBackup` requests expect Coreflow to complete remote archive replication. Cloudly validates archive object size and SHA-256 checksums, writes a manifest, records target metadata, and marks completed backups as `replicated`. Restores read the manifest and objects back through the configured target writer.
|
||||
|
||||
## Task Automation
|
||||
|
||||
Cloudly registers a TaskBuffer-backed task manager. The API and dashboard can list tasks, trigger tasks manually, inspect execution logs/metrics, and request cancellation for running tasks.
|
||||
|
||||
Predefined tasks currently include:
|
||||
|
||||
| Task | Purpose |
|
||||
| --- | --- |
|
||||
| `cloudflare-domain-sync` | Imports and updates domains from configured Cloudflare zones. |
|
||||
| `dns-sync` | Iterates DNS entries marked as external; provider sync is currently a placeholder. |
|
||||
| `cert-renewal` | Checks activated domains for certificate renewal; renewal logic is currently a placeholder. |
|
||||
| `cleanup` | Removes old task executions and contains placeholders for log/image cleanup. |
|
||||
| `health-check` | Iterates deployments and records health metrics; runtime health checks are currently placeholders. |
|
||||
| `resource-report` | Generates node resource metrics; values are currently placeholders until runtime metrics are wired in. |
|
||||
| `db-maintenance` | Maintenance shell for database optimization tasks. |
|
||||
| `security-scan` | Security scan shell for exposed ports, image freshness, and weak configuration checks. |
|
||||
| `docker-cleanup` | Docker cleanup shell for containers, images, volumes, and networks. |
|
||||
| `backup-all-services` | Registered by the backup manager and enabled only when `CLOUDLY_BACKUP_CRON` is set. |
|
||||
|
||||
## External Gateway Integration
|
||||
|
||||
Cloudly can integrate with a dcrouter gateway when the gateway URL and API token are present in settings. The current integration syncs externally available domains into Cloudly and passes an external gateway route configuration to Coreflow. Coreflow can then ask dcrouter for certificates and synchronize public routes while still routing to cluster-local Coretraffic.
|
||||
@@ -238,7 +286,7 @@ Important paths:
|
||||
|
||||
## Accuracy Notes
|
||||
|
||||
The package metadata and settings schema include fields for several cloud providers. The code paths currently exercised in this repository are Cloudflare for ACME DNS-01, Hetzner for selected node/bare-metal provisioning paths, S3-compatible storage, MongoDB/SmartData, CoreBuild, Coreflow, Corestore, and optional dcrouter integration. Verify provider-specific behavior in the relevant manager before relying on it operationally.
|
||||
The package metadata and settings schema include fields for several cloud providers. The code paths currently exercised in this repository are Cloudflare for ACME DNS-01 and domain sync, Hetzner for selected node/bare-metal provisioning paths, S3-compatible storage, SMB/S3 backup archive targets, MongoDB/SmartData, CoreBuild, Coreflow, Corestore, and optional dcrouter integration. Several provider connection tests and predefined tasks are configuration checks or implementation shells; verify provider-specific behavior in the relevant manager before relying on it operationally.
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
|
||||
Reference in New Issue
Block a user