AWS CDK Asset Node.js Proxy Agent v5

2.0.166 · active · verified Thu Apr 16

The `aws-cdk-asset-node-proxy-agent-v5` library provides an AWS CDK Construct that configures Node.js-based assets (e.g., Lambda functions) to use an HTTP/HTTPS proxy during their build and bundling phases. This is critical for CDK deployments in corporate environments where internet access requires going through a proxy, leveraging the `proxy-agent` Node.js library. It is an experimental construct from `cdklabs` and is currently at version 2.0.166, aligning with AWS CDK v2 releases, with updates tied to CDK's release cadence.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.asset_node_proxy_agent_v5'
```
cause Incorrect import path. Python packages convert hyphens in their PyPI names to underscores for module names.

fix Change the import statement to `from aws_cdk_asset_node_proxy_agent_v5 import NodeProxyAgent`.
```
Error: unable to get local issuer certificate
```
cause Often seen when using a corporate proxy with SSL interception, and the certificate authority (CA) certificate is not trusted by the Node.js environment during asset bundling.

fix Ensure that the CA certificate is available and trusted within your CDK build environment, potentially by setting the `NODE_EXTRA_CA_CERTS` environment variable or adding the certificate to the system trust store.
```
npm ERR! code ENOTFOUND
```
cause Node.js package manager (npm) cannot resolve hostnames, often indicating a misconfigured proxy, incorrect `NO_PROXY` settings, or network issues.

fix Double-check the `http_proxy`, `https_proxy`, and crucially, the `no_proxy` settings passed to `NodeProxyAgent`. Ensure `no_proxy` includes internal hosts that should bypass the proxy. Verify proxy server accessibility.

Warnings

gotcha The `NodeProxyAgent` configures proxy settings for Node.js *asset bundling* (e.g., when `NodejsFunction` builds its code package). It does NOT configure runtime proxy settings for the deployed Lambda function itself. If your Lambda needs to egress through a proxy at runtime, that must be configured separately.
Fix: Understand the distinction between build-time and runtime proxying. For runtime proxying, use Lambda environment variables or a custom layer that configures `https-proxy-agent` or similar.
breaking This construct is specific to Node.js `proxy-agent` v5. If your project relies on an older or newer major version of `proxy-agent` in a custom build step, this construct might not be compatible or could override existing configurations unexpectedly.
Fix: Ensure your Node.js asset's dependencies and build environment are compatible with `proxy-agent` v5. If using a different version, consider if this construct is necessary or if manual configuration is more appropriate.
gotcha The `http_proxy`, `https_proxy`, and `no_proxy` arguments to `NodeProxyAgent` override any existing `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables *during the asset bundling process*. Ensure your construct parameters correctly reflect the desired proxy configuration.
Fix: Explicitly pass all required proxy settings (including `no_proxy`) to the `NodeProxyAgent` constructor. Do not rely solely on environment variables if the construct is instantiated with parameters, as parameters take precedence.

Install

pip install aws-cdk-asset-node-proxy-agent-v5 Install with pip

Imports

NodeProxyAgent

wrong:

from aws_cdk.asset_node_proxy_agent_v5 import NodeProxyAgent

correct:

from aws_cdk_asset_node_proxy_agent_v5 import NodeProxyAgent

Python packages use underscores for their module names, not hyphens, despite PyPI name.

Quickstart

This quickstart demonstrates how to integrate `NodeProxyAgent` into your CDK application. It sets up an `NodeProxyAgent` instance to configure proxy settings for Node.js assets during synthesis, using environment variables for proxy URLs. A sample `NodejsFunction` is included, which will then use these proxy settings during its bundling process.

import os
from aws_cdk import App, Stack, Environment
from aws_cdk.aws_lambda_nodejs import NodejsFunction
from aws_cdk_asset_node_proxy_agent_v5 import NodeProxyAgent


class MyProxyStack(Stack):
    def __init__(self_stack, scope, id, **kwargs):
        super().__init__(scope, id, **kwargs)

        # Define proxy configuration - ensure these env vars are set in your build environment
        http_proxy = os.environ.get('HTTP_PROXY', '')
        https_proxy = os.environ.get('HTTPS_PROXY', '')
        no_proxy = os.environ.get('NO_PROXY', '')

        if http_proxy or https_proxy:
            # Instantiate the NodeProxyAgent construct
            NodeProxyAgent(self_stack, "NodeProxyAgent",
                           http_proxy=http_proxy,
                           https_proxy=https_proxy,
                           no_proxy=no_proxy
            )
            print(f"NodeProxyAgent configured with HTTP_PROXY: {http_proxy} and HTTPS_PROXY: {https_proxy}")
        else:
            print("No proxy environment variables found. NodeProxyAgent not configured.")

        # Example Node.js Lambda function, its bundling will use the configured proxy
        NodejsFunction(
            self_stack, "MyProxyEnabledFunction",
            entry="./lambda/index.ts", # Replace with your Node.js Lambda entry point
            handler="handler",
            memory_size=128
        )


app = App()
MyProxyStack(app, "MyProxyEnabledStack",
             env=Environment(account=os.environ.get('CDK_DEFAULT_ACCOUNT', '123456789012'),
                             region=os.environ.get('CDK_DEFAULT_REGION', 'us-east-1'))
)
app.synth()

view raw JSON →