/qontract-development-cli

Qontract Development CLI

Primary LanguagePythonMIT LicenseMIT

Qontract Development CLI

PyPI PyPI platforms PyPI - License

Qontract Development CLI supports your daily qontract-reconcile development work.

[toc]

Installation

You can install this library from PyPI with pip:

python3 -m pip install qontract-development-cli

Or install it with pipx:

pipx install qontract-development-cli

You can also use pipx to run the library without installing it:

pipx run qontract-development-cli

Quickstart

  • Create initial configuration

    qd config init

    qd init

  • Create a profile sql-query to run the sql-query integration

    qd profile create sql-query

    qd profile create

  • Run sql-query profile

    qd profile run dev sql-query

    qd sql_query

Features

Qontract Development CLI currently provides the following features (get help with -h or --help):

  • Run qontract-reconcile and qontract-server as docker containers on your local machine
  • Support for different App-Interface environments (dev, prod, ...) via the env command
  • Configure your qontract-reconcile integration with the profile command
  • Support pull request reviews (see profile create)
  • Bootstrap your initial configurations with the config command
  • Shell auto-completion (see qd --help)
  • Automatically restart qontract-reconcile container when files change
  • Automatically rebuild the App-Interface bundle and restart the qontract-server container when files change

Examples

Take a look at the examples directory for different profile examples.

Usage

The following sections describe all available commands and their options.

Config

Manage global qontract-development-cli configuration.

qd config [sub-cmd] --help

  • edit: open the configuration file in your favorite editor
  • init: create a default configuration

Global Settings

Key Description Default
debug Enable/disable debug mode false
defaults_profile Name of defaults profile defaults
docker_compose_project_name Docker compose project name qontract-development
editor Your favorite editor $EDITOR or vim
environments_dir Directory to store environment files User config directory / environments
profiles_dir Directory to store profile files User config directory / profiles
worktrees_dir Directory to store git repo worktrees User cache directory / worktrees

Environments

An environment specifies app-interface instance settings, e.g., dev vs. prod config and path to the actual app-interface instance.

qd env [sub-cmd] --help

  • edit: Create/edit an environment file in your editor.
  • ls: List all available environments.
  • rm: Remove environment.
  • show: Display environment.

Environment Settings

Key Description Default
app_interface_path Path to local app-interface instance ~/workspace/app-interface
app_interface_state_bucket S3 bucket empty
app_interface_state_bucket_account AWS S3 account empty
config app-interface config ~/workspace/qontract-reconcile/config.dev.toml
gitlab_pr_submitter_queue_url Gitlab pr submitter queue url
run_qontract_reconcile Run qontract-reconcile container true
run_qontract_server Run qontract-server container true
run_vault Run vault container false

👉 Bold keys are mandatory or should be customized.

Profiles

A profile specifies all settings to run a qontract-reconcile integration (e.g., sql-query).

qd profile [sub-cmd] --help

  • create: Create a new profile to run an integration.

    Supports the creation of a new profile from an open PR/MR. See $ qd profile create --help for all available options.

  • edit: Edit a profile in your editor.

  • ls: List all available profiles.

  • rm: Remove profile.

  • run: Run a profile.

  • show: Display profile.

--no-dry-run

By default, qd runs integrations in dry-run mode if not explicitly specified differently in the profile config. There is also a --no-dry-run flag which lets you disable dry-run mode from the command line.

qd profile run dev my-integration --no-dry-run

The command line flag takes precedence over any configuration you might have in the profile settings.

Profile Settings

Key Description Default
additional_environment Dictionary of additional environment variables to pass to the qontract-reconcile container {}
container_uid Change ownership of /recconcile files in container to this user id current UID
command Command to run in the qontract-reconcile container. dockerfiles/hack/run-integration.py
command_extra_args Additional arguments to pass to the command.
debugger Python debugger debugpy
dry_run Run --dry-run mode true
extra_hosts List of 'HOSTNAME:IP' mapping entries for qontract-reconcile /etc/hosts. See extra_hosts docker compose file. []
integration_name Intergration name
integration_extra_args Intergration extra arguments
internal_redhat_ca Inject Red Hat internal CAs and REQUESTS_CA_BUNDLE environment variable false
log_level Log level info
app_interface_path App-interface instance path. (Overrides env.app_interface_path)
app_interface_pr App-interface PR/MR number
app_interface_upstream Upstream remote name upstream
qontract_reconcile_build_image Build qontract-reconcile image true
qontract_reconcile_image Qontract-reconcile image quay.io/app-sre/qontract-reconcile:latest
qontract_reconcile_path Qontract-reconcile path ~/workspace/qontract-reconcile
qontract_reconcile_pr Qontract-reconcile PR/MR number
qontract_reconcile_upstream Upstream remote name upstream
qontract_server_build_image Build qontract-server image true
qontract_server_image Qontract-server image quay.io/app-sre/qontract-server:latest
qontract_server_path Qontract-server path ~/workspace/qontract-server
qontract_schemas_path Qontract-schemas path ~/workspace/qontract-schemas
qontract_schemas_pr Qontract-schemas PR/MR number
qontract_schemas_upstream Upstream remote name upstream
run_once If 'true', execute the integration once and exit true
sleep_duration_secs If not run_once, sleep duration until integration runs again 10
localstack Run localstack container and set AWS related environment variables false
localstack_compose_file Path to your Localstack docker-compose file qontract_server_path / dev/localstack/docker-compose.yml
skip_initial_make_bundle Skip initial make bundle step false

👉 Bold keys are mandatory or should be customized.

PR/MR support

It's a pretty handy feature to create a profile from a pull request (merge request). E.g.:

qd profile create --app-interface PATH_TO_YOUR_LOCAL/app-interface-dev-data --app-interface-pr NUMBER --qontract-schemas-pr NUMBER --qontract-reconcile-pr NUMBER --integration-name glitchtip --integration-extra-args '' glitchtip-pr-check

Which results in this profile:

$ qd profile show glitchtip-pr-check
---
app_interface_path: PATH_TO_YOUR_LOCAL/app-interface-dev-data
app_interface_pr: NUMBER
integration_name: glitchtip
qontract_reconcile_pr: NUMBER
qontract_schemas_pr: NUMBER

Running this profile will:

  • Create new git worktrees (see config.worktrees_dir) for app-interface-dev-data, qontract-schema, and qontract-reconcile PRs
  • Start the containers with the adapted path to these worktrees
  • Restarting the profile will fetch PR updates

👉 A git worktree cleanup isn't implemented yet

Development

Ruff Checked with mypy

Release

  • Bump the version in pyproject.toml
  • Update the CHANGELOG.md
  • Commit the changes