Deep Dive into Scalr's Platform Architecture

Reviewed for accuracy by Ryan Fee on June 6, 2025.

Running Infrastructure as Code securely once you have more than a handful of workspaces is hard for platform teams. Scalr is a platform for Terraform and OpenTofu operations that takes on a lot of that work. This post walks through how it is built: the SaaS architecture, the three-tiered hierarchy, how objects are inherited, the backend options for state, how agents run jobs inside your own network, and how you can manage Scalr itself as code. Each part comes with a working example.

Scalr Overview

Scalr is a Software-as-a-Service (SaaS) platform that acts as a remote state and operations backend for Terraform and OpenTofu. Because Scalr hosts and runs it, you don't have to stand up or maintain the management tool's own infrastructure. Scalr runs on IaaS platforms and secures the workloads it deploys there. The underlying cloud providers handle continuous monitoring and auditing, holding certifications like SOC2, ISO 27001, and PCI DSS. All data in Scalr is encrypted in transit and at rest.

Advantages of the SaaS model include:

• Reduced Operational Overhead: Teams focus on IaC, not tool management.
• Scalability: Handles growing IaC needs without user intervention for scaling.
• Accessibility: Cloud-based for distributed team collaboration.
• Managed Security: Scalr secures the platform, building on the cloud providers' security.

Scalr offers features like Role-Based Access Control (RBAC), Open Policy Agent (OPA) integration, a private module registry, and full Terraform/Tofu CLI support. Billing is run-based, with nothing else factoring into the cost.

Platform Architecture

Scalr's architecture is built on a three-tiered hierarchy: Account, Environment, and Workspace. This is the structure you organize objects in, enforce policies through, and report against. It also sets where central control ends and team-level operations begin.

• Account Scope: The highest administrative level, typically managed by central platform teams. It handles global configurations like IAM, OPA policies, module registry, provider credentials, VCS providers, and shared variables. The account scope offers unified reporting and dashboards for all workspaces and runs across environments, crucial for oversight. Objects defined here can cascade down, ensuring organizational consistency.
• Environment Scope: Nested under Accounts, environments enable self-service by decentralizing operations. They act as logical groupings (e.g., "production," "development") or akin to cloud sub-accounts, isolating workspaces, teams, and configurations. Access requires explicit permissions, separating concerns and reducing change impact.
• Workspace Scope: The most granular level, children of an Environment, where Terraform/OpenTofu runs execute and state files are stored. Each workspace links to a single state file and related objects like variables and run history. Engineers interact here via CLI, VCS, or Scalr's no-code module deployments.

This hierarchy facilitates governance and team autonomy, comparable to AWS Organizations.

Managing the Hierarchy with the Scalr Terraform Provider

Using the Scalr Terraform provider is a best practice for managing this structure, aligning with GitOps principles.

Conceptual example:

terraform {
  required_providers {
    scalr = {
      source  = "registry.scalr.io/scalr/scalr"
      version = "~> 1.5" # Check for the latest compatible version
    }
  }
}
 
provider "scalr" {
  hostname = var.scalr_hostname
  token    = var.scalr_api_token
}
 
variable "scalr_hostname" {
  type        = string
  description = "Scalr account hostname (e.g., myaccount.scalr.io)."
}
 
variable "scalr_api_token" {
  type        = string
  sensitive   = true
  description = "Scalr API token."
}
 
variable "scalr_account_id" {
  type        = string
  description = "Your Scalr Account ID (e.g., acc-xxxxxxxxxxxx)."
}
 
# Define an Environment
resource "scalr_environment" "production_env" {
  name       = "production"
  account_id = var.scalr_account_id
}
 
# Define a Workspace within the Production Environment
resource "scalr_workspace" "app_server_prod" {
  name           = "app-server-prod"
  environment_id = scalr_environment.production_env.id
  vcs_provider_id = data.scalr_vcs_provider.github.id
  vcs_repo {
    identifier = "your-org/infra-repo"
    branch     = "main"
    path       = "terraform/app-server/prod"
  }
  terraform_version = "1.5.7"
}
 
data "scalr_vcs_provider" "github" {
  name       = "My-GitHub-Connection"
  account_id = var.scalr_account_id
}

This example creates a "production" environment and an "app-server-prod" workspace. Automating Scalr setup via Terraform (a "Scalr vending machine") reduces operational overhead.

Inheritance for Variables, Policies, and Credentials

Scalr's hierarchy enables object inheritance: configurations at higher scopes (Account/Environment) can be inherited by lower scopes (Environment/Workspace), ensuring consistency.

Variable Inheritance

Scalr supports Terraform input variables (passed as .tfvars.json) and shell variables (exported to the runtime). Both are inheritable: Account -> Environment -> Workspace. Variables can be overridden at lower scopes unless marked "final." Sensitive variables are masked.

Example: Defining and Inheriting Variables with the Scalr Terraform Provider

The scalr_variable resource manages variables programmatically.

# In your Scalr Account configuration
variable "scalr_account_id" {
  type = string
}
 
resource "scalr_variable" "global_region" {
  key        = "aws_region"
  value      = "us-east-1"
  category   = "shell"
  account_id = var.scalr_account_id
  final      = true
  description = "Global default AWS region, non-overridable."
}
 
resource "scalr_variable" "default_instance_type_tf_var" {
  key        = "TF_VAR_instance_type"
  value      = "t3.micro"
  category   = "shell"
  account_id = var.scalr_account_id
  description = "Default EC2 instance type, can be overridden."
}

aws_region is final at account level. All workspaces will inherit it.

Policy Inheritance (OPA)

Scalr uses Open Policy Agent (OPA) for policy-as-code. OPA policy groups, created at the account scope, are assigned to environments and inherited by their workspaces. Policies evaluate at pre-plan (run context) or post-plan (Terraform plan output) stages.

Example: Defining an OPA Policy and Linking it

An OPA policy (Rego code) in VCS, e.g., to ensure S3 buckets are private:

#s3_private.rego
package terraform
import input.tfplan as tfplan
 
deny[reason] {
    r := tfplan.resource_changes[_]
    r.mode == "managed"
    r.type == "aws_s3_bucket"
    r.change.after.acl == "public-read" # Example check
    reason := sprintf("%s: S3 bucket ACL must not be public-read.", [r.address])
}

Using the Scalr Terraform provider:

data "scalr_vcs_provider" "main_vcs" {
  name       = "My-GitHub-Enterprise"
  account_id = var.scalr_account_id
}
 
resource "scalr_policy_group" "s3_security_policies" {
  name            = "s3-security-best-practices"
  account_id      = var.scalr_account_id
  vcs_provider_id = data.scalr_vcs_provider.main_vcs.id
  vcs_repo {
    identifier = "your-org/opa-policies"
    path       = "policies"
    branch     = "main"
  }
  environments = ["*"] # Link to all environments
}

This policy group applies to all environments.

Credential Inheritance (Provider Configurations)

Provider configurations in Scalr manage cloud provider authentication. Created at the account scope, they can be assigned to environments (often as default) or workspaces. Workspaces inherit the environment's default if set.

Example: Defining and Setting Default Provider Configuration

resource "scalr_provider_configuration" "aws_prod_credentials" {
  name       = "aws-production-role"
  account_id = var.scalr_account_id
  aws {
    account_type     = "regular"
    credentials_type = "role_delegation"
    trusted_entity_type = "aws_service"
    role_arn         = "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/ScalrProdExecutionRole"
  }
}
 
resource "scalr_environment" "production_env" {
  name                            = "production"
  account_id                      = var.scalr_account_id
  default_provider_configurations = [scalr_provider_configuration.aws_prod_credentials.id]
}

Workspaces in production_env use aws_prod_credentials by default.

Flexible State Management: Scalr-Managed vs. Customer-Managed Backend

Scalr offers flexibility for Terraform state storage. Three primary models exist:

Scalr Remote Backend w/ Customer Managed State Storage ("Bring Your Own Bucket"): Scalr is the remote backend for operations, but state files, artifacts, plans, and logs are in the customer's AWS S3 or GCP bucket. Variables and provider configs remain in Scalr. Offers data location control. Requires creating a "storage profile" in Scalr (an Enterprise-plan feature).

Non-Scalr Backend w/ Customer Managed State Storage: Users configure standard backends (e.g., S3, Azure Blob) in Terraform code. Scalr can orchestrate runs, but state/locking is by the chosen backend. Customer handles state encryption.

terraform {
  backend "s3" {
    bucket         = "my-terraform-state-bucket-name"
    key            = "path/to/my/app.tfstate"
    region         = "us-west-2"
    encrypt        = true
  }
}

Scalr Remote Backend w/ Scalr State Storage (Default): Scalr manages state storage in a Scalr-managed, encrypted Google Cloud Storage bucket. Offers full feature functionality and simplified setup.

terraform {
  backend "remote" {
    hostname     = "<your-account>.scalr.io"
    organization = "<your-environment-id>"
    workspaces {
      name = "<your-workspace-name>"
    }
  }
}

Secure and Flexible Execution: Self-Hosted Agents

For security, private network access, or custom tooling, Scalr provides self-hosted agents for Terraform/OpenTofu runs and VCS interactions within customer infrastructure. This is vital for organizations unable to expose internal systems directly. Agents require only outbound HTTPS to Scalr.io.

Agents for Runs

Self-hosted agents execute runs on customer-controlled infrastructure. The agent polls Scalr.io for jobs, executes operations, and reports results. Scalr.io never needs network access to the agent. Each agent handles multiple concurrent runs (default 5), separate from Scalr.io's shared runners. Prerequisites include supported OS (Linux, Docker, Kubernetes), network access to *.scalr.io and *.docker.io, and appropriate sizing. ARM64 is supported.

Kubernetes Deployment (Helm): Scalr offers an official Helm chart.

helm repo add scalr-agent-helm https://scalr.github.io/agent-helm/
helm repo update
kubectl create secret generic scalr-agent-token-secret --from-literal=SCALR_TOKEN='<your-agent-token>' --namespace scalr-agents
# values-run-agent.yaml:
# agent:
#   type: "run"
#   scalr_url: "https://<your-account>.scalr.io"
#   scalr_token_secret_name: "scalr-agent-token-secret"
helm install scalr-run-agent scalr-agent-helm/agent-local -f values-run-agent.yaml --namespace scalr-agents --create-namespace

This uses the agent-local chart.

Docker Deployment Example:

docker run \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/scalr-agent:/var/lib/scalr-agent \
  -e SCALR_URL="https://<your-account>.scalr.io" \
  -e SCALR_TOKEN="<your-agent-token>" \
  -e SCALR_DATA_HOME="/var/lib/scalr-agent" \
  --rm -it --pull=always --name=scalr-run-agent scalr/agent:latest run

Agents for Private VCS Providers

For internal VCS providers (e.g., GitHub Enterprise, GitLab Self-Managed) not publicly accessible, Scalr VCS agents enable secure integration. The agent relays communication: private VCS connects to the agent internally; the agent uses outbound HTTPS to Scalr.io for syncing repo data. Run and VCS agents should be on separate infrastructure. VCS agent pools are configured at Account scope in Scalr. Deployment is similar to Run agents, specifying type: "vcs" in configuration.

Scalr supports various deployment methods (VM, Docker, Kubernetes via Helm) for agents.

Managing Scalr as Code: Automation and Control

Scalr itself can be managed programmatically, aligning with "platform as code" principles for consistency and auditability. This reduces manual configuration and error risk.

Scalr Terraform Provider

The Scalr Terraform provider manages Scalr resources (Accounts, Environments, Workspaces, variables, policies, etc.) declaratively using HCL. It automates Scalr setup, enabling "Scalr vending machines." Authentication uses a Scalr API token or service account for runs within Scalr.

Basic Provider Configuration:

terraform {
  required_providers {
    scalr = {
      source  = "registry.scalr.io/scalr/scalr"
      version = "~> 1.5" // Check registry for latest [6, 20, 21]
    }
  }
}
 
provider "scalr" {
  hostname = var.scalr_hostname
  token    = var.scalr_api_token
}
 
variable "scalr_hostname" {
  type        = string
}
 
variable "scalr_api_token" {
  type        = string
  sensitive   = true
}

The Scalr Ignite repository (https://github.com/sierra-cedar/scalr-ignite) offers comprehensive examples.

Scalr CLI

The Scalr CLI allows direct API interaction for scripting, ad-hoc tasks, and CI/CD integration. Configure with scalr -configure or environment variables (SCALR_HOSTNAME, SCALR_TOKEN). Syntax: scalr COMMAND. Create/update operations can use JSON blobs.

Example: Creating an Environment (flags):

export SCALR_HOSTNAME="myaccount.scalr.io"
export SCALR_TOKEN="your_cli_api_token"
scalr create-environment -name="cli-demo-env" -account-id="acc-your-account-id"

Scalr API

A comprehensive REST API offers deep programmatic control for custom automation. Authenticate with a Bearer token. Exposes CRUD operations for most Scalr objects.

Conclusion: Building a Scalable and Governed IaC Practice with Scalr

Scalr's architecture effectively addresses IaC management challenges at scale. Its SaaS model simplifies operations, while the three-tiered hierarchy (Account, Environment, Workspace) offers a clear framework for organization and governance. Object inheritance for variables, policies, and credentials ensures consistency. Flexible state management and self-hosted agents for runs and private VCS cater to diverse security needs. Scalr's "platform as code" approach via its Terraform provider, CLI, and API enables comprehensive automation and control. This combination lets teams manage cloud infrastructure with confidence, precision, and scalability.