--- title: "guardctl" description: "Generate values.yaml, secrets.yaml, and the identity provider bootstrap file for a deployment with guardctl." source: "Guardian Platform" --- `guardctl` is a command-line tool in the [deployment repository](https://github.com/eqtylab/deployment/tree/main/guardctl) 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](./chart-values.mdx). ## 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](./prerequisites.mdx#deployment-repository) clone, install from the `guardctl/` directory with uv (recommended) or pip: ```bash 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: ```bash guardctl --help ``` ## Generate the Files Run the interactive wizard: ```bash 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](./aws-kms.mdx#iam-roles-for-service-accounts) 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: ```bash 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://` 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](#fill-in-the-placeholders). ### Options | Flag | Short | Description | | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--cloud` | `-c` | Cloud provider: `aws`, `azure`, or `gcp` | | `--domain` | `-d` | Platform domain, validated as a DNS name | | `--environment` | `-e` | Environment name, lowercased and validated as a DNS label | | `--auth` | `-a` | Identity provider: `auth0`, `entra`, or `keycloak` | | `--database` | `-D` | `bundled` or `external`. Defaults to `external` when the environment is `production`, otherwise `bundled` | | `--artifact-source` | | `cloudsmith` (default) for a stable release delivered to Cloudsmith; `github` for GHCR, for a version not yet delivered to Cloudsmith; it pins every image to `latest`, so remove those `image.tag` lines | | `--output` | `-o` | Output directory, created if missing (default `output`) | | `--interactive/--no-interactive` | `-i/-I` | Run the wizard (default) or skip it | | `--force` | `-f` | Overwrite existing generated files without asking | ### 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: | File | Contents | Where it is used | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `values-.yaml` | Helm values for every platform service, set for your cloud, storage, key management, and identity provider | The `values.yaml` described in [Chart Values](./chart-values.mdx), passed to the platform install | | `secrets-.yaml` | Secrets for your configuration only, with `global.secrets.create: true` so Helm creates them | The `secrets.yaml` described in [Chart Values](./chart-values.mdx#secrets-file-secretsyaml), passed to the platform install | | `bootstrap-.yaml` | Values for the `auth0-bootstrap`, `entra-bootstrap`, or `keycloak-bootstrap` chart, with your domain filled in | The identity provider bootstrap: [Auth0](./auth0.mdx#3-prepare-the-bootstrap-values), [Microsoft Entra ID](./microsoft-entra-id.mdx#3-prepare-the-bootstrap-values), or [Keycloak](./keycloak.mdx#3-prepare-the-bootstrap-values) in place of `bootstrap-values.yaml` | With the Cloudsmith artifact source, `values-.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](./connected-install.mdx). ## 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-.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-.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 `` 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](./external-database.mdx) 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](./auth0.mdx#2-create-pre-bootstrap-secrets)). 5. **Auth0.** The bootstrap file sets the post-login Action's `actions.postLogin.authService.url` to `https:///authService`. The API identifier (`auth-service.config.idp.auth0.apiIdentifier`, `guardian.config.auth0Audience`, and the bootstrap file's `auth0.api.identifier`) defaults to `https://`; 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@`. 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-.yaml` readable only by your user (mode `0600`). Never commit it to version control. ## Related - [Chart Values](./chart-values.mdx) — every setting in the values and secrets files, including those `guardctl` does not generate - [Deployment Process](./deployment-process.mdx) — where generating configuration fits in the full deployment order - [Connected Install](./connected-install.mdx) — installing from Cloudsmith or GHCR with the generated files - [Keycloak](./keycloak.mdx) — running the bootstrap chart and collecting the client secrets it creates - [Auth0](./auth0.mdx) — setting up the Auth0 applications, API, and Actions - [Microsoft Entra ID](./microsoft-entra-id.mdx) — creating the Entra app registrations