Add a new application to Phalanx

This page provides the steps for integrating an application with Phalanx by adding the application’s Helm chart. This is the last step of adding a new application to Phalanx and should be done after you have written the Helm chart and defined the secrets it needs.

For background on building an application, see the Build documentation.

Add documentation

Every new application added to Phalanx must have a corresponding folder in the docs/applications directory containing at least an index.rst file and a values.md file. The values.md file is boilerplate to incorporate the documentation of the values.yaml file for the new application.

For the page title in index.rst, always use the format application — description. The _description_ portion will generally be the same as the short description in the Chart.yaml file of the corresponding Helm chart. Keep it very succinct, ideally just a few words.

The new application must then be added to docs/applications/index.rst in the appropriate section.

For a simple example that you can copy if desired, see the docs for the HIPS service.

Configure other Phalanx applications

If the application needs to listen on hostnames other than the normal cluster-wide hostname, you will need to configure cert-manager so that it can generate a TLS certificate for that hostname. See Add TLS certificates for a new hostname for more details.

If your application exposes Prometheus endpoints, you will want to configure these in the telegraf application’s prometheus_config.

Add an Argo CD Application for your application

Finally, you need to tell Argo CD to deploy your application in some environments. This is done by creating a Kubernetes Application resource that tells Argo CD how to manage your application.

1. For each environment in which your application will run, create a values-environment.yaml file in your application’s directory. This should hold only the customization specific to that Rubin Science Platform environment. Any shared configuration should go into the defaults of your chart (values.yaml).

   If it is a third-party application repackaged as a Phalanx chart, you will need to add its configuration a little differently. See Configure the external chart for more discussion.)

2. Create the Argo CD application resource. This is a new file in environments/templates named name-application.yaml where _name_ must match the name of the application (and thus the name of the directory containing its Helm chart under applications).

   The contents of this file should look like:

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

   Replace every instance of <name> with the name of your application. This creates the namespace and Argo CD application for your application. Note that this is where we tell Argo CD to inject the global.host, global.baseUrl, and global.vaultSecretsPath settings.

   The template values here come from the environments/values-environment.yaml configuration file for each environment. You should not need to change those values when adding a new application.

3. Edit environments/values.yaml and add your new application to the applications key with an appropriate comment, similar to the other applications already listed. Please maintain the alphabetical order of the applications. Except in very unusual circumstances, the application should default to false (not installed).

4. Finally, enable your application in one of the values-enviornment.yaml files in environments. Do this by adding a key for your application under applications (in alphabetical order) with a value of true. This environment will be the first place your application is deployed.

   You almost certainly want to start in a development or integration environment and enable your new application in production environments only after it has been smoke-tested in less critical environments.