Set Up Oso Fallback

Oso Fallback is intended to be deployed within your infrastructure where it is accessible by applications that have integrations with Oso Cloud. A standard Oso Fallback deployment is composed of one or more Oso Fallback nodes behind a load balancer. Each Oso Fallback node operates independently, so the load balancer enables the capacity to be scaled horizontally in the event of increased load from applications accessing Oso Fallback.

Because Oso Fallback nodes operate independently, two distinct nodes may differ in their copies of the rules and data by up to one minute. We recommend using load balancers with session affinity to ensure consistent communication with the same Oso Fallback node. Otherwise, it is possible for the same client to communicate with multiple nodes, which may result in different responses between consecutive requests.

System requirements

The minimum requirements for running the Oso Fallback node are:

• 1 CPU
• 256MB RAM
• 3x the disk space required for your environment

How much disk space do I need?

The total size of an environment is available on the Fallback status page (opens in a new tab). We recommend you allocate 3x the current size to provide headroom for growth and sufficient space to pull down the latest copy of rules and data.

Ephemeral storage vs. persistent storage

The Oso Fallback node may be deployed with ephemeral disk storage. In that mode, the Oso Fallback node polls Oso Cloud for the environment's latest copy of rules and data and downloads them to its local data directory on startup. If Oso Cloud is inaccessible, the Oso Fallback node will not start up.

If you deploy the Oso Fallback node with persistent storage, it will attempt to start from the copy of rules and data found in the configured data directory. Even if Oso Cloud is inaccessible, the Oso Fallback node can start up as long as the data directory has an eligible copy of rules and data; for example, if the Oso Fallback node was restarted.

If you want to ensure that new Oso Fallback nodes can start from uninitialized storage even if Oso Cloud is down, see Use Oso Fallback Offline Snapshots.

Deploy Oso Fallback node

The Oso Fallback node is distributed as a Docker image in Oso's public repository (opens in a new tab) with support for amd64 and arm64 architectures. The application binds to port 8080 in the container which needs to be mapped to the desired port on the host system.

Pull the latest image from the repository

Configure Oso Fallback

The minimum configuration to start the Oso Fallback node is:

Additional environment variables are available.

Configure your load balancer

Oso Fallback node does not respond to health checks until a copy of rules and data has been loaded. If Oso Fallback node is deployed with ephemeral storage or is being launched for the first time, it will need to download the latest copy of rules and data from the Oso control plane. The time to download the copy is dependent on the size of the environment. We recommend configuring a health check grace period on the load balancer that will allow the copy of rules and data to be downloaded before issuing health checks.

Use Oso Fallback offline snapshots

If Oso Cloud is unavailable, existing Oso Fallback nodes will keep running, but new Oso Fallback nodes will be unable to start unless they are starting from a previously initialized data directory. See Ephemeral storage vs. persistent storage.

If you want to ensure that you can always start new Oso Fallback nodes, you can use the --export flag to export snapshots and use them to seed new nodes with the --import flag.

For example, to export a snapshot, run:

To seed a service with this snapshot, run:

Note the use of the --volume flag. We need this to read and write the file outside of the Docker container.

The Oso Fallback node will always attempt to download the latest data, but the --import option will allow it to start even if Oso Cloud is down and the data directory is empty.

Update Oso Client SDKs

The Client SDKs support an additional parameter for the Oso Fallback node host or load balancer address. On every request, the client tries Oso Cloud first. If Oso Cloud returns repeated HTTP 400, HTTP 5xx or HTTP connection errors, the Oso Client SDK will automatically make the same request against the provided Oso Fallback URL after it has exhausted retry attempts for Oso Cloud.

The following sample code illustrates initializing the Oso Client SDK with an Oso Fallback node running on the same host as the application on port 8080:

const apiKey = "<please provide your api key here>";
const oso = new Oso("https://api.osohq.com", apiKey, { fallbackUrl: "http://localhost:8080" });

Test Oso Fallback

To ensure Oso Fallback is ready when you need it, we recommend performing some chaos testing to partition a subset of your authorization requests from Oso Cloud. This will result in the clients using Oso Fallback to respond to authorization requests. You can use proxies or use an unresolvable hostname for the Oso Cloud URL when configuring the client SDK. To verify the usage of Oso Fallback, you can query the oso_fallback_http_requests metric exported by each Oso Fallback node (see Monitoring for more details on available metrics).