Integrate with Plural

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.