Command-line interface¶
Many administrative actions for Phalanx environments are being moved into a Phalanx command-line tool. The commands for the phalanx CLI are documented here.
You can get detailed help for any phalanx command by running phalanx help followed by the command (either one or two words).
phalanx¶
Administrative command-line interface for Phalanx.
phalanx [OPTIONS] COMMAND [ARGS]...
Options
- --version¶
Show the version and exit.
application¶
Commands for Phalanx application configuration.
phalanx application [OPTIONS] COMMAND [ARGS]...
add-helm-repos¶
Configure dependency Helm repositories in Helm.
Add all third-party Helm chart repositories used by Phalanx applications to the local Helm cache.
This will also be done as necessary by lint commands, so using this command is not necessary. It is provided as a convenience for helping to manage your local Helm configuration.
phalanx application add-helm-repos [OPTIONS] [NAME]
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- NAME¶
Optional argument
create¶
Create a new application from a starter template.
This command creates the framework for a new Phalanx application from the named template (which must be one of the starter charts) and adds the appropriate documentation stubs, Argo CD Application resource, and environment configuration.
phalanx application create [OPTIONS] NAME
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- -d, --description <description>¶
Short description of the new application. Must start with capital letter and, with the application name, be less than 80 characters.
- -p, --project <project>¶
Argo CD project for the application.
- Options:
infrastructure | rsp | rubin | roundtable | monitoring | support | prompt | telescope
- -s, --starter <starter>¶
Helm starter to use as the basis for the chart.
- Options:
empty | web-service | fastapi-safir | fastapi-safir-uws
Arguments
- NAME¶
Required argument
lint¶
Lint the Helm charts for applications.
Update and download any third-party dependency charts and then lint the Helm chart for the given applications. If no environment is specified, each chart is linted for all environments for which it has a configuration.
phalanx application lint [OPTIONS] APPLICATION ...
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- -e, --environment, --env <ENV>¶
Only lint this environment.
Arguments
- APPLICATION ...¶
Optional argument(s)
lint-all¶
Lint the Helm charts for every application and environment.
Update and download any third-party dependency charts and then lint the Helm charts for each application and environment combination.
phalanx application lint-all [OPTIONS]
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- --git¶
Only lint applications changed relative to a Git branch.
- --git-branch <BRANCH>¶
Base Git branch against which to compare.
- Default:
'origin/main'
Environment variables
- GITHUB_BASE_REF
Provide a default for
--git-branch
template¶
Expand the chart of an application for an environment.
Print the expanded Kubernetes resources for an application as configured for the given environment to standard output. This is intended for testing and debugging purposes; normally, charts should be installed with Argo CD.
phalanx application template [OPTIONS] NAME ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- NAME¶
Required argument
- ENVIRONMENT¶
Required argument
environment¶
Commands for Phalanx environment configuration.
phalanx environment [OPTIONS] COMMAND [ARGS]...
install¶
Install Phalanx into an environment.
Bootstrap Phalanx for an environment. Assumes that the currently enabled Kubernetes configuration is the cluster into which to install Phalanx.
The secrets tree for the environment must already be present in Vault. Read-only Vault credentials must be supplied by either setting the environment variables VAULT_ROLE_ID and VAULT_SECRET_ID to the credentials of a Vault AppRole, or setting VAULT_TOKEN to a read-only Vault token.
phalanx environment install [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- --git-branch <git_branch>¶
Override Git branch for Argo CD.
- --force-noninteractive¶
Force installation without a prompt.
- --vault-role-id <vault_role_id>¶
Role ID for vault-secrets-operator.
- --vault-secret-id <vault_secret_id>¶
Secret ID for vault-secrets-operator.
- --vault-token <vault_token>¶
Read-only token for vault-secrets-operator.
Arguments
- ENVIRONMENT¶
Required argument
Environment variables
- GITHUB_HEAD_REF
Provide a default for
--git-branch
- VAULT_ROLE_ID
Provide a default for
--vault-role-id
- VAULT_SECRET_ID
Provide a default for
--vault-secret-id
- VAULT_TOKEN
Provide a default for
--vault-token
lint¶
Lint the top-level Helm chart for an environment.
Lint the parent Argo CD Helm chart that installs the Argo CD applications for an environment. If the environment is not given, lints the instantiation of that chart for each environment.
phalanx environment lint [OPTIONS] [ENVIRONMENT]
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Optional argument
schema¶
Generate schema for environment configuration.
The output is a JSON schema for the values-<environment>.yaml file for a
Phalanx environment. If the --output flag is not given, the schema is
printed to standard output.
Users normally don’t need to run this command. It is used to update the schema file in the Phalanx repository, which is used by a pre-commit hook to validate environment configuration files before committing them.
phalanx environment schema [OPTIONS]
Options
- -o, --output <output>¶
Path to which to write schema.
template¶
Expand the top-level chart for an environment.
Print the expanded Kubernetes resources for the top-level chart configured for the given environment. This is intended for testing and debugging purposes; normally, charts should be installed with Argo CD.
phalanx environment template [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Required argument
help¶
Show help for any command.
phalanx help [OPTIONS] [TOPIC] [SUBTOPIC]
Arguments
- TOPIC¶
Optional argument
- SUBTOPIC¶
Optional argument
secrets¶
Secret manipulation commands.
phalanx secrets [OPTIONS] COMMAND [ARGS]...
audit¶
Audit secrets for an environment.
The secrets stored in Vault for the given environment will be compared to the secrets required for all applications enabled for that environment, and any discrepencies will be noted. The audit report will be printed to standard output and will be empty if no issues were found.
A Vault token with read access to the Vault data for the given environment must be available in the static secrets or present in the VAULT_TOKEN environment variable.
The Vault server does not clearly distinguish between unknown paths and permission denied errors, so if the Vault token doesn’t have write access or if the path doesn’t exist, all secrets will be reported as missing.
phalanx secrets audit [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- --secrets <secrets>¶
YAML file containing static secrets for this environment.
Arguments
- ENVIRONMENT¶
Required argument
list¶
List all secrets required for a given environment.
phalanx secrets list [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Required argument
onepassword-secrets¶
Write the 1Password secrets for the given environment.
The resulting YAML file will be in the same format as that generated by
static-template (without the secret descriptions) and is suitable as
the value of the --secrets flag to other commands. If the --output
flag is not given, the YAML will be written to standard output.
The environment variable OP_CONNECT_TOKEN must be set to the 1Password Connect token for the given environment.
phalanx secrets onepassword-secrets [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- -o, --output <output>¶
Path to which to write 1Password secrets.
Arguments
- ENVIRONMENT¶
Required argument
schema¶
Generate schema for application secret definition.
The output is a JSON schema for the secrets.yaml file for an application,
which specifies the secrets required for that application. If the
--output flag is not given, the schema is printed to standard output.
Users normally don’t need to run this command. It is used to update the schema file in the Phalanx repository, which is used by a pre-commit hook to validate secrets.yaml files before committing them.
phalanx secrets schema [OPTIONS]
Options
- -o, --output <output>¶
Path to which to write schema.
static-template¶
Generate a template for static secrets.
Static secrets may be provided to other commands that need to know them
(most notably phalanx secrets sync) via the --secrets flag, which
points to a YAML file containing the static secrets for an environment.
This command generates a template for that YAML file. It will contain the
descriptions for each secret and a place for the value of that secret to
be filled in.
The template is public information, but (somewhat obviously) once secret values have been added to it, this file must be kept secure and private to Phalanx administrators for that environment.
phalanx secrets static-template [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Required argument
sync¶
Synchronize environment secrets with Vault.
The secrets required for all enabled applications for the given environment are compared with the secrets stored for that environment in Vault, any missing or incorrect secrets are updated, and optionally any extraneous secrets may be deleted.
The environment variable VAULT_TOKEN must be set to a token with read and
write access to the secrets for this environment (and optionally delete
access). If Vault credentials are managed through this tool, such a token
can be created with the phalanx vault create-write-token command.
Alternatively, the environment variable OP_CONNECT_TOKEN may set to a
1Password Connect token for that environment if the Vault write token is
stored in the 1Password vault.
phalanx secrets sync [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- --delete¶
Delete any unexpected secrets in Vault.
- --regenerate¶
Regenerate (change) all generated secrets.
- --secrets <secrets>¶
YAML file containing static secrets for this environment.
Arguments
- ENVIRONMENT¶
Required argument
vault¶
Vault management commands.
phalanx vault [OPTIONS] COMMAND [ARGS]...
audit¶
Audit Vault credentials for an environment.
The audit report will be printed to standard output and will be empty if no issues were found.
The environment variable VAULT_TOKEN must be set to a token with access to read policies, AppRoles, tokens, and token accessors.
phalanx vault audit [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Required argument
copy-secrets¶
Copy secrets from another Vault path prefix.
Copy secrets for an environment from another Vault path prefix in the same Vault server, overwriting any secrets that already exist with the same name. This command is intended primarily for changing the Vault path prefix for an environment without regenerating its secrets.
The environment variable VAULT_TOKEN must be set to a token with read access to the old path and write access to the currently configured Vault path for the given environment.
phalanx vault copy-secrets [OPTIONS] ENVIRONMENT OLD_PREFIX
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Required argument
- OLD_PREFIX¶
Required argument
create-read-approle¶
Create a new Vault read AppRole.
The created AppRole will have read access to all of the Vault secrets for the given environment. It is intended for use by vault-secrets-operator to maintain Kubernetes secrets from the Phalanx Vault secrets.
The environment variable VAULT_TOKEN must be set to a token with access to create policies and AppRoles, list AppRole SecretID accessors, and revoke AppRole SecretIDs.
phalanx vault create-read-approle [OPTIONS] ENVIRONMENT
Options
- --as-secret <as_secret>¶
Output the credentials as a Kubernetes Secret for vault-secrets-operator, with the provided name, suitable for passing to kubectl apply.
- -c, --config <config>¶
Path to root of Phalanx configuration.
- --token-lifetime <token_lifetime>¶
Maximum token lifetime in seconds.
Arguments
- ENVIRONMENT¶
Required argument
create-write-token¶
Create a new Vault write token.
The created token will have read, write, delete, and destroy access to all of the Vault secrets for the given environment. It is intended for interactive use with this tool synchronize environment secrets to Vault.
The environment variable VAULT_TOKEN must be set to a token with access to list token accessors, create policies, and create and revoke tokens.
phalanx vault create-write-token [OPTIONS] ENVIRONMENT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
- --lifetime <lifetime>¶
Token lifetime in Vault duration format.
Arguments
- ENVIRONMENT¶
Required argument
export-secrets¶
Write the Vault secrets for the given environment.
One JSON file per application with secrets will be created in the output directory, containing the secrets for that application. If the value of a secret is not known, it will be written as null.
The environment variable VAULT_TOKEN must be set to a token with read access to the Vault data for the given environment.
phalanx vault export-secrets [OPTIONS] ENVIRONMENT OUTPUT
Options
- -c, --config <config>¶
Path to root of Phalanx configuration.
Arguments
- ENVIRONMENT¶
Required argument
- OUTPUT¶
Required argument