Skip to main content

Environments

The environments array in .greyhound/applications.yaml defines named deployment targets that compose one or more applications into a single environment. Each environment specifies which applications to include, what cluster to deploy to, and any overrides to apply.

Defining an Environment​

Every environment needs a name and at least one application to import:

environments:
  - name: staging
    from_applications:
      - name: api
      - name: web

The from_applications list references applications declared in the same file's applications array. Applications are imported in the order they appear.

Application Aliases​

You can alias an application within an environment to avoid name collisions:

environments:
  - name: staging
    from_applications:
      - name: api
        alias: backend-api
      - name: web

Cluster Override​

Each environment inherits the default_cluster from its applications. Override it at the environment level to deploy to a different cluster:

environments:
  - name: staging
    from_applications:
      - name: api
    cluster: shared-staging-eks

Deployment Behavior​

Control whether the environment auto-deploys after provisioning:

environments:
  - name: staging
    from_applications:
      - name: api
    auto_deploy: false

When auto_deploy is false, the environment is provisioned but not deployed until manually triggered. Defaults to true.

Removing Services​

Exclude specific services from an application within this environment. This is useful for stripping out services that aren't needed in certain contexts (e.g., removing debug tooling from production-like environments):

environments:
  - name: staging
    from_applications:
      - name: api
    removed_services:
      api:
        services:
          - debug-dashboard
          - seed-runner

The key is the application name, and services accepts a single service name or an array.

Optional Applications​

Add environment-specific optional applications that aren't part of any imported application's config:

environments:
  - name: staging
    from_applications:
      - name: api
    optional_applications:
      - name: monitoring-sidecar
        repository: your-org/monitoring
        branch: main

These follow the same format as application-level optional applications.

Additional Configs​

Apply extra configuration sources to the environment. These are processed after the base config:

environments:
  - name: staging
    from_applications:
      - name: api
    additional_configs:
      - .greyhound/staging-overrides.yaml
      - .greyhound/feature-flags.yaml

Database Pools​

Override or extend the application-level database pool defaults for this environment:

environments:
  - name: staging
    from_applications:
      - name: api
    database_pools:
      - staging-aurora-pool

When specified, these replace the default_database_pools inherited from the imported applications.

Resource Shares​

Define environment-level resource sharing in addition to (or instead of) application-level shares. The schema is the same as application resource shares:

environments:
  - name: dev
    from_applications:
      - name: api
    resource_shares:
      - source_environment: staging
        target_environment: dev
        resource_type: Service
        resource_name: auth-service

Variable Overrides​

Apply environment-specific variable overrides that take effect during provisioning. The schema is the same as application variable overrides:

environments:
  - name: staging
    from_applications:
      - name: api
    variable_overrides:
      - service_name: api
        variable_name: DATABASE_URL
        variable_value: ${database.staging-pool.writer_endpoint}
        priority: 1

Environment-level overrides merge with application-level overrides. When both set the same variable on the same service, priority determines which wins (lower number = higher precedence).

Putting It Together​

Here's a complete example with two applications deployed across two environments:

applications:
  - name: api
    repository: your-org/api
    branch: main
    default_cluster: shared-nonprod-eks
    default_database_pools:
      - shared-aurora-pool
    additional_applications:
      - name: auth-service
        repository: your-org/auth
        branch: main

  - name: web
    repository: your-org/web
    branch: main
    default_cluster: shared-nonprod-eks

environments:
  - name: staging
    from_applications:
      - name: api
      - name: web
    cluster: shared-staging-eks
    database_pools:
      - staging-aurora-pool
    variable_overrides:
      - service_name: api
        variable_name: LOG_LEVEL
        variable_value: info

  - name: dev
    from_applications:
      - name: api
      - name: web
    removed_services:
      api:
        services: seed-runner
    resource_shares:
      - source_environment: staging
        target_environment: dev
        resource_type: Endpoint
        resource_name: auth-endpoint
        fallback_environment: staging

Schema Reference​

See the App Imports schema for the full configuration reference.