getting-started.md

id	title	hide_title	hide_table_of_contents	description	tags	draft	unlisted
getting-started	Getting Started	false	false	A quick overview of how to get started with StackQL Deploy, including basic concepts and the essential components of a deployment.		false	false

import File from '/src/components/File';

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.

Installing stackql-deploy

Installing stackql-deploy globally is as easy as...

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

this will setup stackql-deploy and all its dependencies.

Note for macOS users
to install stackql-deploy in a virtual environment (which may be necessary on macOS), use the following:

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

How stackql-deploy works

The core components of stackql-deploy are the stack directory, the stackql_manifest.yml file and resource query (.iql) files. These files define your infrastructure and guide the deployment process.

stackql-deploy uses the stackql_manifest.yml file in the stack-dir, to render query templates (.iql files) in the resources sub directory of the stack-dir, targeting an environment (stack-env). stackql is used to execute the queries to deploy, test, update or delete resources as directed. This is summarized in the diagram below:

flowchart LR
    subgraph stack-dir
        direction LR
        B(Manifest File) --> C(Resource Files)
    end

    A(stackql-deploy) -->|uses...|stack-dir
    stack-dir -->|deploys to...|D(☁️ Your Environment)

Loading

stackql_manifest.yml File

The stackql_manifest.yml file is the basis of your stack configuration. It contains the definitions of the resources you want to manage, the providers you're using (such as AWS, Google Cloud, or Azure), and the environment-specific settings that will guide the deployment.

This manifest file acts as a blueprint for your infrastructure, describing the resources and how they should be configured. An example stackql_manifest.yml file is shown here:

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  

The stackql_manifest.yml file is detailed here.

Resource Query Files

Each resource or query defined in the resources section of the stackql_manifest.yml has an associated StackQL query file (using the .iql extension by convention). The query file defines queries to deploy and test a cloud resource. These queries are demarcated by query anchors (or hints). Available query anchors include:

• exists : tests for the existence or non-existence of a resource
• create : creates the resource in the desired state using a StackQL INSERT statement
• update : updates the resource to the desired state using a StackQL UPDATE statement
• createorupdate: for idempotent resources, uses a StackQL INSERT statement
• statecheck: tests the state of a resource after a DML operation, typically to determine if the resource is in the desired state
• exports : variables to export from the resource to be used in subsequent queries
• delete : deletes a resource using a StackQL DELETE statement

An example resource query file is shown here:

/*+ 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 }}'

Resource queries are detailed here.

stackql-deploy commands

Basic stackql-deploy commands include:

• build : provisions a stack to the desired state in a specified environment (including create and update operations if necessary)
• test : tests a stack to confirm all resources exist and are in their desired state
• teardown : de-provisions a stack

here are some examples:

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

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

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

For more detailed information see cli-reference/build, cli-reference/test, cli-reference/teardown, or other commands available.

stackql-deploy deployment flow

stackql-deploy processes the resources defined in the stackql_manifest.yml in top down order (teardown operations are processed in reverse order).

Quick Start

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: A basic setup for deploying a VPC, including subnets and routing configurations.
• Azure Quick Start Template: A setup for creating a Resource Group with associated resources.
• Google Cloud Quick Start Template: A configuration for deploying a VPC with network and firewall rules.

These templates are designed to help you kickstart your infrastructure deployment with minimal effort, providing a solid foundation that you can customize to meet your specific needs.