Plural
Search…
Integrate with Plural
This guide is for open-source project owners who would like to offer their project as a Plural application.

1. Create a new directory in plural-artifacts

Clone the plural-artifacts repository
1
git clone github.com/pluralsh/plural-artifacts
Copied!
For this getting started guide, let's pretend that we are onboarding Hasura. We have a useful make target to scaffold some of the necessary stubs for integrating with Plural.
1
plural create
Copied!
The repository structure after running the make command should look something like this:
1
hasura/
2
Pluralfile
3
helm
4
plural
5
repository.yaml
6
terraform
Copied!
In the steps below we will go through and fill out the stubs.

2. Add your helm chart

This section assumes familiarity with helm, the Kubernetes package manager. If you have not worked with helm before, it's strongly recommended that you read through the helm docs to understand core helm concepts, particularly helm templates and helm template values.

Getting Started with Helm

From the root of your newly created hasura directory, navigate to the helm chart.
1
cd helm/hasura
Copied!
A helm chart is organized as a collection of files inside of a directory:
1
hasura/
2
Chart.yaml # A YAML file containing information about the chart
3
values.yaml # The default configuration values for this chart
4
values.schema.json # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
5
charts/ # A directory containing any charts upon which this chart depends.
6
templates/ # A directory of templates that, when combined with values,
7
# will generate valid Kubernetes manifest files.
Copied!
The Chart.yaml file contains a description of the chart. You can access it from within a template.
The templates/ directory is for template files. When Helm evaluates a chart, it will send all of the files in the templates/ directory through the template rendering engine. It then collects the results of those templates and sends them on to Kubernetes.
The values.yaml file is also important to templates. This file contains the default values for a chart. These values may be overridden by users during helm install or helm upgrade.
You should also see a deps.yaml file. This is a Plural file used to track dependencies and sequence order of installations and upgrades.

1. Fill out Chart.yaml

Open up the Chart.yaml file.
Chart.yaml is a yaml file containing information about the chart. You can refer to the helm documentation for a comprehensive list of fields in the chart.
The yaml is largely self-documenting. The field to pay attention to is the field at the end, dependencies. If your open source project has an existing helm chart (for example on ArtifactHub), this is where you'll want to link it.
1
dependencies:
2
- name: hasura
3
version: 1.1.6
4
repository: https://charts.platy.plus
Copied!

2. Fill out templates/

Next, let's fill out the templates/ directory. Recall that the templates/ directory is for template files. When Helm evaluates a chart, it will send all of the files in the templates/ directory through the template rendering engine. It then collects the results of those templates and sends them on to Kubernetes.
The Plural platform includes a number of custom resources that you might find useful to fully productionize your application and can copy and paste over for your own use:
  • dashboard.yaml -- creates dashboards in the console that reference Prometheus metrics
  • runbook.yaml -- creates interactive tutorials in the console that show how to perform common maintenance tasks. For more documentation on runbooks refer here.
  • proxies.yaml -- wrappers around kubectl port-forward and kubectl proxy which allow you to get shells into running pods, databases or access private web uis
  • configurationOverlay.yaml -- creates form fields to modify helm configuration within the console
  • logfilter.yaml

3. Fill outdeps.yaml

The deps.yaml file is a Plural file that is used for determining the sequence of installations and updates. It should look something like this:
1
apiVersion: plural.sh/v1alpha1
2
kind: Dependencies
3
metadata:
4
application: true
5
description: Deploys hasura crafted for the target cloud
6
spec:
7
dependencies:
8
- type: helm
9
name: bootstrap
10
repo: bootstrap
11
version: ">= 0.5.1"
12
- type: helm
13
name: ingress-nginx
14
repo: ingress-nginx
15
version: ">= 0.1.2"
16
- type: helm
17
name: postgres
18
repo: postgres
19
version: ">= 0.1.6"
20
- type: terraform
21
name: aws
22
repo: hasura
23
version: ">= 0.1.0"
24
optional: true
25
- type: terraform
26
name: azure
27
repo: hasura
28
version: ">= 0.1.0"
29
optional: true
30
- type: terraform
31
name: gcp
32
repo: hasura
33
version: ">= 0.1.0"
34
optional: true
35
Copied!

2. Add your cloud config

From the root of the plural-artifacts/ directory, navigate to the terraform/ directory. Terraform is a tool for creating, updating, and destroying cloud infrastructure via configuration rather than a graphical user interface. If you are not familiar with it, we suggest reading through the Terraform docs. The files that are located inside this directory are responsible for creating various cloud objects -- i.e. Kubernetes namespaces, AWS IAM roles, and service accounts.
1
cd terraform
Copied!
You should see three folders:
1
terraform
2
aws
3
azure
4
gcp
Copied!
They each have the same structure:
1
terraform/aws
2
deps.yaml
3
main.tf
4
terraform.tfvars
5
variables.tf
Copied!
  • main.tf will contain the main set of configuration for your Terraform module. You can also create other configuration files and organize them however it makes sense for your project. It will look something like this:
1
resource "kubernetes_namespace" "hasura" {
2
metadata {
3
name = var.namespace
4
labels = {
5
"app.kubernetes.io/managed-by" = "plural"
6
"app.plural.sh/name" = "hasura"
7
}
8
}
9
}
10
11
data "aws_iam_role" "postgres" {
12
name = "${var.cluster_name}-postgres"
13
}
14
15
resource "kubernetes_service_account" "postgres" {
16
metadata {
17
name = "postgres-pod"
18
namespace = var.namespace
19
20
annotations = {
21
"eks.amazonaws.com/role-arn" = data.aws_iam_role.postgres.arn
22
}
23
}
24
25
depends_on = [
26
kubernetes_namespace.superset
27
]
28
}
Copied!
  • variables.tf will contain the variable definitions for your terraform module (the variables are used in main.tf

3. Add your Plural config

Finally, let's look at how to set up the config that will go to Plural.
From the root of plural-artifacts/, navigate to plural/recipes.
1
plural/recipes
2
hasura-aws.yaml
3
hasura-azure.yaml
4
hasura-gcp.yaml
Copied!
Here, you will specify the other Plural packages that must be installed alongside this package, as well as configuration and documentation for parameters that you will be asking users to input.
1
name: hasura-aws
2
description: Installs hasura on an EKS cluster
3
provider: AWS
4
dependencies: # Other Plural packages that must be installed alongside this bundle
5
- repo: bootstrap
6
name: aws-k8s
7
- repo: ingress-nginx
8
name: ingress-nginx-aws
9
- repo: postgres
10
name: aws-postgres
11
sections:
12
- name: hasura
13
items:
14
- type: TERRAFORM
15
name: aws
16
- type: HELM
17
name: hasura
18
configuration: # Users will be asked to input values for these parameters
19
- name: hostname
20
documentation: Fully Qualified Domain Name to use for your hasura installation, eg hasura.topleveldomain.com if topleveldomain.com is the domain you inputed for dns_domain above.
21
type: DOMAIN
Copied!

4. Testing Locally

You can validate your changes locally using the plural link command. You'll need to have your packages pushed to plural first, then installed in an installation repo. Once done, you can link your local version of a helm or terraform package using:
1
plural link helm <app-name> --path ../path/to/helm --name <chart-name>
Copied!

5. Push your local changes and open a PR in plural-artifacts

Assuming that you have been working on a branch add-hasura you should now commit your changes and open up a PR on Github.
1
git add .
2
git commit -m "Integrate hasura changes"
3
git push
Copied!
You may add @michaeljguarino as a reviewer on the PR.