guardctl

guardctl is a command-line tool in the deployment repository that asks about your cloud, domain, database, identity provider, and image registry, then writes the three files a deployment starts from: Helm values, Helm secrets, and the values for your identity provider’s bootstrap chart.

It generates the minimum configuration to get running. For settings it does not cover, such as the Gateway Stack, OpenBao, or policy report signing, layer them from Chart Values.

Before You Begin

• Python 3.10 or later
• The answers to the prompts below: your domain, cloud region, key management settings, and identity provider tenant details

Install

From your deployment repository clone, install from the guardctl/ directory with uv (recommended) or pip:

cd deployment/guardctl

# With uv
uv venv && source .venv/bin/activate
uv pip install -e .

# Or with pip
python3 -m venv env && source env/bin/activate
pip install -e .

Confirm the install:

guardctl --help

Generate the Files

Run the interactive wizard:

guardctl init

It prompts, in order, for:

1. Domain: the platform domain, such as guardian.example.com; required, with no default
2. Environment: a name (default development), lowercased and used in the file names. It must be a DNS label: up to 63 lowercase letters, digits, and hyphens, starting and ending with a letter or digit. development and dev also add http://localhost:5173 to the bootstrap file’s callbacks and origins
3. Database mode: bundled PostgreSQL in the cluster, or external managed PostgreSQL. Defaults to external when the environment is production, otherwise bundled
4. Cloud provider: aws, azure, or gcp. AWS also asks for the region and whether S3 access uses an IAM role (IRSA or instance profile) instead of static keys. With AWS KMS, step 5 asks the same for KMS
5. Key management provider: AWS KMS, Azure Key Vault, or GCP KMS (defaults to your cloud’s), then its settings. On AWS, AWS KMS also asks whether it uses an IAM role instead of static keys, defaulting to the S3 answer; with a role, guardctl sets useIamRole and an Auth Service service account annotated with a YOUR_IAM_ROLE_ARN placeholder for the role ARN; drop the annotation for an instance profile. The Key Vault URL and GCP project ID have no default; sovereign-cloud Key Vault URLs and GCP KMS multi-regions such as us are accepted
6. Identity provider: auth0, entra, or keycloak, then its tenant domain and audience, tenant ID, or URL and realm. The Auth0 domain has no default. The Keycloak URL, without a trailing slash, is also used for the bootstrap file’s and the post-install hook’s keycloak.url
7. Image registry: URL (with an optional port), username, and email, pre-filled for Cloudsmith (docker.cloudsmith.io, username eqtylab/prod); another registry also asks for the image repository prefix

guardctl then shows a configuration summary and asks for confirmation before writing anything.

To skip the prompts, pass -I with --cloud, --domain, --environment, and --auth, all of which are required in this mode:

guardctl init -I \
  --cloud azure \
  --domain guardian.example.com \
  --environment staging \
  --auth keycloak \
  --database bundled

Non-interactive mode uses defaults for everything the wizard would otherwise ask: your cloud’s key management provider with its settings left empty, static S3 and AWS KMS keys on AWS, us-east-1 for the AWS region, https://<domain> for the Auth0 API identifier, the hook’s auth0.domain and the GCP KMS projectId and locationId left empty and marked REQUIRED, a placeholder for the Auth0 domain elsewhere, and the Entra tenant ID read from the Entra secret. Fill these in as described in Fill In the Placeholders.

Options

Regenerating Files

guardctl does not silently replace files from an earlier run. If any of the three files already exists in the output directory, the wizard asks before overwriting them (default no), and non-interactive mode exits unless you pass --force.

Regenerating creates new random secrets, which no longer match a running deployment’s database password or Auth Service secrets. To change the configuration of an existing deployment, write to a different --output directory and copy over only the values you need.

Generated Files

guardctl writes three files to the output directory, named after the environment:

With the Cloudsmith artifact source, values-<env>.yaml already sets the Cloudsmith image prefix and the secrets file sets the pull-secret registry and username. Cloudsmith output sets no per-service image values, so the release chart’s tags and digests and global.imagePullPolicy apply. Install as described in Connected Install.

Fill In the Placeholders

guardctl generates random values for the database password, the Auth Service API and JWT secrets, the governance worker encryption key, and, for Keycloak and Entra, the token exchange private key. For Entra it also turns on token exchange, so every Auth Service replica signs with that key. Fill in the rest before deploying:

1. Secrets. Each value you must supply in secrets-<env>.yaml is marked # REQUIRED and names what goes there:
   • The identity provider’s client IDs and secrets, created by the bootstrap chart or by hand on the identity provider’s page
   • The governance worker’s client ID and secret
   • Storage credentials (omitted on AWS when S3 access uses an IAM role)
   • Key management credentials (omitted on AWS when AWS KMS uses an IAM role). The GCP KMS service account JSON is marked OPTIONAL; leave it empty for Workload Identity
   • The image registry password: your Cloudsmith entitlement token, or a GitHub token with read:packages for GHCR. For GHCR, also fill in the username with your GitHub username
2. Values. Values the charts require are left empty in values-<env>.yaml and marked # REQUIRED: the GCP KMS projectId and locationId, entra.platformAdminEmail, auth0.domain, and global.postgresql.host for an external database. The platform chart does not render until they are set. Also replace each YOUR_* placeholder, such as the bucket or storage account names, the IAM role ARNs for IRSA (on the Governance Service and Integrity Service service accounts for S3, and on the Auth Service one for AWS KMS; one role can serve all three if it trusts each service account and carries both policies), the Auth0 SPA client ID, or the Entra client ID. For Entra, also replace <backend-client-id> in entraScopes. Under auth-service.config.keyManagement, fill any empty vaultUrl or tenantId for Azure Key Vault, and set aws_kms.region for AWS KMS.
3. External database. With --database external, fill in the REQUIRED global.postgresql.host, replace TODO-set-managed-pg-host.example.com in gatewayDsn in the secrets file, set the database password and the one inside gatewayDsn to the instance’s master password, and create the postgres-ca Secret (or a ConfigMap, setting global.postgresql.sslRootCert.configMapName in place of secretName), or set sslMode: require. See External Database for the databases to create.
4. Shared values. gatewayDsn repeats the generated database password, so change both together. With the bundled database, its host guardian-platform-postgresql assumes the release name guardian-platform; change it if you install under another name. For Auth0, the generated apiSecret must equal auth-service-api-secret in the bootstrap’s auth0-management secret (Auth0).
5. Auth0. The bootstrap file sets the post-login Action’s actions.postLogin.authService.url to https://<domain>/authService. The API identifier (auth-service.config.idp.auth0.apiIdentifier, guardian.config.auth0Audience, and the bootstrap file’s auth0.api.identifier) defaults to https://<domain>; if you use another, change all three together.
6. Bootstrap file. Review the domain-derived URLs and, for Auth0 and Keycloak, the platform admin email, which defaults to admin@<domain>. Entra’s admin email is the REQUIRED entra.platformAdminEmail in the values file. Install the bootstrap chart from your deployment repository clone; it is not on Cloudsmith.

guardctl writes secrets-<env>.yaml readable only by your user (mode 0600). Never commit it to version control.

Related

• Chart Values — every setting in the values and secrets files, including those guardctl does not generate
• Deployment Process — where generating configuration fits in the full deployment order
• Connected Install — installing from Cloudsmith or GHCR with the generated files
• Keycloak — running the bootstrap chart and collecting the client secrets it creates
• Auth0 — setting up the Auth0 applications, API, and Actions
• Microsoft Entra ID — creating the Entra app registrations