Existing Kubernetes Cluster

The existing cluster installation method is recommended if you already have a Kubernetes cluster running in production and would like to deploy Enterprise Server to it.

With Existing Kubernetes Cluster installation, you can install DeepSource Enterprise Server into an existing cluster with our pre-packaged kubectl plugins for licensing, configuration, and environment conformance testing.

Simple Installation

If you have an existing Kubernetes cluster you can run the following command from a workstation that has kubectl access to the cluster.

 curl https://kots.io/install | bash
 kubectl kots install deepsource-fowl

This will install the KOTS (Kubernetes off-the-shelf software) plugin on the workstation, then install the DeepSource Enterprise Admin Console on the cluster and set up a port forward on the ClusterIP to enable you to access the admin from https://localhost:8800. From here you’ll be walked through the preflight checks, configuration and initial deployment of the application.

If you need to use your existing deployment pipeline (i.e. internal image registry, version control system), make custom configuration tweaks and/or deploy to multiple or remote environments, please see our advanced existing cluster installation instructions below.

Ingress Controller

If you are installing to an existing cluster, we expect you to bring your own Ingress Controller. You will have to add the annotations to the Config section in the admin console under the Ingress Controller Annotations option.

For the K8s NGINX Ingress Controller, a tested set of annotations are available at:

kubernetes.io/ingress.class: "<your-ingress-class>"
nginx.ingress.kubernetes.io/ssl-redirect: "true"
kubernetes.io/tls-acme: "true"
cert-manager.io/cluster-issuer: "<your-cluster-issuer>" // Ignore if cert-manager isn't used in your cluster
nginx.ingress.kubernetes.io/service-upstream: "true"
nginx.ingress.kubernetes.io/client-body-buffer-size: "1M"
nginx.ingress.kubernetes.io/proxy-connect-timeout: "75"
nginx.ingress.kubernetes.io/proxy-send-timeout: "180"
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
nginx.ingress.kubernetes.io/use-regex: "true"
nginx.ingress.kubernetes.io/configuration-snippet: |
  if ($cookie_bifrost = 1) {
    proxy_pass http://bifrost.<deepsource-application-namespace>;
  }
  if ($arg_state = "Ymlmcm9zdA==") {
    proxy_pass http://bifrost.<deepsource-application-namespace>;
  }
nginx.ingress.kubernetes.io/server-snippet: |
  add_header X-Frame-Options "SAMEORIGIN";
  proxy_set_header X-Forwarded-Proto https;
  proxy_set_header Connection "";
  server_tokens off;
  proxy_intercept_errors on;
  location = /graphql/cli/ {
    client_max_body_size 5M;
    client_body_buffer_size 5M;
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location = /graphql/ {
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location = /dtc/ {
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location @debug {
    proxy_pass http://mater.<deepsource-application-namespace>;
  }
  location = / {
    rewrite / /login permanent;
  }
  location = /healthz {
    return 200;
  }
  location ~ ^/api {
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location ~ ^/(bb|gh|gl|gsr|ads|bbd)/(.*)/(.*).svg {
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location ~ ^/directory {
    proxy_pass http://bifrost.<deepsource-application-namespace>;
  }
  location ~ ^/groups {
    proxy_pass http://bifrost.<deepsource-application-namespace>;
  }
  location ~ ^/services {
    client_body_buffer_size 5M;
    error_page 500 502 503 504 @debug;
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location ~ ^/discover {
    proxy_pass http://bifrost.<deepsource-application-namespace>;
  }
  location ~ ^/support {
    proxy_pass http://bifrost.<deepsource-application-namespace>;
  }
  location ~ ^/sockets {
    proxy_pass http://janus.<deepsource-application-namespace>;
  }
  location ~ ^/(prod-asgard-static|asgard-artifacts) {
    proxy_pass http://minio.<deepsource-application-namespace>:9000;
  }
  location ~ ^/saml2 {
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }
  location ~ ^/scim {
    proxy_pass http://asgard-main.<deepsource-application-namespace>:8000;
  }

<deepsource-application-namespace> is the Kubernetes namespace where the application is installed, usually deepsource in case of installing in an existing cluster with KOTS.

Advanced Installation

DeepSource Enterprise is packaged as a Kubernetes application that can run on any Kubernetes cluster that meets minimum requirements:

  • Kubernetes v1.16.0 or later (although we recommend v1.19)
  • A default storage class that can be used for relocatable storage
  • A single namespace that all of the DeepSource Enterprise components will be deployed to
  • A standard ingress controller that can be accessed by the clients sending error reports

To verify that your cluster meets the minimum requirements, you can run our preflight checks before installing. To run the preflight checks on your cluster, run:

curl https://krew.sh/preflight | bash
kubectl preflight https://enterprise.deepsource.io/preflight

This will not run anything in your cluster, but will review your cluster version and resources and provide a summary to help you identify if the cluster meets the minimum or recommended requirements.

Considerations prior to installation

  • Ensure you have two node pools:
    • One for application workloads. We recommend having 16 CPUs and 32 GB memory for your application workload node pool.
    • One for analysis workloads. We recommend having 10 CPUs and 36 GB memory for your analysis workload node pool.
  • Ensure you have two namespaces created. One of the namespace will be used for deploying the application workloads and the other namespace (named as atlas-jobs) will be used for running analysis workloads.
  • You will also need to add node selectors to both your node pools to ensure proper isolation of application workloads from analysis workloads.

View and apply kubernetes manifests

If you’re unable or uncomfortable installing the admin console directly from KOTS, you can first pull the manifests that you’ll be deploying and kubectl apply those manifests. By default, these manifests are delivered with an empty kustomization.yaml in case you need to make last mile configuration changes with kustomize.

curl https://kots.io/install | bash
kubectl kots pull deepsource-fowl --license-file ~/path/application-license.yaml

Edit configuration locally

Using your favorite editor open the file: ~/deepsource-fowl/upstream/userdata/config.yaml, make any changes you need and save it, and then rerun kots pull to apply those changes to the deployable YAML manifest.

kubectl kots pull `deepsource-fowl` --license-file ~/path/license.yaml

The output should look like this:

Kubernetes application files created in ~/deepsource-fowl

Apply the files to the cluster

kubectl apply -k ~/deepsource-fowl/overlays/midstream

Using an internal registry

If your cluster is unable to download images from external registries, you’ll also need to store the images in your internal registry. If your workstation has push access to that registry, KOTS can download, retag, push those images on your behalf and prepare a YAML overlay with the new image location referenced.

kubectl kots pull deepsource-fowl \
  --license-file ~/path/application-license.yaml \
  --rewrite-images \
  --image-namespace deepsource-fowl \
  --registry-endpoint https://registry.yourorg.com

This command will:

  • Download and store all manifests in ~/deepsource-enterprise/upstream
  • Find all images referenced in all application manifests
  • Pull the images into ~/deepsource-enterprise/images
  • Retag and push each image to the internal image registry
  • Add a kustomize patch to the kustomization.yaml in the midstream, changing all image names, and persisting your local configuration changes to the config.yaml

After this process has completed you can deploy the application leveraging the internal images by running:

 kubectl apply -k ~/deepsource-fowl/overlays/midstream