DocumentationAPI ReferenceCommunity
Documentation

Helm & Kubernetes: Installation

Suggest Edits

Please read the following guide and visit https://github.com/diffgram/diffgram-helm to get the helm chart.

Note we have merged open source and enterprise codebases so enterprise users can start with the diffgram-helm like normal.

Introduction

The diffgram/diffgram-helm repository is the best way to use Diffgram with Kubernetes. The chart contains all the required components to get started and all the configuration values to scale or customize your deployment requirements.

Chart Components

  • Nginx Ingress
  • External service for Postgres DB Connection
  • Postgres Database (If not using external service)
  • diffgram/default component
  • diffgram/walrus component
  • diffgram/frontend component
  • diffgram/event component

Optional Dependencies

Domain/Subdomain Preferred Over Path

It is best to install diffgram on a domain or subdomain.
Like example.com or diffgram.example.com.

It is possible to install it as example.com/diffgram but strongly not recommended. If you must see the /path install case notes below

Useful Tutorials

Diffgram Helm Chart Quick Start Guide

If you are looking to get Diffgram up and running on kubernetes as fast as possible we recommend the following guide for Proof of Concept deployments.

The guide will walk you through deploying the Diffgram chart with the default values and features. But does not necessarly meet productions ready requirements. Please make sure to test workloads and tune the services CPU and RAM if you want to get the helm chart to Production with sustained work loads.

Requirements

  • A domain which you or your organization owns, and acces to adding DNS records to the Domain.
  • A Kubernetes Cluster
  • A working installation of kubectl
  • A working installation of helm

Domain Availability

For this guide you will not be able to use the infamout "example.com" domain. You need a domain that is internet accesible and also a domain you can add DNS records to. This is important because to issue SSL certificates the Let's Encrypt serviers will have to resolve the domain address in order to issue a valid SSL certificate.

Getting a Kubernetes Cluster

There are many ways you can create a kubernetes cluster. We recommend using any of the top cloud providers managed services:

Installing Kubectl

Once you have a cluster you can visit Kubernetes Official Documentation for installing kubectl.

Installing Helm V3

For this guide, we use helm's latest release. You can visit the Official installation instructions

Cloning the Helm repo & Installing

Clone the git repo for helm:
git clone https://github.com/diffgram/diffgram-helm
And now install:

# If you don't want tls you can skip this
helm repo add jetstack https://charts.jetstack.io
helm install cert-manager --namespace default jetstack/cert-manager --set installCRDs=true

# Install Diffgram
helm install diffgram . -f values.yaml`

Make sure you inspect all the values of the values.yaml file and set them to the correct values for your deployment. For this quick install guide, you can use the defaults.

Configurations:

The following are some of the most important configurations of the values.yaml in the helm chart. Please feel free to contact us if you have any questions on any of the configurations.

4.1 Database Settings

1. dbSettings.dbProvider: Set this to “rds”, "azure", or "local" depending on your DB managed service.

2. dbSettings.rdsEndpoint: Set this to your RDS instance endpoint, so diffgram can use it as the database.

3. dbSettings.dbProvider: Set this to “rds”

4, dbSettings.dbUser: Set this to the postgres user you want to use with Diffgram.

5. dbSettings.dbName: Set this to Postgres Database name you want to create the tables on

6. dbSettings.dbPassword: Set this to RDS instance’s password

4.2 Diffgram Configuration Settings

1. diffgramSecrets.DIFFGRAM_AWS_ACCESS_KEY_ID: Set this to your AWS credentials access key. Make sure the account has permissions to the S3 bucket you’ll use as static storage.

2. diffgramSecrets.DIFFGRAM_AWS_ACCESS_KEY_SECRET: Set this to your AWS credentials secret. Make sure the account has permissions to the S3 bucket you’ll use as static storage.

3. diffgramSettings.DIFFGRAM_S3_BUCKET_NAME: Set this to your S3’s bucket name for static file storage.

4. diffgramSettings.ML__DIFFGRAM_S3_BUCKET_NAME: Set this to your S3’s bucket name for static file storage.

5. diffgramSettings.DIFFGRAM_STATIC_STORAGE_PROVIDER: Set this to the provider you will use. Either aws, gcp or azure. Depending on this value, the helm will or will not require the above configurations. Case sensitive.

Warnings

Updating Kubernetes Cluster Version

❗️

Use Extreme Caution When Updating Kubernetes Cluster Version

When updating k8s itself (not Diffgram version) use extreme caution because various providers make it easy "one click" to do the upgrade, but the upgrade may cause breaking changes and may be hours, days, or even weeks of work to correct.
Those breaking changes may easily bring down an active cluster and render it inoperable until corrected.
Our support terms always exclude pure k8s support, and we can only provide limited support for k8s/diffgram maintenance recommendations.

We strongly recommend before doing any k8s cluster updates to thoroughly research breaking changes, effects on helm etc. If you are an enterprise customer we suggest contacting support to have a direct line to our team for any issues (although again we caution that our advice will be limited to Diffgram interactions not general k8s support).

Enterprise Common Errors

If you are getting a similar error to this:

Error: failed pre-install: warning: Hook pre-install diffgram/templates/hooks/secret_gcr_db_migrations.yaml failed: Secret in version "v1" cannot be handled as a Secret: v1.Secret.ObjectMeta: v1.ObjectMeta.TypeMeta: Kind: Data: decode base64: illegal base64 data at input byte 8, error found in #10 byte of ...|gram_team"},"kind":"|..., bigger context ...|":{".dockerconfigjson":"provided_by_diffgram_team"},"kind":"Secret","metadata":{"annotations":{"helm|..

Please make sure that you have the imagePullCredentials.gcrCredentials setup with the secret key provided by the Diffgram Team. If you are still having trouble setting up the enterprise installation, please contact us.

/path install notes

We strongly advise against this install route, but if you must for your case some considerations:

  • May need something like nginx.ingress.kubernetes.io/rewrite-target: /$2
  • Other ingress files may easily conflict
  • You may have 308 redirect or 302 or similar http issues to deal with.
  • diffgram-rabbitmq may need to be moved under Diffgram e.g. 
  rules:
    - host: {{ .Values.diffgramDomain }}
      http:
        paths:
         - path: /rabbit
            pathType: ImplementationSpecific
            backend:
              service:
                name: diffgram-rabbitmq
                port:
                  number: 15672

Updated about 2 years ago