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_SECRET_TEMPLATE

Template for a Secret containing AppRole 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.

HelmFailedError(command, args, exc)

A Helm command failed.

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.

UnknownEnvironmentError(name)

No configuration found for an environment name.

UnresolvedSecretsError(secrets)

Some secrets could not be resolved.

VaultNotFoundError(url, path)

Secret could not be found in Vault.

Class Inheritance Diagram#

Inheritance diagram of phalanx.exceptions.ApplicationExistsError, phalanx.exceptions.HelmFailedError, phalanx.exceptions.InvalidApplicationConfigError, phalanx.exceptions.InvalidEnvironmentConfigError, phalanx.exceptions.InvalidSecretConfigError, phalanx.exceptions.MalformedOnepasswordSecretError, phalanx.exceptions.MissingOnepasswordSecretsError, phalanx.exceptions.NoOnepasswordConfigError, phalanx.exceptions.NoOnepasswordCredentialsError, phalanx.exceptions.UnknownEnvironmentError, phalanx.exceptions.UnresolvedSecretsError, phalanx.exceptions.VaultNotFoundError

phalanx.factory Module#

Factory for Phalanx support code components.

Classes#

Factory(path)

Factory to create Phalanx components.

Class Inheritance Diagram#

Inheritance diagram of phalanx.factory.Factory

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.

Class Inheritance Diagram#

Inheritance diagram of phalanx.models.applications.Application, phalanx.models.applications.ApplicationConfig, phalanx.models.applications.ApplicationInstance, phalanx.models.applications.DocLink

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

Configuration common to EnvironmentConfig and Environment.

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#

Inheritance diagram of phalanx.models.environments.ControlSystemConfig, phalanx.models.environments.Environment, phalanx.models.environments.EnvironmentBaseConfig, phalanx.models.environments.EnvironmentConfig, phalanx.models.environments.EnvironmentDetails, phalanx.models.environments.GCPMetadata, phalanx.models.environments.GafaelfawrGitHubGroup, phalanx.models.environments.GafaelfawrGitHubTeam, phalanx.models.environments.GafaelfawrScope, phalanx.models.environments.IdentityProvider, phalanx.models.environments.OnepasswordConfig, phalanx.models.environments.PhalanxConfig

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#

Inheritance diagram of phalanx.models.gafaelfawr.Token

phalanx.models.helm Module#

Models for Helm commands.

Classes#

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

A Helm chart starter.

Class Inheritance Diagram#

Inheritance diagram of phalanx.models.helm.HelmStarter

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#

Inheritance diagram of phalanx.models.secrets.ConditionalMixin, phalanx.models.secrets.ConditionalSecretConfig, phalanx.models.secrets.ConditionalSecretCopyRules, phalanx.models.secrets.ConditionalSimpleSecretGenerateRules, phalanx.models.secrets.ConditionalSourceSecretGenerateRules, phalanx.models.secrets.PullSecret, phalanx.models.secrets.RegistryPullSecret, phalanx.models.secrets.ResolvedSecrets, phalanx.models.secrets.Secret, phalanx.models.secrets.SecretConfig, phalanx.models.secrets.SecretCopyRules, phalanx.models.secrets.SecretGenerateType, phalanx.models.secrets.SecretOnepasswordConfig, phalanx.models.secrets.SimpleSecretGenerateRules, phalanx.models.secrets.SourceSecretGenerateRules, phalanx.models.secrets.StaticSecret, phalanx.models.secrets.StaticSecrets

phalanx.models.vault Module#

Models representing Vault objects.

Classes#

VaultAppRole

Newly-created Vault AppRole for secret access.

VaultAppRoleMetadata

Metadata about a new or existing Vault AppRole.

VaultToken

Newly-created Vault token for secret access.

VaultTokenMetadata

Metadata about a new or existing Vault token.

Class Inheritance Diagram#

Inheritance diagram of phalanx.models.vault.VaultAppRole, phalanx.models.vault.VaultAppRoleMetadata, phalanx.models.vault.VaultToken, phalanx.models.vault.VaultTokenMetadata

phalanx.services.application Module#

Service for manipulating Phalanx applications.

Classes#

ApplicationService(path, config_storage, ...)

Service for manipulating Phalanx applications.

Class Inheritance Diagram#

Inheritance diagram of phalanx.services.application.ApplicationService

phalanx.services.environment Module#

Service for manipulating Phalanx environments.

Classes#

EnvironmentService(config_storage, helm_storage)

Service for manipulating Phalanx environments.

Class Inheritance Diagram#

Inheritance diagram of phalanx.services.environment.EnvironmentService

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#

Inheritance diagram of phalanx.services.secrets.SecretsAuditReport, phalanx.services.secrets.SecretsService

phalanx.services.vault Module#

Service to manage Vault authentication.

Classes#

VaultService(config_storage, vault_storage)

Service to manage Vault authentication.

Class Inheritance Diagram#

Inheritance diagram of phalanx.services.vault.VaultService

phalanx.storage.config Module#

Parsing and analysis of Phalanx configuration.

Classes#

ConfigStorage(path)

Analyze Phalanx configuration and convert it to models.

Class Inheritance Diagram#

Inheritance diagram of phalanx.storage.config.ConfigStorage

phalanx.storage.helm Module#

Interface to Helm operations.

Classes#

HelmStorage(config_storage)

Interface to Helm operations.

Class Inheritance Diagram#

Inheritance diagram of phalanx.storage.helm.HelmStorage

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#

Inheritance diagram of phalanx.storage.onepassword.OnepasswordClient, phalanx.storage.onepassword.OnepasswordStorage

phalanx.storage.vault Module#

Store, retrieve, and manipulate data stored in Vault.

Classes#

VaultClient(url, path)

Store, retrieve, and manipulate data stored in Vault.

VaultStorage()

Create Vault clients for specific environments.

Class Inheritance Diagram#

Inheritance diagram of phalanx.storage.vault.VaultClient, phalanx.storage.vault.VaultStorage

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#

Inheritance diagram of phalanx.yaml.YAMLFoldedString