feat(scloud): a74cd045bb27e8c493af0760e380db34651236b8

serverpod_cloud · serverpod_cloud · commit 86359f29db25 · 2026-04-21T14:20:25.000Z
diff --git a/serverpod_cloud_cli/lib/commands/deploy/deploy.dart b/serverpod_cloud_cli/lib/commands/deploy/deploy.dart
@@ -15,6 +15,7 @@ import 'package:serverpod_cloud_cli/project_zipper/project_zipper_exceptions.dar
 import 'package:serverpod_cloud_cli/shared/exceptions/exit_exceptions.dart';
 import 'package:serverpod_cloud_cli/util/dart_version_util.dart'
     show ProjectDartVersionHint;
+import 'package:serverpod_cloud_cli/util/deploy_multi_instance_serverpod_warning.dart';
 import 'package:serverpod_cloud_cli/util/pubspec_validator.dart'
     show TenantProjectPubspec;
 import 'package:serverpod_cloud_cli/util/scloud_config/scloud_config_io.dart';
@@ -83,6 +84,13 @@ abstract class Deploy {
     late final String uploadDescription;
 
     if (!dryRun) {
+      await warnIfLegacyServerpodWithMultipleInstances(
+        cloudApiClient: cloudApiClient,
+        projectId: projectId,
+        logger: logger,
+        serverpodVersionConstraint: pubspecValidator.serverpodVersion,
+      );
+
       final serverpodVersion = pubspecValidator.serverpodVersion;
 
       await logger.progress('Retrieving upload description...', () async {
diff --git a/serverpod_cloud_cli/lib/constants.dart b/serverpod_cloud_cli/lib/constants.dart
@@ -17,6 +17,10 @@ abstract final class VersionConstants {
   /// The constraint for which Serverpod versions are supported for tenant
   /// projects in Serverpod Cloud.
   static const supportedServerpodConstraint = '>=$minSupportedServerpodVersion';
+
+  /// Minimum Serverpod version recommended when deploying with more than one
+  /// server instance (scaling / rolling deploy behavior).
+  static const serverpodMultiInstanceSafeMinVersion = '3.3.0';
 }
 
 abstract final class ProjectConfigFileConstants {
diff --git a/serverpod_cloud_cli/lib/util/deploy_multi_instance_serverpod_warning.dart b/serverpod_cloud_cli/lib/util/deploy_multi_instance_serverpod_warning.dart
@@ -0,0 +1,67 @@
+import 'package:ground_control_client/ground_control_client.dart'
+    show Client, ComputeInfo;
+import 'package:pub_semver/pub_semver.dart';
+import 'package:serverpod_cloud_cli/command_logger/command_logger.dart';
+import 'package:serverpod_cloud_cli/constants.dart' show VersionConstants;
+
+/// True when the pubspec's Serverpod constraint does not allow any
+/// [VersionConstants.serverpodMultiInstanceSafeMinVersion] or newer release.
+bool serverpodConstraintPrecludesMultiInstanceSafeRelease(
+  final String? serverpodVersionConstraint,
+) {
+  if (serverpodVersionConstraint == null) {
+    return false;
+  }
+  try {
+    final projectConstraint = VersionConstraint.parse(
+      serverpodVersionConstraint,
+    );
+    final fromSafe = VersionConstraint.parse(
+      '>=${VersionConstants.serverpodMultiInstanceSafeMinVersion}',
+    );
+    return !projectConstraint.allowsAny(fromSafe);
+  } on FormatException {
+    return false;
+  }
+}
+
+/// True when compute is configured for more than one running instance
+/// at minimum or maximum scale.
+bool computeUsesMoreThanOneInstance(final ComputeInfo compute) =>
+    compute.minInstances > 1 || compute.maxInstances > 1;
+
+/// When the project cannot resolve to Serverpod
+/// [VersionConstants.serverpodMultiInstanceSafeMinVersion]+ and the capsule
+/// is scaled beyond a single instance, logs a warning. Failures reading
+/// compute are ignored (debug log only).
+Future<void> warnIfLegacyServerpodWithMultipleInstances({
+  required final Client cloudApiClient,
+  required final String projectId,
+  required final CommandLogger logger,
+  required final String? serverpodVersionConstraint,
+}) async {
+  if (!serverpodConstraintPrecludesMultiInstanceSafeRelease(
+    serverpodVersionConstraint,
+  )) {
+    return;
+  }
+  try {
+    final compute = await cloudApiClient.compute.readCompute(
+      cloudCapsuleId: projectId,
+    );
+    if (!computeUsesMoreThanOneInstance(compute)) {
+      return;
+    }
+    logger.warning(
+      'Multiple server instances are enabled, but your Serverpod constraint does not allow it. '
+      'Upgrade to Serverpod ${VersionConstants.serverpodMultiInstanceSafeMinVersion} '
+      'or later to reduce the risk of disruption during scaling and deployment.',
+      newParagraph: true,
+    );
+  } on Exception catch (e) {
+    logger.debug(
+      'Could not read compute configuration for legacy Serverpod scaling '
+      'warning: $e',
+    );
+  }
+}
diff --git a/serverpod_cloud_cli/test/deploy_multi_instance_serverpod_warning_test.dart b/serverpod_cloud_cli/test/deploy_multi_instance_serverpod_warning_test.dart
@@ -0,0 +1,77 @@
+import 'package:ground_control_client/ground_control_client.dart';
+import 'package:serverpod_cloud_cli/util/deploy_multi_instance_serverpod_warning.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('serverpodConstraintPrecludesMultiInstanceSafeRelease', () {
+    test('Given ^3.2.0 when evaluated then returns false', () {
+      expect(
+        serverpodConstraintPrecludesMultiInstanceSafeRelease('^3.2.0'),
+        isFalse,
+      );
+    });
+
+    test('Given 3.3.0 when evaluated then returns false', () {
+      expect(
+        serverpodConstraintPrecludesMultiInstanceSafeRelease('3.3.0'),
+        isFalse,
+      );
+    });
+
+    test('Given >=3.2.0 <3.3.0 when evaluated then returns true', () {
+      expect(
+        serverpodConstraintPrecludesMultiInstanceSafeRelease('>=3.2.0 <3.3.0'),
+        isTrue,
+      );
+    });
+
+    test('Given ^3.3.0 when evaluated then returns false', () {
+      expect(
+        serverpodConstraintPrecludesMultiInstanceSafeRelease('^3.3.0'),
+        isFalse,
+      );
+    });
+
+    test('Given null when evaluated then returns false', () {
+      expect(
+        serverpodConstraintPrecludesMultiInstanceSafeRelease(null),
+        isFalse,
+      );
+    });
+  });
+
+  group('computeUsesMoreThanOneInstance', () {
+    test('Given min 1 max 1 when evaluated then returns false', () {
+      final info = ComputeInfo(
+        cloudCapsuleId: 'c1',
+        size: ComputeSizeOption.small,
+        minInstances: 1,
+        maxInstances: 1,
+        memoryMb: 512,
+      );
+      expect(computeUsesMoreThanOneInstance(info), isFalse);
+    });
+
+    test('Given min 1 max 2 when evaluated then returns true', () {
+      final info = ComputeInfo(
+        cloudCapsuleId: 'c1',
+        size: ComputeSizeOption.small,
+        minInstances: 1,
+        maxInstances: 2,
+        memoryMb: 512,
+      );
+      expect(computeUsesMoreThanOneInstance(info), isTrue);
+    });
+
+    test('Given min 2 max 2 when evaluated then returns true', () {
+      final info = ComputeInfo(
+        cloudCapsuleId: 'c1',
+        size: ComputeSizeOption.small,
+        minInstances: 2,
+        maxInstances: 2,
+        memoryMb: 512,
+      );
+      expect(computeUsesMoreThanOneInstance(info), isTrue);
+    });
+  });
+}
diff --git a/serverpod_cloud_cli/test_integration/commands/deploy_command_test.dart b/serverpod_cloud_cli/test_integration/commands/deploy_command_test.dart
@@ -42,10 +42,21 @@ void main() {
       fileUploaderFactory: (final _) => mockFileUploader,
     ),
   );
+  var readComputeMaxInstancesForTest = 1;
+  ComputeInfo buildReadComputeAnswer() => ComputeInfoBuilder()
+      .withMaxInstances(readComputeMaxInstancesForTest)
+      .build();
 
   setUp(() {
     mockFileUploader.init();
     logger.clear();
+    readComputeMaxInstancesForTest = 1;
+    reset(client.compute);
+    when(
+      () => client.compute.readCompute(
+        cloudCapsuleId: any(named: 'cloudCapsuleId'),
+      ),
+    ).thenAnswer((final _) async => buildReadComputeAnswer());
   });
 
   test('Given deploy command when instantiated then requires login', () {
@@ -141,6 +152,111 @@ project:
       },
     );
 
+    group(
+      'and legacy Serverpod constraint with multi-instance compute when deploying',
+      () {
+        late String testProjectDir;
+
+        setUp(() async {
+          await d.dir(ProjectFactory.defaultDirectoryName, [
+            d.file('pubspec.yaml', '''
+name: ${ProjectFactory.defaultPackageName}
+environment:
+  sdk: ${ProjectFactory.validSdkVersion}
+dependencies:
+  serverpod: ">=3.2.0 <3.3.0"
+'''),
+            d.file('scloud.yaml', '''
+project:
+  projectId: "${BucketUploadDescription.projectId}"
+  dartSdk: "${VersionConstants.minSupportedSdkVersion}"
+'''),
+          ]).create();
+          testProjectDir = p.join(
+            d.sandbox,
+            ProjectFactory.defaultDirectoryName,
+          );
+
+          when(
+            () => client.deploy.createUploadDescription(
+              any(),
+              serverpodVersion: any(named: 'serverpodVersion'),
+              dartVersion: any(named: 'dartVersion'),
+            ),
+          ).thenAnswer(
+            (final _) async => BucketUploadDescription.uploadDescription,
+          );
+          readComputeMaxInstancesForTest = 2;
+        });
+
+        test('then logs multi-instance scaling warning', () async {
+          await cli.run([
+            'deploy',
+            '--project',
+            BucketUploadDescription.projectId,
+            '--project-dir',
+            testProjectDir,
+          ]);
+
+          expect(logger.warningCalls, isNotEmpty);
+          expect(
+            logger.warningCalls.first.message,
+            contains(VersionConstants.serverpodMultiInstanceSafeMinVersion),
+          );
+        });
+      },
+    );
+
+    group(
+      'and Serverpod ^3.3.0 with multi-instance compute when deploying',
+      () {
+        late String testProjectDir;
+
+        setUp(() async {
+          await d.dir(ProjectFactory.defaultDirectoryName, [
+            d.file('pubspec.yaml', '''
+name: ${ProjectFactory.defaultPackageName}
+environment:
+  sdk: ${ProjectFactory.validSdkVersion}
+dependencies:
+  serverpod: "^3.3.0"
+'''),
+            d.file('scloud.yaml', '''
+project:
+  projectId: "${BucketUploadDescription.projectId}"
+  dartSdk: "${VersionConstants.minSupportedSdkVersion}"
+'''),
+          ]).create();
+          testProjectDir = p.join(
+            d.sandbox,
+            ProjectFactory.defaultDirectoryName,
+          );
+
+          when(
+            () => client.deploy.createUploadDescription(
+              any(),
+              serverpodVersion: any(named: 'serverpodVersion'),
+              dartVersion: any(named: 'dartVersion'),
+            ),
+          ).thenAnswer(
+            (final _) async => BucketUploadDescription.uploadDescription,
+          );
+          readComputeMaxInstancesForTest = 2;
+        });
+
+        test('then logs no warning', () async {
+          await cli.run([
+            'deploy',
+            '--project',
+            BucketUploadDescription.projectId,
+            '--project-dir',
+            testProjectDir,
+          ]);
+          expect(logger.warningCalls, isEmpty);
+        });
+      },
+    );
+
     group('and invalid output option value when running deploy command', () {
       late Future cliCommandFuture;
       setUp(() async {
diff --git a/serverpod_cloud_cli/test_integration/commands/launch_command_test.dart b/serverpod_cloud_cli/test_integration/commands/launch_command_test.dart
@@ -61,6 +61,14 @@ void main() {
   setUp(() {
     mockFileUploader.init();
     logger.clear();
+    reset(client.compute);
+    when(
+      () => client.compute.readCompute(
+        cloudCapsuleId: any(named: 'cloudCapsuleId'),
+      ),
+    ).thenAnswer(
+      (final _) async => ComputeInfoBuilder().withMaxInstances(1).build(),
+    );
   });
 
   tearDown(() {
diff --git a/serverpod_cloud_cli/test_integration/commands/project_command/link_command_test.dart b/serverpod_cloud_cli/test_integration/commands/project_command/link_command_test.dart
@@ -347,17 +347,20 @@ project:
           await expectLater(commandResult, completes);
         });
 
-        test('then scloud.yaml contains dartSdk from .tool-versions', () async {
-          await commandResult;
+        test(
+          'then scloud.yaml omits dartSdk when only .tool-versions is present',
+          () async {
+            await commandResult;
 
-          final resolved = resolveProjectDartSdkVersion(
-            Directory(testProjectDir),
-          );
-          final expected = d.dir(testProjectDir, [
-            d.file('scloud.yaml', contains('dartSdk: "$resolved"')),
-          ]);
-          await expectLater(expected.validate(), completes);
-        });
+            final resolved = resolveProjectDartSdkVersion(
+              Directory(testProjectDir),
+            );
+            final expected = d.dir(testProjectDir, [
+              d.file('scloud.yaml', contains('dartSdk: "$resolved"')),
+            ]);
+            await expectLater(expected.validate(), completes);
+          },
+        );
       });
 
       group('and .tool-versions file with dart entry when executing link '
