Skip to main content

Getting Started

Welcome to the Infrastream User Guide. This documentation is designed for developers and product teams who will be using the Infrastream platform to deploy and manage their applications on Google Cloud.

The core principle to understand is that you will never interact directly with cloud infrastructure tools like the GCP Console. Instead, your entire workflow is centered around a central Git repository where you declare the desired state of your applications and services using simple text files called Manifests. This is a GitOps workflow, and it provides a simple, powerful, and secure way to manage your resources.

Your First 15 Minutes: Onboarding an Application​

This guide provides a high-level overview of the process for deploying a brand new application. For this scenario, we'll assume your application has already been containerized and the image is available in a container registry.

Deploying an application involves defining its release lifecycle. This requires creating three manifests:

  1. A ReleaseTrack to define the deployment stages.
  2. An ApplicationSet as a logical container for your application.
  3. The Application manifest itself.

Step 1: Create a ReleaseTrack Manifest

A ReleaseTrack defines the path your application versions will follow from development to production. This is a crucial step for ensuring that every change is validated in lower environments before reaching production. It enforces a safe, consistent, and auditable release process.

Deeper Dive

To learn more about the benefits of this approach and how the different release stages work, see the Application Release Process guide.

  • Convention: It is recommended to organize your repository using logical folders. For a ReleaseTrack, you might place it in a release-track subdirectory.
  • File: Create a new YAML file (e.g., my-product-releasetrack.yaml).
# Note: The Engine discovers this file automatically. 
# Its location in the repository does not affect its execution.
apiVersion: lowops.manifests.v1
kind: ReleaseTrack
metadata:
  name: my-product-releasetrack
  # Relationships are defined here via metadata, not folder paths.
  organizational-unit: your-ou
  organization: your-org
spec:
  releaseStages:
    - environments:
        - development
    - environments:
        - staging
    - environments:
        - production

Step 2: Create an ApplicationSet Manifest

An ApplicationSet is a logical grouping for applications that are released together.

  • Convention: You might place this in an application-set subdirectory.
  • File: Create a new YAML file (e.g., my-app-set.yaml).
apiVersion: lowops.manifests.v1
kind: ApplicationSet
metadata:
  name: my-app-set
  release-track: my-product-releasetrack
  organizational-unit: your-ou
  organization: your-org
spec:
  description: "A logical grouping for my product's applications"

Step 3: Create the Application Manifest

Now you can finally define your application.

  • Convention: You might place this in an application subdirectory.
  • File: Create a new YAML file (e.g., my-new-app.yaml).
apiVersion: lowops.manifests.v1
kind: Application
metadata:
  name: my-new-app
  application-set: my-app-set
  release-track: my-product-releasetrack
  organizational-unit: your-ou
  organization: your-org
spec:
  source: my-app-build-definition # Must reference a BuildDefinition or ExternalApplication
  container: default
  project: your-project-name
  target: CLOUDRUN # Or GKE, or COMPUTE

Step 4: Configure the Application for an Environment

The Application manifest defines what your application is, but not how it should run in a specific environment. For that, you need a DeploymentConfig. This manifest provides environment-specific settings like environment variables, scaling, and health checks.

  • Convention: You might group DeploymentConfigs by project or environment.
  • File: Create a new YAML file. Crucially, the metadata.name inside this file must match the name of the Application manifest (e.g., my-new-app). The file name itself can be anything (e.g., my-new-app-dev.yaml).
apiVersion: lowops.manifests.v1
kind: DeploymentConfig
metadata:
  name: my-new-app # Must match the Application's name
  # --- Parent Metadata ---
  project: your-project-name
  environment: development
  organizational-unit: your-ou
  organization: your-org
spec:
  version: "1.0.0"
  container:
    env:
      - name: DATABASE_URL
        value: "your-dev-database-url"
  scaling:
    min: 1
    max: 5

Step 5: Submit Your Change for Review

Once you have added all these new manifests, you will commit the change and open a Pull Request (PR). This is the standard process for proposing a change.

Step 6: The Automated Workflow

As soon as you open the PR, the Infrastream platform gets to work:

  1. Plan: It runs an automated process that calculates the necessary infrastructure changes and posts a "plan" as a comment in your PR.
  2. Review: The system automatically requests reviews from the designated stakeholders.
  3. Merge & Apply: Once approved, you merge the PR. Infrastream immediately detects the merge and automatically applies the changes, deploying your application to the development environment with the specific configurations you provided.

Step 7: Verify Your Deployment

After a few moments, your application will be running. The URL and other details about your running service will be available in the output of the deployment pipeline.

Understanding the GitOps Workflow

The process described above is called GitOps, and it's the foundation of your experience with Infrastream.

  • Git is the Single Source of Truth: The central manifest repository contains the complete, desired state of all infrastructure and applications. The state of the Git repository is the state of the cloud.
  • All Changes Happen Through Pull Requests: No one, not even a platform administrator, makes changes by clicking in a console. Every change, from a new application to a simple configuration update, is proposed via a PR. This provides a clear, auditable history of every modification.
  • Review and Collaboration are Built-in: The PR process is where collaboration happens. Team members and automated systems review proposed changes, discuss them in comments, and ensure that every modification is vetted before it is applied.
  • Automation Handles the Execution: You are responsible for declaring what you want. The Infrastream platform is responsible for the how. This separation of concerns is what makes the system so powerful and secure.