Phalanx internal API

These pages document the Phalanx internal API, which may be of interest when extending the Phalanx command-line tool or documentation build infrastructure.

Phalanx does not provide a library or Python module for external use. This API is only intended for use within the Phalanx code itself.

phalanx Package

Support tooling for Phalanx, SQuaRE’s application development platform.

Variables

__version__

The version string, although phalanx isn't technically released like a typical Python package.

phalanx.constants Module

Constants for the Phalanx support code.

Things that arguably could be configurable but haven’t yet been made into actual configuration options.

Variables

HELM_DOCLINK_ANNOTATION	Annotation in Chart.yaml for application documentation links.
ONEPASSWORD_ENCODED_WARNING	Warning to add to secrets that must be encoded in 1Password.
PULL_SECRET_DESCRIPTION	Description to put in the static secrets YAML file for pull-secret.
VAULT_APPROLE_SECRET_TEMPLATE	Template for a Secret containing AppRole credentials.
VAULT_TOKEN_SECRET_TEMPLATE	Template for a Secret containing token credentials.
VAULT_WRITE_TOKEN_LIFETIME	Default lifetime to set for Vault write tokens.
VAULT_WRITE_TOKEN_WARNING_LIFETIME	Remaining lifetime at which to warn that a token is about to expire.

phalanx.docs.crossref Module

Cross-referencing roles and directives for Phalanx topics.

Functions

setup(app)

Set up the Phalan cross-referencing extensions.

phalanx.docs.jinja Module

Helper functions for Sphinx Jinja templating.

Functions

build_jinja_contexts()

Construct the Jinja contexts used for building Phalanx documentation.

phalanx.exceptions Module

Exceptions for the Phalanx command-line tool.

Classes

ApplicationExistsError(name)	Application being created already exists.
CommandFailedError(command, args, exc)	Execution of a command failed.
CommandTimedOutError(command, args, exc)	Execution of a command failed.
GitRemoteError	Unable to get necessary information from a Git remote.
InvalidApplicationConfigError(name, error, *)	Configuration for an application is invalid.
InvalidEnvironmentConfigError(name, error)	Configuration for an environment is invalid.
InvalidSecretConfigError(application, key, error)	Secret configuration is invalid.
MalformedOnepasswordSecretError(application, ...)	A secret stored in 1Password was malformed.
MissingOnepasswordSecretsError(secrets)	Secrets are missing from 1Password.
NoOnepasswordConfigError	Environment does not use 1Password.
NoOnepasswordCredentialsError()	1Password is configured, but no credentials were supplied.
NoVaultCredentialsError()	Vault credentials are required and were not supplied.
UnknownEnvironmentError(name)	No configuration found for an environment name.
UnresolvedSecretsError(secrets)	Some secrets could not be resolved.
UsageError	An error that should be printed to standard error without a backtrace.
VaultNotFoundError(url, path[, key])	Secret could not be found in Vault.
VaultPathConflictError(path)	Attempt to copy a Vault tree onto itself.

Class Inheritance Diagram

phalanx.factory Module

Factory for Phalanx support code components.

Classes

Factory(path)

Factory to create Phalanx components.

Class Inheritance Diagram

phalanx.github Module

Utility functions used when running under GitHub Actions.

The utility functions in this module can all be called unconditionally. They will detect whether the Phalanx command-line tool is being run under GitHub Actions and, if so, add additional GitHub-specific markers to the output to improve display in GitHub Actions logs.

See GitHub’s documentation for other possibly useful commands that could be added.

Functions

action_group(title)	Wrap a sequence of commands in a GitHub Actions group.
add_mask(secret)	Mask a secret in future GitHub Actions output.

phalanx.models.applications Module

Pydantic models for Phalanx applications.

Classes

Application	A Phalanx application that knows which environments use it.
ApplicationConfig	Configuration for a Phalanx application.
ApplicationInstance	A Phalanx application as configured for a specific environment.
DocLink	A documentation link for an application.
Project(value[, names, module, qualname, ...])	Valid choices for the Argo CD project of an application.

Class Inheritance Diagram

phalanx.models.environments Module

Pydantic models for Phalanx environments.

Classes

ControlSystemConfig	Configuration for the Control System.
Environment	A Phalanx environment and its associated settings.
EnvironmentBaseConfig	Environment configuration options.
EnvironmentConfig	Configuration for a Phalanx environment.
EnvironmentDetails	Full details about an environment, including auth and Argo CD.
GCPMetadata	Google Cloud Platform hosting metadata.
GafaelfawrGitHubGroup	A group based on a GitHub team.
GafaelfawrGitHubTeam	Designates a GitHub team for use as a Gafaelfawr group.
GafaelfawrScope	A Gafaelfawr scope and its associated groups.
IdentityProvider(value[, names, module, ...])	Type of identity provider used by Gafaelfawr.
OnepasswordConfig	Configuration for 1Password static secrets source.
PhalanxConfig	Root container for the entire Phalanx configuration.

Class Inheritance Diagram

phalanx.models.gafaelfawr Module

Models for Gafaelfawr data structures.

Ideally, these should use the same models Gafaelfawr itself uses. Until that’s possible via a PyPI library, these models are largely copied from Gafaelfawr.

Classes

Token

An opaque token.

Class Inheritance Diagram

phalanx.models.helm Module

Models for Helm commands.

Classes

HelmStarter(value[, names, module, ...])

A Helm chart starter.

Class Inheritance Diagram

phalanx.models.secrets Module

Pydantic models for Phalanx application secrets.

Classes

ConditionalMixin	Mix-in class for elements that may have a condition.
ConditionalSecretConfig	Possibly conditional specification for an application secret.
ConditionalSecretCopyRules	Possibly conditional rules for copying a secret value from another.
ConditionalSimpleSecretGenerateRules	Conditional rules for generating a secret value with no source.
ConditionalSourceSecretGenerateRules	Conditional rules for generating a secret from another secret.
PullSecret	Specification for a Docker pull secret.
RegistryPullSecret	Pull secret for a specific Docker Repository.
ResolvedSecrets	All resolved secrets for a given Phalanx environment.
Secret	Specification for an application secret for a specific environment.
SecretConfig	Specification for an application secret.
SecretCopyRules	Rules for copying a secret value from another secret.
SecretGenerateType(value[, names, module, ...])	Type of secret for generated secrets.
SecretOnepasswordConfig	Configuration for how a static secret is stored in 1Password.
SimpleSecretGenerateRules	Rules for generating a secret value with no source information.
SourceSecretGenerateRules	Rules for generating a secret from another secret.
StaticSecret	Value of a static secret provided in a YAML file.
StaticSecrets	Model for the YAML file containing static secrets.

Variables

ConditionalSecretGenerateRules	Represent a PEP 604 union type
SecretGenerateRules	Represent a PEP 604 union type

Class Inheritance Diagram

phalanx.models.vault Module

Models representing Vault objects.

Classes

VaultAppRole	Newly-created Vault AppRole for secret access.
VaultAppRoleCredentials	Credentials for Vault access using an AppRole.
VaultAppRoleMetadata	Metadata about a new or existing Vault AppRole.
VaultCredentials	Credentials used for Vault access.
VaultToken	Newly-created Vault token for secret access.
VaultTokenCredentials	Credentials for Vault access using a token.
VaultTokenMetadata	Metadata about a new or existing Vault token.

Class Inheritance Diagram

phalanx.services.application Module

Service for manipulating Phalanx applications.

Classes

ApplicationService(path, config_storage, ...)

Service for manipulating Phalanx applications.

Class Inheritance Diagram

phalanx.services.environment Module

Service for manipulating Phalanx environments.

Classes

EnvironmentService(*, config_storage, ...)

Service for manipulating Phalanx environments.

Class Inheritance Diagram

phalanx.services.secrets Module

Service to manipulate Phalanx secrets.

Classes

SecretsAuditReport([missing, mismatch, unknown])	Results of auditing secrets against the contents of Vault.
SecretsService(config_storage, ...)	Service to manipulate Phalanx secrets.

Class Inheritance Diagram

phalanx.services.vault Module

Service to manage Vault authentication.

Classes

VaultService(config_storage, vault_storage)

Service to manage Vault authentication.

Class Inheritance Diagram

phalanx.storage.argocd Module

Interface to Argo CD operations.

Classes

ArgoCDStorage()

Interface to Argo CD operations.

Class Inheritance Diagram

phalanx.storage.command Module

Wrapper around executing external commands.

Classes

Command(command)

Wrapper around executing external commands.

Class Inheritance Diagram

phalanx.storage.config Module

Parsing and analysis of Phalanx configuration.

Classes

ConfigStorage(path)

Analyze Phalanx configuration and convert it to models.

Class Inheritance Diagram

phalanx.storage.helm Module

Interface to Helm operations.

Classes

HelmStorage(config_storage)

Interface to Helm operations.

Class Inheritance Diagram

phalanx.storage.kubernetes Module

Storage layer for direct Kubernetes operations.

Classes

KubernetesStorage()

Storage layer for direct Kubernetes operations.

Class Inheritance Diagram

phalanx.storage.onepassword Module

Retrieve secrets stored in 1Password via 1Password Connect.

Classes

OnepasswordClient(url, vault_title)	Retrieve secrets stored in 1Password via 1Password Connect.
OnepasswordStorage()	Create 1Password Connect clients for specific environments.

Class Inheritance Diagram

phalanx.storage.vault Module

Store, retrieve, and manipulate data stored in Vault.

Classes

VaultClient(url, path[, credentials])	Store, retrieve, and manipulate data stored in Vault.
VaultStorage()	Create Vault clients for specific environments.

Class Inheritance Diagram

phalanx.yaml Module

Utility functions for manipulating YAML.

In several places in the Phalanx code, we want to be able to wrap long strings to make them more readable or be able to dump collections.defaultdict objects without adding special object tagging. This module collects utility functions to make this easier.

Classes

YAMLFoldedString

A string that will be folded when encoded in YAML.

Class Inheritance Diagram