Hybrid Deployment
Oso Cloud runs nodes at the edge across multiple regions and availability zones to ensure high availability (up to 99.99% uptime). Oso Cloud is designed to withstand multiple zone and regional outages without any customer-visible impact. We make this level of investment in availability and resilience to save you from having to do so – developing a high availability strategy, running your own infrastructure, building your own alerting, and so on.
Still, for some use cases, you may prefer to add an additional layer of assurance on top of this. For this, we provide the Oso Fallback node. The objective of the Fallback node is to provide the benefits of a fully-managed cloud service with the comfort of owning your infrastructure.
The Oso Fallback node is a read-only instance of Oso that you run in your VPC. If Oso Cloud ever becomes unavailable, the Oso Client will make authorization checks against the Fallback node. The Fallback node works by pulling down the latest copy of your environment's rules and data from Oso Cloud. It may lag ongoing changes to rules and data by up to 30 minutes. The Fallback node is intended only as a last-resort measure to ensure you can make authorization checks even if Oso Cloud is unavailable and will not work as a replacement for making authorization calls to Oso Cloud as part of normal operations.
The Oso Fallback only supports Check API endpoints used for determining access and does not currently support the Management API endpoints used for retrieving the raw rules and data.
Oso Fallback is currently in beta. Reach out if you're interested in learning more:
Deployment
Each Oso Fallback node runs as a standalone process, and we recommend you deploy it as a sidecar to your existing applications. However, we distribute the software as a Docker image to support multiple deployment models if a sidecar is not suitable for your architecture.
System Requirements
The minimum requirements for running the Oso Fallback node are:
- 1 CPU;
- 256MB RAM; and
- 3x the disk space required for your environment.
Configuration
You must configure the following environment variables to start the Oso Fallback node:
Environment Variable | Description |
---|---|
OSO_API_TOKEN | |
OSO_ENVIRONMENT | |
OSO_TENANT |
Additional environment variables you may configure include:
Environment Variable | Default | Accepted Values | Description |
---|---|---|---|
OSO_CLIENT_ID | Randomly generated UUID | String containing the following characters: a-zA-Z0-9.- | Unique identifier for each Oso Fallback node. If set, the OSO_CLIENT_ID must be unique per restart or redeployment. |
OSO_DISABLE_ERROR_LOGGING | false | true, false | Whether error logs are sent to Oso's error collector for review and analysis. |
OSO_DISABLE_TELEMETRY | false | true, false | Whether usage data are sent to Oso's telemetry collector for review and analysis. |
OSO_LOG_LEVEL | error | info, warn, error | Verbosity of log messages printed to stdout. |
OSO_PORT | 8080 | 0 to 65535 | Port for the Oso Fallback node to listen on. |
OSO_DIRECTORY | ./.oso | String containing a valid path | Path where the Fallback node stores data. |
Monitoring
A healthy Oso Fallback node responds with HTTP OK
(200) on
/api/healthcheck
. You may probe this endpoint to assess the liveness of the
node in production environments.
Additionally, you may view the statuses of the connected Fallback nodes on the Fallback status page (opens in a new tab).
Fallback Data
The fallback instance uses the Oso Control plane to poll for the latest snapshots of your environment and download them to its local data directory. If the control plane is inaccessible, the fallback instance will keep running, but the data will not be updated.
You can start a fallback instance from an existing data directory even if it cannot connect to the Oso control plane, and it will begin updating as soon as connectivity is restored.
Updating Oso Clients
The provided clients support an additional parameter for the Fallback node host. On every request, the client tries Oso Cloud first. If Oso Cloud returns repeated HTTP 5xx or HTTP connection errors, the Oso Client will automatically make the same request against the provided Fallback host.
The following sample code illustrates initializing the Oso Client with an Oso Fallback node running as a sidecar exposed on port 8080:
const apiKey = "<please provide your api key here>";
const oso = new Oso("https://api.osohq.com", apiKey, { fallbackUrl: "http://localhost:8080" });
Feedback
We actively invest in ensuring high availability and would appreciate all feedback on Oso Fallback and additional features you would like to see. Please do not hesitate to reach out on Slack (opens in a new tab) and/or submit ideas via the feature request portal (opens in a new tab) in the Oso Cloud UI.