Skip to main content

Client Prerequisites

Everything on this page must exist before the deployment window. Items marked (blocking) stop the install; items marked (degraded) let the install finish but leave a feature broken until provided.

1. AWS account & access (blocking)​

  • A dedicated or shared AWS account where OpenBox will run. The deploy region must be one of: us-east-1, us-east-2, us-west-2, eu-west-1, eu-west-2, eu-central-1, ap-southeast-1, ap-southeast-2, ap-south-1, ap-northeast-1 (EKS Auto Mode availability — other regions need explicit vendor sign-off).
  • An IAM deploy role the operator can assume, with administrator-level access for the deployment window (CloudFormation, EKS, EC2, IAM role creation, Route53, ACM, Secrets Manager, Lambda, S3). If your org enforces an IAM permissions boundary, give us its ARN — the CDK attaches it to every role it creates.
  • One or more IAM role ARNs that should get cluster admin (EKS access entries) — usually your platform team's role. At least one is required.
  • CDK bootstrap is allowed in the account/region (we run cdk bootstrap once if it has never been done).

2. Service quotas (blocking — longest lead time, request first)​

Check in Service Quotas → EC2, in the deploy region:

QuotaMinimumWhy
Running On-Demand G and VT instances≥ 8 vCPUsLlamaFirewall's vLLM runs on one g5.xlarge GPU node (4 vCPUs); headroom for node replacement during upgrades
Running On-Demand Standard (A,C,D,H,I,M,R,T,Z)≥ 64 vCPUscpu/memory/database/guardrails node pools (c6a, m7a, r* families)

A brand-new account commonly has the G-family quota at 0 — the request can take 24–48 h, so file it first. If GPU capacity is impossible for you, tell us in advance: LlamaFirewall can be disabled, which removes prompt-scanning (guardrails-api's LLM checks degrade).

3. Networking — you create it, we import it (blocking)​

The CDK never creates networking. Provide:

  • A VPC in the deploy region.
  • ≥ 2 private subnets in distinct AZs with outbound internet via NAT (image pulls from ghcr.io/quay.io, ACM/STS/Secrets Manager calls). Tag-free is fine; we reference by subnet ID.
  • ≥ 1 security group you own (used by the preflight Lambda and the node NodeClass; we never create SGs). Default egress-all is sufficient.
  • VPC DNS attributes both enabled — enableDnsSupport=true AND enableDnsHostnames=true (a VPC created via aws ec2 create-vpc defaults hostnames to false; EKS nodes cannot join without it): 
    aws ec2 modify-vpc-attribute --vpc-id <vpc> --enable-dns-support
    aws ec2 modify-vpc-attribute --vpc-id <vpc> --enable-dns-hostnames
  • Subnet role tags for the load balancer controller — without these the NLB cannot be placed and the ingress never gets an address: 
    # every private subnet you hand us:
    aws ec2 create-tags --resources <private-subnet-ids> \
      --tags Key=kubernetes.io/role/internal-elb,Value=1
    # public subnets too, only if you chose ingressPublic:
    aws ec2 create-tags --resources <public-subnet-ids> --tags Key=kubernetes.io/role/elb,Value=1
  • ≥ 2 public subnets in distinct AZs — required by default, since the ingress is now internet-facing (restricted to your allowedCidrs). Only optional if you choose ingressPublic: false for an internal NLB
  • Decide cluster API endpoint mode: public+private (default, lets us deploy from outside) or private-only (we must deploy from inside your network — adds setup).

CIDR planning: nothing OpenBox-specific, but if you'll peer the VPC to a corporate VPN later, make sure the CIDR doesn't collide with your VPN-side ranges.

4. DNS & domain (blocking)​

  • A public Route53 hosted zone in the same account, and the domain you want OpenBox under (the zone's name itself or a subdomain of it).
  • If the parent domain lives elsewhere (Cloudflare, GoDaddy, corporate DNS): delegate the zone by adding its 4 NS records at the parent before the deployment window and verify dig NS <your-zone> answers with the Route53 name servers.

Why blocking: the CDK requests an ACM wildcard certificate validated by DNS. If the zone isn't publicly resolvable, cert validation hangs and the deployment stalls at the certificate step. We create 5 records under the domain (identity, openbox-api, opa, openbox-core, openbox-eks) — the record names are chart defaults; nothing else in the zone is touched.

5. Container images: registry token or Marketplace subscription (blocking)​

Which one depends on the chart source agreed with us (see GHCR or AWS Marketplace chart).

AWS Marketplace chart: subscribe your deployment account to the OpenBox listing on AWS Marketplace before the window. There is no token: the cluster's nodes pull images with their own IAM role. Your private subnets' egress must reach 709825985650.dkr.ecr.us-east-1.amazonaws.com, api.ecr.us-east-1.amazonaws.com and prod-us-east-1-starport-layer-bucket.s3.us-east-1.amazonaws.com (the registry is in us-east-1 whatever your region; image layers download from that S3 bucket). The pre-flight check verifies all three. You also need an admin email (§ hand-over item 8) — this chart always creates your organization.

GHCR chart (default): images are pulled from GitHub Container Registry (ghcr.io/openbox-ai/*). The vendor issues a scoped read token (classic PAT with read:packages — fine-grained PATs do not work with ghcr). You store it in your Secrets Manager as a complete .dockerconfigjson document and give us the secret ARN. Secret material never passes through config files or the CDK code — the deployment reads it from Secrets Manager at apply time.

6. Application config & secrets (recommended)​

Both services take their configuration purely from the environment — there is no .env file. You supply two things per service:

  • Non-secret config (coreEnv / backendEnv in the deploy config): plain key/value pairs such as SES_FROM_EMAIL, SES_ROLE_ARN, S3_REGION, CONTROL_PLANE_URL, GITHUB_APP_ID. Validation rejects secret-looking keys here, because these are stored in plaintext.

AWS credentials are not yours to create. The deployment generates a dedicated IAM user, access key, and assumable role for each service and injects them automatically, including the backend's KMS_* set. Your AWS-facing job is only to allow those roles whatever they must reach (e.g. SES sending).

7. Email / SES (degraded if missing)​

The backend sends email (organization invitations, password reset) through AWS SES using credentials and region from the backend env file.

You must provide either:

  • an SES-verified domain or sender identity in a region of your choice, plus an IAM keypair allowed to ses:SendEmail, or
  • an explicit "no email" decision.

If SES is not provided: the install completes and the platform runs — the backend boots with placeholder regions — but every email-dependent flow fails at the send step: invited users never receive invitations and password-reset emails never arrive. Admin-driven workarounds (manual password set in Keycloak) exist but are not a substitute. If your SES account is still in sandbox mode, only verified recipient addresses receive mail — request production access early; it can take 24 h.

8. reCAPTCHA: keys or an explicit opt-out (blocking)​

Registration and login forms are protected by Google reCAPTCHA. Choose one:

  • Use reCAPTCHA — supply the keys below.
  • Switch it off — tell us, and we set recaptchaDisabled: true. Sign-in then works without Google keys.

The deployment refuses a config with neither: reCAPTCHA stays on by default, and without keys nobody could sign in. With keys:

  • Public egress CIDRs for the ingress allowlist (curl -s https://checkip.amazonaws.com from your network; ask your network team for the FULL range). Without them a public install fails validation.

  • Site key (public) and secret key (private) — both go into the deploy config (recaptchaSiteKey / recaptchaSecretKey) and must be supplied together; a site key without its secret key makes every verification fail.

  • The site key's allowed domains list in the Google admin console must include your OpenBox domain (a parent domain covers subdomains).

If missing or the domain isn't allow-listed, the app loads but registration/login form submissions fail captcha verification.

9. Application KMS key (nothing to provide)​

The backend's symmetric KMS key is created automatically in your account (install-scoped alias, rotation off, RETAIN — deleting the stack never deletes the key). You only need the IAM credentials in your backend env file to allow kms:*; the key's ARN comes back as a stack output.

10. License (blocking unless PoC)​

A licensed install needs three values from your OpenBox license bundle: the license token (stored in your Secrets Manager), your tenant ID, and the control-plane URL. PoC/evaluation installs waive all three by agreement.

11. Optional: OPA policy bundle (nothing to provide)​

The policy-bundle bucket and OPA's read access are created automatically (IRSA — no S3 keys to issue or rotate). If you maintain custom OPA policies, upload bundle.tar.gz to that bucket after the install (command is a stack output) and ask us to set opaBundleEnabled: true. Until then OPA runs with the chart's built-in policy — fine for most installs.

Hand-over summary​

Send us, in writing, before the window:

  1. Account ID, region, deploy role ARN (+ permissions boundary ARN if any)
  2. VPC ID, ≥2 private subnet IDs, SG ID(s), (public subnet IDs if public ingress)
  3. Hosted zone ID + domain (delegation verified)
  4. Admin role ARN(s) for cluster access
  5. Chart source (GHCR or AWS Marketplace). GHCR: the Secrets Manager ARN of the registry token. Marketplace: confirmation that the account is subscribed. Plus backend/core env values and the license ARN
  6. reCAPTCHA site and secret key, or a decision to switch reCAPTCHA off; SES decision
  7. Kubernetes version preference (1.31–1.36; we default to a recent stable minor)
  8. Admin email for org pre-seeding — must be on your corporate domain; the domain becomes your organization ID. Optional for the GHCR chart, required for the Marketplace chart

Every one of these maps 1:1 to a field in Config Reference.

Last updated on