Skip to main content

Upgrading Organisations

For the cloud engineer who installed Organisations, with the same AWS credentials: run the newer bundle's installer from a fresh directory in the same account and region; it re-runs the steps a release changes and leaves your administrators and single sign-on as they are.

Before you start: download the latest release from the AlphaAgent Console's Organisation page (Console: licences, usage and billing); the installer does not fetch releases. Requirements are those of the install (Install Organisations).

Upgrade​

  1. Unzip the new bundle into its own directory.
  2. Copy the installer's state file, .alphaagent-org-install.json, from the previous bundle's directory into the new one; it carries the step record and your answers.
  3. Run python3 orgctl.py install with the same --region and credentials. The installer finds the existing Organisation, prints its stacks and reads the running version from the deployed application stack itself. If it is older than the bundle it says "this bundle is <new>; the running install is <old>." and offers the Resume menu: Resume (default: continue from the first incomplete step and update the running install), Redo (every step again; idempotent, slower) or Delete and reinstall (destroy everything, then start fresh; the fresh install is always private, so it asks for a Transit Gateway, your administrators' ranges and the outbound traffic choice, and with console_access set to public in --config it stops before deleting anything). --yes always resumes.
  4. Confirm. The installer prints "Upgrading from <old> to <new>." and "Re-running org-auth, foundation, private-network, push-image, seed-config, spa, app, settle, doctor to apply <new>": the sign-in stack (updated in place), the foundation and data stacks, the private network, the container image, the configuration secrets, the console web application, the application stack, the settle wait and the doctor. saml, console-credential and bootstrap-admin do not re-run and are not asked again.
  5. Wait for the Done banner with your console address.

A stack change that would replace a data-holding resource (a table, secret, bucket, file system, cache, the user pool, a repository, queue, topic or database) stops and asks; only --allow-data-loss skips the question, never --yes or --config. Progress is saved after each step; Ctrl-C stops before the next and the same command resumes. Finally the installer re-reads the running version; a run that leaves the old one in place exits with "This run did not update the running install (still <old>). Run python3 orgctl.py install --redo or report this." instead of Done.

How your console's network access is kept​

The installer has thirteen steps. Network access, outbound traffic and the VPC range stay as they were installed; nothing is asked again.

  • A private console re-applies its private-network step: the attachment is found already available (no new request), and the routes, load balancer access and, with outbound traffic through your Transit Gateway, the endpoints are brought up to the release.
  • A public console (installed before private network access) keeps its internet-facing load balancer and NAT gateway. The private-network step prints "Skipped: public console access", and teardown works as before. Network access cannot be changed in place: a private console means a new install.
  • Before anything changes, the installer checks that each private subnet still has room for what the new release runs there. If not, it stops with the Organisation unchanged and names the smallest range that fits.

Run doctor​

python3 orgctl.py doctor, the last step, checks the configuration secrets, fail-closed configuration, the tables, the administrator roster, the image repositories, the two services, the account-registration template, the web application's CORS rule, the SAML wiring, the sign-out address, the Console credential and, on a private console, the attachment, routes and load balancer access, and the firewall list with outbound traffic through your Transit Gateway. Before checking the services it waits for any rolling restart the preceding steps started. It prints "N passed, N warning(s), N failed, N skipped", exits 2 on a failure, and --json prints data. After an upgrade: sign-out fails if the signed-out address is missing (run python3 orgctl.py org-auth); console-credential warns if the Console is unreachable and fails if the credential was rotated or revoked there (run python3 orgctl.py console-credential, or bundle downloads fail).

Re-run a single step​

Every step has its own command: preflight, org-auth, foundation, private-network, push-image, seed-config, spa, app, settle, console-credential, saml, bootstrap-admin and doctor; a single step skips the requirements block and the confirmation. saml re-asks for the metadata file when your identity provider's certificate rotates; console-credential follows a rotation in the Console.

status, reset and teardown​

  • python3 orgctl.py status prints the installed state (steps, single sign-on values, hostname, load balancer, stack statuses) and never prompts. A stack whose first create failed reads "stuck: <stack>. The first create failed and rolled back. Re-run python3 orgctl.py install: it deletes the stack and creates it again, unless its rollback kept resources, which are then named." Any other stuck stack cannot be updated: delete it, then python3 orgctl.py install --restart-from <step>.
  • python3 orgctl.py reset empties the state file when it was confirmed against another account or region.
  • python3 orgctl.py teardown deletes the Organisation in this account and region; the full resource list and flags are on Install Organisations.

What you should see​

  • The Done banner with "Console: https://<your hostname>"; doctor printing "N passed, 0 failed" (warnings are explained in the table).
  • The Organisations console, for anyone signed in, showing "The Organisations console was updated. Reloading to pick up the latest version…" with Reload now, and reloading itself four seconds later; its footer shows the new version. On live walks an upgrade took 7 to 13 minutes.

Notes​

  • python3 orgctl.py with no command prints the guided welcome ("No install recorded on this machine…", "An install is already under way here: N/13 steps done. Next step: …", or complete) and offers to start or resume.
  • Same account and region only. One installer per directory at a time; status is never blocked.
  • The network answers are fixed for the Organisation's life: console access, outbound traffic, the VPC range, the Transit Gateway, the administrators' ranges and the egress IP addresses. A --config file that gives a different value for one of them stops the run and names the value the Organisation was installed with.
  • Without the copied state file the installer recovers the installation from the live stacks and still applies the release, but may re-ask answers it cannot read back. An interrupted first install finished with single-step commands also upgrades correctly.
  • Teardown never touches the registration stacks in your Studio accounts (Accounts).