Resource model¶

The resources that make up Build, their names, fields and states. Names follow the collection/id pattern; the id patterns below are regular expressions.

flowchart TB
  O["Organisation<br/><small>build environment</small>"] --> P[Product]
  P --> E[Environment]
  P --> N["Neuron<br/><small>service</small>"]
  N --> V[NeuronVersion]
  E --> D[Deployment]
  V -. deployed as .-> D
  D --> DV[DeploymentVersion]

Names¶

Resource	Name format	Notes
Organisation	`organisations/([a-z0-9-]{2,20})`	Shown as a build environment in the console and the `alis org` command; historically a landing zone.
Product	`organisations/*/products/([a-z0-9-]{2})`	Two-character id.
Deployment environment	`organisations//products//environments/([a-z0-9-]{2,20})`
Neuron (service)	`organisations//products//neurons/([a-z0-9-]{2,80})`	The id is the package path with `/` replaced by `-` plus the version, for example `orders-v1`.
NeuronVersion	`.../neurons/*/versions/([a-z0-9-]{2,50})`	The id is the version with dots replaced by hyphens, for example `1-0-1`.
Deployment	`.../environments/*/deployments/([a-z0-9-]{2,50})`	The id is always a neuron id, so a deployment environment has at most one deployment per service.
DeploymentVersion	`.../deployments//versions/`	One per deploy of a deployment.
Package	`packages/<package-id>`	The contract package, for example `packages/acme.sh.orders.v1`.

Organisation¶

The top-level resource in which products are created. Each company normally has its own.

Field	Meaning
`display_name`, `description`, `logo`	Presentation.
`google_project`	The Google Cloud project backing the organisation: `folder_id`, `id`, `number`, `region`, `billing_account_id`, `managed_billing_account`.
`buckets_domain`	Domain used for storage bucket names; `alis.build` by default. Injected as `ALIS_OS_DOMAIN`.
`packages_domain`	Domain for package namespaces; `{orgId}.exchange` by default.
`account`	The account paying for the organisation, `accounts/*`. Without one the organisation brings its own billing account and folder.
`spanner_instance`	The Spanner instance provisioned for the organisation, if any.
`service_account`	The IAM service account provisioned for the organisation.
`git_repo`	The definitions repository: `remote_uri` and its hosting.
`loadbalancer`	The organisation's load balancer.
`state`	`ACTIVE`, `FAILED`, `CREATING`, `UPDATING`, `DESTROYING`, `DELETING`.
`deploy_operation`, `last_successful_deploy_time`, `deploy_executions`	The organisation's own Terraform deploys; the last five executions are kept, each with an optional AI explanation of a failure.

Product¶

A self-standing product with a well-contained feature set, for example sh for a shop.

Field	Meaning
`display_name`, `description`, `logo`	Presentation. `alis product rename` changes the display name only.
`google_project`	The product's Google Cloud project; hosts the image and package registries.
`spanner_database`	The managed Spanner database, auto-configured if left empty on creation.
`service_account`	The product's service account.
`git_repo`	The product's build repository.
`internal_package_registries`	Registry locations for the Go, JavaScript, Python, Dart, .NET, Swift and Rust packages generated by Define.
`docker_registries`	The product's container registry.
`state`	`ACTIVE`, `FAILED`, `CREATING`, `UPDATING`, `DESTROYING`, `DELETING`.
`deploy_operation`, `last_successful_deploy_time`, `deploy_executions`	The product's own Terraform deploys.

A new product is provisioned with one development environment. A production environment is created explicitly.

Deployment environment¶

A deployment target in a product, for example development, staging or production.

Field	Meaning
`display_name`, `description`	Presentation.
`google_project`	The deployment environment's Google Cloud project, where deployments land. Injected as `ALIS_OS_PROJECT`, `ALIS_PROJECT_NR`, `ALIS_REGION`.
`type`	`DEV` or `PROD`. `PROD` deployment environments are gated on deploy and on variable changes. The Google Cloud project inherits an `environment` tag with the same value (`dev` or `prod`), which the Google Cloud console shows as a badge in its project picker.
`envs[]`	Environment variables: `name`, `value`, `store_in_secret_manager`. A secret-backed variable has no stored value and is left out of deployments.
`allowed_branches[]`	Branches designated for this deployment environment. When set, deploy flows warn before deploying a version built from another branch. Empty means any branch.
`monitoring_emails[]`	Addresses that receive alerts.
`state`	`ACTIVE`, `FAILED`, `CREATING`, `UPDATING`, `DESTROYING`, `DELETING`.
`deploy_operation`, `last_successful_deploy_time`, `deploy_executions`	The deployment environment's own Terraform deploys.

Neuron (service)¶

A product is made up of its neurons and their interactions; they split a product's features much like microservices. The console and CLI call them services.

Field	Meaning
`package`	The contract package, `packages/<package-id>`.
`defined_version`	The latest successfully defined contract version. Patch zero is reserved for the contract, for example `1.56.0`.
`version`, `build_commit`	The latest build version and the build-repo commit it was built from.
`latest_version_state`	State of the latest version (see below).
`last_version_logs_uri`	Build logs of the latest version; empty when every image was retagged.
`last_version_created_by`, `last_version_create_time`	Who built the latest version and when.
`type`	`RELEASED` (available to other products) or `MANAGED` (builds and stubs come from another neuron).
`release_config`	For released neurons: the organisations that may install releases (empty means public) and the optional and required environment variables of a release.
`managed_config`	For managed neurons: the source neuron and the deployment environments to auto-deploy to on a new release.
`details.description`	An AI-generated description from the protos and build files.

NeuronVersion¶

An immutable version of a service, created by Build.

Field	Meaning
`version`	Semantic version, for example `1.0.1`.
`proto_commit`	The definitions-repo commit at the time the version was created.
`build_commit`	The build-repo commit the version was built from; the image tag.
`branch`	The build-repo branch the commit was on, asserted by the client that ran the build (informational).
`created_by`	The user who ran the build.
`images[]`	Each image's `path` relative to the service (`.`, `worker`) and its state.
`state`	`BUILT`, `RETAGGED`, `BUILDING`, `FAILED`; an aggregation of the image states.
`logs_url`	The build logs.
`package_id`	The package id, for example `acme.sh.orders.v1`.

Deleting a version does not delete its images but prevents the version number from being reused.

Deployment¶

A service version deployed in a deployment environment.

Field	Meaning
`version`	The stable version currently deployed, for example `1.0.54`.
`beta_version`	The beta version, when one is deployed.
`envs[]`	The deployment's own variables, excluding managed `ALIS_*` ones.
`state`	`RUNNING`, `DEPLOYING`, `DEPLOY_FAILED`, `PLANNING`, `PLANNED`, `PLAN_FAILED`, `PLANNING_DESTROY`, `PLAN_DESTROY_FAILED`, `PLANNED_DESTROY`, `DESTROYING`, `DESTROY_FAILED`, `DESTROYED`.
`logs_url`	The deploy logs.
`operation`	The current or last long-running operation.
`package`	The contract package this deployment serves.
`created_by`	The user who last deployed; empty when a service account did (auto-deploy).
`feature_freeze`	When true, every deploy, plan and destroy of this deployment is refused with `DEPLOYMENT_FROZEN`. Only a product admin can change it, on its own, and changing it leaves `update_time` alone.

A DeploymentVersion records each deploy of a deployment.

Package ids¶

A service's package id <org>.<product>.<path>.<vN> maps deterministically to its resource name and folders. See Package ids and folders.