diff --git a/README.md b/README.md index 45768f9fe..2cc34bb82 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Install the 3.x release line explicitly: ```sh npm install -g osls@3 -osls --version +serverless --version ``` If you are replacing a global Serverless Framework installation, remove it first so the `serverless` command resolves to osls: diff --git a/docs/cli-reference/create.md b/docs/cli-reference/create.md index b3ac1fa11..4bb30c5e9 100644 --- a/docs/cli-reference/create.md +++ b/docs/cli-reference/create.md @@ -2,19 +2,21 @@ Creates a new service from a remote or local template. -**Create a service in a new folder from a remote template:** +osls does not include a maintained catalog of built-in template names. Use a local template directory, or a trusted remote Git URL, when creating a service from a template. + +**Create a service in a new folder using a local template:** ```bash serverless create \ - --template-url https://github.com/serverless/examples/tree/v3/... \ + --template-path path/to/my/template/folder \ --path myService ``` -**Create a service in a new folder using a local template:** +**Create a service in a new folder from a remote template:** ```bash serverless create \ - --template-path path/to/my/template/folder \ + --template-url https://github.com///tree// \ --path myService ``` @@ -23,7 +25,7 @@ serverless create \ - `--template-url` or `-u` A remotely hosted template URL. Supports plain Git URLs plus GitHub, GitHub Enterprise, GitLab, Bitbucket, and Bitbucket Server. **Required if --template-path is not present**. - `--template-path` The local path of your template. **Required if --template-url is not present**. - `--path` or `-p` The path where the service should be created. -- `--name` or `-n` The name of the service in `serverless.yml`. If `--path` is omitted, Serverless also uses this as the target directory name. +- `--name` or `-n` The name of the service in `serverless.yml`. If `--path` is omitted, osls also uses this as the target directory name. ## Provided lifecycle events @@ -31,28 +33,28 @@ serverless create \ ## Examples -### Creating a named service in a new directory from a remote template +### Creating a named service in a new directory using a local template ```bash serverless create \ - --template-url https://github.com/serverless/examples/tree/v3/... \ + --template-path path/to/my/template/folder \ --path my-new-service \ --name my-new-service ``` -This example will download the template into the `my-new-service` directory. This directory will be created if not present. osls will not overwrite an existing target directory when `--path` is used. +This example will copy the template into the `my-new-service` directory. This directory will be created if not present. osls will not overwrite an existing target directory when `--path` is used. Additionally osls will rename the service according to the name you provide. If `--path` is omitted, osls uses `--name` as the target directory. If `--name` is omitted, the service name defaults to the target directory's final path segment. -### Creating a new service using a local template +### Creating a named service in a new directory from a remote template ```bash serverless create \ - --template-path path/to/my/template/folder \ - --path path/to/my/service \ + --template-url https://github.com///tree// \ + --path my-new-service \ --name my-new-service ``` -This will copy the `path/to/my/template/folder` folder into `path/to/my/service`. If `--name` is provided, the copied template's service name will be renamed to `my-new-service`. If `--name` is omitted, the service name defaults to the target directory's final path segment. +This will download the template into the `my-new-service` directory. If `--name` is provided, the copied template's service name will be renamed to `my-new-service`. If `--name` is omitted, the service name defaults to the target directory's final path segment. -If neither `--path` nor `--name` is provided, osls will create a new directory named after the local template folder and preserve the template's existing service name. +When using a local template, if neither `--path` nor `--name` is provided, osls will create a new directory named after the local template folder and preserve the template's existing service name. diff --git a/docs/cli-reference/deploy-function.md b/docs/cli-reference/deploy-function.md index 5244afc30..01a55c8fe 100644 --- a/docs/cli-reference/deploy-function.md +++ b/docs/cli-reference/deploy-function.md @@ -1,6 +1,6 @@ # AWS - Deploy Function -The `sls deploy function` command deploys an individual function without AWS CloudFormation. This command simply swaps out the zip file that your CloudFormation stack is pointing toward. This is a much faster way of deploying changes in code. +The `serverless deploy function` command deploys an individual function without AWS CloudFormation. This command simply swaps out the zip file that your CloudFormation stack is pointing toward. This is a much faster way of deploying changes in code. ```bash serverless deploy function -f functionName diff --git a/docs/cli-reference/deploy-list.md b/docs/cli-reference/deploy-list.md index 1b747bd4d..d1a596f81 100644 --- a/docs/cli-reference/deploy-list.md +++ b/docs/cli-reference/deploy-list.md @@ -1,6 +1,6 @@ # AWS - Deploy List -The `sls deploy list [functions]` command will list information about your deployments. +The `serverless deploy list [functions]` command will list information about your deployments. You can either see all available deployments in your S3 deployment bucket by running `serverless deploy list` or you can see the deployed functions by running `serverless deploy list functions`. diff --git a/docs/cli-reference/deploy.md b/docs/cli-reference/deploy.md index 454f5c693..9f0acf28a 100644 --- a/docs/cli-reference/deploy.md +++ b/docs/cli-reference/deploy.md @@ -1,6 +1,6 @@ # AWS - deploy -The `sls deploy` command deploys your entire service via CloudFormation. Run this command when you have made infrastructure changes (i.e., you edited `serverless.yml`). Use `serverless deploy function -f myFunction` when you have made code changes and you want to quickly upload your updated code to AWS Lambda or just change function configuration. +The `serverless deploy` command deploys your entire service via CloudFormation. Run this command when you have made infrastructure changes (i.e., you edited `serverless.yml`). Use `serverless deploy function -f myFunction` when you have made code changes and you want to quickly upload your updated code to AWS Lambda or just change function configuration. ```bash serverless deploy diff --git a/docs/cli-reference/package.md b/docs/cli-reference/package.md index f281f4610..9177fdf29 100644 --- a/docs/cli-reference/package.md +++ b/docs/cli-reference/package.md @@ -1,6 +1,6 @@ # AWS - package -The `sls package` command packages your entire infrastructure into the `.serverless` directory by default and make it ready for deployment. You can specify another packaging directory by passing the `--package` option. +The `serverless package` command packages your entire infrastructure into the `.serverless` directory by default and make it ready for deployment. You can specify another packaging directory by passing the `--package` option. ```bash serverless package diff --git a/docs/cli-reference/print.md b/docs/cli-reference/print.md index 966ab575a..9a124737f 100644 --- a/docs/cli-reference/print.md +++ b/docs/cli-reference/print.md @@ -44,10 +44,10 @@ resources: BucketName: ${self:custom.bucketName} ``` -Using `sls print` will resolve the variables in `provider.stage` and `BucketName`. +Using `serverless print` will resolve the variables in `provider.stage` and `BucketName`. ```bash -$ sls print +$ serverless print service: my-service custom: bucketName: test @@ -69,11 +69,11 @@ resources: This prints the provider name: ```bash -sls print --path provider.name --format text +serverless print --path provider.name --format text ``` And this prints all function names: ```bash -sls print --path functions --transform keys --format text +serverless print --path functions --transform keys --format text ``` diff --git a/docs/cli-reference/remove.md b/docs/cli-reference/remove.md index ad4b15e92..7f1cc4e78 100644 --- a/docs/cli-reference/remove.md +++ b/docs/cli-reference/remove.md @@ -1,6 +1,6 @@ # AWS - Remove -The `sls remove` command will remove the deployed service, defined in your current working directory, from the provider. +The `serverless remove` command will remove the deployed service, defined in your current working directory, from the provider. ```bash serverless remove diff --git a/docs/events/apigateway.md b/docs/events/apigateway.md index a6429b501..dd6b0a14f 100644 --- a/docs/events/apigateway.md +++ b/docs/events/apigateway.md @@ -1839,7 +1839,7 @@ The log streams will be generated in a dedicated log group which follows the nam To be able to write logs, API Gateway [needs a CloudWatch role configured](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html). This setting is per region, shared by all the APIs. There are three approaches for handling it: -- Let osls create and assign an IAM role for you (default behavior). Note that since this is a shared setting, this role is not removed when you remove the deployment. +- Let serverless create and assign an IAM role for you (default behavior). Note that since this is a shared setting, this role is not removed when you remove the deployment. - Let osls assign an existing IAM role that you created before the deployment, if not already assigned: ```yml diff --git a/docs/getting-started.md b/docs/getting-started.md index 6ba73b15d..8529fa345 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -12,61 +12,86 @@ npm install -g osls _Requires Node.js `^20.19.0 || ^22.13.0 || >=24`. If you don’t already have a supported Node.js version on your machine, [install it first](https://nodejs.org/)._ +The package installs the `osls`, `sls`, and `serverless` commands. This guide uses `serverless` because osls 3.x is intended as a drop-in replacement for Serverless Framework v3. + +## Configure AWS Credentials + +Before deploying, configure AWS credentials for the AWS account and region you want to use. See the [AWS credentials guide](./guides/credentials.md) for supported options. + ## Creating A Service -To create your first project (known as a service), run the `serverless` command below, then follow the prompts. +A project is known as a service. Create a new service directory: ```bash -# Create a new serverless project -serverless - -# Move into the newly created directory -cd your-service-name +mkdir osls-hello +cd osls-hello ``` -The `serverless` command will guide you to: +Create `serverless.yml`: -1. Create a new project -2. Configure your [AWS credentials](./guides/credentials.md) +```yaml +service: osls-hello -Your new serverless project will contain a `serverless.yml` file. This file features simple syntax for deploying infrastructure to AWS, such as AWS Lambda functions, infrastructure that triggers those functions with events, and additional infrastructure your AWS Lambda functions may need for various use-cases. You can learn more about this in the [Core Concepts documentation](./guides/intro.md). +provider: + name: aws + runtime: nodejs24.x + region: us-east-1 + stage: dev -If you want to start from an example project, check out the [project examples from Serverless Inc. and our community](https://github.com/serverless/examples). You can install any example by passing a GitHub URL using the `--template-url` option: +functions: + hello: + handler: handler.hello + url: true +``` -```bash -serverless create --template-url=https://github.com/serverless/examples/tree/v3/... +Create `handler.js`: + +```js +'use strict'; + +module.exports.hello = async () => ({ + statusCode: 200, + headers: { + 'Content-Type': 'text/plain', + }, + body: 'Hello from osls!\n', +}); ``` -Please note that you can use `serverless` or `sls` to run osls commands. +The `serverless.yml` file defines your AWS Lambda functions, the events that trigger them, and any additional AWS infrastructure your functions need. This example creates a public [Lambda Function URL](./guides/functions.md#lambda-function-urls). You can learn more in the [Core Concepts documentation](./guides/intro.md). + +osls does not include a maintained catalog of built-in templates. If you want to start from a template, use a trusted remote Git URL or local template directory with the [`create` command](./cli-reference/create.md). ## Deploying -If you haven't done so already within the `serverless` command, you can deploy the project at any time by running: +Deploy the service: ```bash -sls deploy +serverless deploy ``` -The deployed AWS Lambda functions and other essential information such as API Endpoint URLs will be displayed in the command output. +The deployed AWS Lambda functions and other essential information, such as Function URL endpoints, will be displayed in the command output. More details on deploying can be found [here](./guides/deploying.md). -## Developing On The Cloud - -Many osls users choose to develop on the cloud, since it matches reality and emulating Lambda locally can be complex. To develop on the cloud quickly, without sacrificing speed, we recommend the following workflow... +## Invoking Your Function -To deploy code changes quickly, skip the `serverless deploy` command which is much slower since it triggers a full AWS CloudFormation update. Instead, deploy code and configuration changes to individual AWS Lambda functions in seconds via the `deploy function` command, with `-f [function name in serverless.yml]` set to the function you want to deploy. +To retrieve service information, including the Function URL, run: ```bash -sls deploy function -f my-api +serverless info ``` -More details on the `deploy function` command can be found [here](./cli-reference/deploy-function.md). +Open the Function URL from the deploy or info output in a browser, or test it with `curl`: -To invoke your AWS Lambda function on the cloud, you can find URLs for your functions w/ API endpoints in the `serverless deploy` output, or retrieve them via `serverless info`. If your functions do not have API endpoints, you can use the `invoke` command, like this: +```bash +curl https://your-function-url-id.lambda-url.us-east-1.on.aws/ +``` + +If your function does not have an HTTP endpoint, or if you want to invoke it through the AWS Lambda API, use the `invoke` command: ```bash -sls invoke -f hello +serverless invoke -f hello # Invoke and display logs: serverless invoke -f hello --log @@ -74,34 +99,42 @@ serverless invoke -f hello --log More details on the `invoke` command can be found [here](./cli-reference/invoke.md). -## Developing Locally +## Developing On The Cloud + +Many osls users choose to develop on the cloud, since it matches reality and emulating Lambda locally can be complex. To deploy code changes quickly, skip the `serverless deploy` command, which is much slower since it triggers a full AWS CloudFormation update. Instead, deploy code and configuration changes to individual AWS Lambda functions in seconds via the `deploy function` command, with `-f [function name in serverless.yml]` set to the function you want to deploy. -Many osls users rely on local emulation to develop more quickly. Please note, emulating AWS Lambda and other cloud services is never accurate and the process can be complex. We recommend the following workflow to develop locally... +```bash +serverless deploy function -f hello +``` + +More details on the `deploy function` command can be found [here](./cli-reference/deploy-function.md). + +## Developing Locally Use the `invoke local` command to invoke your function locally: ```bash -sls invoke local -f my-api +serverless invoke local -f hello ``` -You can also pass data to this local invocation via a variety of ways. Here's one of them: +You can also pass data to this local invocation: ```bash -serverless invoke local --function functionName --data '{"a":"bar"}' +serverless invoke local --function hello --data '{"a":"bar"}' ``` -More details on the `invoke local` command can be found [here](./cli-reference/invoke-local.md) +More details on the `invoke local` command can be found [here](./cli-reference/invoke-local.md). A popular plugin, `serverless-offline`, allows you to run a server locally and emulate AWS API Gateway. -More details on the **serverless-offline** plugin command can be found [here](https://github.com/dherault/serverless-offline) +More details on the **serverless-offline** plugin command can be found [here](https://github.com/dherault/serverless-offline). ## Remove Your Service -If you want to delete your service, run `remove`. This will delete all the AWS resources created by your project and ensure that you don't incur any unexpected charges. It will also remove the service from Serverless Dashboard. +If you want to delete your service, run `remove`. This will delete the AWS resources created by your project and ensure that you don't incur any unexpected charges. ```bash -sls remove +serverless remove ``` More details on the `remove` command can be found [here](./cli-reference/remove.md). diff --git a/docs/guides/configuration-validation.md b/docs/guides/configuration-validation.md index 1ee4e8230..2af721630 100644 --- a/docs/guides/configuration-validation.md +++ b/docs/guides/configuration-validation.md @@ -8,7 +8,7 @@ If you were presented with configuration error (or a warning, depending on `conf - Configuration related to external plugin does not have an associated JSON Schema. In such cases, please report the issue with the plugin author and provide them the details on how to [extend validation schema](./plugins) in order to permanently correct the issue. - However unlikely, there may be a bug (or missing) schema configuration for osls. If you believe this to be the case please report at [https://github.com/oss-serverless/osls/issues/new](https://github.com/oss-serverless/osls/issues/new) -**Note**: In a warning mode (with `configValidationMode: warn` set in configuration) osls commands are not blocked in any way, e.g. `sls deploy` will still attempt to deploy the service normally (still depending on the source of the warning, success of a deployment may vary) +**Note**: In a warning mode (with `configValidationMode: warn` set in configuration) osls commands are not blocked in any way, e.g. `serverless deploy` will still attempt to deploy the service normally (still depending on the source of the warning, success of a deployment may vary) When the setting is not explicitly specified, osls defaults to `configValidationMode: warn`. Starting with osls v4.0.0, the default will change to `configValidationMode: error`. If you find this functionality problematic, you may also turn it off with `configValidationMode: off` setting. diff --git a/docs/guides/credentials.md b/docs/guides/credentials.md index 0716ec9c2..e51088932 100644 --- a/docs/guides/credentials.md +++ b/docs/guides/credentials.md @@ -151,7 +151,7 @@ Now you can switch per project (/ API) by executing once when you start your pro `export AWS_PROFILE="profileName2"`. -in the Terminal. Now everything is set to execute all the `serverless` CLI options like `sls deploy`. +in the Terminal. Now everything is set to execute all the `serverless` CLI options like `serverless deploy`. ##### Using the `aws-profile` option diff --git a/docs/guides/functions.md b/docs/guides/functions.md index b15fcc184..c7e63c32e 100644 --- a/docs/guides/functions.md +++ b/docs/guides/functions.md @@ -391,7 +391,7 @@ functions: - flag ``` -During the first deployment when locally built images are used, the CLI will automatically create a dedicated ECR repository to store these images, with name `serverless--`. By default, older versions of images uploaded to ECR are not removed as they still might be in use by versioned functions. To automatically expire old images, set `provider.ecr.maxImageCount` to limit the number of images retained in the repository. During `sls remove`, the created ECR repository will be removed. During deployment, the CLI will attempt to `docker login` to ECR if needed. Depending on your local configuration, docker authorization token might be stored unencrypted. Please refer to documentation for more details: https://docs.docker.com/engine/reference/commandline/login/#credentials-store +During the first deployment when locally built images are used, the CLI will automatically create a dedicated ECR repository to store these images, with name `serverless--`. By default, older versions of images uploaded to ECR are not removed as they still might be in use by versioned functions. To automatically expire old images, set `provider.ecr.maxImageCount` to limit the number of images retained in the repository. During `serverless remove`, the created ECR repository will be removed. During deployment, the CLI will attempt to `docker login` to ECR if needed. Depending on your local configuration, docker authorization token might be stored unencrypted. Please refer to documentation for more details: https://docs.docker.com/engine/reference/commandline/login/#credentials-store ## Instruction set architecture @@ -930,14 +930,14 @@ The `provider.lambdaHashingVersion` property and old hashing algorithm compatibi Please keep in mind that these changes require two deployments with manual configuration adjustment between them. It also creates two additional versions and temporarily overrides descriptions of your functions. Migration will need to be done separately for each of your environments/stages. -1. Run `sls deploy` with additional `--enforce-hash-update` flag: that flag will override the description for Lambda functions, which will force the creation of new versions. +1. Run `serverless deploy` with additional `--enforce-hash-update` flag: that flag will override the description for Lambda functions, which will force the creation of new versions. 2. Remove `provider.lambdaHashingVersion` setting from your configuration: your service will now always deploy with the new Lambda version hashes (which is the new default in v3). -3. Run `sls deploy`, this time without additional `--enforce-hash-update` flag: that will restore the original descriptions on all Lambda functions. +3. Run `serverless deploy`, this time without additional `--enforce-hash-update` flag: that will restore the original descriptions on all Lambda functions. Now your whole service is fully migrated to the new Lambda Hashing Algorithm. If you do not want to temporarily override descriptions of your functions or would like to avoid creating unnecessary versions of your functions, you might want to use one of the following approaches: -- Ensure that code for all your functions will change during deployment, remove `provider.lambdaHashingVersion` from your configuration, and run `sls deploy`. Due to the fact that all functions have code changed, all your functions will be migrated to new hashing algorithm. Please note that the change can be caused by e.g. upgrading a dependency used by all your functions so you can pair it with regular chores. -- Add a dummy file that will be included in deployment artifacts for all your functions, remove `provider.lambdaHashingVersion` from your configuration, and run `sls deploy`. Due to the fact that all functions have code changed, all your functions will be migrated to new hashing algorithm. -- If it is safe in your case (e.g. it's only development sandbox), you can also tear down the whole service by `sls remove`, remove `provider.lambdaHashingVersion` from your configuration, and run `sls deploy`. Newly recreated environment will be using new hashing algorithm. +- Ensure that code for all your functions will change during deployment, remove `provider.lambdaHashingVersion` from your configuration, and run `serverless deploy`. Due to the fact that all functions have code changed, all your functions will be migrated to new hashing algorithm. Please note that the change can be caused by e.g. upgrading a dependency used by all your functions so you can pair it with regular chores. +- Add a dummy file that will be included in deployment artifacts for all your functions, remove `provider.lambdaHashingVersion` from your configuration, and run `serverless deploy`. Due to the fact that all functions have code changed, all your functions will be migrated to new hashing algorithm. +- If it is safe in your case (e.g. it's only development sandbox), you can also tear down the whole service by `serverless remove`, remove `provider.lambdaHashingVersion` from your configuration, and run `serverless deploy`. Newly recreated environment will be using new hashing algorithm. diff --git a/docs/guides/services.md b/docs/guides/services.md index 024370100..44e469b35 100644 --- a/docs/guides/services.md +++ b/docs/guides/services.md @@ -27,7 +27,7 @@ resources: # Additional AWS resources to deploy ``` -To create a new service, run the `serverless` command and check out the [Getting started guide](../getting-started.md). +To create a new service, create a `serverless.yml` file and check out the [Getting started guide](../getting-started.md). ## Organization diff --git a/docs/guides/variables.md b/docs/guides/variables.md index d1c7324a0..6e5109031 100644 --- a/docs/guides/variables.md +++ b/docs/guides/variables.md @@ -48,16 +48,16 @@ provider: MY_SECRET: ${file(./config.${opt:stage, 'dev'}.json):CREDS} ``` -If `sls deploy --stage qa` is run, the option `stage=qa` is used inside the `${file(./config.${opt:stage, 'dev'}.json):CREDS}` variable and it will resolve the `config.qa.json` file and use the `CREDS` key defined. +If `serverless deploy --stage qa` is run, the option `stage=qa` is used inside the `${file(./config.${opt:stage, 'dev'}.json):CREDS}` variable and it will resolve the `config.qa.json` file and use the `CREDS` key defined. **How that works:** -1. stage is set to `qa` from the option supplied to the `sls deploy --stage qa` command +1. stage is set to `qa` from the option supplied to the `serverless deploy --stage qa` command 2. `${opt:stage, 'dev'}` resolves to `qa` and is used in `${file(./config.${opt:stage, 'dev'}.json):CREDS}` 3. `${file(./config.qa.json):CREDS}` is found & the `CREDS` value is read 4. `MY_SECRET` value is set -Likewise, if `sls deploy --stage prod` is run the `config.prod.json` file would be found and used. +Likewise, if `serverless deploy --stage prod` is run the `config.prod.json` file would be found and used. If no `--stage` flag is provided, the fallback `dev` will be used and result in `${file(./config.dev.json):CREDS}`. diff --git a/docs/guides/workflow.md b/docs/guides/workflow.md index ef8b09686..a609fa328 100644 --- a/docs/guides/workflow.md +++ b/docs/guides/workflow.md @@ -29,10 +29,10 @@ A handy list of commands to use when developing with osls. ##### Create A Service: -Creates a new Service +Creates a new service from a local template directory ```bash -serverless create -p [TARGET DIRECTORY] --template-url [TEMPLATE URL] +serverless create -p [TARGET DIRECTORY] --template-path [LOCAL TEMPLATE DIRECTORY] ``` ##### Install A Service