{"id":21262838,"url":"https://github.com/stackql/stackql-deploy","last_synced_at":"2025-07-11T04:31:09.709Z","repository":{"id":232934516,"uuid":"785476010","full_name":"stackql/stackql-deploy","owner":"stackql","description":"Model driven resource provisioning and deployment framework using StackQL.","archived":false,"fork":false,"pushed_at":"2024-11-19T03:26:39.000Z","size":4572,"stargazers_count":3,"open_issues_count":10,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-19T03:30:24.125Z","etag":null,"topics":["configuration-management","hacktoberfest","infrastructure-as-code","stackql"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/stackql-deploy/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackql.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-12T00:39:22.000Z","updated_at":"2024-11-19T02:50:36.000Z","dependencies_parsed_at":"2024-04-21T23:42:45.822Z","dependency_job_id":"d7bda9b5-eead-439a-b2cc-394b3950b146","html_url":"https://github.com/stackql/stackql-deploy","commit_stats":null,"previous_names":["stackql/stackql-deploy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-deploy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-deploy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-deploy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-deploy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/stackql-deploy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225291991,"owners_count":17451086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration-management","hacktoberfest","infrastructure-as-code","stackql"],"created_at":"2024-11-21T04:59:29.459Z","updated_at":"2025-07-11T04:31:09.702Z","avatar_url":"https://github.com/stackql.png","language":"Python","readme":"\u003c!-- web assets --\u003e\r\n\r\n[logo]: https://stackql.io/img/stackql-logo-bold.png \"stackql logo\"\r\n[deploylogo]: https://stackql.io/img/stackql-deploy-logo.png \"stackql-deploy logo\"\r\n[stackqlrepo]: https://github.com/stackql/stackql\r\n[homepage]: https://stackql.io/\r\n[docs]: https://stackql.io/docs\r\n[blog]: https://stackql.io/blog\r\n[registry]: https://github.com/stackql/stackql-provider-registry\r\n\r\n\u003c!-- [readthedocs]: --\u003e\r\n\r\n[pypi]: https://pypi.org/project/stackql-deploy/\r\n\r\n\u003c!-- badges --\u003e\r\n\r\n[badge1]: https://img.shields.io/badge/platform-windows%20macos%20linux-brightgreen \"Platforms\"\r\n[badge2]: https://img.shields.io/pypi/v/stackql-deploy \"PyPi Version\"\r\n[badge3]: https://img.shields.io/pypi/dm/stackql-deploy \"PyPi Downloads\"\r\n[badge4]: https://img.shields.io/github/license/stackql/stackql \"License\"\r\n\r\n\u003c!-- github links --\u003e\r\n\r\n[discussions]: https://github.com/orgs/stackql/discussions\r\n[issues]: https://github.com/stackql/stackql-deploy/issues/new/choose\r\n\r\n\u003c!-- misc links --\u003e\r\n\r\n[twitter]: https://twitter.com/stackql\r\n\r\n\u003c!-- language: lang-none --\u003e\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n[![logo]][stackqlrepo]  \r\n![badge1]\r\n![badge2]\r\n![badge3]\r\n![badge4]\r\n\r\n\u003c/div\u003e\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n### Model driven resource provisioning and deployment framework using StackQL.\r\n\r\n\u003cp align=\"center\"\u003e\r\n\r\n\u003c!-- [__Read the docs »__][readthedocs]   --\u003e\r\n\r\n[**PyPi**][pypi]\r\n[**Raise an Issue**][issues]\r\n\r\n\u003c/p\u003e\r\n\u003c/div\u003e\r\n\r\n## About The Project\r\n\r\n[**`stackql-deploy`**][pypi] is an open-source command line utility which implements a declarative, model driven framework to deploy and manage multi cloud stacks using [**`stackql`**][stackqlrepo]. [**`stackql-deploy`**][pypi] is distributed as a Python script to be used as a CLI tool, do the following to get started:\r\n\u003cbr /\u003e\r\n\r\n```bash\r\npip install stackql-deploy\r\n```\r\n\r\n\u003e **Note for macOS users**  \r\n\u003e to install `stackql-deploy` in a virtual environment (which may be necessary on **macOS**), use the following:\r\n\u003e\r\n\u003e ```bash\r\n\u003e python3 -m venv myenv\r\n\u003e source myenv/bin/activate\r\n\u003e pip install stackql-deploy\r\n\u003e ```\r\n\r\n## About StackQL\r\n\r\nStackQL is a utility which allows you to query and interact with cloud and SaaS resources in real time using SQL grammar. StackQL supports a full set of SQL query/DML grammar, including `JOIN`, `UNION` adn subquery functionality and supports mutation operations on cloud and SaaS resources such as `create`, `update` and `delete`, implemented as `INSERT`, `UPDATE` and `DELETE` respectively. StackQL also supports grammar for performing lifecycle operations such as starting or stopping a VM using the `EXEC` statement.\r\n\r\nStackQL provider definitions are defined in plaintext OpenAPI extensions to the providers specification. These definitions are then used to generate the SQL schema and the API client. The source for the provider definitions are stored in the [**StackQL Registry**][registry].\r\n\r\n## How it works\r\n\r\n\u003c!-- \u003e see [__readthedocs__]() for more detailed documentation --\u003e\r\n\r\nA **`stackql-deploy`** project is a directory containing StackQL scripts with a manifest file at the root of the directory, for example:\r\n\r\n```\r\n├── example_stack\r\n│   ├── resources\r\n│   │   └── monitor_resource_group.iql\r\n│   ├── stackql_manifest.yml\r\n```\r\n\r\nthe `stackql_manifest.yml` defines the resources in the stackql with their properties which can be scoped by environments, for example:\r\n\r\n```yaml\r\nversion: 1\r\nname: example_stack\r\ndescription: oss activity monitor stack\r\nproviders:\r\n    - azure\r\nglobals:\r\n    - name: subscription_id\r\n    description: azure subscription id\r\n    value: \"{{ vars.AZURE_SUBSCRIPTION_ID }}\"\r\n    - name: location\r\n    value: eastus\r\n    - name: resource_group_name_base\r\n    value: \"activity-monitor\"\r\nresources:\r\n    - name: monitor_resource_group\r\n    description: azure resource group for activity monitor\r\n    props:\r\n        - name: resource_group_name\r\n        description: azure resource group name\r\n        value: \"{{ globals.resource_group_name_base }}-{{ globals.stack_env }}\"\r\n        # OR YOU CAN DO...\r\n        # values:\r\n        #   prd:\r\n        #     value: \"activity-monitor-prd\"\r\n        #   sit:\r\n        #     value: \"activity-monitor-sit\"\r\n        #   dev:\r\n        #     value: \"activity-monitor-dev\"\r\n```\r\n\r\n\u003e use `stackql-deploy init {stack_name}` to create a project directory with sample files\r\n\r\nDeployment orchestration using `stackql-deploy` includes:\r\n\r\n- **_pre-flight_** checks, which are StackQL queries that check for the existence or current configuration state of a resource\r\n- **_deployment_** scripts, which are StackQL queries to create or update resoruces (or delete in the case of de-provisioning)\r\n- **_post-deployment_** tests, which are StackQL queries to confirm that resources were deployed and have the desired state\r\n\r\nThis process is described here:\r\n\r\n```mermaid\r\ngraph TB\r\n    A[Start] --\u003e B{foreach\\nresource}\r\n    B --\u003e C[exists\\ncheck]\r\n    C --\u003e D{resource\\nexists?}\r\n    D -- Yes --\u003e E[run update\\nor createorupdate query]\r\n    D -- No --\u003e F[run create\\nor createorupdate query]\r\n    E --\u003e G[run statecheck check]\r\n    F --\u003e G\r\n    G --\u003e H{End}\r\n```\r\n\r\n### `INSERT`, `UPDATE`, `DELETE` queries\r\n\r\nMutation operations are defined as `.iql` files in the `resources` directory, these are templates that are rendered with properties or environment context variables at run time, for example:\r\n\r\n```sql\r\n/*+ create */\r\nINSERT INTO azure.resources.resource_groups(\r\n    resourceGroupName,\r\n    subscriptionId,\r\n    data__location\r\n)\r\nSELECT\r\n    '{{ resource_group_name }}',\r\n    '{{ subscription_id }}',\r\n    '{{ location }}'\r\n\r\n/*+ update */\r\nUPDATE azure.resources.resource_groups\r\nSET data__location = '{{ location }}'\r\nWHERE resourceGroupName = '{{ resource_group_name }}'\r\n    AND subscriptionId = '{{ subscription_id }}'\r\n\r\n/*+ delete */\r\nDELETE FROM azure.resources.resource_groups\r\nWHERE resourceGroupName = '{{ resource_group_name }}' AND subscriptionId = '{{ subscription_id }}'\r\n```\r\n\r\n### Test Queries\r\n\r\nTest files are defined as `.iql` files in the `resources` directory, these files define the per-flight and post-deploy checks to be performed, for example:\r\n\r\n```sql\r\n/*+ exists */\r\nSELECT COUNT(*) as count FROM azure.resources.resource_groups\r\nWHERE subscriptionId = '{{ subscription_id }}'\r\nAND resourceGroupName = '{{ resource_group_name }}'\r\n\r\n/*+ statecheck, retries=5, retry_delay=5 */\r\nSELECT COUNT(*) as count FROM azure.resources.resource_groups\r\nWHERE subscriptionId = '{{ subscription_id }}'\r\nAND resourceGroupName = '{{ resource_group_name }}'\r\nAND location = '{{ location }}'\r\nAND JSON_EXTRACT(properties, '$.provisioningState') = 'Succeeded'\r\n```\r\n\r\n## Usage\r\n\r\n\u003c!-- \u003e see [__readthedocs__]() for more detailed documentation --\u003e\r\n\r\nOnce installed, use the `build`, `test`, or `teardown` commands as shown here:\r\n\r\n```\r\nstackql-deploy build prd example_stack -e AZURE_SUBSCRIPTION_ID 00000000-0000-0000-0000-000000000000 --dry-run\r\nstackql-deploy build prd example_stack -e AZURE_SUBSCRIPTION_ID 00000000-0000-0000-0000-000000000000\r\nstackql-deploy test prd example_stack -e AZURE_SUBSCRIPTION_ID 00000000-0000-0000-0000-000000000000\r\nstackql-deploy teardown prd example_stack -e AZURE_SUBSCRIPTION_ID 00000000-0000-0000-0000-000000000000\r\n```\r\n\r\n\u003e **Note:** `teardown` deprovisions resources in reverse order to creation\r\n\r\nAdditional options include:\r\n\r\n- `--dry-run`: perform a dry run of the stack operations.\r\n- `--on-failure=rollback`: action on failure: rollback, ignore or error.\r\n- `--env-file=.env`: specify an environment variable file.\r\n- `-e KEY=value`: pass additional environment variables.\r\n- `--log-level`: logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL), defaults to INFO.\r\n\r\nUse `stackql-deploy info` to show information about the package and environment, for example:\r\n\r\n```bash\r\n$ stackql-deploy info\r\nstackql-deploy CLI\r\n  Version: 1.7.7\r\n\r\nStackQL Library\r\n  Version: v0.5.748\r\n  pystackql Version: 3.7.0\r\n  Platform: Linux x86_64 (Linux-5.15.133.1-microsoft-standard-WSL2-x86_64-with-glibc2.35), Python 3.10.12\r\n  Binary Path: `/mnt/c/LocalGitRepos/stackql/stackql-deploy/stackql`\r\n\r\nInstalled Providers\r\n  aws: v24.07.00246\r\n  azure: v23.03.00121\r\n  google: v24.09.00251\r\n```\r\n\r\nUse the `--help` option to see more information about the commands and options available:\r\n\r\n```\r\nstackql-deploy --help\r\n```\r\n\r\n## Building and Testing Locally\r\n\r\nTo get started with **stackql-deploy**, install it locally using pip:\r\n\r\n```bash\r\npython3 -m venv venv\r\nsource venv/bin/activate\r\npip install -e .\r\n# ...\r\ndeactivate\r\nrm -rf venv/\r\n```\r\n\r\n### To Remove the Locally Installed Package\r\n\r\n```\r\npip uninstall stackql-deploy\r\npip cache purge\r\n```\r\n\r\n## Building and Deploying to PyPI\r\n\r\nTo distribute **stackql-deploy** on PyPI, you'll need to ensure that you have all required files set up correctly in your project directory. This typically includes your `setup.py`, `README.rst`, `LICENSE`, and any other necessary files.\r\n\r\n### Building the Package\r\n\r\nFirst, ensure you have the latest versions of `setuptools` and `wheel` installed:\r\n\r\n```\r\n# pip install --upgrade setuptools wheel\r\npip install --upgrade build\r\n```\r\n\r\nThen, navigate to your project root directory and build the distribution files:\r\n\r\n```\r\nrm dist/stackql_deploy*\r\npython3 -m build\r\n# or\r\n# python3 setup.py sdist bdist_wheel\r\n```\r\n\r\nThis command generates distribution packages in the `dist/` directory.\r\n\r\n### Uploading the Package to PyPI\r\n\r\nTo upload the package to PyPI, you'll need to use `twine`, a utility for publishing Python packages. First, install `twine`:\r\n\r\n```\r\npip install twine\r\n```\r\n\r\nThen, use `twine` to upload all of the archives under `dist/`:\r\n\r\n```\r\ntwine upload --config-file .pypirc dist/*\r\n```\r\n\r\n### Building the Docs\r\n\r\nNavigate to your `docs` directory and build the Sphinx documentation:\r\n\r\n```\r\ncd docs\r\nmake html\r\n```\r\n\r\n## Code Linting\r\n\r\nTo maintain code quality and consistency, we use `ruff` as the linter for this project. `ruff` offers fast performance and a comprehensive set of linting rules suitable for `stackql-deploy`. You can run the lint check as follows:\r\n\r\n```bash\r\nruff check .\r\n```\r\n\r\nNote: If you need to install ruff, you can do so with `pip install ruff`.\r\n\r\n## Contributing\r\n\r\nContributions are welcome and encouraged.\r\n\r\n## License\r\n\r\nDistributed under the MIT License. See [`LICENSE`](https://github.com/stackql/stackql-deploy/blob/main/LICENSE) for more information.\r\n\r\n## Contact\r\n\r\nGet in touch with us via Twitter at [**@stackql**][twitter], email us at [**info@stackql.io**](info@stackql.io) or start a conversation using [**discussions**][discussions].\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-deploy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fstackql-deploy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-deploy/lists"}