Install on GCP — Nistor Docs

Nistor ships a reference Terraform module for Google Cloud. It is a set of modules for the runtime services, the database, the buckets and the identities Nistor runs as. You use it from your own deployment repository; you do not copy it.

What you need#

A Google Cloud project with billing, and the right to create services, a database instance and service accounts.
Terraform, and an object-storage bucket of your own for its state.
The release images (nistor-runtime and nistor-shell), copied into your own Artifact Registry.

Steps#

In your deployment repository's terraform/, source the reference root, deployments/gcp, as a module pinned to a public release tag, never a branch (as examples/deployment-repository does):
```
module "runtime" {
  source = "git::https://gitlab.com/nistor-io/nistor.git//deployments/gcp?ref=v1.0.0"
  # ...
}
```
The modules live under infra/terraform/modules: core and monitoring, and one module per role under services/ (backend, scheduler, compiler, input-logs, jobs, frontend, migrate-job, ...) and per tool under providers/. The reference root wires them together; its terraform.tfvars.example lists the inputs (project, region, the deployment's tier (dev, test or prod: its sizing and its roles' ENVIRONMENT) and optional instance (the suffix of its resource names, the tier by default), image references, identity-aware proxy settings, database sizing).

The reference root is tested: deployments/gcp/tests (terraform test with mock providers) runs in every pipeline in the CI job terraform-fmt-validate, with its init, validate and tflint. environments/*.tfvars.example shows per-environment overrides. Its inputs (variables.tf) and outputs (outputs.tf) stay stable across 1.x, under the rules of versioning: a minor release adds inputs with defaults and never renames or removes one.
Run terraform init, terraform plan, review, then terraform apply.
Run the migrations once: execute the migrate Cloud Run job (the output migrate_job_name). It runs nistor migrate from the release image. Outside the image, nistor migrate needs a distribution.json or NISTOR_DEV=1, and against Cloud SQL NISTOR_ALLOW_LIVE_MIGRATION=1; prefer the job.
Open the web shell behind your identity provider's proxy.

The install pipeline, ci/templates/install (see its README.md), runs these steps from a deployment repository's own CI for any named deployment, the first install included.

Verify it works#

The migrate job succeeded. Its last execution must show success:

gcloud run jobs executions list --job=<migrate_job_name> --region=<region> --project=<project> --limit=1

Every service is ready. The output service_names lists them. Each one's latest revision must be ready and serve all traffic:
```
gcloud run services list --region=<region> --project=<project>
```
What each role has installed. Every role answers GET /health/installed with the core version, the image's lock digest and each installed tool and plugin with its status. It answers 503 when an activated tool or plugin is not ok. Call it as an account allowed to invoke the service, for example the install pipeline's account (ci_cd_service_account_email):
```
TOKEN=$(gcloud auth print-identity-token \
  --impersonate-service-account=<pipeline account> --audiences=<backend_uri> --include-email)
curl -s -H "Authorization: Bearer $TOKEN" <backend_uri>/health/installed
```
IAP is in front of the web shell. gcloud iap web get-iam-policy --resource-type=cloud-run --service=<frontend service name> --region=<region> --project=<project> fails when IAP is off, and lists who may sign in when it is on (see Identity and access).
Sign in. Open the output frontend_uri in a browser, as the bootstrap_admin_email account. The web shell loads, and you are an administrator. A person without the IAP grant gets 403 from IAP instead.

Then turn the alert policies on (see Monitoring and alerts), and read the rest of the operator guide.

Configure through the API#

After the install, configuration is data, not files on the servers: connections, rules, alert policies and contracts are created through the API, or kept as files in your repository and synced with the CLI (nistor rules sync, nistor alerts sync, nistor odcs sync, ...). See Configuration.

Upgrading#

Change the ref and the image tags, plan, apply, then execute the migrate job. Read Upgrading first.