HTTP - Octelium Docs

ManagementCore APIServices

HTTP

Octelium supports the HTTP mode for any HTTP-based upstreams (e.g. HTTP APIs, web-apps, websockets, gRPC, etc...). You can create an HTTP Service simply as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 8080
7  config:
8    upstream:
9      url: https://example.com

NOTE

For internal/private upstreams behind NAT, you need to remotely serve them via a connected octelium client or container as discussed here.

Access Control

You can control access based on the HTTP request information. Such information are stored in ctx.request.http where it contains the method, path, headers map, the request body and the serialized JSON body map if available as well as other information such as the scheme and full URI. Here is a detailed example of a inline Policy that controls access based on HTTP-specific information:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 8080
7  config:
8    upstream:
9      url: https://example.com
10  authorization:
11    inlinePolicies:
12      - spec:
13          rules:
14          - effect: ALLOW
15            condition:
16              all:
17                of:
18                - match: ctx.request.http.method in ["GET", "POST", "PUT", "DELETE"]
19                - match: ctx.request.http.path.startsWith("/apis")
20                - match: ctx.request.http.uri == "/apis/users?name=john"
21                - match: ctx.request.http.queryParams.name == "john"
22                - match: ctx.request.http.headers["x-custom-header"] == "this-value"
23                - match: ctx.request.http.scheme == "http"
24                - match: string(ctx.request.http.body).toLower().contains("value1")
25                - match: ctx.request.http.bodyMap.key1 == "value1"

Secretless Access

Octelium is capable of supporting secretless access to protected upstreams (read more here) by injecting HTTP-based credentials such as API keys, which are stored and represented in the Cluster as Secrets (read more about Secrets here), on-the-fly to the protected upstream. This eliminates the need to share, mange, distribute and store such typically long-lived, privileged and prone-to-misuse credentials. Octelium supports the following authentication methods:

Basic authentication
Bearer authentication
Custom header authentication
OAuth2 client credentials flow

You first need to create a Secret that holds your credential via octeliumctl create secret (read more here) as follows:

octeliumctl create secret my-api-key

And then reference that Secret depending on your authentication scheme as shown below.

Basic Authentication

In this scheme, authentication information is injected by the Service as Basic <base64(username:password_secret)> for the Authorization request header when the request is sent to the upstream. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://api.example.com
10    http:
11      auth:
12        basic:
13          username: user1
14          password:
15            fromSecret: my-api-key

Bearer Authentication

In this scheme, authentication information is injected by the Service as Bearer <bearer_secret> for the Authorization request header when the request is sent to the upstream. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://api.example.com
10    http:
11      auth:
12        bearer:
13          fromSecret: my-api-key

Authentication via a Custom Header

You can also set your Secret value to a custom request header to the upstream. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://api.example.com
10    http:
11      auth:
12        custom:
13          header: X-Custom-Auth
14          value:
15            fromSecret: my-api-key

OAuth2 Client Credentials

You can also use OAuth2 client credentials authentication flow (read more here). Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://api.example.com
10    http:
11      auth:
12        oauth2ClientCredentials:
13          clientID: my-oauth2-client-id
14          clientSecret:
15            fromSecret: my-oauth2-client-key
16          tokenURL: https://oauth2.example.com/v1
17          scopes: ["scope1", "scope2"]

Sigv4 Authentication

Octelium can also compute and inject AWS Sigv4 auth signatures on the fly for any AWS Sigv4 compliant API for a specific service (e.g. Lambda, S3, etc...) and region. Here is an example for a Lambda function URL that's protected by Sigv4:

1kind: Service
2metadata:
3  name: lambda-01
4spec:
5  mode: HTTP
6  isPublic: true
7  config:
8    upstream:
9      url: https://abcd...efgh.lambda-url.eu-central-1.on.aws
10    http:
11      auth:
12        sigv4:
13          accessKeyID: ABCD...EFGH
14          region: eu-central-1
15          service: lambda
16          secretAccessKey:
17            fromSecret: lambda-access-key

NOTE

You can see a detailed example for S3 here. You can also see a detailed example for Lambda here.

HTTP 2/0

Listening on HTTP 2/0

By default, the Service listens to HTTP 1.1 connections unless TLS is enabled (read more here). However you can force the Service to accept HTTP 2.0 connections as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      listenHTTP2: true

HTTP 2/0 Upstream

A Service by default assumes that the upstream accepts HTTP 1.1 connections unless it's serving TLS connections. You can force the Service to forward the requests over HTTP 2/0 as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      isUpstreamHTTP2: true

Header Manipulation

You can easily manipulate both request and response HTTP headers as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      header:
12        addRequestHeaders:
13        - key: X-HEADER-1
14          value: VALUE-1
15        - key: X-HEADER-2
16          value: VALUE-2
17        removeRequestHeaders:
18        - X-HEADER-3
19        - X-HEADER-4
20        addResponseHeaders:
21        - key: X-HEADER-5
22          value: VALUE-5
23        - key: X-HEADER-6
24          value: VALUE-6
25        removeResponseHeaders:
26        - X-HEADER-7
27        - X-HEADER-8

By default addRequestHeaders and addResponseHeaders actually set or "override" any existing header value. To append instead of overriding such values, you can simply use the append boolean option as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      header:
12        addRequestHeaders:
13        - key: X-HEADER-1
14          value: VALUE-1
15          append: true
16        addResponseHeaders:
17        - key: X-HEADER-2
18          value: VALUE-2
19          append: true

Forwarded Header

By default, Vigil automatically deletes the Forwarded request header (read more here), if set by the downstream, to protect the downstream's privacy and also to protect the upstream from possible spoofing by a malicious downstream. You can, however, explicitly override that default behavior by using the OBFUSCATE mode to obfuscate the for and by values while using the Service public FQDN as the host value. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      forwardedMode: OBFUSCATE

You can also use TRANSPARENT mode to simply pass the Forwarded request header as is, if set by the downstream. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      forwardedMode: TRANSPARENT

Path Manipulation

You can add a prefix to the request's path as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      path:
12        addPrefix: /prefix

Now a request with the path /v1 will become /prefix/v1.

And you can also remove a prefix from the path as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      path:
12        removePrefix: /prefix

Now a request with the path /prefix/v1 will become /v1.

And you can replace a prefix by another by combining both removePrefix and addPrefix as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      path:
12        removePrefix: /v1
13        addPrefix: /v2

Now a request with the path /v1/path will become /v2/path.

Request Body

Octelium enables you to buffer the entire request body before forwarding it to the upstream for it to be checked and used in your access Policies (read more here) and dynamic configuration (read more here).

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      enableRequestBuffering: true

This will include your entire body as base64 string inside the ctx.request.http.body (read more here) field used by your Policies and dynamic configuration rules.

Request Body Maximum Size

You can set the limit on the maximum number of bytes for a request body as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      enableRequestBuffering: true
12      body:
13        maxRequestSize: 100000

JSON Request Body

In many cases such as in REST APIs, the request body is represented by a JSON format. You can enable the body mode as JSON to verify that the request body is a valid JSON as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      enableRequestBuffering: true
12      body:
13        mode: JSON

The JSON modes lets you to directly use the fields of the JSON structure in your Policies and dynamic configuration rules inside the ctx.request.http.bodyMap field. Here is an example, for a request body with a schema that looks as following:

1{
2  "key1": "value1",
3  "key2": 5,
4  "key3:": {
5    "key4": "value4"
6  }
7}

You can set your access Policy rules as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 8080
7  config:
8    upstream:
9      url: https://example.com
10  authorization:
11    inlinePolicies:
12      - spec:
13          rules:
14          - effect: ALLOW
15            condition:
16              all:
17                of:
18                - match: ctx.request.http.bodyMap.key1 == "value1"
19                - match: ctx.request.http.bodyMap.key2 > 2
20                - match: ctx.request.http.bodyMap.key3.key4 == "value4"

Body Validation

JSON Schema Validation

You can validate the JSON body via a JSON schema simply as follows:

NOTE

Note that this feature is currently experimental and the API might change in the next few releases as of v0.10.0.

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      validation:
12        jsonSchema:
13          inline: |
14            {
15              "$schema": "http://json-schema.org/draft-07/schema#",
16              "title": "User",
17              "description": "A user in the system",
18              "type": "object",
19              "properties": {
20                "id": {
21                  "description": "The unique identifier for the user",
22                  "type": "integer"
23                },
24                // The rest of your JSON schema

If the body content is not valid according to the schema, then a status code of 400 is returned.

NOTE

You can use dynamic configuration (read more here), for example for different API REST paths referring to different API resources, to actually use multiple JSON schemas.

Direct Response

NOTE

Since version v0.16, it is more recommended to use direct response plugins. Read more here

You can also return direct response without proxying the request to the upstream. Here is an example of returning a string:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      response:
12        direct:
13          inline: Hello World

You can also return a stream of bytes encoded by base64. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      response:
12        direct:
13          inlineBytes: iVBORw0KGgoAAAANS....

you can also set the response status code and content type of the direct response as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      response:
12        direct:
13          statusCode: 200
14          contentType: image/png
15          inlineBytes: iVBORw0KGgoAAAANS....

NOTE

You can use dynamic configuration (read more here) to return different direct responses for different request paths or even different identities or contexts.

Retry

By default, the Service does not retry a failed request (e.g. whose response status code is 503). You can, however, enable retries with sensible defaults as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    retry: {}

You can explicitly set your retry-specific configurations. The Service uses exponential backoff that starts with an initialInterval duration. This duration is multiplied on each retry by a multiplier floating point value until it reaches the value of a maxInterval duration. The whole process can have a maximum number of retries that can be set via maxRetries and a deadline duration that is controlled by maxElapsedTime. By default, the Service currently retries on 502, 503 and 504 status codes; however, you can explicitly set the status codes via the statusCodes list and additionally use any 5xx error via the retryOnServerErrors boolean flag. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    retry:
11      maxRetries: 10
12      initialInterval:
13        milliseconds: 500
14      maxInterval:
15        seconds: 5
16      maxElapsedTime:
17        seconds: 12
18      multiplier: 1.5
19      statusCodes: [503, 429]
20      retryOnServerErrors: true

HTTPS

By default, the Service listens over plaintext TCP acting as a plaintext HTTP server regardless of whether the upstream is an HTTPS or an HTTP server. You can turn the Service into an HTTPS Service, however, via the isTLS flag as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 443
7  isTLS: true
8  config:
9    upstream:
10      url: https://example.com

NOTE

A Service is accessed over public HTTPS if the public BeyondCorp mode is enabled via isPublic field (read more here), regardless of whether the Service is using isTLS or not. In other words, isTLS is only effective for the private client-based mode. Therefore, if isPublic is enabled while isTLS is not, then the Service is accessed publicly over HTTPS while over plaintext via the client-based mode.

TLS Config

The Service can automatically connect to an HTTPS upstream whose certificate is signed by a public CA. If the upstream is using a private CA, however, you will have to manually add that root CA in a list of trustedCAs. Here is an example:

1kind: Service
2metadata:
3  name: my-api
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://my-upstream:6443
9    tls:
10      trustedCAs:
11      - |
12        -----BEGIN CERTIFICATE-----
13        CA
14        -----END CERTIFICATE-----

You can also skip verifying the upstream's certificate altogether via the insecureSkipVerify which is typically recommended only for troubleshooting/testing use cases. Here is an example:

1kind: Service
2metadata:
3  name: my-api
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://my-upstream:6443
9    tls:
10      insecureSkipVerify: true

If the upstream requires mutual TLS (mTLS), you will have to include your client certificate private key as a Secret (read more here), and then reference it as follows:

1kind: Service
2metadata:
3  name: my-api
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://my-upstream:6443
9    tls:
10      trustedCAs:
11      - |
12        -----BEGIN CERTIFICATE-----
13        CA
14        -----END CERTIFICATE-----
15      clientCertificate:
16        fromSecret: client-private-key

You can also enforce CORS rules as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://example.com
10    http:
11      cors:
12        allowMethods: "POST, GET, OPTIONS"
13        allowHeaders: "X-PINGOTHER, Content-Type"
14        maxAge: "86400"

Dynamic Configuration

You can use dynamic configuration in order to, for example, route to different upstreams and/or setting different upstream credentials, set different request/response headers, etc... depending on the request's context (read more about dynamic configuration here). Here is a simple example for an API gateway (read more here):

1kind: Service
2metadata:
3  name: my-api
4spec:
5  mode: HTTP
6  isPublic: true
7  dynamicConfig:
8    configs:
9    - name: v1
10      upstream:
11        url: https://apiv1.example.com
12      http:
13        path:
14          removePrefix: /v1
15    - name: v2
16      upstream:
17        url: https://apiv2.example.com
18      http:
19        path:
20          removePrefix: /v2
21    rules:
22    - condition:
23        match: ctx.request.http.path.startsWith("/v1")
24      configName: v1
25    - condition:
26        match: ctx.request.http.path.startsWith("/v2")
27      configName: v2

Visibility

The Service emits AccessLogs in real time to the audit collector. Each AccessLog provides application-layer aware information about the request such as the request path, method, etc... as well as the response code and body size. Here is an example:

1{
2  "apiVersion": "core/v1",
3  "kind": "AccessLog",
4  "metadata": {
5    // Omitted for brevity
6  },
7  "entry": {
8      // Omitted for brevity
9    },
10    "info": {
11      "http": {
12        "request": {
13          "path": "/",
14          "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36",
15          "method": "GET",
16          "uri": "/?arg=value"
17        },
18        "response": {
19          "code": 200,
20          "bodyBytes": "615",
21          "body": "PCFET0NUWV...",
22          "contentType": "text/html"
23        },
24        "httpVersion": "HTTP11"
25      }
26    }
27  }
28}

Visibility Options

By default, the Service does not log the request and response body content. However, you can explicitly enable capturing the request/response body content as well as the serialized JSON body map as follows:

1kind: Service
2metadata:
3  name: my-api
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://api.example.com
10    http:
11      visibility:
12        enableRequestBody: true
13        enableRequestBodyMap: true
14        enableResponseBody: true
15        enableResponseBodyMap: true

You can also record all or certain request/response headers inside AccessLogs as follows:

1kind: Service
2metadata:
3  name: my-api
4spec:
5  mode: HTTP
6  port: 80
7  config:
8    upstream:
9      url: https://api.example.com
10    http:
11      visibility:
12        includeAllRequestHeaders: true
13        includeAllResponseHeaders: true
14        includeRequestHeaders: ["X-Custom-Header-1", "X-Custom-Header-2"]
15        includeResponseHeaders: ["X-Custom-Header-3", "X-Custom-Header-4"]
16        excludeRequestHeaders: ["X-Custom-Header-5", "X-Custom-Header-6"]
17        excludeResponseHeaders: ["X-Custom-Header-7", "X-Custom-Header-8"]

gRPC Mode

In the GRPC mode, the Service automatically listens over HTTP 2/0 as required by gRPC protocol. Furthermore, authorization and visibility take advantage of decoding the requests as gRPC requests.

You can control access based on the gRPC request information. Such information are stored in ctx.request.grpc where it contains the service, method and package values. Additionally all the HTTP related information that are exposed in the HTTP mode are also exposed in the variable ctx.request.grpc.http. Here is a detailed example of a inline Policy that controls access based on gRPC-specific information:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: GRPC
6  port: 8080
7  config:
8    upstream:
9      url: https://my-grpc-api.example.com
10  authorization:
11    inlinePolicies:
12      - spec:
13          rules:
14            - effect: ALLOW
15              condition:
16                all:
17                  of:
18                    - match: ctx.request.grpc.method == "GetUser"
19                    - match: ctx.request.grpc.service == "MainService"
20                    - match: ctx.request.grpc.package == "octelium.api.main.core.v1"
21                    - match: ctx.request.grpc.serviceFullName == "octelium.api.main.core.v1.MainService"
22                    - match: ctx.request.grpc.http.path.startsWith("/octelium.api")
23                    - match: ctx.request.grpc.http.headers["x-custom-header"] == "this-value"

As for visibility, the access log contains gRPC-specific information such as the package, service and method in addition to the underlying HTTP information. Here is an example:

1{
2  "apiVersion": "core/v1",
3  "kind": "AccessLog",
4  "metadata": {
5    // Omitted for brevity
6  },
7  "entry": {
8      // Omitted for brevity
9    },
10    "info": {
11      "grpc": {
12        "http": {
13          "request": {
14            "path": "/octelium.api.main.core.v1.MainService/ListService",
15            "userAgent": "octelium-cli/v0.17.1 grpc-go/1.71.1",
16            "method": "POST",
17            "uri": "/octelium.api.main.core.v1.MainService/ListService"
18          },
19          "response": {
20            "code": 200,
21            "bodyBytes": "19130",
22            "contentType": "application/grpc"
23          },
24          "httpVersion": "HTTP2"
25        },
26        "method": "ListService",
27        "service": "MainService",
28        "serviceFullName": "octelium.api.main.core.v1.MainService",
29        "package": "octelium.api.main.core.v1"
30      }
31    }
32  }
33}

Web App Mode

You can use the WEB mode to denote that the Service is a web application that can be accessed by HUMAN Users via their browsers. This mode enables the web Portal to include a "Visit" button to open the Service homepage in a new tab. Here is an example:

1kind: Service
2metadata:
3  name: grafana1
4spec:
5  mode: WEB
6  port: 80
7  isPublic: true
8  config:
9    upstream:
10      url: https://grafana.mycluster.svc

Without explicitly using the WEB mode, no "Visit" button will be shown in the Portal and Users will have to manually type the https://grafana1.<DOMAIN> in their browsers to visit the Service homepage.