v2.0.5 wip

jeffreyaven · jeffreyaven · commit 93a5ac440ab4 · 2026-03-20T12:52:47.000+11:00
diff --git a/examples/aws/aws-vpc-webserver/stackql_manifest.yml b/examples/aws/aws-vpc-webserver/stackql_manifest.yml
@@ -2,7 +2,7 @@ version: 1
 name: "aws-vpc-webserver"
 description: Provisions a complete AWS networking stack (VPC, subnet, internet gateway, route table, security group) with an Apache web server EC2 instance.
 providers:
-  - awscc
+  - awscc::v26.03.00379
 globals:
   - name: region
     description: aws region
diff --git a/examples/aws/patch-doc-test/stackql_manifest.yml b/examples/aws/patch-doc-test/stackql_manifest.yml
@@ -2,7 +2,7 @@ version: 1
 name: "patch-doc-test"
 description: Demonstrates the Cloud Control API update (PatchDocument) workflow using an S3 bucket - deploy, modify versioning config, re-deploy to apply the update.
 providers:
-  - awscc
+  - awscc::v26.03.00379
 globals:
   - name: region
     description: aws region
diff --git a/examples/databricks/serverless/stackql_manifest.yml b/examples/databricks/serverless/stackql_manifest.yml
@@ -2,9 +2,9 @@ version: 1
 name: "stackql-serverless"
 description: creates a serverless databricks workspace
 providers:
-  - awscc
-  - databricks_account
-  - databricks_workspace
+  - awscc::v26.03.00379
+  - databricks_account::v26.03.00381
+  - databricks_workspace::v26.03.00381
 globals:
   - name: databricks_account_id
     description: databricks account id
diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md
@@ -10,44 +10,42 @@ unlisted: false
 ---
 
 import File from '/src/components/File';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 `stackql-deploy` is a model driven, declarative framework for provisioning, de-provisioning and testing cloud resources.  Heard enough and ready to get started? Jump to a [__Quick Start__](#quick-start).
 
 ## Installing `stackql-deploy`
 
-`stackql-deploy` is distributed as a standalone binary with no runtime dependencies required.
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+`stackql-deploy` is distributed as a standalone binary with no runtime dependencies required.  You can also download directly from your browser at [__get-stackql-deploy.io__](https://get-stackql-deploy.io).
 
 <Tabs>
-<TabItem value="macos" label="macOS">
+<TabItem value="linux-macos" label="Linux / macOS">
 
-**Apple Silicon (ARM64):**
+The canonical install URL detects your OS and redirects to the latest release asset automatically:
 
 ```bash
-curl -L https://github.com/stackql/stackql-deploy-rs/releases/latest/download/stackql-deploy-macos-arm64.tar.gz | tar xz
+curl -L https://get-stackql-deploy.io | tar xzf -
 sudo mv stackql-deploy /usr/local/bin/
 ```
 
-**Intel (x86_64):**
+Or download a specific platform build:
+
+**macOS Universal (Apple Silicon + Intel):**
 
 ```bash
-curl -L https://github.com/stackql/stackql-deploy-rs/releases/latest/download/stackql-deploy-macos-x86_64.tar.gz | tar xz
+curl -L https://github.com/stackql/stackql-deploy-rs/releases/latest/download/stackql-deploy-macos-universal.tar.gz | tar xz
 sudo mv stackql-deploy /usr/local/bin/
 ```
 
-</TabItem>
-<TabItem value="linux" label="Linux">
-
-**x86_64:**
+**Linux x86_64:**
 
 ```bash
 curl -L https://github.com/stackql/stackql-deploy-rs/releases/latest/download/stackql-deploy-linux-x86_64.tar.gz | tar xz
 sudo mv stackql-deploy /usr/local/bin/
 ```
 
-**ARM64:**
+**Linux ARM64:**
 
 ```bash
 curl -L https://github.com/stackql/stackql-deploy-rs/releases/latest/download/stackql-deploy-linux-arm64.tar.gz | tar xz
@@ -60,7 +58,7 @@ sudo mv stackql-deploy /usr/local/bin/
 **PowerShell:**
 
 ```powershell
-Invoke-WebRequest -Uri "https://github.com/stackql/stackql-deploy-rs/releases/latest/download/stackql-deploy-windows-x86_64.zip" -OutFile stackql-deploy.zip
+Invoke-WebRequest https://get-stackql-deploy.io -OutFile stackql-deploy.zip
 Expand-Archive stackql-deploy.zip -DestinationPath .
 Move-Item stackql-deploy.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\"
 Remove-Item stackql-deploy.zip
@@ -74,25 +72,27 @@ unzip stackql-deploy.zip
 ```
 
 </TabItem>
-<TabItem value="cargo" label="Cargo (from source)">
+<TabItem value="github-releases" label="GitHub Releases">
 
-If you have Rust installed (via [rustup](https://rustup.rs/)):
+Pre-built binaries are attached to every release on the [__GitHub Releases__](https://github.com/stackql/stackql-deploy-rs/releases) page. A `SHA256SUMS` file is included for verification.
 
-```bash
-cargo install stackql-deploy
-```
-
-This builds from source and installs to `~/.cargo/bin/`.
+| Platform | Asset |
+|----------|-------|
+| Linux x86_64 | `stackql-deploy-linux-x86_64.tar.gz` |
+| Linux ARM64 | `stackql-deploy-linux-arm64.tar.gz` |
+| macOS Universal (Apple Silicon + Intel) | `stackql-deploy-macos-universal.tar.gz` |
+| Windows x86_64 | `stackql-deploy-windows-x86_64.zip` |
 
 </TabItem>
 <TabItem value="github-actions" label="GitHub Actions">
 
-Use the [`stackql/setup-deploy`](https://github.com/marketplace/actions/stackql-deploy) action to install and run `stackql-deploy` in your CI/CD pipelines:
+Use the [`stackql/setup-deploy`](https://github.com/marketplace/actions/stackql-deploy) action to install and run `stackql-deploy` in your CI/CD pipelines.  The action automatically downloads the latest binary for the runner's platform.
+
+**Deploy a stack:**
 
 ```yaml
 steps:
   - uses: actions/checkout@v4
-
   - name: Deploy Stack
     uses: stackql/setup-deploy@v1.0.1
     with:
@@ -102,12 +102,39 @@ steps:
       env_vars: 'AWS_REGION=us-east-1'
 ```
 
-The action automatically downloads the latest binary for the runner's platform. See [__Deploying with GitHub Actions__](/github-actions) for the full reference.
+**Deploy and capture outputs:**
+
+```yaml
+  - name: Deploy Stack
+    id: stackql-deploy
+    uses: stackql/setup-deploy@v1.0.1
+    with:
+      command: 'build'
+      stack_dir: 'examples/my-stack'
+      stack_env: 'prod'
+      output_file: 'deployment-outputs.json'
+      env_vars: 'GOOGLE_PROJECT=my-project'
+
+  - name: Use outputs
+    run: |
+      echo '${{ steps.stackql-deploy.outputs.deployment_outputs }}' | jq .
+```
+
+See [__Deploying with GitHub Actions__](/github-actions) for the full reference.
 
 </TabItem>
-</Tabs>
+<TabItem value="cargo" label="Cargo (from source)">
+
+If you have the Rust toolchain installed (via [rustup](https://rustup.rs/)):
 
-All platform binaries are available on the [__GitHub Releases__](https://github.com/stackql/stackql-deploy-rs/releases) page.
+```bash
+cargo install stackql-deploy
+```
+
+This builds from source and installs to `~/.cargo/bin/`.
+
+</TabItem>
+</Tabs>
 
 ## How `stackql-deploy` works
 
@@ -255,7 +282,8 @@ For more detailed information see [`cli-reference/build`](/cli-reference/build),
 
 To get up and running quickly, `stackql-deploy` provides a set of quick start templates for common cloud providers. These templates include predefined configurations and resource queries tailored to AWS, Azure, and Google Cloud, among others.
 
-- [**AWS Quick Start Template**](/template-library/aws/vpc-and-ec2-instance): A basic setup for deploying a VPC, including subnets and routing configurations.
+- [**AWS Quick Start Template**](/template-library/aws/vpc-and-ec2-instance): A complete VPC networking stack with an EC2 web server using the `awscc` Cloud Control provider.
+- [**Databricks Quick Start Template**](/template-library/databricks/serverless-workspace): A multi-provider stack deploying a Databricks serverless workspace on AWS with Unity Catalog.
 - [**Azure Quick Start Template**](/template-library/azure/simple-vnet-and-vm): A setup for creating a Resource Group with associated resources.
 - [**Google Cloud Quick Start Template**](/template-library/google/k8s-the-hard-way): A configuration for deploying a VPC with network and firewall rules.
 
diff --git a/website/docs/manifest_fields/exports.mdx b/website/docs/manifest_fields/exports.mdx
@@ -1,25 +1,65 @@
-**Type**: `array of strings` (optional)
-
-**Description**: List of variable names to export to a JSON file after deployment completion. Variables must exist in the deployment context (from globals or resource exports). Use with the `--output-file` CLI argument to specify the destination file.
-
-**Usage**: Use this to extract key deployment outputs for use in CI/CD pipelines, downstream processes, or for record-keeping.
-
-**Example**:
-
-```yaml
-exports:
-  - databricks_workspace_name
-  - databricks_workspace_id  
-  - aws_iam_role_arn
-  - deployment_timestamp
-```
-
-**Notes**:
-- `stack_name`, `stack_env`, and `elapsed_time` are automatically included in exports and do not need to be listed
-- Export order: automatic exports (`stack_name`, `stack_env`) first, then user-defined exports, then timing (`elapsed_time`) last
-- `elapsed_time` is formatted as a string showing the total deployment duration (e.g., "0:01:23.456789")
-- Variables are exported exactly as they exist in the deployment context
-- Complex objects and arrays are preserved as JSON structures  
-- If a listed variable doesn't exist in the context, deployment will fail
-- Requires `--output-file` CLI argument to be specified, otherwise exports are skipped
-- Exported JSON file contains a flat object with variable names as keys
+**Type**: `array of strings` (optional)
+
+**Description**: List of variable names to export after a successful `build` or `test` operation. Variables must exist in the deployment context (from globals or resource exports). Exported variables are displayed in a table, written to a sourceable shell file (`.stackql-deploy-exports`), and optionally to a JSON file when `--output-file` is specified.
+
+**Usage**: Use this to extract key deployment outputs for use in CI/CD pipelines, downstream processes, or interactive shell sessions.
+
+**Example**:
+
+```yaml
+exports:
+  - workspace_name
+  - workspace_id
+  - deployment_name
+  - workspace_status
+  - workspace_url
+```
+
+**Output after a successful `build` or `test`**:
+
+```
+┌───────────────┐
+│ stack exports │
+└───────────────┘
++------------------------------------------------------+--------------------------------------------------+
+| variable                                             | value                                            |
++------------------------------------------------------+--------------------------------------------------+
+| STACKQL_DEPLOY__my_stack__dev__workspace_name        | my-stack-dev-workspace                           |
+| STACKQL_DEPLOY__my_stack__dev__workspace_id          | 7474653260057820                                 |
+| STACKQL_DEPLOY__my_stack__dev__deployment_name       | dbc-c83e88ed-1ad3                                |
+| STACKQL_DEPLOY__my_stack__dev__workspace_status      | RUNNING                                          |
+| STACKQL_DEPLOY__my_stack__dev__workspace_url         | https://dbc-c83e88ed-1ad3.cloud.databricks.com   |
+| STACKQL_DEPLOY__my_stack__dev__elapsed_time          | 49.22s                                           |
+| STACKQL_DEPLOY__my_stack__dev__stack_env             | dev                                              |
+| STACKQL_DEPLOY__my_stack__dev__stack_name            | my-stack                                         |
++------------------------------------------------------+--------------------------------------------------+
+
+To load these variables into your shell:
+  source .stackql-deploy-exports
+```
+
+**Loading exports into the shell**:
+
+```bash
+# Linux / macOS / Git Bash
+source .stackql-deploy-exports
+echo $STACKQL_DEPLOY__my_stack__dev__workspace_url
+```
+
+```powershell
+# PowerShell
+Get-Content .stackql-deploy-exports | ForEach-Object { Invoke-Expression $_ }
+```
+
+**Environment variable naming**:
+
+Exported variable names follow the pattern `STACKQL_DEPLOY__<stack_name>__<stack_env>__<variable>`, where hyphens in stack name or env are replaced with underscores (since shell environment variables don't support hyphens).
+
+**Notes**:
+- `stack_name`, `stack_env`, and `elapsed_time` are automatically included in exports and do not need to be listed
+- Stack exports are displayed on both `build` and `test` operations
+- The `.stackql-deploy-exports` file is written to the current working directory and contains `export KEY='value'` lines
+- If `--output-file` is also specified, exports are additionally written as a JSON file
+- Variables are exported exactly as they exist in the deployment context
+- Complex objects and arrays are preserved as JSON structures
+- If a listed variable doesn't exist in the context, the operation will fail
diff --git a/website/docs/template-library/databricks/serverless-workspace.md b/website/docs/template-library/databricks/serverless-workspace.md
