OpenMCF logoOpenMCF

Loading...

AWS HTTP API Gateway

Deploys an AWS API Gateway HTTP API (v2) with a bundled stage, routes with inline integrations, and optional JWT or Lambda authorizers. HTTP APIs offer lower latency and cost compared to REST APIs, with native support for Lambda proxy integration, HTTP proxy integration, CORS, and automatic deployments.

What Gets Created

When you deploy an AwsHttpApiGateway resource, OpenMCF provisions:

  • HTTP API — an API Gateway v2 HTTP API with configured CORS, description, and endpoint settings
  • Stage — a deployment stage (defaults to $default with auto-deploy enabled), with optional access logging and throttling
  • Integrations — deduplicated backend integrations (Lambda proxy or HTTP proxy) shared across routes with identical configuration
  • Routes — API routes mapping request patterns (e.g., GET /users, POST /orders/{id}, $default) to their corresponding integrations
  • Authorizers — optional JWT or Lambda (REQUEST) authorizers referenced by routes for request authorization

Prerequisites

  • AWS credentials configured via environment variables or OpenMCF provider config
  • AWS region specified in provider config or environment
  • Lambda functions already deployed if using AWS_PROXY integrations
  • HTTP endpoints reachable if using HTTP_PROXY integrations
  • Cognito User Pool or OIDC provider if using JWT authorizers
  • Lambda authorizer function if using REQUEST authorizers

Quick Start

Create a file api.yaml:

apiVersion: aws.openmcf.org/v1
kind: AwsHttpApiGateway
metadata:
  name: my-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsHttpApiGateway.my-api
spec:
  region: us-east-1
  routes:
    - routeKey: "$default"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:my-function"

Deploy:

openmcf apply -f api.yaml

This creates an HTTP API with a single catch-all route ($default) that forwards all requests to the specified Lambda function. A $default stage with auto-deploy is created automatically.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
regionstringThe AWS region where the resource will be created (e.g., "us-west-2", "eu-west-1")Non-empty
routesAwsHttpApiGatewayRoute[]API routes mapping request patterns to backend integrationsMinimum 1 item
routes[].routeKeystringRoute key defining the request pattern (e.g., "GET /users", "POST /orders/{id}", "$default")Non-empty
routes[].integrationobjectBackend integration that processes requests matching this routeRequired
routes[].integration.integrationTypestringIntegration type: "AWS_PROXY" (Lambda) or "HTTP_PROXY" (HTTP endpoint)Non-empty; must be "AWS_PROXY" or "HTTP_PROXY"
routes[].integration.integrationUriStringValueOrRefLambda function ARN for AWS_PROXY, upstream HTTP URL for HTTP_PROXY. Can reference AwsLambda via valueFrom.Required

Optional Fields

FieldTypeDefaultDescription
descriptionstring—Human-readable description of the API (max 1024 characters)
disableExecuteApiEndpointboolfalseDisable the default execute-api endpoint when using a custom domain
corsConfiguration.allowOriginsstring[][]Origins allowed to make cross-origin requests (e.g., "https://example.com", "*")
corsConfiguration.allowMethodsstring[][]HTTP methods allowed for cross-origin requests (e.g., "GET", "POST", "OPTIONS")
corsConfiguration.allowHeadersstring[][]Request headers allowed in cross-origin requests (e.g., "Content-Type", "Authorization")
corsConfiguration.exposeHeadersstring[][]Response headers exposed to the browser in cross-origin responses
corsConfiguration.maxAgeSecondsint0Maximum time in seconds that browsers cache CORS preflight results (0–86400)
corsConfiguration.allowCredentialsboolfalseWhether the API supports credentials (cookies, authorization headers) in cross-origin requests
stage.namestring"$default"Stage name. Named stages (e.g., "prod") append the name to the invoke URL path.
stage.autoDeploybooltrueAutomatic deployment when routes, integrations, or authorizers change
stage.accessLog.destinationArnStringValueOrRef—CloudWatch Log Group ARN for access log delivery. Can reference AwsCloudwatchLogGroup via valueFrom.
stage.accessLog.formatstring—Log format template using API Gateway access log variables (e.g., $context.requestId)
stage.defaultThrottle.burstLimitint0Maximum concurrent requests (token bucket size)
stage.defaultThrottle.rateLimitdouble0Steady-state request rate limit in requests per second
stage.stageVariablesmap<string, string>{}Stage variables passed to integrations as environment-specific configuration
routes[].authorizationTypestring"NONE"Authorization type: "NONE", "JWT", or "AWS_IAM"
routes[].authorizerNamestring—Name of the authorizer to use. Required when authorizationType is "JWT". Must match a defined authorizer.
routes[].authorizationScopesstring[][]OAuth 2.0 scopes required for JWT authorization
routes[].integration.payloadFormatVersionstring"2.0"Payload format version for Lambda integrations: "2.0" (recommended) or "1.0". Only applies to AWS_PROXY.
routes[].integration.integrationMethodstring—HTTP method for the integration request. Defaults to the route method for HTTP_PROXY. Always POST for AWS_PROXY.
routes[].integration.timeoutMillisecondsint30000Integration timeout in milliseconds (50–30000). Returns 504 if the backend does not respond in time.
authorizers[].namestring—Unique authorizer name (1–128 characters). Routes reference authorizers by this name.
authorizers[].authorizerTypestring—Authorizer type: "JWT" or "REQUEST"
authorizers[].jwtConfiguration.issuerstring—Token issuer URL. Required for JWT authorizers. (e.g., "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123")
authorizers[].jwtConfiguration.audiencesstring[][]Expected JWT audiences (e.g., Cognito app client ID)
authorizers[].authorizerUriStringValueOrRef—Lambda function invoke ARN for REQUEST authorizers. Can reference AwsLambda via valueFrom.
authorizers[].authorizerCredentialsArnStringValueOrRef—IAM role ARN that API Gateway assumes to invoke the Lambda authorizer. Can reference AwsIamRole via valueFrom.
authorizers[].identitySourcesstring[][]Identity sources for token extraction (e.g., "$request.header.Authorization")
authorizers[].resultTtlSecondsint0Time in seconds that API Gateway caches the authorizer result (0–3600)
authorizers[].enableSimpleResponsesboolfalseEnable simple {"isAuthorized": true/false} responses from Lambda authorizers. Only for REQUEST authorizers.
authorizers[].authorizerPayloadFormatVersionstring—Payload format version for the Lambda authorizer event: "2.0" (recommended) or "1.0". Only for REQUEST authorizers.

Examples

Multi-Route API with CORS

Multiple routes to different Lambda functions with cross-origin support:

apiVersion: aws.openmcf.org/v1
kind: AwsHttpApiGateway
metadata:
  name: users-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsHttpApiGateway.users-api
spec:
  region: us-east-1
  description: "Users service API"
  corsConfiguration:
    allowOrigins:
      - "https://app.example.com"
    allowMethods:
      - "GET"
      - "POST"
      - "PUT"
      - "DELETE"
      - "OPTIONS"
    allowHeaders:
      - "Content-Type"
      - "Authorization"
    maxAgeSeconds: 3600
    allowCredentials: true
  routes:
    - routeKey: "GET /users"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:list-users"
    - routeKey: "POST /users"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:create-user"
    - routeKey: "GET /users/{id}"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:get-user"

JWT-Protected API with Cognito

Routes guarded by a JWT authorizer backed by Amazon Cognito:

apiVersion: aws.openmcf.org/v1
kind: AwsHttpApiGateway
metadata:
  name: secure-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsHttpApiGateway.secure-api
spec:
  region: us-east-1
  description: "Secured API with Cognito JWT authorization"
  corsConfiguration:
    allowOrigins:
      - "https://app.example.com"
    allowMethods:
      - "GET"
      - "POST"
    allowHeaders:
      - "Content-Type"
      - "Authorization"
  routes:
    - routeKey: "GET /profile"
      authorizationType: "JWT"
      authorizerName: "cognito-auth"
      authorizationScopes:
        - "openid"
        - "profile"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:get-profile"
    - routeKey: "POST /orders"
      authorizationType: "JWT"
      authorizerName: "cognito-auth"
      authorizationScopes:
        - "openid"
        - "orders:write"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:create-order"
    - routeKey: "GET /health"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          value: "arn:aws:lambda:us-east-1:123456789012:function:healthcheck"
  authorizers:
    - name: "cognito-auth"
      authorizerType: "JWT"
      jwtConfiguration:
        issuer: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123XYZ"
        audiences:
          - "1a2b3c4d5e6f7g8h9i0j"
      identitySources:
        - "$request.header.Authorization"

HTTP Proxy with Stage Configuration and Throttling

An HTTP proxy API with access logging and default throttle settings:

apiVersion: aws.openmcf.org/v1
kind: AwsHttpApiGateway
metadata:
  name: proxy-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsHttpApiGateway.proxy-api
spec:
  region: us-east-1
  description: "HTTP proxy to internal microservices"
  stage:
    name: "$default"
    autoDeploy: true
    accessLog:
      destinationArn:
        value: "arn:aws:logs:us-east-1:123456789012:log-group:/aws/apigateway/proxy-api"
      format: '{"requestId":"$context.requestId","ip":"$context.identity.sourceIp","method":"$context.httpMethod","path":"$context.routeKey","status":"$context.status","latency":"$context.responseLatency"}'
    defaultThrottle:
      burstLimit: 500
      rateLimit: 1000
    stageVariables:
      backendHost: "internal.example.com"
  routes:
    - routeKey: "$default"
      integration:
        integrationType: "HTTP_PROXY"
        integrationUri:
          value: "https://internal.example.com"
        integrationMethod: "ANY"
        timeoutMilliseconds: 10000

Using Foreign Key References

Reference other OpenMCF-managed resources instead of hardcoding ARNs:

apiVersion: aws.openmcf.org/v1
kind: AwsHttpApiGateway
metadata:
  name: ref-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsHttpApiGateway.ref-api
spec:
  region: us-east-1
  routes:
    - routeKey: "GET /items"
      authorizationType: "JWT"
      authorizerName: "lambda-auth"
      integration:
        integrationType: "AWS_PROXY"
        integrationUri:
          valueFrom:
            kind: AwsLambda
            name: get-items-fn
            fieldPath: "status.outputs.function_arn"
  authorizers:
    - name: "lambda-auth"
      authorizerType: "REQUEST"
      authorizerUri:
        valueFrom:
          kind: AwsLambda
          name: auth-fn
          fieldPath: "status.outputs.function_arn"
      authorizerCredentialsArn:
        valueFrom:
          kind: AwsIamRole
          name: apigw-invoke-role
          fieldPath: "status.outputs.role_arn"
      identitySources:
        - "$request.header.Authorization"
      enableSimpleResponses: true
      authorizerPayloadFormatVersion: "2.0"
      resultTtlSeconds: 300

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
api_idstringThe API Gateway API identifier, used for constructing resource ARNs
api_endpointstringThe default endpoint URL: https://{api-id}.execute-api.{region}.amazonaws.com
api_arnstringThe Amazon Resource Name (ARN) of the API
execution_arnstringThe execution ARN prefix used in Lambda resource-based policies: arn:aws:execute-api:{region}:{account-id}:{api-id}
stage_invoke_urlstringThe invoke URL for the deployed stage (includes stage name for named stages)
stage_namestringThe name of the deployed stage (e.g., "$default", "prod")

Related Components

  • AwsLambda — Lambda functions used as backend integrations via AWS_PROXY
  • AwsIamRole — IAM roles for Lambda authorizer invocation credentials
  • AwsCloudwatchLogGroup — CloudWatch Log Groups for API access logging
  • AwsWebSocketApiGateway — WebSocket APIs for real-time bidirectional communication

Next article

AWS IAM Role

AWS IAM Role Deploys an AWS IAM Role with a configurable trust policy, optional managed policy attachments, and optional inline policy documents. The component creates the role, attaches any specified policies, and exports the role ARN and name for use by other components. What Gets Created When you deploy an AwsIamRole resource, OpenMCF provisions: IAM Role — an iam.Role resource with the specified name, trust (assume-role) policy, optional description, and IAM path Managed Policy Attachments...
Read next article
Presets
3 ready-to-deploy configurationsView presets →