Phalanx Git repository structure

Phalanx is an open source Git repository hosted at lsst-sqre/phalanx. This page provides an overview of this repository’s structure, for both application developers and environment administrators alike. For background on Phalanx and its technologies, see Overview of the Phalanx platform concepts first.

Key directories

applications directory

Browse /applications/ on GitHub

Every Phalanx application has its own sub-directory within applications named after the application itself (commonly the name is also used as a Kubernetes Namespace). A Phalanx application is itself a Helm chart. Helm charts define Kubernetes templates for the application deployment, values for the templates, and references to any sub-charts from external repositories to include as a sub-chart. See the Helm documentation for details on the structure of Helm charts.

Per-environment Helm values

Phalanx Helm charts in Phalanx include the per-environment configuration, in addition to a common set of defaults. A chart’s defaults are located in its main values.yaml file. The per-environment values files, named values-<environment>.yaml, override those default values for the application’s deployment in the corresponding environments.

Applications based on third-party charts

Note that some applications are based entirely (or primarily) on third-party open source charts. In this case, the application’s Helm chart includes that external chart as a dependency through its Chart.yaml. See the Helm documentation on chart dependencies.

environments directory

Browse /environments/ on GitHub

The environments directory is where environments are defined (an environment is a distinct Kubernetes cluster).

The /environments/templates directory contains a Helm template per application, like this one for the noteburst application:

/environments/templates/noteburst-application.yaml

{{- if .Values.noteburst.enabled -}}
apiVersion: v1
kind: Namespace
metadata:
  name: "noteburst"
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: "noteburst"
  namespace: "argocd"
  finalizers:
    - "resources-finalizer.argocd.argoproj.io"
spec:
  destination:
    namespace: "noteburst"
    server: "https://kubernetes.default.svc"
  project: "default"
  source:
    path: "applications/noteburst"
    repoURL: {{ .Values.repoUrl | quote }}
    targetRevision: {{ .Values.targetRevision | quote }}
    helm:
      parameters:
        - name: "global.host"
          value: {{ .Values.fqdn | quote }}
        - name: "global.baseUrl"
          value: "https://{{ .Values.fqdn }}"
      valueFiles:
        - "values.yaml"
        - "values-{{ .Values.environment }}.yaml"
{{- end -}}

The template defines a Kubernetes Namespace and an Argo CD Application for each Phalanx application. Application resources direct Argo CD to deploy and synchronize the corresponding application Helm chart from the Phalanx applications directory.

Notice that these templates are wrapped in a conditional, which controls whether an application is deployed in a given environment. The values.yaml file in the environments directory defines boolean variables for each application. Then in corresponding values files for each environment, named values-<environment>.yaml, applications are enabled, or not, for the specific environment.

installer directory

Browse /installer/ on GitHub

This directory contains a script named install.sh. The arguments to this are the name of the environment, the FQDN, and the read key for Vault (see Secrets management overview for more details on Vault). This installer script is the entry point for setting up a new environment. It can also be run on an existing environment to update it. See the environment bootstrapping documentation for details.

docs directory

Browse /docs/ on GitHub

This directory contains the Sphinx documentation that you are reading now. See Contributing to the documentation.

starters directory

Browse /docs/ on GitHub

This directory contains templates for contributing new applications to Phalanx. See Add a new application to Phalanx.

Branches

The default branch is main. This default branch is considered the source of truth for fullly synchronized Phalanx environments.

Updates to Phalanx are introduced as pull requests on GitHub. Repository members create branches directly on the lsst-sqre/phalanx origin (see the Data Management workflow guide, while external collaborators should fork Phalanx and provide pull requests.

It is possible (particularly in non-production environments) to deploy from branches of Phalanx, which is useful for debugging new and updating applications before updating the main branch. You can learn how to do this in Deploying from a branch for development.

Test and formatting infrastructure

The Phalanx repository uses two levels of testing and continuous integration.

Pre-commit performs file formatting and linting, both on your local editing environment (when configured) and verified in GitHub Actions. In one check, Pre-commit regenerates Helm chart documentation for applications with helm-docs. See the .pre-commit-config.yaml file for configuration details. Learn how to set up Pre-commit in your local editing environment in Setting up pre-commit linting and helm-docs generation.

Second, GitHub Actions runs a CI workflow (.github/workflows/ci.yaml). This workflow has three key jobs:

• Linting with Pre-commit, mirroring the local editing environment.

• Static validation of Helm charts with the helm/chart-testing-action GitHub action.

• An integration test of a Phalanx environment in a minikube.

Next steps

Start working with Phalanx:

• If you are a developer looking to integrate your application into Phalanx, see the Developers section to get started.

• If you are an administrator looking to create a new environment or operate an existing one, see the Administrators section.