DOCSEARCHbyAlgolia
Submit Docs

osls (Open Serverless)

repository·4.x·Indexed 20 days ago

https://github.com/oss-serverless/osls

An open-source CLI tool for deploying serverless applications on AWS using YAML configurations. It maintains compatibility with Serverless Framework v3 configurations and provides tools for service lifecycle management, function invocation, log inspection, and plugin extension. Supported event sources include HTTP APIs, REST APIs, ALB, S3, DynamoDB, EventBridge, and various messaging queues.

Tokens
132.7K
Snippets
483
Records
582
Agent score
66%

What's inside osls

  2. What is osls?

    4.x

    osls (Open Serverless) is an open-source CLI tool for deploying serverless applications on AWS. It uses a serverless.yml configuration file to define AWS Lambda functions, event sources, IAM permissions, and CloudFormation resources.

    It is an independent project that maintains compatibility with most Serverless Framework v3 configurations but is decoupled from the upstream Serverless Framework v4, its Dashboard, and its licensing services.

  3. Overview of the osls CLI

    4.x

    The osls CLI (also invokable as serverless or sls) is used for building, deploying, and operating serverless services on AWS. It supports a wide range of operations including service lifecycle management, inspection, scaffolding, plugin management, and configuration.

    To see the top-level command list, run:

    osls --help

    To see the usage and options for any specific command, append --help or -h to that command.

  4. New capabilities in osls v4

    4.x

    osls v4 introduces several major upgrades and features:

    • AWS SDK v3: Uses the modern AWS SDK for all AWS interactions.
    • IAM Identity Center (AWS SSO) support: Supports AWS SSO credentials via the AWS SDK v3 upgrade.
    • Lambda version pruning: You can opt-in to clean up old Lambda function and layer versions after a full deploy by using provider.pruneFunctionVersions.
    • AWS Lambda Durable Functions: By configuring functions[].durableConfig, osls will publish a function version, generate a durable alias for event targets to invoke, and automatically add the required IAM permissions.

  5. Explore osls reference documentation

    4.x

    The osls documentation is organized into several specialized reference sections:

    • Guides: Covers core concepts, build and test workflows, deployment and operation strategies, and general reference topics.
    • Function Events: A comprehensive list of every supported AWS Lambda event source.
    • CLI Reference: Detailed documentation for every osls command, including all available flags and options.

  6. Share outputs between services using variables

    4.x

    You can inject outputs from one service into another using the ${service.outputName} syntax. This creates an implicit dependency, causing osls to deploy the provider service first.

    1. Expose Output: In the provider service's serverless.yml, define the value in the resources.Outputs section.
    2. Pass Parameter: In serverless-compose.yml, reference the output under the params key of the consumer service.
    3. Consume Parameter: In the consumer service's serverless.yml, access the value using the ${param:parameterName} syntax.

    Important: If a service uses ${param:...}, you must run commands from the root using the service-specific syntax (e.g., osls service-a:deploy) because ${param:...} cannot be resolved outside of the osls compose context.

    # serverless-compose.yml
services:
  service-a:
    path: service-a
  service-b:
    path: service-b
    params:
      queueUrl: ${service-a.queueUrl}
    # service-a/serverless.yml
resources:
  Resources:
    MyQueue:
      Type: AWS::SQS::Queue
  Outputs:
    queueUrl:
      Value: !Ref MyQueue
    # service-b/serverless.yml
provider:
  environment:
    SERVICE_A_QUEUE_URL: ${param:queueUrl}

  7. Package functions individually

    4.x

    To optimize deployments, you can package functions independently instead of one large service-wide package.

    1. Set package.individually: true at the service level (to apply to all functions) or at the function level (to apply only to that function).
    2. Use patterns or artifact within the function's package block to customize its specific contents.
    3. When individually is true, function-level patterns are merged with service-wide patterns.

    Example: Mixed packaging strategy

    service: my-service
package:
  individually: true
  patterns:
    - '!excluded-by-default.json'

functions:
  hello:
    handler: handler.hello
    package:
      # This file is included in this function's package only
      patterns:
        - excluded-by-default.json
  world:
    handler: handler.hello
    package:
      patterns:
        - '!some-file.js'
    service: my-service
package:
  individually: true
functions:
  hello:
    handler: handler.hello
  world:
    handler: handler.hello
    package:
      individually: true

  8. Core concepts of osls

    4.x

    osls is a CLI tool designed to develop and deploy AWS Lambda functions and the associated AWS infrastructure. It manages both application code and infrastructure as a single unit. The core mental model consists of four primary abstractions:

    • Functions: The independent units of execution (AWS Lambda) containing your business logic (e.g., Node.js, Python, or Java code).
    • Events: The triggers that execute functions, such as HTTP requests via API Gateway, S3 uploads, CloudWatch schedules, or SNS messages. When you define an event, osls automatically provisions the necessary AWS infrastructure (like an API Gateway endpoint) to support it.
    • Resources: The AWS infrastructure components your functions interact with, such as DynamoDB tables, S3 buckets, or SNS topics. osls supports any resource definable in AWS CloudFormation.
    • Services: The unit of organization for a project. A service is defined by a configuration file and represents a collection of functions, events, and resources that are deployed together using the osls deploy command.

  9. Convert payload encoding with `contentHandling`

    4.x

    For non-proxy lambda integrations, use contentHandling to manage the conversion between text and binary payloads.

    Available values:

    • CONVERT_TO_BINARY: Base64-decodes a text payload into binary.
    • CONVERT_TO_TEXT: Base64-encodes a binary payload into text.

    You can set this for both request and response within an http event.

    functions:
  binaryExample:
    handler: binaryExample.handler
    events:
      - http:
          path: binary
          method: post
          integration: lambda
          request:
            contentHandling: CONVERT_TO_BINARY
          response:
            contentHandling: CONVERT_TO_TEXT

  10. How parameter resolution priority works

    4.x

    When using the ${param:XXX} variable, osls resolves the value using the following priority order:

    1. CLI Flags: Parameters passed via the --param flag.
    2. Stage-specific params: Values defined under params.<stage> in serverless.yml.
    3. Default params: Values defined under params.default in serverless.yml.
    4. Fallback value: If a fallback is provided in the syntax ${param:XXX, 'default value'}.

    If no value is found in any of these locations and no fallback is provided, the deployment will throw an error.

  11. What are osls plugins?

    4.x

    A plugin is custom JavaScript code that extends the osls framework with new features. Because osls is composed of a group of "core" plugins, custom plugins are written using the same patterns and lifecycle hooks as the core functionality.

    Security Warning: Plugins are executed as JavaScript code. Only install plugins from trusted sources. Treat configured plugins, local plugin paths, and the plugins.localPath setting as trusted code. Do not run osls commands against untrusted projects or pull requests that contain plugin configurations.

  12. How to attach event sources to functions in osls

    4.x

    In osls, you trigger Lambda functions by attaching event sources under the events key within your serverless.yml configuration file. Each supported AWS Lambda event source has its own specific configuration requirements. For a complete list of supported sources and their specific configuration schemas, refer to the individual event source documentation pages.

    functions:
  myFunction:
    handler: handler.hello
    events:
      - eventSourceType: # Configuration depends on the specific event source