quartzctl is an open-source CLI tool designed to automate the installation and maintenance of multi-stage Terraform projects. It leverages a single YAML configuration to define stages, their dependencies, input variables, environment variables, and health checks, streamlining complex infrastructure deployments.
We were tasked with building a fully automated DevSecOps platform with Platform One and Ironbank as its core, while minimizing installation times and risk of transient failures. A high degree of flexibility was also needed, so as to facilitate rapid development of applications and infrastructure for hackathon style environments, all while keeping an eye on security for government customers. Initially developed as a loose conglomeration of bash scripts glued together by a makefile, this eventually became unmaintainable due to increasing complexity of requirements coupled with the expectation of quick turnaround with change requests.
Quartz is an open-source CLI tool designed to automate the full lifecycle of Kubernetes-based platform infrastructure with a focus on DevSecOps enablement. Originally inspired by U.S. government platform initiatives like PlatformOne and BigBang, Quartz simplifies the provisioning, configuration, and teardown of secure, GitOps-enabled environments. It leverages a top-level YAML configuration to drive installations, source secrets, and orchestrate tools like FluxCD or ArgoCD. With robust health checks, retry logic, and zero-interaction execution, Quartz empowers teams to build reproducible, production-like platforms in development or staging deployments.
addsubcommands to streamline adding new stagesgeneratesubcommands to create new projects with all required boilerplate (quartz.yaml, stages), options to enable/disable common items like eks, core helm charts, etc...- Plugin framework to expand beyond AWS and Terraform
- Unwind tightly coupled assumptions of the platform (ex: separate repositories vs monorepo, use of gitops, core application stack, etc...)
- Multi-Stage Management: Define and manage multiple Terraform stages with interdependencies.
- YAML Configuration: Centralized configuration file specifying stages, variables, and settings.
- Dependency Handling: Automatically determines the order of stage execution based on dependencies.
- Dynamic Variables: Pass output variables from one stage as input to another.
- Environment Management: Set environment variables and configuration values per stage.
- Health Checks: Execute pre- and post-apply/destroy health checks to ensure application stability.
- Kubernetes Integration: Monitor Kubernetes deployment statuses and other conditions before proceeding.
- Extensibility: Support for additional features and integrations as needed.
You can install quartz using one of the following methods:
go install github.com/MetroStar/quartzctl@latestDownload the latest release from the Releases page and add it to your system's PATH.
quartz [command] [flags]check: Check environment, configuration and access for installer prerequisites.clean: Perform a full cleanup/teardown of the system.export: Export configured Kubernetes resources to yaml.info: Output configuration info for the current cluster.install: Perform a full install/update of the system.login: Generate a kubeconfig for the current cluster.refresh-secrets: Trigger all external secrets to be refreshed immediately.render: Write internal configuration to yaml (For development use).restart: Restart target resource(s).terraform: Terraform subcommands for configured stages.apply: Runterraform applyfor a stage (--stage <name>required).destroy: Runterraform destroyfor a stage (--stage <name>required).format: Runterraform fmtfor a stage (--stage <name>required).format-all: Runterraform fmtfor all stages.init: Runterraform initfor a stage (--stage <name>required).init-all: Runterraform initfor all stages.output: Runterraform outputfor a stage (--stage <name>required).plan: Runterraform planfor a stage (--stage <name>required).refresh: Runterraform refreshfor a stage (--stage <name>required).refresh-all: Runterraform refreshfor all stages.validate: Runterraform validatefor a stage (--stage <name>required).version: Runterraform version.
help: Shows a list of commands or help for one command
--config: Path to the YAML configuration file (Optional, default:quartz.yaml).--secrets: Path to a YAML file containing secrets as an alternative to environment variables. For development use only (Optional).--help: Shows a list of commands or help for one command.--version: Print the version and build time.
quartz install --config=quartz.yamlThe quartz.yaml file defines the stages and their configurations.
name: sampleenv # unique name of quartz cluster/environment
dns: # either of domain or zone must be specified
domain: "" # default <name>.<dns.zone>
zone: example.com # default parsed from dns.domain
aws:
region: us-east-1
The stage.yaml file allows for stage directories to override configuration from the cluster quartz.yaml or convention defaults.
# define input variables for the terraform stage and their source
# NOTE: all stages assume the existence of a `settings` input variable that recieves the entire rendered config map unless overridden
vars:
# input variable <my_env_val> defined in variables.tf
my_env_val:
# populate with an environment variable
env: HOSTNAME
my_secret_val:
# populate with a value from the rendered secrets
secret: github.token
my_config_val:
# populate with a value from the rendered config
config: dns.domain
my_stage_output_val:
stage:
name: previous_stage
output: cluster.name
# health checks that determine if the dependent resources are available before or after performing an action on the stage
checks:
# group name, only shows up in logs
pre_install:
# when to run the checks in this group, before/after apply/destroy
before:
- apply
# define health checks derived from the state of a kubernetes resource
kubernetes:
- name: public-cert
namespace: cert-manager
kind: Certificate
state: Ready
timeout: 1200
- name: istio
kind: HelmRelease
state: Ready
init:
before:
- apply
# explicit ordering
order: 1
# check the quartz global configmap for a key/value, useful for confirming one time jobs were successful (Ex. initial admin password change, database setup)
state:
- key: "myapp.initialized"
value: "true"
api:
before:
- apply
order: 2
# perform http requests against the endpoint in a loop until success or timeout
http:
- path: /api/system/status
app: myapp
content:
json:
key: status
value: UP
# options for controlling what is or isn't destroyed (Ex. I'm tearing down the entire cluster, no reason to unconfigure Keycloak and waste time or risk it erroring)
# typically will only use either the include or exclude sections as the logic for using them both is messy and rarely useful
destroy:
include:
- "module.to_destroy"
exclude:
- "module.skip_destroy"
See the included samples for more details.
-
Clone the repository:
git clone https://github.com/MetroStar/quartzctl.git cd quartzctl -
Install taskfile:
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -
Build the application:
task build
task testWe use golangci-lint for linting.
task lintIf you discover a security vulnerability, please follow the guidelines in our SECURITY.md file.
- Dependencies: We use Dependabot to keep dependencies up to date.
- CI/CD: All commits are tested via GitHub Actions workflows.
- Code Scanning: Static analysis is performed using CodeQL and other tools.
We welcome contributions! Please see our CONTRIBUTING.md for guidelines on how to get started.
This project is licensed under the Apache 2.0 License.
For questions or support, please open an issue or contact [email protected].
This project aims to comply with the OpenSSF Best Practices and has a Scorecard to reference.