Project Configuration YAML File

Validated on 23 May 2022 • Last edited on 14 Aug 2024

Functions are blocks of code that run on demand without the need to manage any infrastructure. Develop on your local machine, test your code from the command line (using doctl), then deploy to a production namespace or App Platform — no servers required.

The project.yml file is a YAML configuration file in the root directory of a project which lets you define environment variables, parameters, and other properties for the project and the packages and functions within it.

The structure of the information in project.yml is aligned with the structure of the project. Using this structure, you can scope the properties you define in project.yml to one of three different levels:

Scoped to the project, which is the top-level collection of resources, including at least one package
Scoped to a package, which is a collection of functions
Scoped to individual functions, which may be called actions in the configuration file.

Additionally, the build process for project.yml uses a templating syntax which supports including variables from local .env files or App Platform environment variables.

Properties

Parameters

Parameters are passed into function invocations alongside query or POST parameters from the HTTP request.

Scope: Projects, packages, and functions.
Valid values: Any structure that converts to valid JSON, including nested lists and objects.

This parameters example defines two parameters: param1, which has a single value, and param2, which is a list of two values:

parameters:
  param1: <value>
  param2: 
    - <value>
    - <value>

Environment

Environment values defined in the configuration are added as the environment variables of the process that runs the function.

Scope: Projects, packages, and functions.
Valid values: Must be a string.

You can statically define environment variables in the project.yml file, as in this example:

environment:
  env1: <value>
  env2: <value>

You can also template environment variables from an .env file in the project filesystem or from App Platform’s environment variable configuration.

Main

The main parameter defines the entry point for a function.

Scope: Functions.
Valid values: Must be a string.

packages:
  - name: <package-name>
    functions:
      - name: <function-name>
        main: <main-entry-point>

If you don’t specify a main for a function, the build process tries to detect the correct entry point.

Runtime

The runtime parameter specifies the runtime package used by the function.

Scope: Functions.
Valid values: Any supported runtime. You can use the value default in place of the runtime version (for example, go:default instead of go:1.15).

packages:
  - name: <package-name>
    functions:
      - name: <function-name>
        runtime: <runtime>

If you do not specify a runtime, the build process tries to detect it.

Limits

The limits parameter lets you override the function’s default limits for timeout time, memory allocation, and total log size.

Scope: Functions.
Valid fields and values: An object with at least one field.
- timeout: Timeout time in milliseconds.
- memory: Memory allocation in megabytes.
- logs: Total log size in kilobytes.

packages:
- name: <package-name>
  functions:
    - name: <function-name>
      limits:
        timeout: <milliseconds>
        memory: <megabytes>
        logs: <kilobytes>

Triggers

The triggers parameter lets you create scheduled function triggers.

Scope: Functions.
Valid fields and values:
- name: A name for the trigger.
- sourceType: Currently only the scheduler type of trigger is supported.
- sourceDetails
  - cron: A string using cron syntax to set the trigger schedule.
  - withBody: Optional. An object to be passed as input to the function via POST.

packages:
- name: <package-name>
  functions:
    - name: <function-name>
      triggers:
      - name: <trigger-name>
        sourceType: scheduler
        sourceDetails: 
          cron: <string>
          withBody:  <object>

Web

The web parameter lets you create a web function, meaning you can access it using normal HTTP methods outside of the authenticated REST API. You can also set your web function to receive the request body as raw base64-encoded text by using web: raw. To secure your web function, use the webSecure parameter.

Scope: Functions.
Valid values: Either true, false, or raw. A true value enables web access to the function, and false disables access. A raw value enables web access and also passes in request bodies as raw, base64-encoded text. If you omit the web parameter entirely, it defaults to true.

packages:
- name: <package-name>
  functions:
    - name: <function-name>
      web: true

WebSecure

The webSecure parameter enables authentication for web functions and sets the secret token to the given value. You must provide the secret during HTTP requests by using the X-Require-Whisk-Auth: <secret-token> header.

Scope: Functions.
Valid values: Any string.

packages:
- name: <package-name>
  functions:
    - name: <function-name>
      web: true
      webSecure: <secret-token>

Templating

You can template variables in project.yml from local .env files or App Platform environment variables. This is especially useful in combination with App Platform’s encrypted variables for secret storage.

You can substitute in variables from the runtime environment using the format "${SYMBOL}", where SYMBOL is the name of the variable specified in App Platform. We recommend using quotes around the variable substitution to ensure proper parsing.

Examples

Basic

Here is a simplified example of a project.yml file:

    
        
            
parameters: # project scope
    param1: value
environment:
    env1: value
packages:
  - name: package1
    parameters: # package scope
    environment:
    functions:
      - name: function1
        parameters: # function scope
        environment:
        limits: 
        runtime: 'nodejs:default'
        main: ''

This example defines a single package, package1, and a single function within it, function1, which uses the nodejs:default runtime. This example also defines one parameter, param1, and one environment variable, env1, at the package scope.

With Templating

The following simplified YAML example includes some templated variables:

    
        
            
environment:
  # ENV is statically defined as "production" in this example:
  ENV: production
packages:
  - name: store
    environment:
      # DATABASE_URL will be substituted to the DATABASE_URL_READ_ONLY value
      # defined in App Platform's environment variable configuration. 
      # NOTE: The receiving variable name does not need to match the name as
      # defined in the app / component config. This facilitates narrowly
      # scoped or overlapping values.
      DATABASE_URL: "${DATABASE_URL_READ_ONLY}"
    functions:
      - name: buy 
        environment:
          # PAYMENT_API_KEY will substitute the PAYMENT_API_KEY variable
          # from App Platform's runtime variable configuration.
          PAYMENT_API_KEY: "${PAYMENT_API_KEY}"
          # DATABASE_URL will be substituted with the DATABASE_URL_WRITE 
          # value defined in App Platform's environment variable config.
          DATABASE_URL: "${DATABASE_URL_WRITE}"

By default, the doctl serverless deploy command looks for an .env file in the same directory as the project.yml file. You can also add an --env <path to .env-formatted file> flag to specify an alternate file name and location anywhere on the filesystem.