OpenMCF logoOpenMCF

Loading...

OCI API Gateway

Deploys an Oracle Cloud Infrastructure API Gateway with a bundled API deployment. The gateway provides the managed network endpoint (public or private) while the deployment defines the API specification: routes with HTTP, OCI Functions, or stock-response backends, optional JWT authentication, CORS, rate limiting, and per-route authorization.

What Gets Created

When you deploy an OciApiGateway resource, OpenMCF provisions:

  • API Gateway — an apigateway.Gateway resource in the specified compartment and subnet with configurable endpoint type (public or private), optional TLS certificate, and optional NSG bindings.
  • API Deployment — an apigateway.Deployment resource on the gateway with a path prefix, route definitions, and optional request policies (JWT authentication, CORS, rate limiting). The deployment depends on the gateway and is always created.

Prerequisites

  • OCI credentials configured via environment variables or OpenMCF provider config (API Key, Instance Principal, Security Token, Resource Principal, or OKE Workload Identity)
  • A compartment OCID where the gateway and deployment will be created — either a literal value or a reference to an OciCompartment resource
  • A subnet OCID — for public gateways, this must be a public subnet. Either a literal value or via valueFrom referencing an OciSubnet resource
  • An OCI Certificates service certificate OCID (optional) — if terminating TLS on the gateway
  • OCI Functions function OCIDs (for Functions backends) — if routing to serverless functions
  • A JWKS endpoint URL or static keys (for JWT authentication) — if enabling token-based authentication

Quick Start

Create a file api-gateway.yaml:

apiVersion: oci.openmcf.org/v1
kind: OciApiGateway
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.OciApiGateway.my-api
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  endpointType: endpoint_type_public
  subnetId:
    value: "ocid1.subnet.oc1..example"
  deployment:
    pathPrefix: "/api/v1"
    routes:
      - path: "/health"
        methods:
          - "GET"
        backend:
          type: stock_response
          status: 200
          body: '{"status":"ok"}'

Deploy:

openmcf apply -f api-gateway.yaml

This creates a public API gateway with a single health-check route that returns a stock response. The gateway OCID, hostname, and deployment endpoint URL are exported as stack outputs.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
compartmentIdStringValueOrRefOCID of the compartment where the gateway and deployment will be created. Can reference an OciCompartment resource via valueFrom.Required
endpointTypeenumWhether the gateway is internet-facing or VCN-internal. Values: public, private. Immutable after creation.Required, not unspecified
subnetIdStringValueOrRefOCID of the subnet for the gateway. Public gateways require a public subnet. Immutable after creation. Can reference an OciSubnet resource via valueFrom.Required
deploymentDeploymentThe API deployment defining routes, backends, and policies.Required
deployment.pathPrefixstringURL path prefix for all routes (e.g., "/api/v1"). Must start with "/". Immutable after creation.Min length 1, starts with /
deployment.routesRoute[]Route definitions. Routes are evaluated in order; first match wins.Min 1 item

Optional Fields

FieldTypeDefaultDescription
displayNamestringmetadata nameDisplay name for the gateway.
certificateIdstring—OCID of an OCI Certificates service certificate for TLS termination.
networkSecurityGroupIdsStringValueOrRef[]—NSGs applied to the gateway. Can reference OciSecurityGroup resources via valueFrom.
deployment.displayNamestring"{gatewayName}-deployment"Display name for the deployment.
deployment.loggingPoliciesLoggingPolicies—Access and execution logging configuration.
deployment.requestPoliciesRequestPolicies—Deployment-level JWT authentication, CORS, and rate limiting.

Route

FieldTypeDescription
pathstringURL path pattern (e.g., "/users/{userId}", "/health").
methodsstring[]HTTP methods this route handles (e.g., ["GET", "POST"]). When empty, all methods are accepted.
backendBackendBackend that processes matching requests. Required.
authorizationRouteAuthorizationPer-route authorization policy.
loggingPoliciesLoggingPoliciesPer-route logging override.

Backend

FieldTypeDescription
typeenumBackend type. Values: http, oracle_functions, stock_response.
urlstringTarget URL for HTTP backends. Required when type is http.
functionIdstringOCID of the OCI function. Required when type is oracle_functions.
statusint32HTTP status code for stock responses.
bodystringResponse body for stock responses.
connectTimeoutInSecondsfloatConnection timeout. Applicable to http and oracle_functions.
readTimeoutInSecondsfloatRead timeout. Applicable to http and oracle_functions.
sendTimeoutInSecondsfloatSend timeout. Applicable to http and oracle_functions.
isSslVerifyDisabledboolSkip TLS verification for HTTP backends.
headersBackendHeader[]Custom headers added to backend requests.

RequestPolicies (Deployment-Level)

FieldTypeDescription
authenticationAuthenticationJWT-based authentication. See below.
corsCorsPolicyCross-Origin Resource Sharing policy. See below.
rateLimitingRateLimitingRate limiting policy. See below.

Authentication (JWT)

FieldTypeDescription
issuersstring[]Allowed token issuers (iss claim).
audiencesstring[]Allowed audiences (aud claim).
tokenHeaderstringHTTP header containing the token. Defaults to "Authorization".
tokenQueryParamstringQuery parameter containing the token.
tokenAuthSchemestringAuth scheme prefix (e.g., "Bearer"). Defaults to "Bearer".
maxClockSkewInSecondsfloatClock skew tolerance for exp/nbf/iat claims.
isAnonymousAccessAllowedboolAllow unauthenticated requests (routes can still enforce authorization).
publicKeysPublicKeysPublic key configuration for signature verification. Required.
verifyClaimsVerifyClaim[]Additional claims to verify.

CorsPolicy

FieldTypeDescription
allowedOriginsstring[]Allowed origins (e.g., ["*"] or ["https://app.example.com"]). Min 1.
allowedMethodsstring[]Allowed HTTP methods.
allowedHeadersstring[]Allowed request headers.
exposedHeadersstring[]Response headers exposed to the browser.
isAllowCredentialsEnabledboolAllow credentials (cookies, auth headers).
maxAgeInSecondsint32Preflight response cache duration.

RateLimiting

FieldTypeDescription
rateInRequestsPerSecondint32Maximum requests per second. Must be > 0.
rateKeyenumGrouping key. Values: client_ip (per-IP), total (aggregate).

Examples

Public Gateway with HTTP Backend

A public gateway proxying requests to an upstream service:

apiVersion: oci.openmcf.org/v1
kind: OciApiGateway
metadata:
  name: api-proxy
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.OciApiGateway.api-proxy
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  endpointType: endpoint_type_public
  subnetId:
    value: "ocid1.subnet.oc1..example"
  deployment:
    pathPrefix: "/api/v1"
    routes:
      - path: "/users"
        methods:
          - "GET"
          - "POST"
        backend:
          type: http
          url: "https://backend.example.com:8080"
      - path: "/users/{userId}"
        methods:
          - "GET"
          - "PUT"
          - "DELETE"
        backend:
          type: http
          url: "https://backend.example.com:8080"

Functions Backend with JWT Authentication

A gateway routing to OCI Functions with JWT authentication via remote JWKS and CORS for a browser client:

apiVersion: oci.openmcf.org/v1
kind: OciApiGateway
metadata:
  name: serverless-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.OciApiGateway.serverless-api
spec:
  compartmentId:
    valueFrom:
      kind: OciCompartment
      name: prod-compartment
      fieldPath: status.outputs.compartmentId
  endpointType: endpoint_type_public
  subnetId:
    valueFrom:
      kind: OciSubnet
      name: public-subnet
      fieldPath: status.outputs.subnetId
  deployment:
    pathPrefix: "/fn"
    loggingPolicies:
      accessLog:
        isEnabled: true
      executionLog:
        isEnabled: true
        logLevel: info
    requestPolicies:
      authentication:
        issuers:
          - "https://auth.example.com/"
        audiences:
          - "https://api.example.com"
        publicKeys:
          type: remote_jwks
          uri: "https://auth.example.com/.well-known/jwks.json"
          maxCacheDurationInHours: 24
      cors:
        allowedOrigins:
          - "https://app.example.com"
        allowedMethods:
          - "GET"
          - "POST"
          - "OPTIONS"
        allowedHeaders:
          - "Authorization"
          - "Content-Type"
        maxAgeInSeconds: 3600
    routes:
      - path: "/process"
        methods:
          - "POST"
        backend:
          type: oracle_functions
          functionId: "ocid1.fnfunc.oc1..example"
        authorization:
          type: authentication_only
      - path: "/health"
        methods:
          - "GET"
        backend:
          type: stock_response
          status: 200
          body: '{"status":"ok"}'
        authorization:
          type: anonymous

Private Gateway with Rate Limiting

A VCN-internal gateway with rate limiting for internal microservice communication:

apiVersion: oci.openmcf.org/v1
kind: OciApiGateway
metadata:
  name: internal-api
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.OciApiGateway.internal-api
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  endpointType: private
  subnetId:
    value: "ocid1.subnet.oc1..example"
  networkSecurityGroupIds:
    - valueFrom:
        kind: OciSecurityGroup
        name: api-nsg
        fieldPath: status.outputs.networkSecurityGroupId
  deployment:
    pathPrefix: "/internal"
    requestPolicies:
      rateLimiting:
        rateInRequestsPerSecond: 100
        rateKey: client_ip
    routes:
      - path: "/data"
        methods:
          - "GET"
        backend:
          type: http
          url: "http://data-service.internal:8080"
          connectTimeoutInSeconds: 5
          readTimeoutInSeconds: 30

Stack Outputs

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

OutputTypeDescription
gateway_idstringOCID of the API gateway
hostnamestringHostname assigned by OCI (e.g., "abc123.apigateway.us-ashburn-1.oci.customer-oci.com")
deployment_endpointstringFull endpoint URL (gateway hostname + deployment path prefix)

Related Components

  • OciSubnet — provides the subnet referenced by subnetId via valueFrom
  • OciCompartment — provides the compartment referenced by compartmentId via valueFrom
  • OciSecurityGroup — provides NSGs referenced by networkSecurityGroupIds via valueFrom
  • OciFunctionsApplication — hosts the functions invoked by oracle_functions backends
  • OciDnsRecord — creates CNAME records pointing to the gateway hostname

Next article

OCI Application Load Balancer

OCI Application Load Balancer Deploys an OCI Application Load Balancer (Layer 7) with backend sets, listeners, SSL certificates, virtual hostnames, and rule sets as a single atomic deployment unit. Supports HTTP, HTTP/2, TCP, and gRPC protocols with flexible bandwidth, cookie-based session persistence, health checking, and rule-based request/response manipulation including HTTP redirects, header injection, and access control. What Gets Created When you deploy an OciApplicationLoadBalancer...
Read next article
Presets
3 ready-to-deploy configurationsView presets →