Add Platform-Based Multi-Cloud Support to Reusable Deployment Workflow

[bsubhamay]

Enhancement: Add platform option for multi-cloud platform deployments

Type

Enhancement

Summary

Add an optional platform input to the reusable workflow to support platform-based, multi-provider deployments (e.g., Snowflake on AWS, Databricks on Azure) while keeping the existing required cloud-provider input intact. When platform is provided, the workflow runs in platform mode and orchestrates multiple providers in a defined order.

---

Background / Problem

The reusable workflow currently supports deploying resources for a single provider using:

cloud-provider:
  description: "Target cloud provider (aws, gcp, azure, snowflake, databricks)"
  required: true
  type: string

This is insufficient for common real-world deployments where a platform depends on an underlying cloud provider (e.g., Snowflake + AWS, Databricks + Azure). These require:

• Multi-provider authentication in a single run
• Deterministic sequencing (infra first, platform second, trust updates third)
• Terraform root selection across multiple modules/roots

---

Goals

• Support platform-based deployments (multi-provider orchestration) via a new platform input
• Preserve backward compatibility for existing callers using only cloud-provider
• Provide deterministic execution order for composite platforms
• Make it easy to add new platforms in the future via a mapping layer

---

Non-Goals

• Auto-detect platform from repository structure
• Parallel execution/optimization of apply steps
• Large refactors of existing Terraform modules (beyond wiring and orchestration)
• Introducing new providers outside the existing set

---

Proposed Interface

Existing input (unchanged)

cloud-provider:
  description: "Target cloud provider (aws, gcp, azure, snowflake, databricks)"
  required: true
  type: string

New input (optional)

platform:
  description: "Deployment platform (ws, gcp, azure, snowflake, databricks, platform)"
  required: false
  type: string

---

Resolution Rules

• If platform is provided → run in platform mode
• If platform is not provided → run in provider mode using cloud-provider
• If both are provided → platform takes precedence (and cloud-provider is ignored for execution logic)

---

Supported Platforms (initial set)

platform value	providers involved
snowflake-aws	aws + snowflake
snowflake-azure	azure + snowflake
databricks-azure	azure + databricks
databricks-aws	aws + databricks

---

Execution Model

Platform mode: ordered orchestration

Composite platforms must execute in a deterministic order to satisfy dependencies.

Example: snowflake-aws

1. AWS: Create S3 bucket, IAM role/policies, KMS (if applicable)
2. Snowflake: Create database/schema/file formats/stages/storage integration
3. AWS: Update IAM trust policy using Snowflake External ID (if required)

Example: databricks-azure

1. Azure: Create storage/networking prerequisites
2. Databricks: Create workspace and compute
3. Databricks: Configure Unity Catalog / external locations (if applicable)

Provider mode: current behavior

Single provider execution remains unchanged based on cloud-provider.

---

Terraform Root Resolution

Proposed repo structure (example)

infra/
├── aws/
│   └── tf/
│       └── modules/             # already exists
│           ├── s3/
│           └── iam/
├── snowflake/
│   └── tf/
│       └── modules/             # already exists
│           ├── storage_integration/
│           ├── stage/
│           ├── file_format/
│           └── warehouse/
└── platform/
    └── tf/                      # ✅ NEW orchestration root
        ├── main.tf
        ├── variables.tf
        ├── outputs.tf
        └── terraform.tfvars

Expected behavior

• Provider mode: execute Terraform in infra/<cloud-provider>/...
• Platform mode: execute Terraform roots in infra/platforms/<platform>/... (and/or mapped ordered roots)
• The workflow must support running multiple Terraform roots sequentially for a platform

---

Authentication & Secrets

• Support multiple provider authentications within one workflow run (e.g., AWS + Snowflake)
• Keep provider credentials isolated per stage
• Prefer OIDC where supported; fall back to secrets where required
• Validate required credentials for the resolved platform before executing any apply

---

Validation & Error Handling

• Fail fast if platform is unsupported
• Fail fast if required provider credentials are missing for the selected platform
• Provide clear error messages listing allowed platform values and required secrets/vars

---

Acceptance Criteria (Definition of Done)

• Workflow accepts optional platform input in addition to required cloud-provider
• Existing callers using only cloud-provider continue to work unchanged
• When platform is provided, platform mode runs and platform takes precedence over cloud-provider
• Platform mapping drives provider stages and execution order correctly
• Terraform root resolution supports platform mode (multi-root sequencing)
• Multi-provider authentication works reliably in a single run
• Clear validation and error messages for unsupported platforms / missing credentials
• Documentation updated with platform usage examples

---

Implementation Tasks

• Add platform input to reusable workflow (workflow_call interface)
• Implement resolution logic (platform mode vs provider mode)
• Create platform mapping (platform → ordered providers/roots) in a maintainable form (YAML/JSON/env matrix)
• Implement ordered execution runner that iterates provider stages for platform mode
• Implement Terraform root discovery/execution for platform mode (sequential applies)
• Extend auth steps to support multiple providers in one run
• Add validation: supported platforms + required secrets/vars checks
• Update README with:
  - provider mode vs platform mode
  - supported platforms
  - example invocations
  - expected repo structure
• Add basic tests/linting and a dry-run validation for platform mapping and root resolution

---

Example Invocation (for docs)

jobs:
  deploy:
    uses: <org>/<repo>/.github/workflows/deploy.yml@vX
    with:
      cloud-provider: platform
      platform: snowflake-aws
      environment: devl

[github-actions]

Branch feature/GHA-0039-add-platform-based-multi created 🚀