> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/3.0/use-deployments/overview-4/lambda-services.md).

# Lambda services

Configure AWS Lambda services in Harness — function definitions, alias definitions, and artifact sources.

A Harness service for AWS Lambda holds the function definition, an optional alias definition for canary deployments, and the artifact source that points to your function code. Services are independent of pipelines; configure one and reuse it across stages and pipelines.

***

## What you will learn <a href="#what-you-will-learn" id="what-you-will-learn"></a>

* How to create an AWS Lambda service in Harness.
* How to configure function definitions and alias definitions.
* Which artifact source types are supported and how to configure each one.

***

## Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **AWS connector:** A connector with an IAM role that has `AWSLambda_FullAccess` and `AmazonS3ReadOnlyAccess` (or `AmazonEC2ContainerRegistryReadOnly` for ECR). Go to [AWS IAM permissions](/continuous-delivery/3.0/use-deployments/overview-4.md#aws-iam-permissions) to review the required policies.
* **Function artifact:** A ZIP file in an S3 bucket, or a container image in ECR.

***

## Create a Lambda service <a href="#create-a-lambda-service" id="create-a-lambda-service"></a>

1. Go to **Deployments**, expand the drop-down, and select **Services** under **Resources**.
2. Click **+ New Service**.
3. In the **Create service** panel, select **AWS Lambda** from the **Deployment Target** drop-down.
4. Harness auto-generates a name and ID. You can change both.
5. Under **Storage**, select **Inline** (Harness stores the service configuration) or a Git repository.
6. Add a **function definition**, an optional **alias definition**, and an **artifact source** as described below.
7. Click **Create**.

***

## Add a function definition <a href="#add-a-function-definition" id="add-a-function-definition"></a>

A function definition tells Harness the configuration of the Lambda function to create or update: its name, handler, runtime, memory, and timeout. Harness reads this file at deploy time and applies it to the function in AWS.

Click **+ Add** under **AWS Lambda Function Definition** and configure the manifest store.

| Field                   | Description                                                                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manifest Identifier** | A unique ID for this definition within the service.                                                                                            |
| **Source**              | Where the definition file is stored. Supports Harness Code, GitHub, Git, GitLab, Bitbucket, Azure Repos, and AWS S3.                           |
| **Repository**          | The repository that contains the file. Not shown for Bitbucket when using a repo-level connector — the repository is baked into the connector. |
| **Fetch**               | **Branch** to track a branch head, or **Commit** to pin to a specific SHA.                                                                     |
| **File Path**           | Path to the YAML file from the root of the repository.                                                                                         |

### Function definition YAML <a href="#function-definition-yaml" id="function-definition-yaml"></a>

The format of the function definition file depends on how the function is packaged.

**ZIP package (S3, Artifactory, Nexus)**

Use this format when your artifact is a ZIP file. The `handler` and `runtime` fields are required because Lambda needs to know how to invoke the code inside the ZIP.

| Field          | Required | Description                                                                                |
| -------------- | -------- | ------------------------------------------------------------------------------------------ |
| `functionName` | Yes      | The Lambda function name to create or update.                                              |
| `handler`      | Yes      | The function entry point, for example `index.handler`.                                     |
| `runtime`      | Yes      | The Lambda runtime identifier, for example `nodejs18.x` or `python3.11`.                   |
| `memorySize`   | No       | Memory allocated to the function in MB. Default is `128`.                                  |
| `timeout`      | No       | Maximum execution time in seconds. Default is `3`, maximum is `900`.                       |
| `role`         | No       | ARN of the IAM execution role. If omitted, Harness uses the role on the existing function. |
| `environment`  | No       | Environment variables to set on the function.                                              |
| `layers`       | No       | List of Lambda layer ARNs to attach.                                                       |

<details>

<summary>Example ZIP function definition</summary>

```yaml
functionName: harness-lambda-demo
handler: index.handler
runtime: nodejs18.x
memorySize: 128
timeout: 30
role: arn:aws:iam::123456789012:role/lambda-execution-role
environment:
  variables:
    LOG_LEVEL: info
    APP_ENV: production
```

</details>

**Container image (ECR)**

Use this format when your artifact is a container image from ECR. Image functions do not have a `handler` or `runtime` — those are defined inside the container. The `role` field is required because Harness cannot infer it from the image.

| Field          | Required | Description                                                          |
| -------------- | -------- | -------------------------------------------------------------------- |
| `functionName` | Yes      | The Lambda function name to create or update.                        |
| `packageType`  | Yes      | Must be `Image`.                                                     |
| `role`         | Yes      | ARN of the IAM execution role.                                       |
| `memorySize`   | No       | Memory allocated to the function in MB. Default is `128`.            |
| `timeout`      | No       | Maximum execution time in seconds. Default is `3`, maximum is `900`. |
| `environment`  | No       | Environment variables to set on the function.                        |

<details>

<summary>Example container image function definition</summary>

```yaml
functionName: <+serviceVariables.functionName>
packageType: Image
role: <+serviceVariables.role>
memorySize: 512
timeout: 30
```

For container image functions, define `functionName` and `role` as service variables so the definition stays portable across environments.

</details>

{% hint style="info" %}
**Service variables for ECR functions**

When using a container image, add `functionName` and `role` as service variables (under **Metadata → Variables**). Reference them in the function definition as `<+serviceVariables.functionName>` and `<+serviceVariables.role>`.

For ZIP functions, add `functionName` and `runtime` as service variables and reference them the same way.
{% endhint %}

***

## Add a function alias definition <a href="#add-a-function-alias-definition" id="add-a-function-alias-definition"></a>

An alias definition tells Harness the alias name to create or update during deployment. How it behaves depends on the deployment strategy:

* **Canary:** Required. The canary deploy step creates a weighted alias to split traffic between the previous and new versions. Without an alias definition, the canary deploy step cannot route traffic and the pipeline fails.
* **Rolling:** Optional. When present, the rolling deploy step updates the alias to point to the new version at 100% weight after publishing it. When absent, the rolling deploy completes without creating or modifying any alias.

Click **+ Add** under **AWS Lambda Function Alias Definition** and configure the manifest store using the same fields as the function definition.

### Alias definition YAML <a href="#alias-definition-yaml" id="alias-definition-yaml"></a>

| Field          | Required | Description                                                   |
| -------------- | -------- | ------------------------------------------------------------- |
| `functionName` | Yes      | The Lambda function name, must match the function definition. |
| `name`         | Yes      | The alias name to create or update, for example `live`.       |
| `description`  | No       | A description of the alias.                                   |

<details>

<summary>Example alias definition</summary>

```yaml
functionName: harness-lambda-demo
name: live
description: Harness-managed alias
```

</details>

{% hint style="warning" %}
**ZIP artifact canary: alias required**

If your artifact is a ZIP file (S3, Artifactory, or Nexus) and you are using the canary strategy, add an alias definition to the service before running the pipeline. Without one, the canary deploy step has no alias name to target and the pipeline fails.

ECR container image canary deployments do not require an alias definition — the canary deploy step manages the alias automatically.
{% endhint %}

***

## Alias behavior <a href="#alias-behavior" id="alias-behavior"></a>

The rolling deploy step reads the service's manifest list at runtime and acts on what it finds:

| Service manifests                      | What the rolling deploy step does                                                                       |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Function definition only               | Publishes a new version; no alias is created or updated.                                                |
| Function definition + alias definition | Publishes a new version; creates or updates the named alias to point to the new version at 100% weight. |

The alias definition type in Harness is `AwsLambdaFunctionAliasDefinition`. Go to [Add a function alias definition](#add-a-function-alias-definition) to configure the alias.

{% hint style="info" %}
**Rolling vs. canary with an alias**

Both rolling and canary can use an alias, but they behave differently. A rolling deploy sets the alias to 100% of the new version in one step. A canary deploy splits traffic across versions using a weighted alias and promotes gradually.
{% endhint %}

***

## Alias and artifact type requirements <a href="#alias-and-artifact-type-requirements" id="alias-and-artifact-type-requirements"></a>

The canary deploy step behaves differently depending on whether your function artifact is a ZIP package or a container image from ECR.

| Artifact type                | Alias definition required                                               | Execution path                                                                             |
| ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| ZIP (S3, Artifactory, Nexus) | Yes — add an `AwsLambdaFunctionAliasDefinition` manifest to the service | Manifest fetch → Harness rendering → artifact download → canary deploy → traffic shifts    |
| Container image (ECR)        | No — the canary deploy step manages the alias automatically             | Manifest fetch → canary deploy → traffic shifts (rendering and download steps are skipped) |

For ZIP artifacts, the canary deploy step reads the alias manifest to determine the alias name and creates a weighted alias with that name. Without the manifest, the step has no alias name to target and the pipeline fails.

For ECR image functions, there is no ZIP to download and no manifest to render. The canary deploy step handles alias management internally without requiring a declared alias manifest in the service. The service only needs a function definition manifest (`AwsLambdaFunctionDefinition`).

***

## Add an artifact source <a href="#add-an-artifact-source" id="add-an-artifact-source"></a>

The artifact source points to the function code package. Harness fetches it at deploy time and uploads it to Lambda.

Click **+ Add** under **Artifact source** and select a type.

{% tabs %}
{% tab title="Amazon S3" %}
Use this type for a function packaged as a ZIP file stored in S3.

| Field           | Description                                                                              |
| --------------- | ---------------------------------------------------------------------------------------- |
| **Connector**   | A Harness AWS connector with `AmazonS3ReadOnlyAccess`.                                   |
| **Region**      | The AWS region where the S3 bucket is located.                                           |
| **Bucket Name** | The name of the S3 bucket.                                                               |
| **File Path**   | The path to the ZIP file within the bucket, for example `lambda-functions/function.zip`. |
| {% endtab %}    |                                                                                          |

{% tab title="Amazon ECR" %}
Use this type for a function packaged as a container image stored in ECR.

| Field          | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| **Connector**  | A Harness AWS connector with `AmazonEC2ContainerRegistryReadOnly`.                   |
| **Region**     | The AWS region where the ECR repository is located.                                  |
| **Image Path** | The repository name, for example `my-lambda-image`.                                  |
| **Tag**        | The image tag. Supports a fixed value, runtime input (`<+input>`), or an expression. |
| {% endtab %}   |                                                                                      |

{% tab title="Artifactory" %}

| Field                  | Description                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------- |
| **Connector**          | A Harness Artifactory connector.                                                       |
| **Repository**         | The Artifactory repository name.                                                       |
| **Artifact Directory** | The path to the directory containing the artifact.                                     |
| **Artifact Details**   | Select **Value** and enter the artifact name, or select **Regex** to match by pattern. |
| {% endtab %}           |                                                                                        |
| {% endtabs %}          |                                                                                        |

***

## Advanced service options <a href="#advanced-service-options" id="advanced-service-options"></a>

Expand **Metadata** at the bottom of the service panel to access additional configuration:

* **Config Files:** Attach configuration files such as properties files or scripts. Harness makes these available to the delegate at deploy time.
* **Variables:** Define service-level variables for use in pipeline expressions. Reference them as:
  * CEL: `${{serviceVariables.<name>}}`
  * JEXL: `<+serviceVariables.<name>>`

***

## Use an existing service <a href="#use-an-existing-service" id="use-an-existing-service"></a>

When you configure a stage, select **Existing** in the **Choose service** panel. Use the **Project**, **Organization**, and **Account** tabs to select from the appropriate scope. Only AWS Lambda services appear when your stage deployment type is AWS Lambda.

***

## Next steps <a href="#next-steps" id="next-steps"></a>

* Go to [Lambda infrastructure](/continuous-delivery/3.0/use-deployments/overview-4/lambda-infrastructure.md) to configure environments and infrastructure definitions.
* Go to [Overview](/continuous-delivery/3.0/use-deployments/overview-4.md#deployment-strategies) to review canary and rolling strategy options.

{% @harness-feedback/feedback %}