Skip to main content

Getting Started

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:

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:

stackql_manifest.yml
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:

example_res_grp.iql
/*+ 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:

deploy my-azure-stack to the prd environment
stackql-deploy build my-azure-stack prd \
-e AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
test my-azure-stack in the sit environment
stackql-deploy test my-azure-stack sit \
-e AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
teardown my-azure-stack in the dev environment
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.

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.