From 8e2f68b7a893a4ccba4516ed3a1cd2f2395025b2 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Tue, 19 May 2026 20:50:46 +0200 Subject: [PATCH 1/3] Add a v4 upgrade guide --- README.md | 1 + docs/README.md | 1 + docs/guides/upgrading-to-v4.md | 194 +++++++++++++++++++++++++++++++++ 3 files changed, 196 insertions(+) create mode 100644 docs/guides/upgrading-to-v4.md diff --git a/README.md b/README.md index 1a4c050f0..734a2de1a 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,7 @@ This repository contains the following differences with the original Serverless ## Learn More +- [Upgrading to v4](./docs/guides/upgrading-to-v4.md) - [Configuration Validation](./docs/guides/configuration-validation.md) - [Resolution of Environment Variables](./docs/guides/environment-variables.md) - [Deprecations](./docs/guides/deprecations.md) diff --git a/docs/README.md b/docs/README.md index 4f237919b..98b6f9bca 100644 --- a/docs/README.md +++ b/docs/README.md @@ -73,6 +73,7 @@ ## Learn More +- [Upgrading to v4](./guides/upgrading-to-v4.md) - [Configuration Validation](./guides/configuration-validation.md) - [Resolution of Environment Variables](./guides/environment-variables.md) - [Deprecations](./guides/deprecations.md) diff --git a/docs/guides/upgrading-to-v4.md b/docs/guides/upgrading-to-v4.md new file mode 100644 index 000000000..0610d2798 --- /dev/null +++ b/docs/guides/upgrading-to-v4.md @@ -0,0 +1,194 @@ +# Upgrading from osls v3 to v4 + +osls 4.x is a major release focused on **modernizing the CLI**: a leaner dependency tree, AWS SDK for JavaScript v3 across the board, and stricter configuration validation. + +This guide covers what's new, how to install 4.x, and the breaking changes to plan for when you upgrade from 3.x. + +## What's in osls v4 + +- **AWS SDK v3**: osls uses the AWS SDK under the hood to interact with AWS. v4 upgrades from the deprecated AWS SDK v2 to v3. +- **IAM Identity Center (AWS SSO) support**: Thanks to the upgrade to the AWS SDK v3, the `osls` CLI now supports AWS IAM Identity Center (formerly AWS SSO) credentials. +- **Leaner dependencies**: the AWS SDK is upgraded and multiple dependencies are removed to minimize supply chain risks. + +Several 3.x options and commands were deprecated for a long time; 4.x removes them in favor of these foundations. The [breaking changes](#breaking-changes) section is your migration checklist. + +## osls vs Serverless Framework + +This guide is for upgrading the **`osls`** CLI (`npm install osls`), not [Serverless Framework](https://github.com/serverless/serverless). Both projects use "v3" and "v4" version numbers, but they are **different projects**. + +**History (osls 3.x):** osls 3.x began as a fork of Serverless Framework v3. The repo was `oss-serverless/serverless` on GitHub and `osls` in npm. For clarity, the GitHub repo has been renamed to `oss-serverless/osls` to match. + +**osls 4.x:** Continues the osls 3.x line with its own roadmap and improvements. It is unrelated to Serverless Framework v4. + +If you are coming from Serverless Framework v3, you can upgrade to osls 4.x directly since osls 3.x was based on Serverless Framework v3. + +## Install osls 4.x + +osls is distributed on npm only (there is no standalone binary). + +```bash +npm install -g osls@4 +``` + +Verify the installed version: + +```bash +serverless --version +``` + +### Removed CLI commands + +These commands were deprecated (and broken) in 3.x and are removed in 4.x: + +| Removed command | Replacement | +|-----------------|----------------------------------------------------| +| `sls upgrade` | `npm install -g osls@4` (or the dist-tag you need) | +| `sls uninstall` | `npm uninstall -g osls` | + +## Breaking changes + +### Configuration validation defaults to `error` + +In 4.x, invalid `serverless.yml` configuration **fails the command by default** (`configValidationMode: error`). In older 3.x setups that never set this property, invalid configuration often surfaced only as warnings. + +If you need the previous behavior while migrating: + +```yaml +configValidationMode: warn +``` + +See [Configuration validation](./configuration-validation.md). + +### IAM settings must use `provider.iam` + +Top-level provider IAM properties were deprecated in 3.x and are **removed** in 4.x. Move them under `provider.iam`: + +| 3.x (removed) | 4.x | +|------------------------------------|-----------------------------------------| +| `provider.role` | `provider.iam.role` | +| `provider.rolePermissionsBoundary` | `provider.iam.role.permissionsBoundary` | +| `provider.iamRoleStatements` | `provider.iam.role.statements` | +| `provider.iamManagedPolicies` | `provider.iam.role.managedPolicies` | +| `provider.cfnRole` | `provider.iam.deploymentRole` | + +`provider.iam.role.permissionsBoundary` is also accepted (CloudFormation naming). + +See the [IAM guide](./iam.md). + +### Packaging: use `package.patterns` instead of `include` / `exclude` + +`package.include` and `package.exclude` are no longer accepted. Use `package.patterns` instead. Prefix patterns with `!` to exclude. + +**Before (3.x):** + +```yaml +package: + include: + - src/** + exclude: + - node_modules/** +``` + +**After (4.x):** + +```yaml +package: + patterns: + - src/** + - '!node_modules/**' +``` + +The same applies to function- and layer-level `package` blocks. See [Packaging](./packaging.md#patterns). + +### `variablesResolutionMode: 20210219` is rejected + +The legacy variables resolver mode is no longer supported. Remove `variablesResolutionMode` from your configuration. + +If you still have `variablesResolutionMode: 20210326`, it is accepted as a no-op in 4.x but deprecated, remove it when convenient. + +See [Variables](./variables.md) and [Deprecations](./deprecations.md). + +### Serverless Console configuration is rejected + +The `console` property in `serverless.yml` (legacy Serverless Dashboard configuration) is no longer accepted. You can safely remove it as `osls` is not compatible with Serverless Console or Dashboard. + +### `provider.lambdaHashingVersion` removed + +The `provider.lambdaHashingVersion` property and the old `20200924` hashing algorithm are removed. osls 4.x always uses the current default hashing algorithm. + +Remove `provider.lambdaHashingVersion` from your configuration. If you relied on the old algorithm, expect Lambda version identifiers to change on the next deployment (functions will be updated, not necessarily replaced). + +### EventBridge: native CloudFormation only + +The legacy EventBridge custom-resource implementation and `provider.eventBridge.useCloudFormation` are removed. EventBridge events are always provisioned with native CloudFormation resources. + +Remove `provider.eventBridge.useCloudFormation` from your configuration. + +If you previously relied on the legacy custom-resource path, migrate by: + +1. Removing (or commenting out) EventBridge event definitions. +2. Running `sls deploy` to remove the old resources. +3. Restoring the EventBridge events and deploying again. + +See [EventBridge](../events/event-bridge.md). + +### Alexa Skill events require an application ID + +The bare `alexaSkill` event form without an `appId` is no longer supported. Use one of: + +```yaml +events: + - alexaSkill: amzn1.ask.skill.xx-xx-xx-xx +``` + +```yaml +events: + - alexaSkill: + appId: amzn1.ask.skill.xx-xx-xx-xx +``` + +See [Alexa Skill](../events/alexa-skill.md). + +### Plugin custom variables: `configurationVariablesSources` only + +Plugins that extend variable resolution via the old `variableResolvers` API will fail with `OLD_VARIABLE_RESOLVER_NOT_SUPPORTED`. Migrate to `configurationVariablesSources`. + +See [Custom variables](./plugins/custom-variables.md). + +### Plugin CLI options must declare a `type` + +Plugin command options must define `type` as `string`, `boolean`, or `multiple`. Options without a `type` cause `INVALID_CLI_OPTIONS_SCHEMA`. + +See [Custom commands](./plugins/custom-commands.md#command-options). + +### AWS SDK v2 removed from osls + +osls no longer bundles AWS SDK for JavaScript v2. All built-in AWS calls use **AWS SDK v3** (`@aws-sdk/client-*` packages). + +For most users this is transparent. **Plugin authors** that imported `aws-sdk` from osls internals or assumed v2 behavior must migrate their plugins to AWS SDK v3. + +### Internal AWS client changes (plugin authors) + +If your plugin uses osls AWS client helpers, verify behavior against 4.x: request/response shapes follow SDK v3 conventions (for example command input objects and async clients). + +## Still deprecated in 4.x (removed in 5.0.0) + +These items still work in 4.x but emit deprecation warnings. Clean them up when you can: + +| Item | Action | +|--------------------------------------|-------------------------------------------------------------------------| +| `projectDir` | Remove, ignored | +| `variablesResolutionMode: 20210326` | Remove, no-op | +| `provider.websocket.useProviderTags` | Remove, provider tags are applied by default | +| `provider.httpApi.useProviderTags` | Remove, provider tags are applied by default | +| Kinesis consumer naming | Set `provider.kinesis.consumerNamingMode: serviceSpecific` before 5.0.0 | + +See [Deprecations](./deprecations.md). + +## Getting help + +- [Deprecations](./deprecations.md) +- [Configuration validation](./configuration-validation.md) +- [GitHub issues](https://github.com/oss-serverless/osls/issues/new) + +If something in this guide is unclear or missing, open a GitHub pull request, contributions are welcome. From 5afb0228ca691bef2bf493024695e7aa8bd12931 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Tue, 19 May 2026 23:24:50 +0200 Subject: [PATCH 2/3] Improve upgrade guide intro --- docs/guides/upgrading-to-v4.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/guides/upgrading-to-v4.md b/docs/guides/upgrading-to-v4.md index 0610d2798..5ee59111c 100644 --- a/docs/guides/upgrading-to-v4.md +++ b/docs/guides/upgrading-to-v4.md @@ -1,16 +1,9 @@ # Upgrading from osls v3 to v4 -osls 4.x is a major release focused on **modernizing the CLI**: a leaner dependency tree, AWS SDK for JavaScript v3 across the board, and stricter configuration validation. +osls v4 is a major release focused on internal upgrades and cleanup: -This guide covers what's new, how to install 4.x, and the breaking changes to plan for when you upgrade from 3.x. - -## What's in osls v4 - -- **AWS SDK v3**: osls uses the AWS SDK under the hood to interact with AWS. v4 upgrades from the deprecated AWS SDK v2 to v3. -- **IAM Identity Center (AWS SSO) support**: Thanks to the upgrade to the AWS SDK v3, the `osls` CLI now supports AWS IAM Identity Center (formerly AWS SSO) credentials. -- **Leaner dependencies**: the AWS SDK is upgraded and multiple dependencies are removed to minimize supply chain risks. - -Several 3.x options and commands were deprecated for a long time; 4.x removes them in favor of these foundations. The [breaking changes](#breaking-changes) section is your migration checklist. +- **AWS SDK v3**: osls uses the AWS SDK under the hood to interact with AWS. osls v4 upgrades from the deprecated AWS SDK v2 to v3. +- **IAM Identity Center (AWS SSO) support**: Thanks to the upgrade to the AWS SDK v3, the `osls` CLI now supports AWS IAM Identity Center (aka SSO) credentials. ## osls vs Serverless Framework @@ -24,15 +17,14 @@ If you are coming from Serverless Framework v3, you can upgrade to osls 4.x dire ## Install osls 4.x -osls is distributed on npm only (there is no standalone binary). - ```bash npm install -g osls@4 ``` -Verify the installed version: +If you are migrating from Serverless Framework, you can either use the `osls` command explicitly or use osls as a stand-in for `serverless`: ```bash +npm remove -g serverless serverless --version ``` From 3dc12f518a7d71676b4f356b5885f9cf8e9c54da Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Tue, 19 May 2026 23:26:13 +0200 Subject: [PATCH 3/3] Fix linting --- docs/guides/upgrading-to-v4.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/upgrading-to-v4.md b/docs/guides/upgrading-to-v4.md index 5ee59111c..b3cb43391 100644 --- a/docs/guides/upgrading-to-v4.md +++ b/docs/guides/upgrading-to-v4.md @@ -33,7 +33,7 @@ serverless --version These commands were deprecated (and broken) in 3.x and are removed in 4.x: | Removed command | Replacement | -|-----------------|----------------------------------------------------| +| --------------- | -------------------------------------------------- | | `sls upgrade` | `npm install -g osls@4` (or the dist-tag you need) | | `sls uninstall` | `npm uninstall -g osls` | @@ -56,7 +56,7 @@ See [Configuration validation](./configuration-validation.md). Top-level provider IAM properties were deprecated in 3.x and are **removed** in 4.x. Move them under `provider.iam`: | 3.x (removed) | 4.x | -|------------------------------------|-----------------------------------------| +| ---------------------------------- | --------------------------------------- | | `provider.role` | `provider.iam.role` | | `provider.rolePermissionsBoundary` | `provider.iam.role.permissionsBoundary` | | `provider.iamRoleStatements` | `provider.iam.role.statements` | @@ -168,7 +168,7 @@ If your plugin uses osls AWS client helpers, verify behavior against 4.x: reques These items still work in 4.x but emit deprecation warnings. Clean them up when you can: | Item | Action | -|--------------------------------------|-------------------------------------------------------------------------| +| ------------------------------------ | ----------------------------------------------------------------------- | | `projectDir` | Remove, ignored | | `variablesResolutionMode: 20210326` | Remove, no-op | | `provider.websocket.useProviderTags` | Remove, provider tags are applied by default |