Get startedSign in

Add an Application

Is something missing from the Plural marketplace? Are you a vendor who wants to add your solution? We'd love for you to onboard your application! This guide outlines the process.

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:

yaml
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:

hcl
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:
FunctionInput (type)Returned valueDescription
fileExistsPath (string)BooleanChecks if a file exists
pathJoinParts ([]string)StringJoins parts of a path
repoRootXStringReturns the path of the installation repository
repoNameXStringReturns the base path of repoRoot
repoUrlXStringReturns the remote.origin.url of the installation repository
branchNameXStringReturns the name of the branch used for the installation repository
dumpConfigXString, ErrorReturns the Plural CLI config
dumpAesKeyXString, ErrorReturns the AES keys used for the installation repository
readFilePath (strong)StringReturns the contents of a file as a string
readLinePrompt (string)String, ErrorPrompts the user for input and returns the inputted string
readPasswordPrompt (string)String, ErrorPrompts the user for a password input and returns the inputted string
readLineDefaultPrompt, Default (string)string, errorPrompts the user for input and returns the inputted string or the default value if input is empty
homeDirParts ([]string)string, errorReturns the path of the user's home directory with the path parts appended to it
knownHostsXstring, errorReturns the contents of the .ssh/known_hosts file in the user's home directory
probeObject (interface{}), Path (string)interface{}, errorChecks if the object exists at the input path
dedupeObject (interface{}), Path, Value (string)stringReturns Object if it exists at the input Path, otherwise returns Value as a string
dedupeObjObject (interface{}), Path (string), Value (interface{})interface{}Returns Object if it exists at the input Path, otherwise returns Value as an interface{}. Used for complex data types
namespaceName (string)stringReturns the namespace for an application
secretNamespace, Name (string)map[string]interface{}Returns the content of a Kubernetes secret
importValueTool, Path (string)stringReturns the value from another tool at the given path. An example use case is to use a value from the Terraform output in the Helm chart
toYamlValue (interface{})string, errorFormats the input value as YAML
eabCredentialCluster, Provider (string)api.EabCredential, errorCreates a new set of EAB credentials in the Plural API for when using cert-manager with the Plural DNS
Template values:
PathDescription
.ValuesThe (recipe) values a user inputted for the given application
.ConfigurationAllows for getting values from other applications stored in the context.yaml file. For example, to use the hostname configured for Grafana in another application {{ .Configuration.grafana.hostname }} can be used.
.LicenseThe License for this application installation
.ConfigThe Plural CLI configuration object. Please see below for a detailed explanation
.OIDCThe OIDC configuration object for an application. Please see below for a detailed explanation
.RegionThe cloud region configured for the workspace of the installation
.ProjectThe cloud project configured for the workspace of the installation
.ClusterThe name of the cluster configured for the workspace of the installation
.ProviderThe name of the cloud provider configured for the workspace of the installation
.ContextThe context map of the Plural cloud provider config for the workspace of the installation
.SMTPThe SMTP configuration of the workspace. Please see below for a detailed explanation
.Applications.HelmValuesFunction that can be used to get the Helm values from another application. This differs from .Configuration as this can access all Helm values for an application, not only those stored in the context.yaml. For example, to use the generated Grafana admin password in another application you can do {{ $grafanaValues := .Applications.HelmValues "grafana" }} then {{ $grafanaValues.grafana.grafana.admin.password }}.
.Applications.TerraformValuesFunction that can be used to get the Terraform outputs from another application. Usage is similar to .Applications.HelmValues. For example, to get the Terraform outputs of the bootstrap application you can use {{ $bootstrapOutputs := .Applications.TerraformValues "bootstrap" }}
.Acme.KeyIdThe ACME key ID for to the application when using Plural DNS
.Acme.SecretThe ACME secret for to the application when using Plural DNS
.Config values:
PathDescription
.Config.EmailThe user email address of the current CLI user
.Config.TokenThe Plural token of the current CLI user
.Config.NamespacePrefixThe prefix to add to namespaces created for Plural applications
.Config.EndpointThe Plural endpoint the CLI will use
.Config.LockProfile
.Config.ReportErrorsIf CLI errors should be reported back to Plural
.COnfig.metadata.NameName of the CLI config that is currently being used
.OIDC values:
PathDescription
.OIDC.IdThe ID of the OIDC provider for the application
.OIDC.ClientIdThe Client ID for the OIDC provider of the application
.OIDC.ClientSecretThe Client Secret for the OIDC provider of the application
.OIDC.RedirectUrisList of redirect URIs for the OIDC provider of the application
.OIDC.BindingsList of bindings for the OIDC provider of the application. Please see below for a detailed explanation
.OIDC.Configuration.IssuerThe Issuer of the OIDC provider for the application
.OIDC.Configuration.AuthorizationEndpointThe Authorization endpoint of the OIDC provider for the application
.OIDC.Configuration.TokenEndpointThe Token endpoint of the OIDC provider for the application
.OIDC.Configuration.JwksUriThe JWKS URI of the OIDC provider for the application
.OIDC.Configuration.UserinfoEndpointThe endpoint exposing user info of the OIDC provider for the application
.OIDC.Bindings values:
PathDescription
.OIDC.Bindings.User.IdThe ID of the user that's bound to the application's OIDC provider
.OIDC.Bindings.User.EmailThe Email of the user that's bound to the application's OIDC provider
.OIDC.Bindings.User.NameThe Name of the user that's bound to the application's OIDC provider
.OIDC.Bindings.Group.IdThe ID of the group that's bound to the application's OIDC provider
.OIDC.Bindings.Group.NameThe Name of the group that's bound to the application's OIDC provider
.SMTP values:
PathDescription
.SMTP.Service
.SMTP.ServerThe SMTP server configured for the workspace
.SMTP.PortThe SMTP port configured for the workspace
.SMTP.SenderThe SMTP sender to use for the application
.SMTP.UserThe username used to login to the SMTP server
.SMTP.PasswordThe password used to login to the SMTP server