Add an Application

The two main functionalities that make Plural work are dependency tracking between DevOps tools (Helm and Terraform) and templating.

When a user sets up a new Plural workspace in a git repository a workspace.yaml file is created that stores global values for that cluster such as the cloud account and region, the cluster and VPC name and what subdomain all the applications will be hosted under. Next, the user can install an application using the plural bundle <app_name> <bundle> CLI command. The CLI will then prompt the user for for inputs needed to setup that application, along with any dependencies of the application. These inputs are saved in the context.yaml file.

Next, the user runs plural build which will create a wrapper Helm chart and Terraform module. The wrapper Helm chart and Terraform module depend on the application Helm chart(s) and Terraform module(s) it gets from the Plural API, which the CLI downloads. The CLI will then generate the values.yaml for the wrapper helm chart and main.tf for the wrapper Terraform module using the values saved in the context.yaml using its templating engine.

Plural application artifacts

As mentioned above, the Plural CLI creates a wrapper Helm chart and Terraform module for each installed application and inputs the user defined values for that installation. Some extra files are necessary in Helm charts and Terraform modules for Plural to be able to understand their dependencies and run them through its templating engine. Namely, a deps.yaml file which lists the dependencies of the Helm chart or Terraform module, and the values.yaml.tpl and terraform.tfvars file for Helm and Terraform respectively.

The values.yaml.tpl and terraform.tfvars files are run through the Plural templating engine, which is similar to that of Helm, and are used to generate the values.yaml for the wrapper helm chart and main.tf for the wrapper Terraform module.

The next example is a snippet of the values.yaml.tpl file for Grafana:

grafana:
  admin:
    password: {{ dedupe . "grafana.grafana.admin.password" (randAlphaNum 14) }}
    user: admin
  ingress:
    tls:
    - hosts:
      - {{ .Values.hostname }}
      secretName: grafana-tls
    hosts:
    - {{ .Values.hostname }}

In the above example, the hostname a for Grafana that is saved in the context.yaml will be set in the ingress for Grafana by {{ .Values.hostname }}. It also showcases dedupe, which is one of the templating functions available in the Plural CLI.

We are using the dedupe function so that a new random password for the Grafana admin is not generated if it has already been set. The reason grafana.grafana.admin.password is specified for the path, is because the CLI will create a wrapper Helm chart named grafana in a user's installation workspace. Please see this section of the Helm docs for an explanation on how to pass values to a subchart.

The next snippet shows a part of the terraform.tfvars for the AWS bootstrap terraform module:

vpc_name = {{ .Values.vpc_name | quote }}
cluster_name = {{ .Cluster | quote }}

Except for the user's application inputs from the context.yaml and the aforementioned dedupe function, Plural includes a lot of other values and functions that make it possible to simplify otherwise complex application configurations.

Templating reference

Along with the standard functions available in the Go templating language, the following Plural specific functions can be used.

Functions:

Template values:

.Config values:

.OIDC values:

.OIDC.Bindings values:

.SMTP values: