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.

-s, --starter <starter>#

Helm starter to use as the basis for the chart.

Options:

empty | web-service

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]...

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.

The environment variable VAULT_TOKEN must be set to a token with read access to the Vault data for the given environment.

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.

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.

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