Adding an external Helm chart

Sometimes, rather than deploying a new service we wrote ourselves (see Create a new service), we want to deploy an existing external service in the Rubin Science Platform with some customizations.

If the service has an existing published Helm chart (and most major open source services do, albeit sometimes not from the upstream service maintainers), we should use that Helm chart. Below are details on how to do that.

This guide is somewhat general since every external service will be different in new and exciting ways. Expect to spend a lot of time reading the upstream Helm chart documentation and iterating on configuration approaches when adding an external Helm chart.

Potential problems

No existing Helm chart

If the service does not have an existing published Helm chart, you should consider that a red flag that prompts you to reconsider whether this service is the right choice for the Rubin Science Platform. To deploy it, you will need to write and maintain a Helm chart and keep it up-to-date for new releases of the service. This can be a substantial amount of work. For large and complex services, it can even be a full-time job.

We cannot accept services in the Rubin Science Platform that are not kept up-to-date. It is a hard requirement that every service keep up with new upstream development and releases so that we get continued security support. You must be able to commit to doing this for the lifetime of the project before adding an external service to the Rubin Science Platform.

If the benefit to the Rubin Science Platform seems worth the ongoing effort to write and maintain a Helm chart, try to contribute that Helm chart to the upstream maintainers so that we can share the burden of maintaining it with other projects that use Kubernetes.

No published Helm chart

If the service has an existing, maintained Helm chart, but it’s not published in a Helm repository, this is also a red flag, albeit a lesser one. This normally means the people maintaining the Helm chart don’t entirely understand Helm or the conventions of the Kubernetes ecosystem. In exceptional circumstances we can import such an external Helm chart into the charts repository, but we would prefer not to do this since keeping it up-to-date with upstream changes is very awkward.

Configure the external chart

Configuration mostly involves carefully reading the documentation of the upstream Helm chart and building a values.yaml file that configures it appropriately. You may also need to add additional resources not created by the upstream Helm chart, particularly VaultSecret objects to create any secrets that it needs. (See Add a secret with 1Password and VaultSecret for more about secrets.)

If the required configuration for the chart is simple enough, you can reference the chart directly from Phalanx and put its configuration in the per-environment Phalanx values-*.yaml files. In this case, you can skip ahead to Add a new service to Phalanx, although still read the information below on what settings you may need to configure.

If configuring the chart is sufficiently complex, if you want to provide additional Kubernetes resources that are not part of the upstream chart, or if there is substantial configuration that should be shared between all Rubin Science Platform environments, you may want to create a wrapper chart. This is a chart that lives in the charts repository and includes the upstream chart as a subchart. The advantage of this approach is that you can provide a default values.yaml file that does all the shared configuration, and you can easily add new Kubernetes resources to the deployed namespace by putting them in the templates directory of the wrapper chart. The drawback is the additional complexity of adding yet another layer of chart and values.yaml files. Once the Phalanx configuration has also been added, there will be three layers of charts to reason about.

Tell Argo CD about the upstream Helm repository

Argo CD has to know about every Helm repository that contributes charts to the Rubin Science Platform. If upstream runs their own Helm chart repository, you will therefore need to add it to the Argo CD configuration.

In the Phalanx repository, check the argo-cd.config.helm.repositories configuration option in any values file to see if the repository used by the upstream chart is already listed. If it is not, you will need to add a stanza like:

- url: https://kubernetes.github.io/ingress-nginx/
  name: ingress-nginx

to that configuration key for the values-*.yaml file for every environment in Phalanx that will deploy this service. (The example above is for the ingress-nginx chart; the URL and name will obviously vary.) Do that as a pull request, probably as part of your pull request to add your Argo CD application (see Add a new service to Phalanx).