Skip to content

Organisations, products and services

The hierarchy the Build tools organise work in, the two repositories behind it, how package ids tie the pieces together, and how access is granted. Read this to understand where a service lives and why its contract lives somewhere else.

The hierarchy

flowchart LR
  O["Build environment<br/><small>organisation: acme</small>"] --> P1[Product: sh]
  O --> P2[Product: am]
  P1 --> S1[Service: orders-v1]
  P1 --> S2[Service: web-v1]
  P1 --> E1[Deployment environment:<br/>Development]
  P1 --> E2[Deployment environment:<br/>Production]
  P2 ~~~ E2

A build environment is the top-level container, an Alis Build Environment on alisx.com. In resource names and in the alis org command it is an organisation; older material calls it a landing zone. A company normally has one. It owns a Google Cloud project, the definitions repository shared by all its products, a Spanner instance, a load balancer and the workstations of its builders. It is created inside your own Google Cloud organisation, so the infrastructure is yours.

A product is a self-contained feature set with a two-letter id, such as sh for a shop or am for asset management. It owns a Google Cloud project that hosts its container registry and its package registries, a build repository, and its deployment environments. Products are the unit of team ownership: a builder is a builder on a product.

A service is one deployable part of a product. Resource names call it a neuron; the console's Services page and the CLI call it a service. A service has one protobuf contract, its Docker images and one Terraform module. Products are made up of their services and the interactions between them, much like microservices.

A deployment environment belongs to a product and is where its services run: Development, Staging, Production. Each has its own Google Cloud project, so deployment environments are isolated at the project boundary. See Deployment environments and versions.

Two repositories

Every product works out of two repositories, both cloned by alis clone <org>.<product>:

Repository Owned by Path on disk Holds
Definitions repo the build environment ~/alis.build/<org>/define .proto files for every service of every product, under <org>/<product>/<path>/<vN>/
Build repo the product ~/alis.build/<org>/build/<product> Each service's implementation, Dockerfiles and infra/, under <path>/<vN>/

The contract lives apart from the implementation on purpose. Contracts are shared: a service in product am calls acme.sh.orders.v1, and both products read the same definition from the same repository. Keeping all contracts in one place per build environment makes cross-service imports resolve and makes a contract change visible to everyone who depends on it. The implementation, by contrast, is private to its product and can change as often as the team likes without affecting anyone else, as long as the contract holds.

Package ids tie it together

A service is addressed everywhere by its package id, <org>.<product>.<path>.<vN>, for example acme.sh.orders.v1. The id is at once:

  • the protobuf package of its contract;
  • the name of the generated packages in the product's registries;
  • the path of its define folder (acme/sh/orders/v1) and its build folder (orders/v1);
  • the basis of its resource name (.../neurons/orders-v1).

The version segment (v1, v2) is part of the identity, so a breaking change to a contract is a new service, acme.sh.orders.v2, that can run beside the old one while clients move over. See Package ids and folders.

Sharing a contract with another product

Generated packages land in the owning product's registries. Another product can consume them only once the contract is shared with it (alis packages share <pkg> --with <org>.<product>); from then on every new contract version is delivered automatically. This keeps a product's dependencies explicit and lets the owning team see who depends on their contract.

Teams and access

Access is granted at two levels with two roles:

Level Role What it grants
Build environment administrator Create products, manage access, approve requests to join.
Build environment builder Builder on every product in the build environment.
Product administrator Manage the product's access, share its contracts, create deployment environments.
Product builder Define, build and deploy the product's services; read its deployment environments.

Administrators grant roles with alis org share and alis product share, or on the product's Sharing page. Someone without access asks for it with alis org join or alis product request, which opens a conversation the administrators approve from their own view. Access propagates to the cloud projects and the git repositories in the background, so a new builder can clone and deploy without any cloud console work. Changing a deployment environment's variables needs the deployment environment administrator role.

Access and billing are separate. A member with Build access works against their active account, which alis accounts select chooses from the CLI, and that account is invoiced at the end of the month for its members' usage. See Accounts and billing.