Roadrunner SMB™ — Deployment Guide

Last Updated: 2026-06-06

Who this is for

This guide is for AWS® administrators and DevOps engineers deploying Roadrunner SMB from the AWS Marketplace into an existing VPC. It assumes familiarity with CloudFormation®, VPC networking, and Active Directory®.

Not a fit for this guide: customers who want to evaluate RRSMB before having an AD domain ready. See Quick Start for the end-to-end first-deployment flow.

Marketplace launch: two CloudFormation stacks

AWS Marketplace launch uses a launcher (parent) template plus a nested appliance (child) template. Buyers interact with the parent; the parent creates the child automatically.

Day-one outputs (Admin UI, FTS link, NLB DNS, bootstrap secret): CloudFormation console → parent stack → Outputs tab. The parent re-exports the values you need from the nested stack.

Advanced / ops outputs (subnet IDs chosen, EFS IDs, ECS names, validation summaries): nested stack → Outputs tab. Use these for troubleshooting and automation, not for first-time setup.

Launch requires acknowledging IAM custom names and CAPABILITY_AUTO_EXPAND (nested stack creation).

IAM planning: The deployer principal (your IAM user/role) is install-time only — not used by the appliance at runtime. For permission tiers, deployer vs runtime roles, and the template-derived permission matrix, see Identity and permissions and Deployer permission matrix.

Cluster ID vs stack names

Marketplace deploys use a fixed cluster ID of rrsmb-prod for all DynamoDB-backed resources. This is separate from CloudFormation stack names:

One appliance per AWS Region per account is the supported deployment model today (Single-AZ and Dual-AZ both use cluster ID rrsmb-prod).

Architecture Overview

Roadrunner SMB deploys a configurable 1–4 node active-active SMB cluster into your AWS VPC. During deployment, select a node count from 1 to 4: use 1 node for evaluation and non-HA testing; use multiple nodes for HA production workloads. All nodes serve SMB traffic simultaneously; the Network Load Balancer distributes connections across them.

Your VPC (example topology; node count is 1–4)
│
├── AZ-1 (private subnet)         AZ-2 (private subnet)
│   └── RRSMB node(s)             └── RRSMB node(s)
│
├── AZ-1 / AZ-2 public subnets
│   └── Network Load Balancer (NLB in public subnets)
│       ├── Port 443 (TLS)  → Admin UI (restrict with AdminIngressCidr)
│       └── Port 445 (TCP)  → SMB from SmbClientCidr (VPC/private clients; not public internet by default)
│
├── Amazon EFS (shared storage — all nodes mount it)
│   ├── Share data (one EFS access point per share)
│   └── CTDB cluster coordination files
│
└── Amazon DynamoDB (regional, no AZ boundary)
    ├── NT ACL store
    └── CTDB cluster mutex

Key components

AWS Prerequisites

Account quotas

Verify your account has sufficient quota for:

• EC2: up to 4 instances (matches ClusterSize; m5.large by default)
• EFS: 1 file system, 2+ mount targets
• DynamoDB: 2 tables
• ECS: 1 cluster, 1 service, up to 4 tasks (matches ClusterSize)
• NLB: 1 load balancer, 2 listeners, 2 target groups
• Secrets Manager: 1 secret (bootstrap secret created by stack for First-Time Setup)
• CloudWatch Logs: 1 log group

Networking requirements

Roadrunner SMB deploys into your existing VPC. Before any product resources are created, the stack runs read-only VPC discovery and validation (and optional AD discovery hints). If your VPC does not meet requirements, the stack fails immediately with VPC Unsuitable: … and rolls back.

See VPC prerequisites for the full Step 0 flow, enforced checks, warnings, and stack outputs.

VPC endpoints (optional but recommended)

The deploy-time checker warns (but does not block by default) if these Interface endpoints are missing; add them to reduce NAT usage:

• com.amazonaws.<region>.ecr.api
• com.amazonaws.<region>.ecr.dkr
• com.amazonaws.<region>.secretsmanager
• com.amazonaws.<region>.logs
• com.amazonaws.<region>.sts

S3 and DynamoDB Gateway endpoints are required by default (RequireS3Endpoint / RequireDynamoDbEndpoint).

CloudFormation Parameters

At Marketplace launch (parent stack)

The buyer launch form exposes only:

Subnets, container image, and all other settings use release-baked defaults on the nested stack. Private and public subnets are auto-discovered from the VPC.

Note: Active Directory join credentials (and optional manual DC IP) are entered in the First-Time Setup wizard — not as CloudFormation parameters.

Advanced parameters (nested stack only)

The nested appliance template supports additional parameters (PrivateSubnetIds, PublicSubnetIds, AdminIngressCidr, AdminCidr, BackendImageUri, ApplianceState, sizing overrides, and more). These are not shown at Marketplace launch. To change them:

1. CloudFormation → open the nested stack (…-InnerStack-…) → Update.
2. Modify the parameter(s) you need → submit the stack update.

Common nested parameters:

Naming trap: AdminCidr does not control Admin UI access. Use AdminIngressCidr for HTTPS/443 to the Admin UI. Use AdminCidr only for metrics scraping from your observability network. | PrivateSubnetIds / PublicSubnetIds | (auto) | Optional comma-separated subnet IDs; blank = auto-discovery | | ApplianceState | Running | Running or Stopped — update via CloudFormation stack update | | BackendImageUri | (release default) | Marketplace ECR image for this version; updated automatically by in-appliance auto-update |

Stack Outputs

Parent stack (use these first)

After deployment, open the parent stack (RoadrunnerSMB-SingleAZ or RoadrunnerSMB-DualAZ) → Outputs:

Nested stack (advanced / ops)

The nested stack (…-InnerStack-…) also exposes detailed outputs:

Public endpoints (NLB)

The Marketplace stack uses one Network Load Balancer in public subnets. AdminUIUrl and NlbDnsName share the same DNS hostname.

• Admin UI (TLS/443): Reachable from the internet by default (AdminIngressCidr defaults to 0.0.0.0/0). Narrow to office, VPN, or bastion CIDRs for production.
• SMB (TCP/445): Restricted to SmbClientCidr (default 10.0.0.0/8 — your VPC and private client networks). SMB is not exposed to the public internet unless you deliberately widen SmbClientCidr.

Administrators use AdminUIUrl. SMB clients on allowed networks mount \\<NlbDnsName>\<sharename>.

RRSMB nodes and EFS stay in private subnets. The NLB is placed in public subnets (or subnets you supply via PublicSubnetIds).

To find endpoints later in the AWS Console:

1. Open CloudFormation → parent stack (RoadrunnerSMB-SingleAZ / RoadrunnerSMB-DualAZ) → Outputs → copy AdminUIUrl, AFirstTimeSetupInstructions, or NlbDnsName.
2. Open EC2 → Load Balancers and locate the stack NLB (name includes your environment label).
3. Confirm listeners: TCP/445 (SMB) and TLS/443 (Admin UI).
4. If the Admin UI is unreachable, verify your client IP is inside AdminIngressCidr, then check EC2 → Security Groups → rrsmb-<EnvironmentName>-nlb → inbound 443, and Target Groups for healthy Admin tasks.

Multi-AZ Topology

The stack distributes nodes across the provided subnets. AWS attempts to balance instances across AZs automatically.

Resilience: with subnets in 2+ AZs, tasks spread across zones. On multi-node deployments, AWS load balancing and ECS health checks steer SMB traffic away from unhealthy tasks; CTDB coordinates clustered Samba state while Roadrunner SMB enforces readiness/fencing.

AZ placement rules:

• Provide subnets in at least 2 AZs
• The stack creates one EFS mount target per subnet
• On multi-node clusters, the loss of a single node is absorbed by surviving nodes; single-node (1) deployments have no HA within the appliance tier

Scaling

Cluster size is 1–4 nodes. Set or change it in either of these equivalent ways:

Admin UI (recommended after deploy):

1. Open AdminUIUrl → Cluster
2. Set Customer Cluster Node Target (1–4) with the slider
3. Click Apply — CloudFormation updates ClusterSize; ASG and ECS converge asynchronously

CloudFormation:

1. Update the parent stack Cluster Node Count (ClusterSize) — the launcher passes it to the nested stack
2. The ASG and ECS service update via rolling replacement

Supported deployment size: 1–4 nodes. 1-node mode is for evaluation, trial, and non-HA use. Production HA deployments should use multiple nodes. Deployments outside 1–4 are not validated and not supported.

EC2 hosts and ECS tasks

At steady state, ECS DesiredCount and ASG DesiredCapacity both equal ClusterSize (ClusterSize is the CloudFormation Cluster Node Count). Roadrunner SMB runs one ECS task per EC2 host.

ASG MaxSize is ClusterSize + 1 (for example 2 nodes → max 3 instances). The extra slot is for rolling container or host updates only — the ASG returns to ClusterSize when the update completes. You do not run a permanently idle spare node under normal operation.

Stop and start (scale to zero)

The Admin UI Cluster slider supports 1–4 only. To stop all compute during evaluations or periods of inactivity:

To bring the cluster back online:

• Update the CloudFormation stack with ApplianceState=Running and the desired Cluster Node Count; or
• Set ASG desired capacity back to ClusterSize (and min/max to match the stack) if you stopped manually — then align ApplianceState on the stack so future stack updates stay consistent.

EC2 and ECS task charges stop while at zero. EFS, DynamoDB, NLB, and other retained AWS resources may still incur charges. See FAQ — scale to zero.

The Admin UI slider does not support scaling to zero. See Admin Guide — Cluster.

Admin UI access

Marketplace: Open AFirstTimeSetupInstructions or AdminUIUrl from the parent stack Outputs tab. The Admin UI is served over HTTPS on port 443 on the NLB.

Security groups and parameters

AdminCidr does not control Admin UI access. To restrict who can open the Admin UI from the public internet (or to limit access to a VPN or jump box), update AdminIngressCidr on the nested stack. CloudFormation updates inbound 443 on the NLB security group.

Port 8888 on RRSMB tasks is the internal Admin API port (NLB → task path only). Customers use AdminUIUrl (HTTPS/443), not task port 8888 directly.

Patterns (office IP, VPN, jump box) and Console steps: Security overview — Restricting Admin UI access · Quick Start — Harden for production.

Non-Marketplace dev topologies may differ; always follow the AdminUIUrl output for your stack.

Updating the Software

Roadrunner SMB automatically checks for newer approved releases (release manifest + Marketplace release ECR repository) about every 90 seconds. When a newer approved build is detected and automatic updates are enabled, Roadrunner SMB schedules a rolling update for the next local midnight after detection — the start of the next calendar day in the deployed AWS Region’s timezone. The rolling update replaces nodes sequentially to preserve service availability on multi-node deployments.

Use the Admin UI Software Update page to apply immediately (Apply latest approved version), defer a scheduled update by 24 hours, or disable automatic updates.

Change control: Customers should still review release notes before allowing production updates when operational change control is required.

Advanced recovery (for example rollback coordinated with support) may involve CloudFormation parameters; routine updates do not require manually editing BackendImageUri.

Post-Deployment Checklist

After the stack reaches CREATE_COMPLETE:

• Admin UI is accessible at AdminUIUrl
• Bootstrap secret retrieved from AWS Secrets Manager using BootstrapSecretConsoleUrl / BootstrapSecretArn outputs
• First-Time Setup wizard completes successfully
• Domain join succeeds (Setup page shows domain joined)
• Cluster page shows all nodes as healthy (green)
• Create a test share and mount from a Windows® machine
• Verify file read and write in the mounted share

Cluster Stop/Start for Planned Downtime

Use a CloudFormation stack update to change ApplianceState — do not change ECS or ASG capacity directly unless you follow the manual scale-to-zero path in Stop and start. All data on EFS and DynamoDB is retained while stopped.

Stop the appliance:

1. In CloudFormation, open your Roadrunner SMB stack (RoadrunnerSMB-SingleAZ / RoadrunnerSMB-DualAZ).
2. Update → set ApplianceState (under Advanced) to Stopped.
3. Wait for UPDATE_COMPLETE. ECS desired count and ASG min/desired/max scale to 0.

Start the appliance:

1. Update the same stack → ApplianceState = Running (confirm Cluster Node Count is set as needed).
2. Wait for ECS tasks to reach ClusterSize and NLB target groups to show healthy targets.

See FAQ — scale to zero for billing and metering notes during stop periods.

References

• Quick Start Guide
• Identity and permissions
• Deployer permission matrix
• Admin Guide
• Known Limitations
• Support & Troubleshooting
• AWS Marketplace deployment summary