Skip to main content

Core Concepts

To use Infrastream effectively, you only need to understand a few core concepts. These concepts form the foundation of the platform and will guide you in how you define, deploy, and manage your applications and services.

Manifests: Your Declarative Interface​

The most important concept in Infrastream is the Manifest. A manifest is a simple, human-readable text file (written in YAML) where you declare the resources you need.

Think of it like providing a blueprint to an automated factory. You don't need to know how to operate the machinery, weld the steel, or run the electrical wiring. You simply provide a precise blueprint that describes the final product, and the factory (Infrastream) handles the entire complex assembly process for you.

You are responsible for defining what you want, and Infrastream is responsible for the how.

For example, to request a database, you don't write complex scripts. Each resource is its own standalone manifest file; you declare what you want, and the platform figures out how to build it:

# A complete, standalone manifest in its own file.
# File: .../project/your-project-name/database/my-app-db.yaml
apiVersion: lowops.manifests.v1
kind: Database
metadata:
  name: my-app-db      # The name of your new database
  # --- Parent linkage (see "How manifests connect" below) ---
  project: your-project-name
  environment: development
  organizational-unit: your-ou
  organization: your-org
spec:
  alloydb:             # Choose the engine: 'alloydb' (PostgreSQL) or 'spanner'
    clusterSize: 3     # 1 = single primary; >1 adds read-pool instances
    cpuCount: 4        # vCPUs per instance

You declare the desired state, and the platform takes on the complex tasks of provisioning the database, configuring it, setting up networking and firewalls, and ensuring it meets all security and compliance requirements.

Reference

Every field of every manifest is documented in the Manifest Reference, generated directly from the engine's schema.

How manifests connect: metadata, not folders​

Manifests form a graph, and every manifest declares its place in that graph through its metadata block — not through where the file sits on disk. The engine discovers every .yaml file in the repository and resolves each one's parents from its metadata keys (organization, organizational-unit, environment, project, release-track, application-set, github-connection, github-repository, …).

You are free to organize files however you like, but a convention that mirrors the hierarchy keeps large repositories readable:

manifests/
├── organization.yaml                         # kind: Organization
├── organization-user/…                       # people
├── organization-user-group/…                 # teams
├── github-connection/
│   └── default/
│       ├── default.yaml                       # kind: GithubConnection
│       └── github-repository/
│           └── hello-service/
│               ├── hello-service.yaml         # kind: GithubRepository
│               └── build-definition/
│                   └── hello-service.yaml     # kind: BuildDefinition
├── artifact-registry/…                        # private registries
├── external-registry/…                        # upstream registries + trusted repos
└── organizational-unit/
    └── retail-banking/
        ├── retail-banking.yaml                # kind: OrganizationalUnit
        ├── environment/
        │   └── prod/
        │       ├── prod.yaml                   # kind: Environment
        │       └── project/
        │           └── login-svc/
        │               ├── login-svc.yaml      # kind: Project
        │               ├── database/…          # kind: Database, Bucket, Redis, …
        │               └── deployment-config/  # kind: DeploymentConfig (per env)
        └── release-track/
            └── main-track/
                ├── main-track.yaml             # kind: ReleaseTrack
                └── application-set/
                    └── core-apis/
                        ├── core-apis.yaml      # kind: ApplicationSet
                        └── application/…        # kind: Application / ExternalApplication

The Infrastream model: three connected axes​

Resources are organized along three axes that link together through metadata.

1. Landscape — where things live (broad → specific):

  • Organization — the top-level container, managed by the central platform team; holds global security policies, workforce federation, and billing.
  • OrganizationalUnit (OU) — a line of business or product area (e.g. "Retail Banking") with its own configuration, inheriting the Organization's policies.
  • Environment — a stage such as dev, staging, or prod within an OU.
  • Project — a Google Cloud project scope that hosts a set of related resources (databases, buckets, pub/sub topics, secrets, …).

2. Delivery — how software ships:

  • ReleaseTrack — the ordered path a version follows through environments (pre-release → release stages), with approval gates between stages.
  • ApplicationSet — a logical bundle of applications released together.
  • Application / ExternalApplication — a deployable service. An Application is built from your source; an ExternalApplication runs a third-party/prebuilt image.
  • DeploymentConfig — the per-environment tuning (version, env vars, scaling, health, ports) for an application; its metadata.name matches the application it configures.

3. Source & build — where images come from:

  • GithubConnection → GithubRepository → BuildDefinition — connect a GitHub org, manage repositories, and generate CI that builds and publishes container images.
  • ArtifactRegistry (your private registries) and ExternalRegistry + TrustedRepository (curated upstream images) supply the images applications deploy.

An Application ties the axes together: it references a source (a BuildDefinition or ExternalApplication), belongs to an ApplicationSet on a ReleaseTrack, targets a Project, and is tuned per Environment by a DeploymentConfig.

The Core Project: The Hub for Shared Services​

While you will do most of your work within your team's Project manifests, it is useful to know about the Core Project.

The Core Project is a special, central Google Cloud project that provides foundational services consumed by all other projects in the organization. If a Project is your team's office, the Core Project is the building's central facilities management—it hosts the Spanner State Ledger, the Infrastream Engine execution environment, the core Shared VPC networking, and enterprise security tools that all offices share.

Because the Core Project manages highly critical shared infrastructure, it is completely opaque to end-users. You will never need to edit a manifest for the Core Project directly; the Engine handles its configuration and lifecycle automatically, ensuring a seamless delete/rehydrate flow for disaster recovery. Knowing it exists simply helps you understand where the core services that power your applications come from.