diff --git a/docs/cli-reference/config-credentials.md b/docs/cli-reference/config-credentials.md index fe7af1cb9..26ea016c6 100644 --- a/docs/cli-reference/config-credentials.md +++ b/docs/cli-reference/config-credentials.md @@ -1,7 +1,7 @@ # AWS - Config Credentials ```bash -serverless config credentials --provider provider --key key --secret secret +osls config credentials --provider provider --key key --secret secret ``` ## Options @@ -21,7 +21,7 @@ serverless config credentials --provider provider --key key --secret secret ### Configure the `default` profile ```bash -serverless config credentials --provider aws --key 1234 --secret 5678 +osls config credentials --provider aws --key 1234 --secret 5678 ``` This example will configure the `default` profile with the `aws_access_key_id` of `1234` and the `aws_secret_access_key` of `5678`. @@ -29,7 +29,7 @@ This example will configure the `default` profile with the `aws_access_key_id` o ### Configure a custom profile ```bash -serverless config credentials \ +osls config credentials \ --provider aws \ --key 1234 \ --secret 5678 \ @@ -41,7 +41,7 @@ This example create and configure a `custom-profile` profile with the `aws_acces ### Update an existing profile ```bash -serverless config credentials \ +osls config credentials \ --provider aws \ --key 1234 \ --secret 5678 \ diff --git a/docs/cli-reference/create.md b/docs/cli-reference/create.md index b3ac1fa11..78cc8e933 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/... \ +osls create \ + --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 \ +osls create \ + --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/... \ +osls create \ + --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 \ +osls create \ + --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 d587fd5ee..a134f41f4 100644 --- a/docs/cli-reference/deploy-function.md +++ b/docs/cli-reference/deploy-function.md @@ -1,9 +1,9 @@ # 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 `osls 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 +osls deploy function -f functionName ``` **Note:** This command **now** deploys both function configuration and code by @@ -11,7 +11,7 @@ default. Just as before, this puts your function in an inconsistent state that is out of sync with your CloudFormation stack. Use this for faster development cycles and not production deployments -**Note:** This command is not supported for functions configured with `durableConfig` locally or already deployed with durable configuration in AWS. Use `serverless deploy` so osls can publish a new durable function version and retarget the generated durable alias. +**Note:** This command is not supported for functions configured with `durableConfig` locally or already deployed with durable configuration in AWS. Use `osls deploy` so osls can publish a new durable function version and retarget the generated durable alias. ## Options @@ -25,13 +25,13 @@ cycles and not production deployments ### Deployment without stage and region options ```bash -serverless deploy function --function helloWorld +osls deploy function --function helloWorld ``` ### Deployment with stage and region options ```bash -serverless deploy function --function helloWorld \ +osls deploy function --function helloWorld \ --stage dev \ --region us-east-1 ``` @@ -39,5 +39,5 @@ serverless deploy function --function helloWorld \ ### Deploy only configuration changes ```bash -serverless deploy function --function helloWorld --update-config +osls deploy function --function helloWorld --update-config ``` diff --git a/docs/cli-reference/deploy-list.md b/docs/cli-reference/deploy-list.md index 1b747bd4d..9a4a0f636 100644 --- a/docs/cli-reference/deploy-list.md +++ b/docs/cli-reference/deploy-list.md @@ -1,10 +1,10 @@ # AWS - Deploy List -The `sls deploy list [functions]` command will list information about your deployments. +The `osls 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`. +You can either see all available deployments in your S3 deployment bucket by running `osls deploy list` or you can see the deployed functions by running `osls deploy list functions`. -The displayed information is useful when rolling back a deployment or function via `serverless rollback`. +The displayed information is useful when rolling back a deployment or function via `osls rollback`. ## Options @@ -16,11 +16,11 @@ The displayed information is useful when rolling back a deployment or function v ### List existing deploys ```bash -serverless deploy list +osls deploy list ``` ### List deployed functions and their versions ```bash -serverless deploy list functions +osls deploy list functions ``` diff --git a/docs/cli-reference/deploy.md b/docs/cli-reference/deploy.md index 454f5c693..d94536e73 100644 --- a/docs/cli-reference/deploy.md +++ b/docs/cli-reference/deploy.md @@ -1,9 +1,9 @@ # 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 `osls deploy` command deploys your entire service via CloudFormation. Run this command when you have made infrastructure changes (i.e., you edited `serverless.yml`). Use `osls 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 +osls deploy ``` ## Options @@ -21,14 +21,14 @@ serverless deploy ## Artifacts -After the `serverless deploy` command runs, the framework runs `serverless package` in the background first then deploys the generated package. +After the `osls deploy` command runs, the framework runs `osls package` in the background first then deploys the generated package. ## Examples ### Deployment without stage and region options ```bash -serverless deploy +osls deploy ``` This is the simplest deployment usage possible. With this command osls will deploy your service to the defined @@ -37,7 +37,7 @@ provider in the default stage (`dev`) to the default region (`us-east-1`). ### Deployment with stage and region options ```bash -serverless deploy --stage production --region eu-central-1 +osls deploy --stage production --region eu-central-1 ``` With this example we've defined that we want our service to be deployed to the `production` stage in the region @@ -46,7 +46,7 @@ With this example we've defined that we want our service to be deployed to the ` ### Deployment from a pre-packaged directory ```bash -serverless deploy --package /path/to/package/directory +osls deploy --package /path/to/package/directory ``` With this example, the packaging step will be skipped and the CLI will start deploying the package from the `/path/to/package/directory` directory. @@ -56,5 +56,5 @@ With this example, the packaging step will be skipped and the CLI will start dep - `SLS_AWS_MONITORING_FREQUENCY` allows the adjustment of the deployment monitoring frequency time in ms, default is `5000`. ```bash -SLS_AWS_MONITORING_FREQUENCY=10000 serverless deploy +SLS_AWS_MONITORING_FREQUENCY=10000 osls deploy ``` diff --git a/docs/cli-reference/generate-event.md b/docs/cli-reference/generate-event.md index a087e75ff..d3f42dbce 100644 --- a/docs/cli-reference/generate-event.md +++ b/docs/cli-reference/generate-event.md @@ -11,7 +11,7 @@ layout: Doc Creates sample Lambda function payloads for different types of events. ```bash -serverless generate-event --type eventType +osls generate-event --type eventType ``` ## Options @@ -40,17 +40,17 @@ serverless generate-event --type eventType ### Generate SQS event payload ```bash -serverless generate-event -t aws:sqs +osls generate-event -t aws:sqs ``` ### Generate Kinesis event payload with body ```bash -serverless generate-event -t aws:kinesis -b '{"foo": "bar"}' +osls generate-event -t aws:kinesis -b '{"foo": "bar"}' ``` ### Generate SQS event and save it to a file ```bash -serverless generate-event -t aws:sqs > event.json +osls generate-event -t aws:sqs > event.json ``` diff --git a/docs/cli-reference/info.md b/docs/cli-reference/info.md index 417796d49..875d04ce4 100644 --- a/docs/cli-reference/info.md +++ b/docs/cli-reference/info.md @@ -3,7 +3,7 @@ Displays information about the deployed service. ```bash -serverless info +osls info ``` ## Options @@ -26,7 +26,7 @@ See the example below for an example output. **Example:** ```bash -$ serverless info +$ osls info Service Information service: my-serverless-service @@ -45,7 +45,7 @@ functions: When using the `--verbose` flag, the `info` command will also append all Stack Outputs to the output: ```bash -$ serverless info --verbose +$ osls info --verbose Service Information service: my-serverless-service diff --git a/docs/cli-reference/install.md b/docs/cli-reference/install.md index bef48ec9a..ee67bdf72 100644 --- a/docs/cli-reference/install.md +++ b/docs/cli-reference/install.md @@ -3,7 +3,7 @@ Installs a service from a remote Git URL into a new directory in the current working directory. ```bash -serverless install --url https://github.com/some/service +osls install --url https://github.com/some/service ``` ## Options @@ -29,7 +29,7 @@ serverless install --url https://github.com/some/service ### Installing a service from a remote URL ```bash -serverless install --url https://github.com/pmuens/serverless-crud +osls install --url https://github.com/pmuens/serverless-crud ``` This example downloads the `serverless-crud` service from the remote repository, creates a new directory named `serverless-crud` in the current working directory, and unzips the files into it. @@ -37,7 +37,7 @@ This example downloads the `serverless-crud` service from the remote repository, ### Installing a service from a remote URL with a new service name ```bash -serverless install --url https://github.com/pmuens/serverless-crud --name my-crud +osls install --url https://github.com/pmuens/serverless-crud --name my-crud ``` This example downloads the `serverless-crud` service from the remote repository, creates a new directory named `my-crud` in the current working directory, and renames the service to `my-crud` if `serverless.yml` exists in the service root. @@ -45,7 +45,7 @@ This example downloads the `serverless-crud` service from the remote repository, ### Installing a service from a repository subdirectory URL ```bash -serverless install --url https://github.com/serverless/examples/tree/master/aws-node-rest-api-with-dynamodb +osls install --url https://github.com/serverless/examples/tree/master/aws-node-rest-api-with-dynamodb ``` This example downloads the `aws-node-rest-api-with-dynamodb` service from a repository subdirectory. diff --git a/docs/cli-reference/invoke-local.md b/docs/cli-reference/invoke-local.md index 7d7c16ebc..0d5a70c7b 100644 --- a/docs/cli-reference/invoke-local.md +++ b/docs/cli-reference/invoke-local.md @@ -3,7 +3,7 @@ This runs your code locally by emulating the AWS Lambda environment. Please keep in mind, it's not a 100% perfect emulation, there may be some differences, but it works for the vast majority of users. We mock the `context` with simple mock data. ```bash -serverless invoke local --function functionName +osls invoke local --function functionName ``` **Note:** Please refer to [this guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-set-up-simple-proxy.html#api-gateway-simple-proxy-for-lambda-input-format) for event data passing when your function uses the `http` event with a Lambda Proxy integration. @@ -23,7 +23,7 @@ serverless invoke local --function functionName runtimes. * `--docker-arg` Pass additional arguments to docker run command when `--docker` is option used. e.g. `--docker-arg '-p 9229:9229' --docker-arg '-v /var:/host_var'` -> **Security note:** When `serverless invoke local` receives a `--path` or `--contextPath` value ending in `.js`, the CLI loads it with Node.js (`require()`), which executes the file so it can export event or context data. Treat JavaScript input files and paths supplied by scripts or CI as trusted input. Prefer JSON or YAML files for event and context data from untrusted sources. +> **Security note:** When `osls invoke local` receives a `--path` or `--contextPath` value ending in `.js`, the CLI loads it with Node.js (`require()`), which executes the file so it can export event or context data. Treat JavaScript input files and paths supplied by scripts or CI as trusted input. Prefer JSON or YAML files for event and context data from untrusted sources. ## Environment @@ -37,7 +37,7 @@ set, that allows you to determine a local execution within your code. ### Local function invocation ```bash -serverless invoke local --function functionName +osls invoke local --function functionName ``` This example will locally invoke your function. @@ -45,23 +45,23 @@ This example will locally invoke your function. ### Local function invocation with data ```bash -serverless invoke local --function functionName --data '{"a":"bar"}' +osls invoke local --function functionName --data '{"a":"bar"}' ``` ```bash -serverless invoke local --function functionName --raw --data "hello world" +osls invoke local --function functionName --raw --data "hello world" ``` ### Local function invocation with data from standard input ```bash -node dataGenerator.js | serverless invoke local --function functionName +node dataGenerator.js | osls invoke local --function functionName ``` ### Local function invocation with a data file ```bash -serverless invoke local --function functionName --path lib/data.json +osls invoke local --function functionName --path lib/data.json ``` This example will pass the JSON data in the `lib/data.json` file (relative to the root of the service) while invoking the specified/deployed function. @@ -80,13 +80,13 @@ Example `data.json`: ### Local function invocation with custom context ```bash -serverless invoke local --function functionName --context '{"timeout":120}' +osls invoke local --function functionName --context '{"timeout":120}' ``` ### Local function invocation with context file ```bash -serverless invoke local --function functionName \ +osls invoke local --function functionName \ --contextPath lib/context.json ``` @@ -95,11 +95,11 @@ This example will pass the JSON context in the `lib/context.json` file (relative ### Local function invocation, setting environment variables ```bash -serverless invoke local -f functionName -e VAR1=value1 +osls invoke local -f functionName -e VAR1=value1 # Or more than one variable -serverless invoke local -f functionName \ +osls invoke local -f functionName \ -e VAR1=value1 \ -e VAR2=value2 ``` @@ -142,7 +142,7 @@ Lambda functions assume an _IAM role_ during execution: the framework creates th Unless you explicitly state otherwise, every call to the AWS SDK inside the lambda function is made using this role (a temporary pair of key / secret is generated and set by AWS as environment variables, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`). -When you use `serverless invoke local`, the situation is quite different: the role isn't available (the function is executed on your local machine), so unless you set a different user directly in the code (or via a key pair of environment variables), the AWS SDK will use the default profile specified inside your AWS credential configuration file. +When you use `osls invoke local`, the situation is quite different: the role isn't available (the function is executed on your local machine), so unless you set a different user directly in the code (or via a key pair of environment variables), the AWS SDK will use the default profile specified inside your AWS credential configuration file. Take a look to the official AWS documentation (in this particular instance, for the javascript SDK, but should be similar for all SDKs): diff --git a/docs/cli-reference/invoke.md b/docs/cli-reference/invoke.md index e08fbff84..b29f87abc 100644 --- a/docs/cli-reference/invoke.md +++ b/docs/cli-reference/invoke.md @@ -3,7 +3,7 @@ Invokes a deployed function. You can send event data, read logs and display other important information of the function invocation. ```bash -serverless invoke [local] --function functionName +osls invoke [local] --function functionName ``` **Note:** Please refer to [this guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-set-up-simple-proxy.html#api-gateway-simple-proxy-for-lambda-input-format) for event data passing when your function uses the `http` event with a Lambda Proxy integration. @@ -32,7 +32,7 @@ serverless invoke [local] --function functionName Invokes a function locally for testing and logs the output. Keep in mind that we mock the `context` with simple mock data. ```bash -serverless invoke local --function functionName +osls invoke local --function functionName ``` ## Options @@ -44,14 +44,14 @@ serverless invoke local --function functionName - `--contextPath` or `-x`, The path to a json file holding input context to be passed to the invoked function. Relative paths are resolved from the root directory of the service. Absolute paths are also accepted. - `--context` or `-c`, String data to be passed as a context to your function. Same like with `--data`, context included in `--contextPath` will overwrite the context you passed with `--context` flag. -> **Security note:** For `serverless invoke local`, `.js` files provided with `--path` or `--contextPath` are loaded with Node.js and executed. Treat those files and any paths supplied by scripts or CI as trusted input. Prefer JSON or YAML files for event and context data from untrusted sources. +> **Security note:** For `osls invoke local`, `.js` files provided with `--path` or `--contextPath` are loaded with Node.js and executed. Treat those files and any paths supplied by scripts or CI as trusted input. Prefer JSON or YAML files for event and context data from untrusted sources. ## Examples ### AWS ```bash -serverless invoke --function functionName --stage dev --region us-east-1 +osls invoke --function functionName --stage dev --region us-east-1 ``` This example will invoke your deployed function named `functionName` in region `us-east-1` in stage `dev`. This will @@ -60,19 +60,19 @@ output the result of the invocation in your terminal. #### Function invocation with data ```bash -serverless invoke --function functionName --data "hello world" +osls invoke --function functionName --data "hello world" ``` #### Function invocation with custom context ```bash -serverless invoke --function functionName --context "hello world" +osls invoke --function functionName --context "hello world" ``` #### Function invocation with context passing ```bash -serverless invoke --function functionName --contextPath lib/context.json +osls invoke --function functionName --contextPath lib/context.json ``` This example will pass the json context in the `lib/context.json` file (relative to the root of the service) while invoking the specified/deployed function. @@ -80,13 +80,13 @@ This example will pass the json context in the `lib/context.json` file (relative #### Function invocation with data from standard input ```bash -node dataGenerator.js | serverless invoke --function functionName +node dataGenerator.js | osls invoke --function functionName ``` #### Function invocation with logging ```bash -serverless invoke --function functionName --log +osls invoke --function functionName --log ``` Just like the first example, but will also outputs logging information about your invocation. @@ -94,7 +94,7 @@ Just like the first example, but will also outputs logging information about you #### Function invocation with data passing ```bash -serverless invoke --function functionName --path lib/data.json +osls invoke --function functionName --path lib/data.json ``` This example will pass the json data in the `lib/data.json` file (relative to the root of the service) while invoking @@ -114,7 +114,7 @@ the specified/deployed function. #### Function invocation with durable execution name ```bash -serverless invoke --function functionName --qualifier durable --durable-execution-name order-12345 +osls invoke --function functionName --qualifier durable --durable-execution-name order-12345 ``` This example invokes a durable function with a unique execution name. Durable functions require a qualified invocation, so provide `--qualifier` with a version, alias, or `$LATEST`; use `durable` for the alias generated by osls. When Lambda returns a durable execution ARN, osls prints it so you can track the execution. If you invoke a function with an execution name that already exists, Lambda handles the invocation idempotently only when the payload matches. See the [Functions guide](../guides/functions.md#aws-lambda-durable-functions) for more information on configuring durable functions. @@ -122,13 +122,13 @@ This example invokes a durable function with a unique execution name. Durable fu ### Local function invocation with custom context ```bash -serverless invoke local --function functionName --context "hello world" +osls invoke local --function functionName --context "hello world" ``` ### Local function invocation with context passing ```bash -serverless invoke local --function functionName \ +osls invoke local --function functionName \ --contextPath lib/context.json ``` @@ -144,7 +144,7 @@ Lambda functions assume an _IAM role_ during execution: the framework creates th Unless you explicitly state otherwise, every call to the AWS SDK inside the lambda function is made using this role (a temporary pair of key / secret is generated and set by AWS as environment variables, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`). -When you use `serverless invoke local`, the situation is quite different: the role isn't available (the function is executed on your local machine), so unless you set a different user directly in the code (or via a key pair of environment variables), the AWS SDK will use the default profile specified inside you AWS credential configuration file. +When you use `osls invoke local`, the situation is quite different: the role isn't available (the function is executed on your local machine), so unless you set a different user directly in the code (or via a key pair of environment variables), the AWS SDK will use the default profile specified inside you AWS credential configuration file. Take a look to the official AWS documentation (in this particular instance, for the javascript SDK, but should be similar for all SDKs): diff --git a/docs/cli-reference/logs.md b/docs/cli-reference/logs.md index 1d4de32e8..694d3e759 100644 --- a/docs/cli-reference/logs.md +++ b/docs/cli-reference/logs.md @@ -3,10 +3,10 @@ Lets you watch the logs of a specific function. ```bash -serverless logs -f hello +osls logs -f hello # Optionally tail the logs with --tail or -t -serverless logs -f hello -t +osls logs -f hello -t ``` This command returns as many log events as can fit in 1MB (up to 10,000 log events). You can use the `--filter` option to ensure the logs you're looking for are included. @@ -54,31 +54,31 @@ Dates and times without an explicit UTC offset are interpreted as UTC. **Note:** There's a small lag between invoking the function and actually having the log event registered in CloudWatch. So it takes a few seconds for the logs to show up right after invoking the function. ```bash -serverless logs -f hello +osls logs -f hello ``` This will fetch the logs from last 10 minutes as startTime was not given. ```bash -serverless logs -f hello --startTime 5h +osls logs -f hello --startTime 5h ``` This will fetch the logs that happened in the past 5 hours. ```bash -serverless logs -f hello --startTime 1469694264 +osls logs -f hello --startTime 1469694264 ``` This will fetch the logs that happened starting at epoch `1469694264`. ```bash -serverless logs -f hello -t +osls logs -f hello -t ``` osls will tail the CloudWatch log output and print new log messages coming in starting from 10 seconds ago. ```bash -serverless logs -f hello --filter serverless +osls logs -f hello --filter serverless ``` This will fetch only the logs that contain the string `serverless` diff --git a/docs/cli-reference/metrics.md b/docs/cli-reference/metrics.md index 8ce87be0f..cd34e1490 100644 --- a/docs/cli-reference/metrics.md +++ b/docs/cli-reference/metrics.md @@ -3,7 +3,7 @@ Lets you watch the metrics of a specific function. ```bash -serverless metrics +osls metrics ``` ## Options @@ -11,7 +11,7 @@ serverless metrics - `--function` or `-f` The function you want to fetch the metrics for. - `--stage` or `-s` The stage you want to view the function metrics for. If not provided, the plugin will use the default stage listed in `serverless.yml`. If that doesn't exist either it'll just fetch the metrics from the `dev` stage. - `--region` or `-r` The region you want to view the function metrics for. If not provided, the plugin will use the default region listed in `serverless.yml`. If that doesn't exist either it'll just fetch the metrics from the `us-east-1` region. -- `--startTime` A specific unit in time to start fetching metrics from (ie: `2010-10-20`, `1469705761`, `30m` (30 minutes ago), `2h` (2 hours ago) or `3d` (3 days ago)). Accepts the same formats as [`serverless logs --startTime`](./logs.md): relative time, ISO 8601 dates and datetimes (interpreted as UTC unless an explicit offset is given), or Unix epoch time in seconds or milliseconds. Defaults to 24h ago. +- `--startTime` A specific unit in time to start fetching metrics from (ie: `2010-10-20`, `1469705761`, `30m` (30 minutes ago), `2h` (2 hours ago) or `3d` (3 days ago)). Accepts the same formats as [`osls logs --startTime`](./logs.md): relative time, ISO 8601 dates and datetimes (interpreted as UTC unless an explicit offset is given), or Unix epoch time in seconds or milliseconds. Defaults to 24h ago. - `--endTime` A specific unit in time to end fetching metrics from (ie: `2010-10-21` or `1469705761`). Accepts the same formats as `--startTime`. Defaults to now. ## Examples @@ -21,7 +21,7 @@ serverless metrics ### See service wide metrics for the last 24h ```bash -serverless metrics +osls metrics ``` Displays service wide metrics for the last 24h. @@ -29,7 +29,7 @@ Displays service wide metrics for the last 24h. ### See service wide metrics for a specific timespan ```bash -serverless metrics --startTime 2016-01-01 --endTime 2016-01-02 +osls metrics --startTime 2016-01-01 --endTime 2016-01-02 ``` Displays service wide metrics for the time between January 1, 2016 and January 2, 2016. @@ -37,7 +37,7 @@ Displays service wide metrics for the time between January 1, 2016 and January 2 ### See all metrics for the function `hello` of the last 24h ```bash -serverless metrics --function hello +osls metrics --function hello ``` Displays all `hello` function metrics for the last 24h. @@ -45,7 +45,7 @@ Displays all `hello` function metrics for the last 24h. ### See metrics for the function `hello` of a specific timespan ```bash -serverless metrics --function hello \ +osls metrics --function hello \ --startTime 2016-01-01 \ --endTime 2016-01-02 ``` diff --git a/docs/cli-reference/package.md b/docs/cli-reference/package.md index f281f4610..0df6353e7 100644 --- a/docs/cli-reference/package.md +++ b/docs/cli-reference/package.md @@ -1,9 +1,9 @@ # 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 `osls 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 +osls package ``` ## Options @@ -17,7 +17,7 @@ serverless package ### Packaging without stage and region options ```bash -serverless package +osls package ``` This example packages your service while using the default stage (`dev`) and default region (`us-east-1`). The generated package would be the default `.serverless` directory inside your service. @@ -25,7 +25,7 @@ This example packages your service while using the default stage (`dev`) and def ### Packaging with stage and region options ```bash -serverless package --stage production --region eu-central-1 +osls package --stage production --region eu-central-1 ``` This example packages your service while using the `production` stage in the region @@ -34,7 +34,7 @@ This example packages your service while using the `production` stage in the reg ### Packaging to a custom path ```bash -serverless package --package /path/to/package/directory +osls package --package /path/to/package/directory ``` This example packages your service using the default stage and region and output the generated package into the custom path you provided at `/path/to/package/directory`. diff --git a/docs/cli-reference/plugin-install.md b/docs/cli-reference/plugin-install.md index a7c47b564..67cc9a359 100644 --- a/docs/cli-reference/plugin-install.md +++ b/docs/cli-reference/plugin-install.md @@ -6,7 +6,7 @@ If you want a specific version, semver range, or npm dist-tag, specify ` \ +osls rollback function --function \ --function-version ``` -**Note:** You can only rollback a function which was previously deployed through `serverless deploy`. Functions are not versioned when running `serverless deploy function`. +**Note:** You can only rollback a function which was previously deployed through `osls deploy`. Functions are not versioned when running `osls deploy function`. -**Note:** This command is not supported for functions configured with `durableConfig` locally or already deployed with durable configuration in AWS. Use `serverless deploy` to publish and retarget durable function versions. +**Note:** This command is not supported for functions configured with `durableConfig` locally or already deployed with durable configuration in AWS. Use `osls deploy` to publish and retarget durable function versions. ## Options @@ -20,7 +20,7 @@ serverless rollback function --function \ ### AWS -At first you want to run `serverless deploy list functions` to see all the deployed functions of your service and their corresponding versions. -After picking a function and the version you can run the `serverless rollback function` command to rollback the function. +At first you want to run `osls deploy list functions` to see all the deployed functions of your service and their corresponding versions. +After picking a function and the version you can run the `osls rollback function` command to rollback the function. -E.g. `serverless rollback function -f my-function --function-version 23` rolls back the function `my-function` to the version `23`. +E.g. `osls rollback function -f my-function --function-version 23` rolls back the function `my-function` to the version `23`. diff --git a/docs/cli-reference/rollback.md b/docs/cli-reference/rollback.md index 162890511..c68b1b048 100644 --- a/docs/cli-reference/rollback.md +++ b/docs/cli-reference/rollback.md @@ -3,7 +3,7 @@ Rollback a service to a specific deployment. ```bash -serverless rollback --timestamp timestamp +osls rollback --timestamp timestamp ``` If `timestamp` is not specified, the CLI will show your existing deployments. @@ -22,12 +22,12 @@ If `timestamp` is not specified, the CLI will show your existing deployments. ### AWS -At first you want to run `serverless deploy list` to show your existing deployments. This will provide you with a list of the deployments stored in your S3 bucket. You can then use the timestamp of one of these deployments to set your infrastructure stack to this specific deployment. +At first you want to run `osls deploy list` to show your existing deployments. This will provide you with a list of the deployments stored in your S3 bucket. You can then use the timestamp of one of these deployments to set your infrastructure stack to this specific deployment. **Example:** ``` -$ serverless deploy list +$ osls deploy list Serverless: Listing deployments: Serverless: ------------- Serverless: Timestamp: 1476790110568 @@ -60,7 +60,7 @@ Serverless: Files: Serverless: - compiled-cloudformation-template.json Serverless: - mail-service.zip -$ serverless rollback -t 1476893957131 +$ osls rollback -t 1476893957131 Serverless: Updating Stack... Serverless: Checking Stack update progress... ..... diff --git a/docs/events/apigateway.md b/docs/events/apigateway.md index a6429b501..021426f46 100644 --- a/docs/events/apigateway.md +++ b/docs/events/apigateway.md @@ -1361,7 +1361,7 @@ There's a lot going on in these two templates, but all you need to know to set u endpoint of your proxy, and the URI you want to set a proxy to. Now that you have these two CloudFormation templates defined in your `serverless.yml` file, you can simply run -`serverless deploy` and that will deploy these custom resources for you along with your service and set up a proxy on your Rest API. +`osls deploy` and that will deploy these custom resources for you along with your service and set up a proxy on your Rest API. ## Accessing private resources using VPC Link diff --git a/docs/events/cloudfront.md b/docs/events/cloudfront.md index d16c58156..1dc0ef057 100644 --- a/docs/events/cloudfront.md +++ b/docs/events/cloudfront.md @@ -17,7 +17,7 @@ Lambda@Edge has four options when the Lambda function is triggered **NOTE:** Deployments and removals can take up to 30 minutes due to the CloudFront CDN propagation. -**IMPORTANT:** Due to current [Lambda@Edge limitations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-edge-delete-replicas.html) it's necessary to set the `DeletionPolicy` to `Retain` for AWS Lambda functions which use the `cloudFront` event. osls will do this automatically for you. However bear in mind that **you have to delete those AWS Lambda functions manually** once you've removed the service via `serverless remove`. +**IMPORTANT:** Due to current [Lambda@Edge limitations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-edge-delete-replicas.html) it's necessary to set the `DeletionPolicy` to `Retain` for AWS Lambda functions which use the `cloudFront` event. osls will do this automatically for you. However bear in mind that **you have to delete those AWS Lambda functions manually** once you've removed the service via `osls remove`. **MEMORY AND TIMEOUT LIMITS:** According to [AWS Limits on Lambda@Edge](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html#limits-lambda-at-edge) the limits for viewer-request and viewer-response are 128MB memory and 5 seconds timeout and for origin-request and origin-response are 3008MB memory and 30 seconds timeout. diff --git a/docs/events/cloudwatch-log.md b/docs/events/cloudwatch-log.md index 0ad95ec02..9ca65869c 100644 --- a/docs/events/cloudwatch-log.md +++ b/docs/events/cloudwatch-log.md @@ -32,7 +32,7 @@ functions: ### Example -Update your `serverless.yml` file as follows and run `serverless deploy`. +Update your `serverless.yml` file as follows and run `osls deploy`. ```yml functions: @@ -46,7 +46,7 @@ functions: - cloudwatchLog: '/aws/lambda/hello2' ``` -Next up, edit `serverless.yml` and swap out the `logGroup` names. After that run `serverless deploy` again (the deployment will fail). +Next up, edit `serverless.yml` and swap out the `logGroup` names. After that run `osls deploy` again (the deployment will fail). ```yml functions: diff --git a/docs/events/http-api.md b/docs/events/http-api.md index a95019129..d197899ed 100644 --- a/docs/events/http-api.md +++ b/docs/events/http-api.md @@ -315,7 +315,7 @@ In such case no API and stage resources are created, therefore extending HTTP AP ## HTTP API URL -When deploying functions with `httpApi` events, the URL of the HTTP API will be displayed in the `serverless deploy` and `serverless info` output. +When deploying functions with `httpApi` events, the URL of the HTTP API will be displayed in the `osls deploy` and `osls info` output. The URL is also exported as a CloudFormation output under the `HttpApiUrl` output. diff --git a/docs/events/sqs.md b/docs/events/sqs.md index 0ef6a7899..ad0b0a99f 100644 --- a/docs/events/sqs.md +++ b/docs/events/sqs.md @@ -101,7 +101,7 @@ The examples above show how to consume messages from an existing SQS queue. To c [Lift](https://github.com/getlift/lift) is a plugin that simplifies deploying pieces of applications via "[constructs](https://github.com/getlift/lift#constructs)". Lift can be installed via: ``` -serverless plugin install -n serverless-lift +osls plugin install -n serverless-lift ``` We can use the [`queue` construct](https://github.com/getlift/lift/blob/master/docs/queue.md) to deploy an SQS queue with its Lambda consumer: diff --git a/docs/getting-started.md b/docs/getting-started.md index 6ba73b15d..cc58dbb0f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -12,96 +12,129 @@ 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 `osls` to avoid confusion with other Serverless Framework installations. + +## 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 +osls 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 +osls 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 +osls invoke -f hello # Invoke and display logs: -serverless invoke -f hello --log +osls 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 `osls 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 +osls 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 +osls 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"}' +osls 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 +osls remove ``` More details on the `remove` command can be found [here](./cli-reference/remove.md). diff --git a/docs/guides/compose.md b/docs/guides/compose.md index e8890de49..0a46991d6 100644 --- a/docs/guides/compose.md +++ b/docs/guides/compose.md @@ -43,10 +43,10 @@ _Note: JS/TS configuration files are also supported (`serverless-compose.{yml,ts ## Usage -To deploy all services, instead of running `serverless deploy` in each service, you can now deploy all services at once by running `serverless deploy` at the root: +To deploy all services, instead of running `osls deploy` in each service, you can now deploy all services at once by running `osls deploy` at the root: ```bash -$ serverless deploy +$ osls deploy Deploying myapp to stage dev @@ -58,7 +58,7 @@ Deploying myapp to stage dev In order to limit the number of services that are deployed concurrently, use `--max-concurrency` flag: ```bash -$ serverless deploy --max-concurrency 5 +$ osls deploy --max-concurrency 5 ``` ### Service dependencies and variables @@ -101,7 +101,7 @@ Let's break down the example above into 3 steps: Value: !Ref MyQueue ``` -2. Because of the dependency introduced by the variable, `serverless deploy` will automatically **deploy `service-a` first, and then `service-b`.** +2. Because of the dependency introduced by the variable, `osls deploy` will automatically **deploy `service-a` first, and then `service-b`.** 3. The value will be passed to `service-b` [as a parameter](./parameters.md) named `queueUrl`. Parameters can be referenced in osls configuration via the `${param:xxx}` syntax: @@ -143,18 +143,18 @@ As seen in the above example, it is possible to configure more than one dependen ### Global commands -On top of `serverless deploy`, the following commands can be run globally across all services: +On top of `osls deploy`, the following commands can be run globally across all services: -- `serverless logs` to fetch logs from **all functions across all services** -- `serverless info` to view all services info -- `serverless remove` to remove all services -- `serverless outputs` to view all services outputs -- `serverless refresh-outputs` to refresh outputs of all services +- `osls logs` to fetch logs from **all functions across all services** +- `osls info` to view all services info +- `osls remove` to remove all services +- `osls outputs` to view all services outputs +- `osls refresh-outputs` to refresh outputs of all services For example, it is possible to tail logs for all functions at once: ```bash -$ serverless logs --tail +$ osls logs --tail service-a › users › START service-a › users › 2021-12-31 16:54:14 INFO New user created @@ -173,34 +173,34 @@ service-b › billing › END Duration: 7 ms ... It is possible to run commands for a specific service only. For example to deploy only a specific service: ```bash -serverless deploy --service=service-a +osls deploy --service=service-a # Shortcut alternative -serverless service-a:deploy +osls service-a:deploy ``` Or tail logs of a single function: ```bash -serverless logs --service=service-a --function=index +osls logs --service=service-a --function=index # Shortcut alternative -serverless service-a:logs --function=index +osls service-a:logs --function=index ``` All osls commands are supported **only via service-specific commands**, including custom commands from plugins, for example: ```bash -serverless service-a:offline +osls service-a:offline ``` ### Service-specific commands when using parameters -The `serverless service-a:deploy` command is the equivalent of running `serverless deploy` in service-a's directory. Both can be used. +The `osls service-a:deploy` command is the equivalent of running `osls deploy` in service-a's directory. Both can be used. -However, if "service-a" uses `${param:xxx}` to reference parameters injected by `serverless-compose.yml`, then `serverless service-a:deploy` must be used. Indeed, `${param:xxx}` cannot be resolved outside of osls compose. +However, if "service-a" uses `${param:xxx}` to reference parameters injected by `serverless-compose.yml`, then `osls service-a:deploy` must be used. Indeed, `${param:xxx}` cannot be resolved outside of osls compose. -In these cases, you must run all commands from the root: `serverless service-a:deploy`. +In these cases, you must run all commands from the root: `osls service-a:deploy`. ## Configuration @@ -228,19 +228,19 @@ The [osls security model](./security.md) applies to Compose as well, with a few The outputs of a service are stored locally (in the `.serverless/` directory). If a colleague deployed changes that changed the outputs of a service, you can refresh your local state via the `refresh-outputs` command: ``` -serverless refresh-outputs +osls refresh-outputs ``` This command has no impact on deployed services, it can be run at any time without unintended side effects. ## Removing services -To delete the whole project (and all its services), run `serverless remove` in the same directory as `serverless-compose.yml`. This will run [`serverless remove`](../cli-reference/remove.md) in each service directory. +To delete the whole project (and all its services), run `osls remove` in the same directory as `serverless-compose.yml`. This will run [`osls remove`](../cli-reference/remove.md) in each service directory. To delete only one service: 1. make sure no other service depends on it (else these services will be broken) -2. run `serverless :remove` +2. run `osls :remove` 3. then remove the service from `serverless-compose.yml` If you remove the service from `serverless-compose.yml` without doing step 1 first, the service will still be deployed in your AWS account. diff --git a/docs/guides/configuration-validation.md b/docs/guides/configuration-validation.md index d428dc7d2..e60be8d81 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. `osls 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: 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 44a2ff6e6..7745021f3 100644 --- a/docs/guides/credentials.md +++ b/docs/guides/credentials.md @@ -63,7 +63,7 @@ As a quick setup to get started you can export them as environment variables so export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are now available for serverless to use -serverless deploy +osls deploy # 'export' command is valid only for unix shells # In Windows use 'set' instead of 'export' @@ -92,14 +92,14 @@ export cafile="/path/to/cafile1.pem,/path/to/cafile2.pem" For a more permanent solution you can also set up credentials through AWS profiles. Here are different methods you can use to do so. -##### Setup with `serverless config credentials` command +##### Setup with `osls config credentials` command -osls provides a convenient way to configure AWS profiles with the help of the `serverless config credentials` command. +osls provides a convenient way to configure AWS profiles with the help of the `osls config credentials` command. Here's an example how you can configure the `default` AWS profile: ```bash -serverless config credentials \ +osls config credentials \ --provider aws \ --key AKIAIOSFODNN7EXAMPLE \ --secret wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY @@ -151,14 +151,14 @@ 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 `osls deploy`. ##### Using the `aws-profile` option You can always specify the profile which should be used via the `aws-profile` option like this: ```bash -serverless deploy --aws-profile devProfile +osls deploy --aws-profile devProfile ``` ##### Using web identity token @@ -185,7 +185,7 @@ custom: #### Profile in place with the 'invoke local' command -**Be aware!** Due to the way AWS IAM and the local environment works, if you invoke your lambda functions locally using the CLI command `serverless invoke local -f ...` the IAM role/profile could be (and probably is) different from the one set in the `serverless.yml` configuration file. +**Be aware!** Due to the way AWS IAM and the local environment works, if you invoke your lambda functions locally using the CLI command `osls invoke local -f ...` the IAM role/profile could be (and probably is) different from the one set in the `serverless.yml` configuration file. Thus, most likely, a different set of permissions will be in place, altering the interaction between your lambda functions and other AWS resources. _Please, refer to the [`invoke local`](../cli-reference/invoke-local.md#aws---invoke-local) CLI command documentation for more details._ diff --git a/docs/guides/deploying.md b/docs/guides/deploying.md index 10e129858..3b2dac851 100644 --- a/docs/guides/deploying.md +++ b/docs/guides/deploying.md @@ -7,7 +7,7 @@ osls was designed to provision your AWS Lambda Functions, Events and infrastruct This is the main method for doing deployments with osls: ```bash -serverless deploy +osls deploy ``` Use this method when you have updated your Function, Event or Resource configuration in `serverless.yml` and you want to deploy that change (or multiple changes at the same time) to Amazon Web Services. @@ -49,9 +49,9 @@ provider: - Use this in your CI/CD systems, as it is the safest method of deployment. - You can print the progress during the deployment if you use `verbose` mode, like this: ``` - serverless deploy --verbose + osls deploy --verbose ``` -- This method uses the AWS CloudFormation Stack Update method. CloudFormation is slow, so this method is slower. If you want to develop more quickly, use the `serverless deploy function` command (described below) +- This method uses the AWS CloudFormation Stack Update method. CloudFormation is slow, so this method is slower. If you want to develop more quickly, use the `osls deploy function` command (described below) - This method defaults to `dev` stage and `us-east-1` region. You can change the default stage and region in your `serverless.yml` file by setting the `stage` and `region` properties inside a `provider` object as the following example shows: @@ -68,7 +68,7 @@ provider: - You can also deploy to different stages and regions by passing in flags to the command: ``` - serverless deploy --stage production --region eu-central-1 + osls deploy --stage production --region eu-central-1 ``` - You can specify your own S3 bucket which should be used to store all the deployment artifacts. @@ -94,7 +94,7 @@ Check out the [deploy command docs](../cli-reference/deploy.md) for all details This deployment method does not touch your AWS CloudFormation Stack. Instead, it simply overwrites the zip file of the current function on AWS. This method is much faster, since it does not rely on CloudFormation. ```bash -serverless deploy function --function myFunction +osls deploy function --function myFunction ``` -**Note:** You can always enforce a deployment using the `--force` option. -**Note:** You can use `--update-config` to change only Lambda configuration without deploying code. @@ -109,19 +109,19 @@ serverless deploy function --function myFunction ### Tips - Use this when you are developing and want to test on AWS because it's much faster. -- During development, people will often run this command several times, as opposed to `serverless deploy` which is only run when larger infrastructure provisioning is required. +- During development, people will often run this command several times, as opposed to `osls deploy` which is only run when larger infrastructure provisioning is required. Check out the [deploy command docs](../cli-reference/deploy.md) for all details and options. ## Deploying a package -This deployment option takes a deployment directory that has already been created with `serverless package` and deploys it to the cloud provider. This allows you to easily integrate CI / CD workflows with osls. +This deployment option takes a deployment directory that has already been created with `osls package` and deploys it to the cloud provider. This allows you to easily integrate CI / CD workflows with osls. ```bash -serverless deploy --package path-to-package +osls deploy --package path-to-package ``` ### How It Works -- The argument to the `--package` flag is a directory that has been previously packaged by osls (with `serverless package`). +- The argument to the `--package` flag is a directory that has been previously packaged by osls (with `osls package`). - The deploy process bypasses the package step and uses the existing package to deploy and update CloudFormation stacks. diff --git a/docs/guides/environment-variables.md b/docs/guides/environment-variables.md index e9f6403ae..c3222c85a 100644 --- a/docs/guides/environment-variables.md +++ b/docs/guides/environment-variables.md @@ -18,7 +18,7 @@ With that option enabled, `.env` files will also be excluded from the package in osls loads `.env.{stage}` from the service directory when present; otherwise it falls back to `.env`. If stage is not explicitly defined, it defaults to `dev`. Invalid stage names are rejected before `.env.{stage}` is read. -osls loads `.env` files quietly by default. Avoid `DOTENV_CONFIG_DEBUG=true` or `DOTENV_CONFIG_QUIET=false` when using machine-readable commands such as `serverless print`, or when using osls compose, because those dotenv options can write runtime loading messages to stdout. +osls loads `.env` files quietly by default. Avoid `DOTENV_CONFIG_DEBUG=true` or `DOTENV_CONFIG_QUIET=false` when using machine-readable commands such as `osls print`, or when using osls compose, because those dotenv options can write runtime loading messages to stdout. ### Variable expansion diff --git a/docs/guides/events.md b/docs/guides/events.md index f5fd23d26..76c8d5d47 100644 --- a/docs/guides/events.md +++ b/docs/guides/events.md @@ -64,4 +64,4 @@ functions: ## Deploying -To deploy or update your Functions, Events and Infrastructure, run `serverless deploy`. +To deploy or update your Functions, Events and Infrastructure, run `osls deploy`. diff --git a/docs/guides/functions.md b/docs/guides/functions.md index f6aba68dd..b3d8c8776 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 `osls 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 @@ -492,12 +492,12 @@ Lambda Function URLs for durable functions are configured on the generated `dura You can provide an execution name when invoking a durable function: ```bash -serverless invoke --function orderProcessor --qualifier durable --durable-execution-name order-12345 +osls invoke --function orderProcessor --qualifier durable --durable-execution-name order-12345 ``` If you invoke a function with an execution name that already exists, Lambda handles the invocation idempotently only when the payload matches. A matching running execution returns existing execution information, and a matching closed execution returns the closed result. A different payload for the same execution name returns an error. Execution names must be 1-64 characters and can contain alphanumeric characters, hyphens, or underscores. -Use `serverless deploy` after code or durable configuration changes so CloudFormation can publish a new function version and update generated aliases and event targets. Adding or removing `durableConfig` may still require Lambda function replacement as described above. `serverless deploy function` and `serverless rollback function` are not supported for functions configured with `durableConfig` locally or already deployed with durable configuration because they update `$LATEST` without publishing and retargeting the durable alias. +Use `osls deploy` after code or durable configuration changes so CloudFormation can publish a new function version and update generated aliases and event targets. Adding or removing `durableConfig` may still require Lambda function replacement as described above. `osls deploy function` and `osls rollback function` are not supported for functions configured with `durableConfig` locally or already deployed with durable configuration because they update `$LATEST` without publishing and retargeting the durable alias. Functions currently configured with `durableConfig` are skipped by osls function pruning because durable executions may depend on retained versions for replay. @@ -564,7 +564,7 @@ functions: handler: handler.users ``` -Then, when you run `serverless deploy`, VPC configuration will be deployed along with your lambda function. +Then, when you run `osls deploy`, VPC configuration will be deployed along with your lambda function. If you have a provider VPC set but wish to have specific functions with no VPC, you can set the `vpc` value for these functions to `~` (null). For example: @@ -768,7 +768,7 @@ functions: By default, osls creates function versions for every deploy. This behavior is optional, and can be turned off in cases where you don't invoke past versions by their qualifier. If you would like to do this, you can invoke your functions as `arn:aws:lambda:....:function/myFunc:3` to invoke version 3 for example. -Older versions are not removed automatically unless you enable `provider.pruneFunctionVersions`. When enabled, osls deletes function and layer versions beyond the configured limit after a full service deploy (`serverless deploy`), keeping the newest versions. Function versions referenced by an alias are never deleted; layer versions are pruned purely by recency. `serverless deploy function` does not publish new versions and does not prune. +Older versions are not removed automatically unless you enable `provider.pruneFunctionVersions`. When enabled, osls deletes function and layer versions beyond the configured limit after a full service deploy (`osls deploy`), keeping the newest versions. Function versions referenced by an alias are never deleted; layer versions are pruned purely by recency. `osls deploy function` does not publish new versions and does not prune. To turn off function versioning, set the provider-level option `versionFunctions`. `pruneFunctionVersions` cannot be used when `versionFunctions` is `false`, unless the only functions publishing versions are durable: at least one function configures `durableConfig` and no other function sets `versionFunction: true`. Functions configured with `durableConfig` are always skipped by function pruning, so in this configuration only layer versions are pruned. diff --git a/docs/guides/iam.md b/docs/guides/iam.md index 2e0ef30fb..b35d843c5 100644 --- a/docs/guides/iam.md +++ b/docs/guides/iam.md @@ -142,9 +142,9 @@ provider: name: aws # declare one of the following... iam: - role: myDefaultRole # must validly reference a role defined in the service - role: arn:aws:iam::0123456789:role//my/default/path/roleInMyAccount # must validly reference a role defined in your account - role: # must validly resolve to the ARN of a role you have the rights to use + role: myDefaultRole # must validly reference a role defined in the service + role: arn:aws:iam::0123456789:role//my/default/path/roleInMyAccount # must validly reference a role defined in your account + role: # must validly resolve to the ARN of a role you have the rights to use Fn::GetAtt: - myRole - Arn @@ -162,7 +162,7 @@ resources: Type: AWS::IAM::Role Properties: Path: /my/default/path/ - RoleName: MyDefaultRole # required if you want to use 'serverless deploy --function' later on + RoleName: MyDefaultRole # required if you want to use 'osls deploy --function' later on AssumeRolePolicyDocument: Version: '2012-10-17' Statement: @@ -187,20 +187,19 @@ resources: - logs:TagResource Resource: - 'Fn::Join': - - ':' - - - - 'arn:aws:logs' - - Ref: 'AWS::Region' - - Ref: 'AWS::AccountId' - - 'log-group:/aws/lambda/*:*:*' - - Effect: "Allow" - Action: - - "s3:PutObject" - Resource: - Fn::Join: - - "" - - - "arn:aws:s3:::" - - "Ref" : "ServerlessDeploymentBucket" + - ':' + - - 'arn:aws:logs' + - Ref: 'AWS::Region' + - Ref: 'AWS::AccountId' + - 'log-group:/aws/lambda/*:*:*' + - Effect: 'Allow' + Action: + - 's3:PutObject' + Resource: + Fn::Join: + - '' + - - 'arn:aws:s3:::' + - 'Ref': 'ServerlessDeploymentBucket' ``` ### Custom IAM Roles For Each Function diff --git a/docs/guides/intro.md b/docs/guides/intro.md index 1115ab9bf..026ac5242 100644 --- a/docs/guides/intro.md +++ b/docs/guides/intro.md @@ -69,7 +69,7 @@ functions: # Your "Functions" resources: # The "Resources" your "Functions" use. Raw AWS CloudFormation goes in here. ``` -When deploying with the CLI via `serverless deploy`, everything in the configuration file is deployed at once. +When deploying with the CLI via `osls deploy`, everything in the configuration file is deployed at once. [Learn more on configuring a service](./services.md) diff --git a/docs/guides/packaging.md b/docs/guides/packaging.md index 7644e597a..9704e8eaa 100644 --- a/docs/guides/packaging.md +++ b/docs/guides/packaging.md @@ -7,13 +7,13 @@ Using the osls CLI tool, you can package your project without deploying it to AW Running the following command will build and save all of the deployment artifacts in the service's .serverless directory: ```bash -serverless package +osls package ``` However, you can also use the --package option to add a destination path and osls will store your deployment artifacts there (./my-artifacts in the following case): ```bash -serverless package --package my-artifacts +osls package --package my-artifacts ``` ## Package Configuration diff --git a/docs/guides/parameters.md b/docs/guides/parameters.md index 89e43edbc..f8c850a98 100644 --- a/docs/guides/parameters.md +++ b/docs/guides/parameters.md @@ -11,7 +11,7 @@ Parameters can be defined in `serverless.yml` or passed via CLI with `--param="< Parameters can be passed directly via CLI `--param` flag, following the pattern `--param="="`: ``` -serverless deploy --param="domain=myapp.com" --param="key=value" +osls deploy --param="domain=myapp.com" --param="key=value" ``` Parameters can then be used via the `${param:XXX}` variables: diff --git a/docs/guides/plugins/README.md b/docs/guides/plugins/README.md index 6898fbf53..e1322d4a8 100644 --- a/docs/guides/plugins/README.md +++ b/docs/guides/plugins/README.md @@ -17,12 +17,12 @@ Plugins are installed per service. They are not applied globally. To install a plugin, run the following command in a service directory: ``` -serverless plugin install -n example-osls-plugin +osls plugin install -n example-osls-plugin ``` This command will install the plugin via NPM and register it in `serverless.yml`. -`serverless plugin install --name` accepts npm package names, scoped package names, semver ranges, and npm dist-tags. For example, `example-osls-plugin`, `@example/osls-plugin`, `example-osls-plugin@^1.0.0`, and `example-osls-plugin@next` are valid install specs. Literal embedded quotes are not accepted in osls v4; quote the full `--name` value at the shell level if your version range contains spaces. +`osls plugin install --name` accepts npm package names, scoped package names, semver ranges, and npm dist-tags. For example, `example-osls-plugin`, `@example/osls-plugin`, `example-osls-plugin@^1.0.0`, and `example-osls-plugin@next` are valid install specs. Literal embedded quotes are not accepted in osls v4; quote the full `--name` value at the shell level if your version range contains spaces. npm lifecycle scripts are ignored by default during plugin install. If you trust the plugin and need its lifecycle scripts to run, pass `--allow-install-scripts`. diff --git a/docs/guides/plugins/cli-output.md b/docs/guides/plugins/cli-output.md index 726ee481a..8cafc6926 100644 --- a/docs/guides/plugins/cli-output.md +++ b/docs/guides/plugins/cli-output.md @@ -84,7 +84,7 @@ class MyPlugin { - Plugins should only write to `stdout` in commands they define (to avoid breaking the output of other commands). - The only content written to `stdout` should be the main output of the command. -Take, for example, the `serverless invoke` command: +Take, for example, the `osls invoke` command: - Its output is the result of the Lambda invocation: by writing that result (and only that) to `stdout`, it allows any script to parse the result of the Lambda invocation. - All other messages should be written to `stderr`: such logs are useful to humans, for example configuration warnings, upgrade notifications, Lambda logs… Since they are written to `stderr`, they do not break the parsable output of `stdout`. @@ -189,7 +189,7 @@ progress.get('my-plugin-progress').remove(); ## Service information -Plugins can add their own sections to the "Service information", i.e. the information displayed after `serverless deploy` or in `serverless info`. +Plugins can add their own sections to the "Service information", i.e. the information displayed after `osls deploy` or in `osls info`. To add a single item: @@ -200,7 +200,7 @@ serverless.addServiceOutputSection('my section', 'content'); The example above will be displayed as: ``` -$ serverless info +$ osls info functions: ... my section: content @@ -215,7 +215,7 @@ serverless.addServiceOutputSection('my section', ['line 1', 'line 2']); The example above will be displayed as: ``` -$ serverless info +$ osls info functions: ... my section: diff --git a/docs/guides/plugins/custom-commands.md b/docs/guides/plugins/custom-commands.md index d68aae016..9b471d84b 100644 --- a/docs/guides/plugins/custom-commands.md +++ b/docs/guides/plugins/custom-commands.md @@ -76,7 +76,7 @@ class MyPlugin { this.commands = { 'my-command': { - // The 'usage' property is used to display the 'serverless --help' output + // The 'usage' property is used to display the 'osls --help' output usage: 'This is my new custom command!', lifecycleEvents: ['run'], options: { diff --git a/docs/guides/resources.md b/docs/guides/resources.md index 3cf4d1f17..237302093 100644 --- a/docs/guides/resources.md +++ b/docs/guides/resources.md @@ -4,7 +4,7 @@ osls deploys using the AWS CloudFormation engine under the hood. If you want to ## Configuration -Every stage you deploy with `serverless.yml` is a single AWS CloudFormation stack. This is where your AWS Lambda functions and their event configurations are defined and it's how they are deployed. When you add `resources` to `serverless.yml`, those resources are added into your CloudFormation stack upon `serverless deploy`. +Every stage you deploy with `serverless.yml` is a single AWS CloudFormation stack. This is where your AWS Lambda functions and their event configurations are defined and it's how they are deployed. When you add `resources` to `serverless.yml`, those resources are added into your CloudFormation stack upon `osls deploy`. Define your AWS resources in a property titled `resources`. What goes in this property is raw CloudFormation template syntax, in YAML, like this: @@ -56,7 +56,7 @@ We're also using the term `normalizedName` or similar terms in this guide. This If you have path variables in your url, they get normalized too, and there is a `Var` added implicitly. So `normalizedPath` for `POST /users/{user_id}` will be normalized to `UsersUseridVarTestPost` _Tip:_ -If you are unsure how a resource is named, that you want to reference from your custom resources, you can issue a `serverless package`. This will create the CloudFormation template for your service in the `.serverless` folder (it is named `cloudformation-template-update-stack.json`). Just open the file and check for the generated resource name. +If you are unsure how a resource is named, that you want to reference from your custom resources, you can issue a `osls package`. This will create the CloudFormation template for your service in the `.serverless` folder (it is named `cloudformation-template-update-stack.json`). Just open the file and check for the generated resource name. | AWS Resource | Name Template | Example | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/docs/guides/security.md b/docs/guides/security.md index e1c8635d2..2f91fcb77 100644 --- a/docs/guides/security.md +++ b/docs/guides/security.md @@ -13,7 +13,7 @@ osls therefore does not, and cannot, defend against a malicious service configur Variable sources such as `${ssm:...}` and `${env:...}` resolve to plain strings before commands run. Those resolved values appear in places you may not expect: -- `serverless print` outputs the fully resolved configuration, including decrypted SSM SecureString values. Do not pipe it into logs that are retained or shared. +- `osls print` outputs the fully resolved configuration, including decrypted SSM SecureString values. Do not pipe it into logs that are retained or shared. - The packaging step writes `.serverless/serverless-state.json`, which contains the resolved service configuration, including provider and function environment values. Keep the `.serverless` directory out of version control and out of uploaded CI artifacts. - Verbose and debug output may include resolved values. Treat retained CI logs of osls runs as potentially secret-bearing. diff --git a/docs/guides/serverless.yml.md b/docs/guides/serverless.yml.md index c8c975720..0eccfd162 100644 --- a/docs/guides/serverless.yml.md +++ b/docs/guides/serverless.yml.md @@ -597,7 +597,7 @@ provider: ## Package -The `serverless package` or `serverless deploy` commands [package the code of all functions into zip files](./packaging.md). +The `osls package` or `osls deploy` commands [package the code of all functions into zip files](./packaging.md). These zip files are then used for deployments. ```yml diff --git a/docs/guides/services.md b/docs/guides/services.md index 024370100..a4d77ef1c 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 @@ -124,20 +124,20 @@ When you deploy a service, all functions, events and resources in `serverless.ym To deploy a service, run the `deploy` command in the same directory as `serverless.yml`: ```bash -serverless deploy +osls deploy ``` Deployment defaults to `dev` stage and `us-east-1` region on AWS. You can deploy to a different stage or region via CLI options: ```bash -serverless deploy --stage prod --region us-east-1 +osls deploy --stage prod --region us-east-1 ``` Check out the [deployment guide](./deploying.md) to learn more about deployments and how they work. Or, check out the [`deploy` command reference](../cli-reference/deploy) to see all the options available. ## Removal -To easily remove your service from your AWS account, you can use the `serverless remove` command. +To easily remove your service from your AWS account, you can use the `osls remove` command. The removal process will only remove the service on your provider's infrastructure (including all the resources mentioned in `serverless.yml`). The service directory will still remain on your local machine, so you can still modify and (re)deploy it to another stage, region or provider later on. @@ -203,7 +203,7 @@ To execute the locally installed CLI executable you have to reference the binary Example: ```bash -npx serverless deploy +npx osls deploy ``` or diff --git a/docs/guides/testing.md b/docs/guides/testing.md index 9ec0db407..a8e8cf7c3 100644 --- a/docs/guides/testing.md +++ b/docs/guides/testing.md @@ -77,7 +77,7 @@ Now, the above class keeps business logic separate. Further, the code responsibl Further, this code doesn't require running any external services. Instead of real `db` and `mailer` services, we can pass mocks and assert that `db.saveUser` and `mailer.sendWelcomeEmail` have been called with the proper arguments. -Unit Tests can easily be written to cover the above class. An integration test can be added by invoking the function (`serverless invoke`) with fixture email address, check if user is actually saved to DB and check if email was received to see if everything is working together. +Unit Tests can easily be written to cover the above class. An integration test can be added by invoking the function (`osls invoke`) with fixture email address, check if user is actually saved to DB and check if email was received to see if everything is working together. ## Other diff --git a/docs/guides/upgrading-to-v4.md b/docs/guides/upgrading-to-v4.md index df8720292..066a68737 100644 --- a/docs/guides/upgrading-to-v4.md +++ b/docs/guides/upgrading-to-v4.md @@ -111,14 +111,14 @@ Versioned plugin configuration entries such as `example-osls-plugin@1.2.3` now f The legacy `plugins.localPath` option is still supported, but module names loaded from that directory must use npm package-name syntax. If you previously loaded uppercase local plugin names such as `MyPlugin` through `.serverless_plugins` or `plugins.localPath`, rename them to lowercase npm-style names or reference them with explicit `./` local paths. -`serverless --help` and the `plugin` management commands skip invalid entries with a warning, so you can still inspect the service and fix the configuration. +`osls --help` and the `plugin` management commands skip invalid entries with a warning, so you can still inspect the service and fix the configuration. ### `plugin install` accepts stricter package specs -`serverless plugin install --name` now accepts only npm package names with optional semver ranges or npm dist-tags. Embedded literal quotes are rejected; quote the whole `--name` value at the shell level when the version range contains spaces or shell metacharacters: +`osls plugin install --name` now accepts only npm package names with optional semver ranges or npm dist-tags. Embedded literal quotes are rejected; quote the whole `--name` value at the shell level when the version range contains spaces or shell metacharacters: ```bash -serverless plugin install --name 'example-osls-plugin@^1.0.0 || 2' +osls plugin install --name 'example-osls-plugin@^1.0.0 || 2' ``` Package aliases, `file:`, `link:`, `workspace:`, `git+`, `github:`, `http:`, `https:`, `npm:`, tarball paths, absolute paths, and relative paths are no longer accepted by `plugin install`. @@ -127,7 +127,7 @@ npm lifecycle scripts are ignored by default during plugin install. Pass `--allo ### `plugin uninstall` accepts package names only -`serverless plugin uninstall --name` now accepts only a bare npm package name. Versioned package specs such as `example-osls-plugin@1.2.3` fail with `INVALID_PLUGIN_UNINSTALL_SPEC`. +`osls plugin uninstall --name` now accepts only a bare npm package name. Versioned package specs such as `example-osls-plugin@1.2.3` fail with `INVALID_PLUGIN_UNINSTALL_SPEC`. ### `variablesResolutionMode: 20210219` is rejected @@ -156,7 +156,7 @@ 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 `serverless deploy` to remove the old resources. +2. Running `osls deploy` to remove the old resources. 3. Restoring the EventBridge events and deploying again. See [EventBridge](../events/event-bridge.md). @@ -190,7 +190,7 @@ Packaging also now fails fast with `EVENT_INVOKE_CONFIG_CONDITIONAL_DESTINATION` ### `logs` and `metrics` time options are parsed strictly -The `--startTime` option of `serverless logs` and the `--startTime` / `--endTime` options of `serverless metrics` are now parsed by a single strict parser: +The `--startTime` option of `osls logs` and the `--startTime` / `--endTime` options of `osls metrics` are now parsed by a single strict parser: - Unix epoch values (e.g. `1469694264`) now work in both commands; they were documented but broken (in `logs` they silently produced a wrong time range, in `metrics` they failed). Digits-only values of 9+ characters are parsed as epoch seconds, or as epoch milliseconds when at or above `10^12` (13+ characters). - Dates and datetimes without an explicit UTC offset are now consistently interpreted as **UTC** in both commands. Previously `metrics` interpreted datetimes (e.g. `2016-07-01T10:00`) in the machine's local time zone. @@ -328,8 +328,8 @@ See [Deprecations](./deprecations.md). ## New in v4 -- `provider.pruneFunctionVersions` — opt-in cleanup of old Lambda function and layer versions after a full `serverless deploy`, keeping the newest N. Replaces third-party version-pruning plugins. See [Functions](./functions.md). -- `functions[].durableConfig` — AWS Lambda Durable Functions support: osls publishes a function version, generates a `durable` alias that event targets and Lambda Function URLs invoke through, and adds the required durable execution IAM permissions. Invoke durable executions with `serverless invoke --qualifier durable --durable-execution-name `. See [AWS Lambda Durable Functions](./functions.md#aws-lambda-durable-functions). +- `provider.pruneFunctionVersions` — opt-in cleanup of old Lambda function and layer versions after a full `osls deploy`, keeping the newest N. Replaces third-party version-pruning plugins. See [Functions](./functions.md). +- `functions[].durableConfig` — AWS Lambda Durable Functions support: osls publishes a function version, generates a `durable` alias that event targets and Lambda Function URLs invoke through, and adds the required durable execution IAM permissions. Invoke durable executions with `osls invoke --qualifier durable --durable-execution-name `. See [AWS Lambda Durable Functions](./functions.md#aws-lambda-durable-functions). ## Getting help diff --git a/docs/guides/variables.md b/docs/guides/variables.md index 16fa17a3e..24433ddd9 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 `osls 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 `osls 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 `osls 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}`. @@ -173,7 +173,7 @@ functions: handler: handler.world ``` -In the above example, you're dynamically adding a prefix to the function names by referencing the `stage` option that you pass in the CLI when you run `serverless deploy --stage dev`. So when you deploy, the function name will always include the stage you're deploying to. +In the above example, you're dynamically adding a prefix to the function names by referencing the `stage` option that you pass in the CLI when you run `osls deploy --stage dev`. So when you deploy, the function name will always include the stage you're deploying to. ## Reference CloudFormation Outputs @@ -497,7 +497,7 @@ functions: - schedule: ${file(./scheduleConfig.js):rate} # Reference a specific module ``` -Address resolution follows the value's own properties. If a JS file exports (or its resolver function returns) a `Proxy`-backed object, address segments are resolved through the proxy's `get` handler instead. The keys `__proto__`, `prototype` and `constructor` are only followed when they are own properties of the value, so an address can never traverse into prototype internals. The same rules apply when such a value is reached another way — a `${self:...}` reference into a property that was populated from a `${file(...)}` variable, and `serverless print --path`, also follow a Proxy's `get` handler, with the same restriction on `__proto__`, `prototype` and `constructor`. +Address resolution follows the value's own properties. If a JS file exports (or its resolver function returns) a `Proxy`-backed object, address segments are resolved through the proxy's `get` handler instead. The keys `__proto__`, `prototype` and `constructor` are only followed when they are own properties of the value, so an address can never traverse into prototype internals. The same rules apply when such a value is reached another way — a `${self:...}` reference into a property that was populated from a `${file(...)}` variable, and `osls print --path`, also follow a Proxy's `get` handler, with the same restriction on `__proto__`, `prototype` and `constructor`. ### Exporting a function @@ -626,7 +626,7 @@ functions: handler: handler.hello ``` -What this says is to use the `stage` CLI option if it exists, if not, use the default stage (which lives in `provider.stage`). So during development you can safely deploy with `serverless deploy`, but during production you can do `serverless deploy --stage production` and the stage will be picked up for you without having to make any changes to `serverless.yml`. +What this says is to use the `stage` CLI option if it exists, if not, use the default stage (which lives in `provider.stage`). So during development you can safely deploy with `osls deploy`, but during production you can do `osls deploy --stage production` and the stage will be picked up for you without having to make any changes to `serverless.yml`. You can have as many variable references as you want, from any source you want, and each of them can be of different type and different name. diff --git a/docs/guides/workflow.md b/docs/guides/workflow.md index ef8b09686..587b5f763 100644 --- a/docs/guides/workflow.md +++ b/docs/guides/workflow.md @@ -5,10 +5,10 @@ Quick recommendations and tips for various processes. ### Development Workflow 1. Write your functions -2. Use `serverless deploy` only when you've made changes to `serverless.yml` and in CI/CD systems. For more information on setting up CI/CD for your serverless app, read [this article](https://serverless.com/blog/ci-cd-workflow-serverless-apps-with-circleci). -3. Use `serverless deploy function -f myFunction` to rapidly deploy changes when you are working on a specific AWS Lambda Function. -4. Use `serverless invoke -f myFunction -l` to test your AWS Lambda Functions on AWS. -5. Open up a separate tab in your console and stream logs in there via `serverless logs -f myFunction -t`. +2. Use `osls deploy` only when you've made changes to `serverless.yml` and in CI/CD systems. For more information on setting up CI/CD for your serverless app, read [this article](https://serverless.com/blog/ci-cd-workflow-serverless-apps-with-circleci). +3. Use `osls deploy function -f myFunction` to rapidly deploy changes when you are working on a specific AWS Lambda Function. +4. Use `osls invoke -f myFunction -l` to test your AWS Lambda Functions on AWS. +5. Open up a separate tab in your console and stream logs in there via `osls logs -f myFunction -t`. 6. Write tests to run locally. ### Using stages @@ -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] +osls create -p [TARGET DIRECTORY] --template-path [LOCAL TEMPLATE DIRECTORY] ``` ##### Install A Service @@ -40,7 +40,7 @@ serverless create -p [TARGET DIRECTORY] --template-url [TEMPLATE URL] This is a convenience method to install a pre-made service locally by downloading the GitHub repository and unzipping it. ```bash -serverless install -u [GITHUB URL OF SERVICE] +osls install -u [GITHUB URL OF SERVICE] ``` ##### Deploy All @@ -48,7 +48,7 @@ serverless install -u [GITHUB URL OF SERVICE] Use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or you simply want to deploy all changes within your Service at the same time. ```bash -serverless deploy -s [STAGE NAME] -r [REGION NAME] -v +osls deploy -s [STAGE NAME] -r [REGION NAME] -v ``` ##### Deploy Function @@ -56,7 +56,7 @@ serverless deploy -s [STAGE NAME] -r [REGION NAME] -v Use this to quickly overwrite your AWS Lambda code on AWS, allowing you to develop faster. ```bash -serverless deploy function -f [FUNCTION NAME] -s [STAGE NAME] -r [REGION NAME] +osls deploy function -f [FUNCTION NAME] -s [STAGE NAME] -r [REGION NAME] ``` ##### Invoke Function @@ -64,7 +64,7 @@ serverless deploy function -f [FUNCTION NAME] -s [STAGE NAME] -r [REGION NAME] Invokes an AWS Lambda Function on AWS and returns logs. ```bash -serverless invoke -f [FUNCTION NAME] \ +osls invoke -f [FUNCTION NAME] \ -s [STAGE NAME] \ -r [REGION NAME] \ -l @@ -75,5 +75,5 @@ serverless invoke -f [FUNCTION NAME] \ Open up a separate tab in your console and stream all logs for a specific Function using this command. ```bash -serverless logs -f [FUNCTION NAME] -s [STAGE NAME] -r [REGION NAME] +osls logs -f [FUNCTION NAME] -s [STAGE NAME] -r [REGION NAME] ```