Upgrade to v1.62

Move from v1.61 or older to v1.62. History is in the CHANGELOG.

Before you start

• Run v1.61.x (v1.61.1 or later on Lambda). Deploy binary and Pulumi library 1.62 together.

• Have the zip's SHA-256 for LambdaArgs.PackageSHA256, and AWS credentials for /sluis/* in SSM (migrate state).

• Read pulumi preview before every apply.

• The binary reads v1 and v2 documents: move it first.

1. Render the policy

sluisctl policy render <file or directory> -o policy.yaml

This merges v1 policy files, access documents and policy/v2 fragments. Name the result in each service document's policy.file.

2. Move the keys out of the service documents

Set each service document to apiVersion: sluis.truvity.github.io/<document>/v2 and move these keys:

v1 key	v2 key
exchange.clustersFile, exchange.awsFile, github.owners	exchange.clusters, exchange.aws, exchange.github.owners
github.runnerTiers, github.catalogueFile, slack.catalogueFile	apps.github.runnerTiers, apps.github.catalogue, apps.slack.catalogue
enabledOrgs, enabledWorkspaces	controllers.github.enabledOrgs, controllers.slack.enabledWorkspaces
policyDir, overlayFile, api	policy.file, directory.workspaces, removed
valkey.passwordEnv, oauthClient.idFile, .secretFile, .secretEnv, adminPasswordEnv, recovery.passwordFile, clientSecretsDir, ...stateSecretFile, directory.workspaces[].keyFile	valkey.passwordSecret, recovery.passwordSecret, signingKey.kms.stateSecret, signingKey.kmsWrapped.stateSecret (issuer/state-secret), keySecret (directory/<id>/key), oauthClient.provider, secrets: {source: env \| file \| ssm, root}

A v2 document naming a retired key is refused. Check with sluis serve --config <file>.

3. Copy the configuration secrets to the instance root

sluis migrate ssm-layout --to-root /sluis/<instance> --dry-run
sluis migrate ssm-layout --to-root /sluis/<instance>

This renames oauth/client-id and client-secret to providers/google/default/..., and clients/<id> to clients/<id>/secret. Old parameters stay.

4. Copy the credentials

sluis migrate --from <config naming /sluis> --to <config naming /sluis/<instance>>

totals.verified equals totals.source.

5. Apply the library and binary

On Lambda, set PackageSHA256, Instance and the documents. On Kubernetes, run helm upgrade. Leave the signing keys unchanged.

Lambda library	Change
environment	SLUIS_ROLE, SLUIS_CONFIG=/opt/sluis/<role>.yaml, OTEL_*; SLUIS_CONFIG_FILE, SLUIS_SECRET_FILES and ssm:<path> variables are refused
documents	one <prefix>-config layer at /opt/sluis; any endpoint is refused unless AllowEndpoints
removed arguments	Catalogues, CataloguePaths, Env, FunctionArgs.Env, FunctionArgs.SecretFiles, SecretFile, ConfigFilePath, StateSecretPath, RecoveryPasswordPath, WrappedSigningArgs.KeepRemoteSigningKeys

Keep config.secrets: {source: file, root: /var/run/sluis/secrets}, project each secret from the secrets value ({name, secretName, key}) and point config.policy.file at the mounted policy. Removed chart values:

Value	Replacement
access, overlay	sluisctl policy render <dir>, passed as policy
directory.workspaces	config.directory.workspaces with keySecret and a secrets entry
config.clientSecretsDir	config.secrets
config.exchange.clustersFile, .awsFile	exchange.clusters, exchange.aws
config.github.*, config.slack.catalogueFile, config.exports	policy.exchange.github.owners, policy.apps.github.runnerTiers, githubApps.catalogue, slackApps, policy.exports
controllerGithub.config.enabledOrgs, controllerSlack.config.enabledWorkspaces	policy.controllers.github.enabledOrgs, policy.controllers.slack.enabledWorkspaces
config.policyDir	config.policy.file

Check sign-in and, on Lambda, that the invoke {"kind":"tick","target":"<org>"} returns "outcome":"ran". To roll back, use the previous layer, zip and library.

6. Retire the asymmetric signing keys (only when moving from kms to WrappedSigning)

Do this alone, at low traffic, after step 5 is healthy.

1. Record both key ids.
2. Run pulumi state delete on <name>-signing-key, <name>-signing-key-rs256 and their aliases, then apply with WrappedSigning.
3. Run aws kms disable-key on each. After lifetimes.token and the longest verifier JWKS cache, run aws kms schedule-key-deletion (30 days minimum).

A fresh token verifies at a relying party. To roll back, run aws kms cancel-key-deletion and aws kms enable-key, pulumi import the keys and aliases, and apply without WrappedSigning.

Clean up

Back up, then delete the parameters under /sluis/private and /sluis/export. Check the next exports pass wrote <root>/export/*. Next: v1.63.

Decided in

ADR 0036.