### Install StackQL Deploy using pip

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/getting-started.md

Installs the stackql-deploy package and its dependencies globally using pip. This is the primary method for setting up the tool on most systems.

```bash
pip install stackql-deploy
# or
pip3 install stackql-deploy
```

--------------------------------

### Example StackQL Deploy Manifest File (stackql_manifest.yml)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/getting-started.md

Defines a sample stackql_manifest.yml file, illustrating the structure for configuring cloud resources. It includes version, name, description, providers, global variables, and resource definitions for an Azure resource group.

```yaml
version: 1
name: "my-azure-stack"
description: description for "my-azure-stack"
providers:
  - azure
globals:
  - name: subscription_id
    description: azure subscription id
    value: "{{ AZURE_SUBSCRIPTION_ID }}"
  - name: location
    description: default location for resources
    value: eastus
  - name: global_tags
    value:
      provisioner: stackql
      stackName: "{{ stack_name }}"
      stackEnv: "{{ stack_env }}"
resources:
  - name: example_res_grp
    props:
      - name: resource_group_name
        value: "{{ stack_name }}-{{ stack_env }}-rg"
    exports:
      - resource_group_name  
```

--------------------------------

### StackQL-Deploy Test Command Example (Bash)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/getting-started.md

Example of using the `stackql-deploy test` command to verify the state of a StackQL stack named 'my-azure-stack' in the 'sit' environment, providing the Azure subscription ID.

```bash
stackql-deploy test my-azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
```

--------------------------------

### Setup and Install StackQL Deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Commands to set up a Python virtual environment, source convenience scripts, activate the environment, and install the stackql-deploy package.

```bash
python3 -m venv myenv
source examples/databricks/serverless/convenience.sh
source venv/bin/activate
pip install stackql-deploy
```

--------------------------------

### StackQL Resource Query File Example (.iql)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/getting-started.md

An example of a StackQL query file (.iql) demonstrating the use of query anchors like 'exists', 'create', 'statecheck', 'exports', and 'delete' to manage Azure resource groups. This file defines operations for checking resource existence, creating, verifying state, exporting variables, and deleting resources.

```sql
/*+ exists */
SELECT COUNT(*) as count FROM azure.resources.resource_groups
WHERE subscriptionId = '{{ subscription_id }}'
AND resourceGroupName = '{{ resource_group_name }}'

/*+ create */
INSERT INTO azure.resources.resource_groups(
   resourceGroupName,
   subscriptionId,
   data__location
)
SELECT
   '{{ resource_group_name }}',
   '{{ subscription_id }}',
   '{{ location }}'

/*+ statecheck, retries=5, retry_delay=5 */
SELECT COUNT(*) as count FROM azure.resources.resource_groups
WHERE subscriptionId = '{{ subscription_id }}'
AND resourceGroupName = '{{ resource_group_name }}'
AND location = '{{ location }}'
AND JSON_EXTRACT(properties, '$.provisioningState') = 'Succeeded'

/*+ exports */
SELECT '{{ resource_group_name }}' as resource_group_name

/*+ delete */
DELETE FROM azure.resources.resource_groups
WHERE resourceGroupName = '{{ resource_group_name }}' AND subscriptionId = '{{ subscription_id }}'
```

--------------------------------

### StackQL-Deploy Build Command Example (Bash)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/getting-started.md

Example of using the `stackql-deploy build` command to provision a StackQL stack named 'my-azure-stack' in the 'prd' environment, specifying an Azure subscription ID via an environment variable.

```bash
stackql-deploy build my-azure-stack prd \
-e AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
```

--------------------------------

### Source Convenience Script and Start StackQL Shell

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/serverless/README.md

This snippet demonstrates how to source a shell script for Databricks serverless convenience functions and then launch the StackQL interactive shell. It assumes the script is available in the 'examples/databricks/serverless/' directory.

```shell
source examples/databricks/serverless/convenience.sh

stackql shell
```

--------------------------------

### StackQL-Deploy Teardown Command Example (Bash)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/getting-started.md

Example of using the `stackql-deploy teardown` command to de-provision a StackQL stack named 'my-azure-stack' in the 'dev' environment, including the Azure subscription ID.

```bash
stackql-deploy teardown my-azure-stack dev \
-e AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
```

--------------------------------

### Install stackql-deploy using pip

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/azure/azure-stack/README.md

This snippet shows how to install the `stackql-deploy` package using pip. It is a prerequisite for using the framework.

```bash
pip install stackql-deploy
```

--------------------------------

### Start StackQL Shell and Pull Registries

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

This snippet shows how to source a convenience script and launch the StackQL interactive shell. It then demonstrates pulling Databricks account and workspace registry information for specified versions. This is useful for initial setup and ensuring access to Databricks resources via StackQL.

```shell
source examples/databricks/serverless/convenience.sh

stackql shell
```

```sql
registry pull databricks_account v24.12.00279;

registry pull databricks_workspace v24.12.00279;
```

--------------------------------

### Start Stackql Interactive Shell

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/serverless/README.md

This snippet shows how to start an interactive stackql shell. Ensure you have sourced the convenience script first. This is useful for performing manual checks and queries against your cloud resources.

```bash
source examples/databricks/serverless/convenience.sh
stackql shell
```

--------------------------------

### Example Stackql-Deploy Manifest File

Source: https://github.com/stackql/stackql-deploy/blob/main/docs/source/manifest_file.md

A basic example of a stackql_manifest.yml file, demonstrating the 'version', 'name', 'description', 'providers', 'globals', and 'resources' sections. It shows how to define global variables and a resource with its properties.

```yaml
version: 1
name: activity_monitor
description: OSS activity monitor stack
providers:
  - azure
globals:
  - name: subscription_id
    description: Azure subscription ID
    value: "{{ vars.AZURE_SUBSCRIPTION_ID }}"
  - name: location
    value: eastus
  - name: resource_group_name_base
    value: "activity-monitor"
resources:
  - name: monitor_resource_group
    description: Azure resource group for activity monitor
    props:
      - name: resource_group_name
        description: Azure resource group name
        value: "{{ globals.resource_group_name_base }}-{{ globals.stack_env }}"
```

--------------------------------

### Install stackql-deploy CLI

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/k8s-the-hard-way/README.md

Installs the stackql-deploy Python package using pip. Includes steps for virtual environment setup, particularly for macOS users.

```bash
pip install stackql-deploy
# or
pip3 install stackql-deploy

# for macOS users in a virtual environment:
python3 -m venv myenv
source myenv/bin/activate
pip install stackql-deploy
```

--------------------------------

### Install stackql-deploy on macOS

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/aws/patch-doc-test/README.md

Instructions for installing stackql-deploy within a virtual environment on macOS, which may be necessary for managing dependencies.

```bash
python3 -m venv myenv
source myenv/bin/activate
pip install stackql-deploy
```

--------------------------------

### Start StackQL Shell and Query Databricks Information

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/classic/README.md

This snippet demonstrates how to initiate an interactive StackQL shell, pull Databricks registry information, and query workspace details. It requires the 'stackql' tool to be installed and accessible from the command line. The output provides account and workspace identifiers.

```shell
source examples/databricks/all-purpose-cluster/convenience.sh
stackql shell
```

```sql
registry pull databricks_account v24.12.00279;
registry pull databricks_workspace v24.12.00279;

select account_id, workspace_name, workspace_id, workspace_status from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>';
```

--------------------------------

### Stackql-Deploy Environment Setup

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/classic/README.md

This snippet details the steps to set up a Python virtual environment and install the stackql-deploy package. It also shows how to source convenience scripts and activate the environment. Dependencies include Python 3 and pip.

```bash
python3 -m venv myenv
source examples/databricks/all-purpose-cluster/convenience.sh
source venv/bin/activate
pip install stackql-deploy
```

--------------------------------

### Install StackQL Deploy using Pip

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/load-balanced-vms/README.md

Installs the stackql-deploy Python package using pip. This is the primary method for installing the CLI tool. For macOS users, instructions for using a virtual environment are also provided.

```bash
pip install stackql-deploy
# or
pip3 install stackql-deploy
```

```bash
python3 -m venv myenv
source myenv/bin/activate
pip install stackql-deploy
```

--------------------------------

### Deploy Cloud Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/k8s-the-hard-way/README.md

Builds and deploys a cloud stack using stackql-deploy. This example demonstrates setting Google Cloud credentials and environment variables, and includes dry-run and debug logging options.

```bash
export GOOGLE_CREDENTIALS=$(cat ./testcreds/k8s-the-hard-way-project-demo-service-account.json)
# deploy a stack
stackql-deploy build \
examples/google/k8s-the-hard-way \	dev \
-e GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo \
--dry-run \
--log-level DEBUG
```

--------------------------------

### StackQL Interactive Shell Commands

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Commands to interact with the StackQL shell for registry pull and querying Databricks account and workspace information. Assumes Databricks environment is configured.

```sql
registry pull databricks_account v24.12.00279;
registry pull databricks_workspace v24.12.00279;

-- This will fail if accounts, subscription, or credentials are in error.
select account_id FROM databricks_account.provisioning.credentials WHERE account_id = '<your databricks account id>';
select account_id, workspace_name, workspace_id, workspace_status from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>';
```

```sql
delete from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>' and workspace_id = '<workspace id>';
```

--------------------------------

### StackQL Deploy Build (Production)

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Executes the stackql-deploy build process for a Databricks serverless environment, showing the generated queries. Requires AWS and Databricks environment variables to be set.

```bash
stackql-deploy build \
examples/databricks/serverless dev \
-e AWS_REGION=${AWS_REGION} \
-e AWS_ACCOUNT_ID=${AWS_ACCOUNT_ID} \
-e DATABRICKS_ACCOUNT_ID=${DATABRICKS_ACCOUNT_ID} \
-e DATABRICKS_AWS_ACCOUNT_ID=${DATABRICKS_AWS_ACCOUNT_ID} \
--show-queries
```

--------------------------------

### Execute StackQL Deploy test command

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/cli-reference/test.md

This example demonstrates how to use the `stackql-deploy test` command to confirm the desired state of resources for a stack in a target environment. It shows how to specify the stack directory, environment, and pass additional environment variables.

```bash
stackql-deploy test azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=631d1c6d-0000-0000-0000-688bfe4e1468
```

--------------------------------

### StackQL Deploy Test

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Runs tests on the deployed Databricks serverless infrastructure using stackql-deploy, showing the queries executed. Requires AWS and Databricks environment variables to be set.

```bash
stackql-deploy test \
examples/databricks/serverless dev \
-e AWS_REGION=${AWS_REGION} \
-e AWS_ACCOUNT_ID=${AWS_ACCOUNT_ID} \
-e DATABRICKS_ACCOUNT_ID=${DATABRICKS_ACCOUNT_ID} \
-e DATABRICKS_AWS_ACCOUNT_ID=${DATABRICKS_AWS_ACCOUNT_ID} \
--show-queries
```

--------------------------------

### StackQL Build Output Variables

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/cli-reference/build.md

Example JSON output demonstrating deployment variables exported after a successful StackQL build. These variables can include stack name, environment, and resource-specific details.

```json
{
  "stack_name": "my-databricks-workspace",
  "stack_env": "prod",
  "workspace_name": "my-databricks-workspace-prod",
  "workspace_id": "123456789012345",
  "deployment_name": "dbc-ab123456-789a",
  "workspace_status": "RUNNING"
}
```

--------------------------------

### Use stackql-deploy GitHub Action for Stack Deployment

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/github-actions.md

This example demonstrates how to configure the `stackql-deploy` GitHub Action in a workflow to build a specified infrastructure stack. It requires the `actions/checkout` action and sets up necessary environment variables for cloud provider authentication.

```yaml
jobs:
  stackql-actions-test:
    name: StackQL Actions Test
    runs-on: ubuntu-latest
    env:
      GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy a Stack
        uses: stackql/setup-deploy@v1.0.1
        with:
          command: 'build'
          stack_dir: 'examples/k8s-the-hard-way'
          stack_env: 'dev'
          env_vars: 'GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo'
```

--------------------------------

### Pull Databricks Registries and Query Credentials in Stackql

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/serverless/README.md

This SQL snippet demonstrates pulling Databricks account and workspace registries and then querying credential and workspace information. It includes a check for valid account and subscription credentials. Requires Databricks account ID.

```sql
registry pull databricks_account v24.12.00279;
registry pull databricks_workspace v24.12.00279;

-- This will fail if accounts, subscription, or credentials are in error.
select account_id FROM databricks_account.provisioning.credentials WHERE account_id = '<your databricks account id>';
select account_id, workspace_name, workspace_id, workspace_status from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>';
```

--------------------------------

### Display StackQL Deploy Version Information (Bash)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/cli-reference/info.md

This command displays the version information for stackql-deploy, its Python dependency (pystackql), the stackql binary, and the operating system platform. It also lists all installed providers and their versions. No external dependencies are required beyond the stackql-deploy tool itself.

```bash
stackql-deploy info
```

--------------------------------

### Build AWS Stack for SIT Environment

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/template-library/aws/vpc-and-ec2-instance.md

Deploys an AWS stack named 'aws-stack' to a 'sit' environment. Requires stackql-deploy to be installed and AWS credentials configured. The example also shows how to set AWS region.

```bash
stackql-deploy build aws-stack sit \
-e AWS_REGION=ap-southeast-2
```

--------------------------------

### Test StackQL Stack for Staging Environment

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/github-actions.md

This example demonstrates how to configure a GitHub Actions job to test a StackQL stack. It specifies the command as 'test', the directory of the stack, the target environment ('sit'), and any necessary environment variables for the cloud provider. Dependencies include the `stackql/setup-deploy` action.

```yaml
jobs:
  stackql-actions-test:
    name: StackQL Actions Test
    runs-on: ubuntu-latest
    env:
      GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Test a Stack
        uses: stackql/setup-deploy@v1.0.1
        with:
          command: 'test'
          stack_dir: 'examples/k8s-the-hard-way'
          stack_env: 'sit'
          env_vars: 'GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo'
```

--------------------------------

### StackQL Deploy Teardown

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Initiates the teardown process for stackql-deploy managed infrastructure in a Databricks serverless environment, displaying the queries executed. Requires AWS and Databricks environment variables to be set.

```bash
stackql-deploy teardown \
examples/databricks/serverless dev \
-e AWS_REGION=${AWS_REGION} \
-e AWS_ACCOUNT_ID=${AWS_ACCOUNT_ID} \
-e DATABRICKS_ACCOUNT_ID=${DATABRICKS_ACCOUNT_ID} \
-e DATABRICKS_AWS_ACCOUNT_ID=${DATABRICKS_AWS_ACCOUNT_ID} \
--show-queries
```

--------------------------------

### Define Conditional Resource Deployment

Source: https://context7.com/stackql/stackql-deploy/llms.txt

YAML examples demonstrating conditional resource deployment. Resources can be deployed based on environment variables or specific conditions, allowing for dynamic infrastructure configurations.

```yaml
resources:
  - name: optional_feature
    if: "{{ ENABLE_FEATURE }}"
    props:
      - name: feature_config
        value: "enabled"

  - name: production_only_resource
    if: "{{ stack_env == 'prd' }}"
    props:
      - name: resource_tier
        value: "premium"
```

--------------------------------

### StackQL Deploy Dry Run

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Performs a dry run of the stackql-deploy build process for a Databricks serverless environment, useful for catching environmental issues before actual deployment. Requires AWS and Databricks environment variables to be set.

```bash
stackql-deploy build \
examples/databricks/serverless dev \
-e AWS_REGION=${AWS_REGION} \
-e AWS_ACCOUNT_ID=${AWS_ACCOUNT_ID} \
-e DATABRICKS_ACCOUNT_ID=${DATABRICKS_ACCOUNT_ID} \
-e DATABRICKS_AWS_ACCOUNT_ID=${DATABRICKS_AWS_ACCOUNT_ID} \
--dry-run
```

--------------------------------

### Azure Stack Configuration Manifest

Source: https://context7.com/stackql/stackql-deploy/llms.txt

A comprehensive example of an Azure stack configuration manifest. It defines providers, global variables, and resources like resource groups, virtual networks, and subnets, utilizing template variables for dynamic values.

```yaml
version: 1
name: "azure-stack"
description: "Azure infrastructure stack"

providers:
  - azure

globals:
  - name: subscription_id
    description: azure subscription id
    value: "{{ AZURE_SUBSCRIPTION_ID }}"
  - name: location
    description: default location for resources
    value: eastus
  - name: admin_password
    description: vm admin password
    value: "{{ AZURE_VM_ADMIN_PASSWORD }}"
  - name: global_tags
    value:
      provisioner: stackql
      stackName: "{{ stack_name }}"
      stackEnv: "{{ stack_env }}"

resources:
  - name: example_resource_group
    props:
      - name: resource_group_name
        value: "{{ stack_name }}-{{ stack_env }}-rg"
    exports:
      - resource_group_name

  - name: example_vnet
    props:
      - name: vnet_name
        value: "{{ stack_name }}-{{ stack_env }}-vnet"
      - name: vnet_cidr_block
        values:
          prd:
            value: "10.0.0.0/16"
          sit:
            value: "10.1.0.0/16"
          dev:
            value: "10.2.0.0/16"
    exports:
      - vnet_name
      - vnet_cidr_block

  - name: example_subnet
    props:
      - name: subnet_name
        value: "{{ stack_name }}-{{ stack_env }}-subnet-1"
      - name: subnet_cidr
        values:
          prd:
            value: "10.0.1.0/24"
          sit:
            value: "10.1.1.0/24"
          dev:
            value: "10.2.1.0/24"
    exports:
      - subnet_name
      - subnet_id

exports:
  - resource_group_name
  - vnet_name
  - subnet_id

```

--------------------------------

### Query Databricks Workspaces with StackQL

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

This SQL snippet demonstrates how to query Databricks workspaces using StackQL. It selects account ID, workspace name, ID, and status for a specific account ID. This is useful for verifying workspace provisioning and status after deployment.

```sql
select account_id, workspace_name, workspace_id, workspace_status from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>';
```

--------------------------------

### StackQL SQL: Pull Databricks Registry and Query Workspaces

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/serverless/README.md

These StackQL SQL commands are used within the interactive shell to pull specific versions of Databricks registry providers (account and workspace) and then query the provisioning status of workspaces within a given account. Replace '<your databricks account id>' with your actual account ID.

```sql
registry pull databricks_account v24.12.00279;

registry pull databricks_workspace v24.12.00279;



select account_id, workspace_name, workspace_id, workspace_status from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>';
```

--------------------------------

### Example YAML Configuration for Deployment Exports

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/exports.mdx

This YAML snippet demonstrates how to define a list of variables to be exported to a JSON file after a Stackql deployment. These variables are sourced from the deployment context, either global variables or resource exports. The `--output-file` CLI argument is required for this feature to function.

```yaml
exports:
  - databricks_workspace_name
  - databricks_workspace_id
  - aws_iam_role_arn
  - deployment_timestamp
```

--------------------------------

### StackQL Manifest Resource Definition (YAML)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/type.mdx

Example of defining a 'query' resource within a stackql_manifest.yml file. This configuration specifies the resource name and its type, 'query', indicating it's intended for data retrieval using an 'exports' method.

```yaml
resources:
- name: get_subnets
  type: query
...
```

--------------------------------

### Deploy StackQL Stack and Export Outputs

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/github-actions.md

This example shows a GitHub Actions workflow to deploy a StackQL stack and export its outputs to a JSON file. It first builds the stack using the 'build' command, specifying the stack directory, environment, and an output file. Subsequently, it uses `jq` to parse specific variables from the output JSON and makes them available as step outputs for use in later workflow steps.

```yaml
jobs:
  deploy-and-process:
    name: Deploy Stack and Process Outputs
    runs-on: ubuntu-latest
    env:
      DATABRICKS_CLIENT_ID: ${{ secrets.DATABRICKS_CLIENT_ID }}
      DATABRICKS_CLIENT_SECRET: ${{ secrets.DATABRICKS_CLIENT_SECRET }}
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy Databricks Stack
        uses: stackql/setup-deploy@v1.0.1
        with:
          command: 'build'
          stack_dir: 'examples/databricks/serverless'
          stack_env: 'prod'
          output_file: './deployment-outputs.json'
          env_vars: |
            DATABRICKS_ACCOUNT_ID=${{ secrets.DATABRICKS_ACCOUNT_ID }}
            AWS_REGION=us-east-1
            AWS_ACCOUNT_ID=${{ secrets.AWS_ACCOUNT_ID }}

      - name: Parse Deployment Outputs
        id: parse_outputs
        run: |
          echo "workspace_name=$(jq -r '.databricks_workspace_name' ./deployment-outputs.json)" >> $GITHUB_OUTPUT
          echo "workspace_id=$(jq -r '.databricks_workspace_id' ./deployment-outputs.json)" >> $GITHUB_OUTPUT
          echo "workspace_status=$(jq -r '.workspace_status' ./deployment-outputs.json)" >> $GITHUB_OUTPUT

      - name: Use Exported Variables
        run: |
          echo "Deployed workspace: ${{ steps.parse_outputs.outputs.workspace_name }}"
          echo "Workspace ID: ${{ steps.parse_outputs.outputs.workspace_id }}"
          echo "Status: ${{ steps.parse_outputs.outputs.workspace_status }}"
```

--------------------------------

### StackQL SHOW METHODS for Idempotent Resource Identification

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/resource-query-files.md

This command helps identify idempotent resources by listing available methods for a given StackQL resource. It shows the `MethodName`, `RequiredParams`, and `SQLVerb` associated with each method. The example demonstrates that `create_or_update` maps to an `INSERT` SQL verb, indicating idempotency.

```plaintext
stackql  >>show methods in azure.network.virtual_networks;
|-------------------------------|--------------------------------|---------|
|          MethodName           |         RequiredParams         | SQLVerb |
|-------------------------------|--------------------------------|---------|
| get                           | resourceGroupName,             | SELECT  |
|                               | subscriptionId,                |         |
|                               | virtualNetworkName             |         |
|-------------------------------|--------------------------------|---------|
| list                          | resourceGroupName,             | SELECT  |
|                               | subscriptionId                 |         |
|-------------------------------|--------------------------------|---------|
| create_or_update              | resourceGroupName,             | INSERT  |
|                               | subscriptionId,                |         |
|                               | virtualNetworkName             |         |
|-------------------------------|--------------------------------|---------|
| delete                        | resourceGroupName,             | DELETE  |
|                               | subscriptionId,                |         |
|                               | virtualNetworkName             |         |
|-------------------------------|--------------------------------|---------|
| check_ip_address_availability | ipAddress, resourceGroupName,  | EXEC    |
|                               | subscriptionId,                |         |
|                               | virtualNetworkName             |         |
|-------------------------------|--------------------------------|---------|
```

--------------------------------

### SQL Query for StackQL Exports

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/exports.mdx

An example SQL query using StackQL's export syntax to select and alias variables defined in the manifest. This query retrieves network details based on provided variables.

```sql
/*+ exports */
SELECT 
'{{ vpc_name }}' as vpc_name,
selfLink as vpc_link
FROM google.compute.networks
WHERE name = '{{ vpc_name }}'
AND project = '{{ project }}'
```

--------------------------------

### Configure Databricks and AWS Environment Variables (Bash)

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/snowflake-interoperability/README.md

Sets up essential environment variables for Databricks and AWS interaction. Includes region, account IDs, and Databricks client credentials. These are crucial for subsequent stackql-deploy operations. Can be skipped if using AWS Cloud Shell.

```bash
#!/usr/bin/env bash

export AWS_REGION='us-east-1' # or wherever you want
export AWS_ACCOUNT_ID='<your aws account ID>'
export DATABRICKS_ACCOUNT_ID='<your databricks account ID>'
export DATABRICKS_AWS_ACCOUNT_ID='<your databricks aws account ID>'

# These need to be created by clickops under [the account level user managment page](https://accounts.cloud.databricks.com/user-management).
export DATABRICKS_CLIENT_ID='<your clickops created CICD agent client id>'
export DATABRICKS_CLIENT_SECRET='<your clickops created CICD agent client secret>'

## These can be skipped if you run on [aws cloud shell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html).
export AWS_SECRET_ACCESS_KEY='<your aws secret per aws cli>'
export AWS_ACCESS_KEY_ID='<your aws access key id per aws cli>'

```

--------------------------------

### Define AWS Internet Gateway Resource in StackQL Manifest

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/template-library/aws/vpc-and-ec2-instance.md

This snippet defines an AWS Internet Gateway resource. It includes tags that are merged from global configurations. No specific properties are defined beyond tags in this example, but the resource is declared.

```yaml
  - name: example_inet_gateway
    props:
      - name: inet_gateway_tags
        value:
          - Key: Name
            Value: "{{ stack_name }}-{{ stack_env }}-inet-gateway"
        merge: ['global_tags']
    exports:
      - internet_gateway_id
```

--------------------------------

### Teardown Stack with Environment Variables (Bash)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/cli-reference/teardown.md

This example demonstrates how to tear down a stack in a specific environment while also setting additional environment variables. This is useful for providing dynamic configuration values during the deprovisioning process. The command utilizes the `stackql-deploy` CLI tool.

```bash
stackql-deploy teardown azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=631d1c6d-0000-0000-0000-688bfe4e1468
```

--------------------------------

### Handle Resource Deletion with postdelete_retries and postdelete_retry_delay (SQL)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/resource-query-files.md

The `postdelete_retries` and `postdelete_retry_delay` options are specific to `exists` queries during teardown operations. They provide a mechanism to allow sufficient time for a resource to be fully deleted by the provider before the operation completes. This example checks for the existence of a GCP compute instance.

```sql
/*+ exists, postdelete_retries=10, postdelete_retry_delay=5 */
SELECT COUNT(*) as count FROM google.compute.instances
WHERE name = '{{ instance_name }}'
AND project = '{{ project }}'
AND zone = '{{ zone }}'
```

--------------------------------

### Check Resource State with statecheck Anchor (SQL)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/resource-query-files.md

The `statecheck` anchor uses StackQL `SELECT` statements to verify if a resource is in its desired state. It must return a single row with a `count` column (1 for desired state, 0 otherwise). This example checks GCP compute network properties and may require retries due to asynchronous provider operations.

```sql
/*+ statecheck, retries=5, retry_delay=10 */
SELECT COUNT(*) as count FROM google.compute.networks
WHERE name = '{{ vpc_name }}'
AND project = '{{ project }}'
AND autoCreateSubnetworks = false
AND JSON_EXTRACT(routingConfig, '$.routingMode') = 'REGIONAL'
```

--------------------------------

### Deploy Azure Stack using stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/azure/azure-stack/README.md

This command deploys an Azure stack using `stackql-deploy`. It specifies the build action, the stack directory, the deployment environment ('sit'), and passes required environment variables like subscription ID and VM admin password.

```bash
export AZURE_VM_ADMIN_PASSWORD="Your_password_here1"
stackql-deploy build \
examples/azure/azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=631d1c6d-2a65-43e7-93c2-688bfe4e1468 \
-e AZURE_VM_ADMIN_PASSWORD=$AZURE_VM_ADMIN_PASSWORD
```

--------------------------------

### Initialize a StackQL Deploy Project

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/load-balanced-vms/README.md

Initializes a new stackql-deploy project directory. The `init` command scaffolds a sample project structure that can be customized for your specific cloud stack.

```bash
stackql-deploy init load-balanced-vms
```

--------------------------------

### Test Azure Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/azure/azure-stack/README.md

This command tests an already deployed Azure stack. It verifies that all resources are present and in the desired state according to the stack definition.

```bash
stackql-deploy test \
examples/azure/azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=631d1c6d-2a65-43e7-93c2-688bfe4e1468 \
-e AZURE_VM_ADMIN_PASSWORD=$AZURE_VM_ADMIN_PASSWORD
```

--------------------------------

### Initialize stackql-deploy Project

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/k8s-the-hard-way/README.md

Scaffolds a new project directory for stackql-deploy. This command initializes the structure for defining and managing cloud resources.

```bash
stackql-deploy init k8s-the-hard-way
```

--------------------------------

### Dry Run Azure Stack Deployment with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/azure/azure-stack/README.md

This command performs a dry run of the Azure stack deployment. It shows the `stackql` queries that would be executed without actually provisioning any resources, useful for validation.

```bash
stackql-deploy build \
examples/azure/azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=631d1c6d-2a65-43e7-93c2-688bfe4e1468 \
--dry-run
```

--------------------------------

### Define Protected Variables

Source: https://context7.com/stackql/stackql-deploy/llms.txt

YAML example for defining protected variables. Sensitive data like passwords or connection strings can be masked in logs by marking them as protected, enhancing security.

```yaml
resources:
  - name: database_connection
    props:
      - name: db_password
        value: "{{ DB_PASSWORD }}"
    protected:
      - db_password
      - connection_string
    exports:
      - connection_string
```

--------------------------------

### Teardown Azure Stack using stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/azure/azure-stack/README.md

This command tears down an Azure stack, deprovisioning all associated resources. It requires the stack directory, deployment environment, and necessary environment variables for authentication.

```bash
stackql-deploy teardown \
examples/azure/azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=631d1c6d-2a65-43e7-93c2-688bfe4e1468 \
-e AZURE_VM_ADMIN_PASSWORD=$AZURE_VM_ADMIN_PASSWORD
```

--------------------------------

### Deploy, Test, and Teardown StackQL Deploy Stacks

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/load-balanced-vms/README.md

Demonstrates the core commands for managing cloud resources with stackql-deploy: `build` for deployment, `test` for running stack tests, and `teardown` for removing resources. It includes setting environment variables like GOOGLE_CREDENTIALS and GOOGLE_PROJECT, and options like `--dry-run` and `--log-level`.

```bash
export GOOGLE_CREDENTIALS=$(cat ./testcreds/stackql-deploy-project-demo-service-account.json)
# deploy a stack
stackql-deploy build \
examples\google\load-balanced-vms \
dev \
-e GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo \
--dry-run \
--log-level DEBUG
```

```bash
# test a stack
stackql-deploy test \
examples/google/k8s-the-hard-way \
dev \
-e GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo \
--dry-run
```

```bash
# teardown a stack
stackql-deploy teardown \
examples/google/k8s-the-hard-way \
dev \
-e GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo \
--dry-run
```

--------------------------------

### Stackql Deploy Manifest: Resource Definitions

Source: https://github.com/stackql/stackql-deploy/blob/main/README.rst

Lists infrastructure components like networks and compute instances that form the stack. Defines resource names, descriptions, and potential properties or exports.

```yaml
resources:
  - name: resource_group
    description: azure resource group for activity monitor app
  - name: storage_account
    description: azure storage account for activity monitor app
    ... (additional properties and exports)
  ...
```

--------------------------------

### Deploy AWS Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/aws/patch-doc-test/README.md

Command to build and deploy an AWS infrastructure stack using stackql-deploy. It specifies the stack directory, deployment environment, and regional configuration, with an option to show the generated SQL queries.

```bash
stackql-deploy build \
examples/aws/patch-doc-test \
sit \
-e AWS_REGION=ap-southeast-2 \
--show-queries
```

--------------------------------

### Test AWS Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/aws/patch-doc-test/README.md

Command to test an existing AWS infrastructure stack deployed with stackql-deploy. This verifies that all resources are present and in the desired state for a specified environment.

```bash
stackql-deploy test \
examples/aws/patch-doc-test \
sit \
-e AWS_REGION=ap-southeast-2
```

--------------------------------

### Dry Run Deployment of AWS Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/aws/patch-doc-test/README.md

Command to perform a dry run of an AWS stack deployment using stackql-deploy. This allows viewing the SQL queries that would be executed without actually provisioning any resources.

```bash
stackql-deploy build \
examples/aws/patch-doc-test \
sit \
-e AWS_REGION=ap-southeast-2 \
--dry-run
```

--------------------------------

### Configure Resources with Reusable Query Templates (YAML)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/file.mdx

This YAML snippet demonstrates how to configure resources in a StackQL deployment. It highlights the use of the 'file' property to specify a common query template file (e.g., 'firewalls.iql') for multiple resources, promoting reusability and consistency. Properties for each resource, such as name, direction, and allowed protocols, are also defined.

```yaml
...
resources:
- name: internal_firewall
  file: firewalls.iql
  props:
  - name: fw_name
    value: "{{ stack_name }}-{{ stack_env }}-allow-internal-fw"
  - name: fw_direction
    value: INGRESS
  - name: fw_source_ranges
    values:
      dev:
        value: ["10.240.0.0/24", "10.200.0.0/16"]
  - name: fw_allowed
    value: [{IPProtocol: tcp}, {IPProtocol: udp}, {IPProtocol: icmp}]
- name: external_firewall
  file: firewalls.iql
  props:
  - name: fw_name
    value: "{{ stack_name }}-{{ stack_env }}-allow-external-fw"
  - name: fw_direction
    value: INGRESS
  - name: fw_source_ranges
    values:
      dev:
        value: ["0.0.0.0/0"]
  - name: fw_allowed
    value: [{IPProtocol: tcp, ports: ["22"]}, {IPProtocol: tcp, ports: ["6443"]},{IPProtocol: icmp}]
...
```

--------------------------------

### YAML Configuration for Resource-Level Authentication

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/auth.mdx

Example of stackql_manifest.yml demonstrating custom 'basic' authentication for a 'users_topic' resource using environment variables for username and password. This configuration leverages exported values from another resource ('app_manager_api_key') for dynamic credential injection.

```yaml
resources:
  - name: app_manager_api_key
    props:
      - name: display_name
        value: "{{ stack_name }}-{{ stack_env }}-app-manager-api-key"
      - name: description
        value: "Kafka API Key owned by 'app-manager' service account"
      - name: owner
        value:
          id: app_manager_id
          api_version: app_manager_api_version
          kind: app_manager_kind
    exports:
      - app_manager_api_key_id
      - app_manager_api_key_secret

  - name: users_topic
    auth:
      confluent:
        type: basic
        username_var: app_manager_api_key_id
        password_var: app_manager_api_key_secret
    props:
      - name: topic_name
        value: "users"
      - name: kafka_cluster
        value: {{ cluster_id }}
      - name: rest_endpoint
        value: {{ cluster_rest_endpoint }}
```

--------------------------------

### Environment-Specific Resource Properties in Manifest

Source: https://github.com/stackql/stackql-deploy/blob/main/docs/source/manifest_file.md

An example illustrating how to define environment-specific configurations for a resource's properties within the stackql-deploy manifest file. It uses a 'values' block keyed by environment names ('prd', 'dev') to set different values for the 'resource_group_name'.

```yaml
resources:
  - name: monitor_resource_group
    props:
      - name: resource_group_name
        values:
          prd:
            value: "activity-monitor-prd"
          dev:
            value: "activity-monitor-dev"
```

--------------------------------

### CI/CD Pipeline Script for StackQL Deployments

Source: https://context7.com/stackql/stackql-deploy/llms.txt

A bash script demonstrating a typical CI/CD pipeline workflow for stackql-deploy. It includes steps for validation (dry run), deployment with rollback on failure, running tests, and checking the exit code for success.

```bash
#!/bin/bash
set -e

# CI/CD Pipeline Script
STACK_NAME="my-stack"
STACK_ENV="prd"

# Validate with dry run
stackql-deploy build $STACK_ENV $STACK_NAME \
  --dry-run \
  --log-level INFO

# Deploy stack
stackql-deploy build $STACK_ENV $STACK_NAME \
  --output-file outputs/${STACK_ENV}.json \
  --on-failure rollback

# Run tests
stackql-deploy test $STACK_ENV $STACK_NAME \
  --output-file test-results/${STACK_ENV}.json

# Check exit code
if [ $? -eq 0 ]; then
  echo "Deployment and tests successful"
else
  echo "Deployment or tests failed"
  exit 1
fi
```

--------------------------------

### Embed SQL for Databricks Grant Permissions in Manifest

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/sql.mdx

This example demonstrates embedding a SQL UPDATE statement directly into a StackQL manifest for the `databricks_workspace/unitycatalog/grants` resource. It utilizes Jinja2 templating for dynamic values and the YAML pipe character for multi-line SQL readability.

```yaml
resources:
  - name: databricks_workspace/unitycatalog/grants
    type: command
    props: []
    sql: |
      /*+ update */
      UPDATE databricks_workspace.unitycatalog.grants
      SET principal = '{{ principal }}',
          privileges = {{ privileges }}
      WHERE full_name = '{{ full_name }}' AND
      securable_type = '{{ securable_type }}' AND
      deployment_name = '{{ deployment_name }}';
```

--------------------------------

### Delete Databricks Workspace in Stackql

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/databricks/serverless/README.md

This SQL command asynchronously deletes a Databricks workspace. You need to provide the account ID and workspace ID obtained from a previous query. Response caching might delay visibility, and bouncing the stackql session can help with token refresh.

```sql
delete from databricks_account.provisioning.workspaces where account_id = '<your databricks account id>' and workspace_id = '<workspace id>';
```

--------------------------------

### StackQL Resource Type Descriptions (Info)

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/type.mdx

Explanation of various resource types available in StackQL deployments, including 'resource', 'query', 'script', 'multi', and 'command'. Each type has specific use cases for provisioning, data retrieval, external script execution, looping resource creation, and command execution during build operations.

```text
- `resource` will typically include `create`, `update`, `delete`, `exists`, `statecheck` and `exports` methods and is intended for provisioning or configuring a resource  
- `query` is designed to return data using an `exports` method
- `script` is used to incorporate an external script in your stack definition (non StackQL query)
- `multi` is used when resources are created in a loop (such as creating 3 vms)
- `command` is used to run a command (like an `UPDATE`, `INSERT`) during a `build` operation (which does not export any variables)
```

--------------------------------

### Teardown AWS Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/aws/patch-doc-test/README.md

Command to tear down and deprovision all resources associated with an AWS infrastructure stack managed by stackql-deploy for a specific environment.

```bash
stackql-deploy teardown \
examples/aws/patch-doc-test \
sit \
-e AWS_REGION=ap-southeast-2
```

--------------------------------

### Conditional SQL Command in StackQL Manifest

Source: https://github.com/stackql/stackql-deploy/blob/main/website/docs/manifest_fields/resources/sql.mdx

This example shows how to conditionally execute a SQL INSERT statement within a StackQL manifest based on an environment variable. The `if` condition ensures the command only runs in a 'production' environment, and the SQL uses templated variables for dynamic table and value insertion.

```yaml
- name: custom_command
  type: command
  if: "environment == 'production'"
  props:
    - name: table_name
      value: "{{ stack_name }}_audit_log"
  sql: |
    /*+ update */
    INSERT INTO {{ table_name }}
    VALUES ('{{ stack_name }}', '{{ stack_env }}', '{{ deployment_timestamp }}');
```

--------------------------------

### Test Cloud Stack with stackql-deploy

Source: https://github.com/stackql/stackql-deploy/blob/main/examples/google/k8s-the-hard-way/README.md

Tests a deployed cloud stack using stackql-deploy. This command verifies the resources and configuration of the stack, with options for dry-run.

```bash
stackql-deploy test \
examples/google/k8s-the-hard-way \	dev \
-e GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo \
--dry-run
```

--------------------------------

### Stackql Deploy Manifest: Providers Configuration

Source: https://github.com/stackql/stackql-deploy/blob/main/README.rst

Defines the cloud service providers that the stack will interact with. Each provider listed will be initialized for use within the stack.

```yaml
providers:
  - azure
  - github
```