Skip to main content

​
Overview

This guide will walk you through the process of deploying SGP in an AWS account. SGP AWS infrastructure is defined by terraform modules managed by Scale.

​
Prerequisites

  • Access to an AWS account with sufficient permissions to create resources
  • The following tools installed:
  • The following from Scale:
    • The SGP AWS Infrastructure Terraform modules
    • A workspace_id and registration_secret unique to your deployment
    • install.sh script to bootstrap the SGP cluster
  • A new application configured in your identity provider to authenticate to the SGP platform (SAML or OIDC) (optional)
  • A custom domain for your deployment (optional)

​
Installation

​
Step 1: Prepare Terraform Root Module

In a new directory, create a .tf file to invoke the SGP AWS infrastructure Terraform modules. Reference the egp-hybrid-cloud-customer-deployment module as the entrypoint for the SGP infrastructure. 
module "egp_hybrid_deployment" {
  source                = "<path to egp-hybrid-cloud-customer-deployment module>"
  scale_account_id      = "<workspace_id>"
  registration_secret   = "<registration_secret>"  # sensitive — use TF_VAR_registration_secret env var

  domain = "<workspace_id>.workspace.egp.scale.com"  # or your custom domain

  # Core services — enable the components you need
  deploy_egp_api    = true   # EGP API backend — required for the SGP platform
  deploy_spellbook  = false  # Spellbook prompt management service (optional)
  deploy_sgp_models = false  # SGP model serving infrastructure (optional)
  deploy_llm_engine = false  # Model Engine service (optional)
  deploy_agentex    = false  # Agentex agentic workflow service (optional)
  create_agentex_tool_cache = false  # Persistent tool cache for Agentex (optional)
  enable_cloud_build = false # Cloud-based container build service for Agentex (optional)
  add_agents_service = false # Agent Service for building and running agents (optional)
  add_document_understanding_capability = false  # Document Understanding (Dex) service (optional)
  enable_reducto    = false  # Reducto OCR and document parsing service (optional)
  enable_train      = false  # SGP model training infrastructure (optional)
  enable_compass    = false  # Compass workflow orchestration service (optional)
  enable_ukbp       = false  # Universal Knowledge Base Pipeline (optional)
  enable_system_manager = true  # System Manager deployment orchestrator — required
  enable_monitoring = false  # Observability stack (optional)

  create_temporal_postgresql = true  # Recommended; set false to use an in-cluster Cassandra instead

  omit_egp_control_plane = false  # Set true to disable communication with Scale's hosted control plane

  base_repository = "<base container registry URL>"  # Only needed if not pulling from Scale's registry

  openai_api_key    = "<openai_api_key>"     # sensitive — use TF_VAR_openai_api_key env var
  openai_org_id     = "<openai_org_id>"
  anthropic_api_key = "<anthropic_api_key>"  # sensitive — use TF_VAR_anthropic_api_key env var
  launch_api_key    = "<launch_api_key>"     # sensitive — use TF_VAR_launch_api_key env var

  authentication_type = "SAML"  # "SAML" or "OIDC"

  use_cmk = true  # Recommended for production: encrypts data at rest using AWS KMS

  # If deploying into an existing VPC rather than creating a new one, provide the IDs here
  # vpc_id             = "<existing VPC ID>"
  # private_subnet_ids = ["<subnet-id-1>", "<subnet-id-2>"]
  # public_subnet_ids  = ["<subnet-id-1>", "<subnet-id-2>"]

  access_cidrs = []  # List of CIDR blocks to allow access; defaults to open to internet

  # Load balancer configuration
  load_balancer_type = "application"  # "application" or "network"
  # waf_name          = "<WAFv2 Web ACL name>"  # Optional; only applies to application load balancers
  internal_lb        = false  # Set true to prevent internet access to the load balancer
  # additional_certs  = ["<certificate ARN>"]  # Additional TLS certificates for the load balancer

  # permissions_boundary_arn = "<ARN>"  # Optional: IAM permissions boundary for provisioned roles

  # See the module documentation for the full list of available variables
}

# Example Terraform provider and backend configuration
provider "aws" {
  region = "<your-aws-region>"
}

terraform {
  required_version = ">= 1.1.7"

  backend "s3" {
    bucket       = "sgp-<workspace_id>-terraform-state"
    key          = "sgp-<workspace_id>-sgp.tfstate"
    region       = "<your-aws-region>"
  }
}

​
Step 2: Provision Infrastructure via Terraform

Run the following commands in the same directory as the previous step’s .tf file. 
terraform init

terraform plan -out=tfplan

# Inspect this plan to review the planned resources to be provisioned before proceeding
terraform show tfplan 

terraform apply tfplan
This step may take significant time due to resource creation dependencies
If a pre-created certificate and domain entry are not provided, you will likely encounter the following error:
Error: creating ELBv2 Listener (arn:aws:elasticloadbalancing:us-east-1:12345678910:loadbalancer/net/scale-egp-<workspace_id>/12345678910): operation error Elastic Load Balancing v2: CreateListener, https response error StatusCode: 400, RequestID: 12345678910, api error UnsupportedCertificate: The certificate 'arn:aws:acm:us-east-1:12345678910:certificate/12345678910' must have a fully-qualified domain name, a supported signature, and a supported key size.
Resolve this by properly configuring DNS and TLS for your domain before re-running terraform apply.

​
Step 3: Bootstrap the Cluster

Note the following values from the previous step’s apply output: 
export SYSTEM_MANAGER_IRSA_ROLE_ARN=$(terraform output -raw system_manager_irsa_role_arn)
export SPICEDB_DATASTORE_URI=$(terraform output -raw spicedb_connection_string)
export AWS_REGION="<your-aws-region>"

​
Configure EKS access

Configure access for yourself to the provisioned EKS cluster:
  1. Navigate to “Elastic Kubernetes Service” on the AWS console
  2. Go to the required cluster
  3. Go to Access
  4. Under IAM access entries click Create Access Entry
  5. Select your current AWS IAM role from the dropdown, leave the Type as Standard
  6. Add the AmazonEKSAdminPolicy and AmazonEKSClusterAdminPolicy to the Cluster scope
  7. Click create

​
Allowlist your IP (if needed)

  1. Navigate to “Elastic Kubernetes Service” on the AWS console
  2. Go to the required cluster
  3. Go to Networking
  4. On the right, click Manage and click Endpoint Access
  5. Under Advanced settings add your IP address

​
Execute install.sh

Run the install.sh script to create the following Kubernetes resources: 
cd <path to install.sh>

# Set the correct kubectl context
aws eks update-kubeconfig --name scale-egp-<workspace_id> --region <aws_region>

# Execute the install.sh script
./install.sh
System Manager is the deployment orchestrator for the SGP platform. It will automatically begin deploying the other services required for the SGP platform within the cluster.

​
Step 4: Verify the Deployment

Wait for all services to be ready: 
kubectl get helmreleases -A  # All should be Ready=True
kubectl get pods -A          # All should be Running

​
Step 5: Configure Identity Provider

​
SAML Configuration

In your Identity Provider, configure a new SAML application with the following settings:
  • Service Entity ID: https://auth.<domain>
  • Redirect URI: https://auth.<domain>/dashboard/org/saml/callback
Modify the configuration scale-egp-<workspace_id>/identity-service-saml-secrets (either via System Manager or directly in AWS Secrets Manager): 
{
  "id": "<workspace_id>",
  "samlConfiguration": {
        "entityId": "<entity id from your identity provider>",
        "x509Cert": "<x509 certificate from your identity provider>",
        "ssoUrl": "<sso URL from your identity provider>",
        "attributeMappings": {
            "email": "<email attribute name from your identity provider>",
            "firstName": "<first name attribute name from your identity provider>",
            "lastName": "<last name attribute name from your identity provider>"
        }
    }
}

​
OIDC Configuration

In your Identity Provider, configure a new OIDC application with the following settings:
  • Redirect URI: https://auth.<domain>/dashboard/org/oidc/callback
Modify the configuration scale-egp-<workspace_id>/identity-service-oidc-secrets (either via System Manager or directly in AWS Secrets Manager) with the following JSON: 
{
  "id": "<workspace_id>",
  "oidcConfiguration": {
    "clientId": "<client ID from your identity provider>",
    "clientSecret": "<client secret from your identity provider>",
    "issuer": "<issuer from your identity provider>",
    "authorizationUrl": "<authorization URL from your identity provider>",
    "tokenUrl": "<token URL from your identity provider>",
    "userInfoUrl": "<user info URL from your identity provider>"
  }
}
After modifying the secret, restart the sgp-system-manager deployment to apply the changes. 
kubectl rollout restart deployment sgp-system-manager -n sgp-system-manager

​
Accessing the Platform

If all goes smoothly, you should be able to navigate to the SGP platform at https://<workspace_id>.workspace.egp.scale.com (or your custom domain) and authenticate via the configured identity provider.