Install on AWS

Admin guide

Greenlight installs into an AWS account you control. Plan on about 15–20 minutes for infrastructure provisioning and another 15–20 minutes for the install wizard.

Azure Supported GCP Supported AWS Supported

This page covers AWS. See Install on Azure or Install on GCP for the equivalent deployment in those clouds.

What Shift provides

Your Shift implementation contact delivers the approved release as a private, versioned greenlight-aws-<version>.zip archive. It opens into one versioned directory holding install.sh, a README and troubleshooting guide written for the installing administrator, the release manifest, and a deployment/ directory with the Terraform configuration, provider lock file, pinned Kubernetes assets, and the Greenlight chart. The script is part of the archive; IT does not write or download it separately. The public docs describe the resources and permissions without publishing the package or image access details.

What you need before you start

• A dedicated AWS member account with billing enabled.
• A provisioning identity with AdministratorAccess in that account.
• A non-overlapping RFC 1918 range if the Greenlight VPC will peer with an existing network. You do not need to decide the region in advance: the installer lists the regions your account has enabled that can host Greenlight, and you pick one.
• A domain where you can delegate one subdomain, such as greenlight.acme.com, to Route 53.
• An IT administrator who can configure the OIDC identity provider, delegate the DNS subdomain, install the Greenlight GitHub App, and become the initial Greenlight org_admin.
• terraform, the AWS CLI, helm, kubectl, jq, curl, and dig at the versions listed in the private package README, plus bash 4.3 or newer. The installer checks all of them before it asks for anything and tells you how to install whatever is missing. On macOS, /bin/bash is 3.2 and too old — brew install bash and run the installer with that one.

What the install provisions

Everything below is created inside the dedicated Greenlight account.

Area	Resources
Network	A VPC spanning two Availability Zones for private node and database subnets, one public ingress subnet in a single Availability Zone, an internet gateway, and NAT
Compute	One EKS cluster with a dedicated system node group, an autoscaling app node group, and cluster-autoscaler
Databases	Two private RDS for PostgreSQL instances: one for Greenlight and one for app-owned logical databases
Storage	Private, encrypted, versioned S3 buckets for app objects, app assets, and platform storage, plus a versioned Terraform state bucket
Registry	ECR repositories for Greenlight and app images
Secrets	Secrets Manager entries for platform, database, integration, and app secrets
DNS and ingress	One Route 53 hosted zone, an NLB with one reserved Elastic IP, Traefik, and cert-manager
Identity	Dedicated IAM roles and IRSA bindings for the control plane, certificates, autoscaling, data access, and deployed apps

The public entry points are the Greenlight/app ingress and the authenticated EKS API. RDS is private, S3 blocks public access, and workloads use IRSA instead of static AWS access keys.

If you want Greenlight to send notification email, provide an SMTP relay such as Amazon SES SMTP or another approved provider. Email remains disabled when no relay is configured.

Greenlight-managed capacity

Greenlight selects and manages the infrastructure profile in the versioned deployment package. The values below describe the standard installation footprint for cost and quota review; they are not settings the installing administrator chooses or maintains.

Resource	Default
EKS system node group	1 × m6a.xlarge
EKS app node group	m6a.xlarge, autoscale 0–3
RDS control plane	PostgreSQL 16, db.t4g.large, 32 GB gp3 with automatic growth
RDS app databases	PostgreSQL 16, db.t4g.large, 32 GB gp3 with automatic growth
S3	Regional, encrypted, versioned, all public access blocked

Greenlight manages workload autoscaling within this profile and delivers capacity changes through versioned releases. Do not edit node groups or database classes directly; the next Greenlight infrastructure reconcile treats the versioned deployment profile as the source of truth.

Required access

Identity	Access	Why
Provisioning identity	AdministratorAccess in the dedicated Greenlight account	Creates resources, IAM roles, policies, and trust bindings
Greenlight runner role	Resource-scoped access to EKS, RDS, Secrets Manager, S3, ECR, and the delegated Route 53 zone	Operates the control plane and provisions app resources
cert-manager role	Route 53 record access on the delegated zone only	Completes DNS-01 certificate challenges
cluster-autoscaler role	Node-group autoscaling actions for the Greenlight cluster	Adjusts the app node group within its configured bounds
Connected-data role	No AWS permissions by default	Receives access inside a connected database only when a DBA grants it
Updater role	Infrastructure access within the dedicated Greenlight account, no registry writes	Applies Greenlight releases inside the maintenance window

The installer creates the runtime roles and their IRSA trust bindings. Your team does not create or distribute long-lived AWS access keys. Delete protection guards the databases, buckets, hosted zone, and cluster, so no automatic update can remove them.

Install inputs

The installing administrator supplies only values specific to the customer’s environment:

Input	Required	Purpose
AWS CLI session	Yes	Selects the dedicated target account; install.sh derives the account ID from the active credentials and points Terraform at that session so it can refresh, so a browser aws login works the same as SSO. No flag overrides the account
--region	Yes	Region where Greenlight resources are created. Omit it in an interactive run and the installer offers the regions your account can use
--control-plane-host	Yes	Delegated DNS zone and final Greenlight hostname
--certificate-contact	No	Contact address on the certificate issuer. Derived from your host name when omitted
--network-range	Only when needed	Replaces the package default when it overlaps a peered network

Every input above has a matching prompt: run ./install.sh with no arguments and it explains and asks for each one, so the flags are only needed for scripted runs — which must also pass --non-interactive: it requires every input up front, stops rather than prompting when one is missing, and is the only thing that skips the two confirmations. A run with no terminal that omits it stops at the first confirmation rather than proceeding on its own.

Resource names, instance sizes, database classes, Terraform provider versions, Kubernetes chart versions, and Greenlight image digests are derived or pinned by the release package. They are not install inputs.

Run the install

After authenticating the AWS CLI to the dedicated Greenlight account, extract the private release archive and run the script it contains:

unzip greenlight-aws.zip
cd greenlight-aws-v<version>

aws sts get-caller-identity

./install.sh

Run it with no arguments. The installer explains and asks for the region and host name, and offers the standard private network 10.240.0.0/16 as a yes/no — that range cannot be changed after install and cannot be peered if it overlaps a network you will connect later; only a “no” asks for a different range. For the region it shows a numbered list, grouped by geography, containing only the enabled regions that can host Greenlight; enter a number, or type a region code if you already know which one you want. Working out that list changes nothing in your account — a region you have not opted into is simply absent, because enabling one is a change the installer will not make for you. To answer up front instead, pass the flags from the table above.

Before it creates anything, the installer checks that the region offers PostgreSQL 16 with the release’s database class and each requested EC2 instance type. If an instance type is not offered there, it names which of the two it rejected and offers the region’s types with the same 4 vCPU / 16 GiB shape; a scripted run names the flag to pass instead and stops before anything is created.

Verify that aws sts get-caller-identity returns the intended account before continuing: that account is where Greenlight installs, and there is no flag that overrides it. The installer prints the identity it is using — role, account, and where the credentials came from — before it does anything, holds every AWS call in the run to the --region you pass even if your shell has a different AWS_REGION exported, and stops with a clear message if Terraform and the AWS CLI resolve different accounts. The package README pins the required CLI versions, and the installer checks all of them in one pass before anything else runs.

1. Validate the target account. Confirm the active AWS identity and account before running the command. The installer checks every required tool and version in one pass, and verifies it can pull the release’s pinned public images, before it creates anything.

2. Confirm twice. The installer shows a review screen — account, region, host name, networking, instance sizes, and the exact image digests — and waits for you to confirm before the Terraform state bucket is created. It then writes a Terraform plan, shows it, and asks you to confirm yes or no. Applying that saved plan file is what runs, so what executes is what you reviewed.

3. Let the packaged script complete. It runs the plan, obtains EKS credentials, and applies the package-pinned Gateway API CRDs, AWS Load Balancer Controller, cluster-autoscaler, Traefik, cert-manager, and Greenlight Helm releases — the Greenlight step also creates the Greenlight database login inside RDS, using a temporary credential the installer discards immediately after. It prints a phase name and the matching guide section before each operation, and for each step that can run for minutes without output it shows what it is waiting for and how long it has been waiting — so a long silence is never ambiguous. It can be rerun safely after a partial failure.

   Running it from a pipeline, or prefer plain output? Pass --no-color (or set NO_COLOR) for text only, with no colour and no progress indicator. Redirected output is already plain. Set GREENLIGHT_INSTALL_VERBOSE=1 to see every command’s full output instead of a progress indicator.

4. Open the install wizard. The install prints Finish setup in the browser: and a temporary URL on the reserved ingress Elastic IP, verified to be the one address your DNS records will point at, that works before your final DNS name and certificate are ready. The wizard then shows the Route 53 nameservers to delegate.

5. Delegate the zone. Create the NS records shown by the wizard in your parent DNS. Greenlight creates the control-plane, wildcard app, and certificate-challenge records inside the delegated zone, then checks on a repeating timer until delegation, the certificate, and HTTPS are live — nothing to click while you wait.

6. Finish the wizard. Configure OIDC, test sign-in, install the GitHub App, bootstrap the plugin marketplace, name the administrator we should contact about your trial and subscription (changed later in Settings → Organization), and confirm the organization and initial administrator.

7. Verify the installation. Open the final HTTPS URL and run the installation-health checks.

Typical elapsed time

Infrastructure provisioning takes about 15–20 minutes. The install wizard usually takes another 15–20 minutes. DNS propagation can extend the total elapsed time.

Post-install verification

Installation health verifies that:

1. The final URL resolves over HTTPS.
2. SSO resolves to a real IdP user with the required role mapping.
3. The GitHub App can reach at least one repository.
4. A plugin marketplace repository has its initial generated commit.
5. The policy bundle and audit log are active.
6. A test app can register and pass the policy check.

The installer is idempotent: rerunning the same version reconciles the existing installation.

Reruns must use the same state location

If you installed with --state-bucket or --state-key, pass the same values on every rerun. A rerun that finds the existing installation but is pointed at a state bucket or key that does not hold its state stops before planning with this run points at a Terraform state that does not describe this installation — it creates nothing, and the message names the flags to rerun with.

Upgrades

Greenlight upgrades through a customer-owned updater inside the same AWS account. It applies the versioned Terraform and Helm release using customer-controlled permissions. See Upgrades.

Next

DNS & TLSThe single delegated zone and wildcard certificate.

Identity, SSO & RBACConnect your OIDC provider and map administrators.

Source control & policyInstall the GitHub App and scope repositories.