Package: neon-diana-utils
Install and Deploy NeonAI DianaDevice Independent API for Neon Applications (Diana) is a collection of microservices that add functionality to NeonAI systems. Diana microservices are deployed in a Kubernetes cluster.After you have installed Diana, usediana --helpto get detailed help.For more information about using NeonAI, seethe NeonAI documentation site.PrerequisitesTo install Diana:Ubuntu20.04 or later.Diana will most likely work on other flavors of Linux, but we have not yet verified this.Python3.8 or later.PipPython package installer.To deploy Diana:KubectlKubernetes command-line tool.Helmpackage manager for Kubernetes.AKubernetesinstallation.The following instructions assume a local installation usingMicrok8sversion 1.26/stable or later.You can likely deploy Diana on a Kubernetes cluster in the cloud, but we have not yet verified this.Use a Python virtual environmentWe recommend you use aPython virtual environmentfor installing and testing Diana. In addition to the usual benefits, using a virtual environment makes it easier to ensure you are using the correct versions of Python and Diana.Create a Python virtual environment:python3.10 -m venv venvOpen a new terminal window. Activate the Python virtual environment in this new window:. venv/bin/activateUsing this new window, proceed with the instructions.Install DianaUse Pip to install Diana:pip install --pre neon-diana-utilsThis command installs the newest pre-release version, which is described in this tutorial.Warning:You can usepip install neon-diana-utilsto install the current stable version. Version 1.0.0 includes Helm chart support. For information on installing and running older versions, seethe archived documentation in the README file.For more information on the available versions of Diana, seethe Python Package Index repo for Neon Diana.Verify Diana is installed:diana --versionTip:If your computer does not recognize this command, you may need to add~/.local/binto your $PATH with a command likeexport PATH=$PATH:/home/${USER}/.local/bin.Usediana --helpfor detailed information about Diana and its commands.The output ofdiana --helplooks like:Usage: diana [OPTIONS] COMMAND [ARGS]...

  Diana: Device Independent API for Neon Applications.

  See also: diana COMMAND --help

Options:
  -v, --version  Print the current version
  --help         Show this message and exit.

Commands:
  configure-backend     Configure a Diana Backend
  configure-mq-backend  Configure RabbitMQ and export user credentials
  make-github-secret    Generate Kubernetes secret for Github images
  make-keys-config      Generate a configuration file with access keys
  make-rmq-config       Generate RabbitMQ definitions
  start-backend         Start a Diana Backend
  stop-backend          Stop a Diana BackendDeploy NeonAI DianaThis example deploys Diana in a localMicrok8s Kubernetescluster.Install and Run Microk8sIf you don't have Microk8s installed, you can install it and create the necessary user with:sudo snap install microk8s --classic
sudo usermod -aG microk8s $USER
newgrp microk8sStart Microk8s:microk8s startEnable the services for persistent storage, DNS, and the Kubernetes dashboard:microk8s enable hostpath-storage
microk8s enable dns
microk8s enable dashboardEnable the MetalLB service:microk8s enable metallbAt the prompt, enter a subnet  which is not being used by your router. For example:10.10.10.10-10.10.10.10Note: Unless you plan on adding multiple nodes, this range only needs one address.After Microk8s is running, usemicrok8s kubectl create token defaultto create a Microk8s token.In the new terminal window, usemicrok8s kubectl port-forward -n kube-system service/kubernetes-dashboard 1443:443to forward the dashboard port.You can now access your Kubernetes dashboard in a browser athttps://localhost:1443/using the token you created in step 2.The process in this terminal needs to keep running. Either background the process, or leave this terminal window open and open a new terminal window to continue working.Set Up DNSThe ingress controller needs URLs to be mapped to services. There are a number of different ways you can accomplish this, depending on your networking setup.For this guide, we will use the simple case of editing the/etc/hostsfile.Edit the/etc/hostsfile. Add one entry for the domain name of each service you intend to run. Add the canonical domain and point it to the IP address you gave MetalLB in step 3.For example, if you plan to run a service namedtest-serviceon thediana.k8sdomain, add the following line:10.10.10.10 test-service.diana.k8sThis tells your computer thattest-service.diana.k8sis at IP address10.10.10.10. Your computer will route all requests fortest-service.diana.k8sto the Kubernetes cluster you set up at10.10.10.10, instead of looking for it on the public internet.Add one line for each service. Point each service to the same IP address.Prepare for DeploymentAfter you set up your Kubernetes cluster and configure DNS, configure the Diana backend with:diana configure-mq-backend OUTPUT_PATHReplaceOUTPUT_PATHwith the directory where you want Diana to store its Helm charts and configurations. For example:diana configure-mq-backend ~/neon_dianaFollow the prompts to provide any necessary configuration parameters.Optional:To add extra TCP ports (i.e. for RabbitMQ), update theOUTPUT_PATH/ingress-nginx/values.yamlfile accordingly.Deploy the NGINX ingress:helm install ingress-nginx OUTPUT_PATH/ingress-common --namespace ingress-nginx --create-namespaceEditOUTPUT_PATH/diana-backend-values.yamland update any necessary configuration. At minimum, you need to update the following parameters:domainChange this to the domain you added to the/etc/hostsfile in step 11.letsencrypt.emailIf you are using a "real" domain, change this to the email address you want to use for theLet's EncryptSSL certificate. For local testing, leave this as is.letsencrypt.serverIf you are using a "real" domain, change this to a valid Let's Encrypt server address, such ashttps://acme-v02.api.letsencrypt.org/directory. For local testing, leave this as is.Deploy the Diana BackendUpdate the Helm dependency:helm dependency update OUTPUT_PATH/diana-backendUse Helm to launch Diana:helm install diana-backend OUTPUT_PATH/test/diana-backend --namespace backend --create-namespaceThis creates thebackendnamespace and launches Diana into that namespace. You can change this to any namespace name you prefer. You may want to use separate namespaces for test versus production deployments, to separate the Diana backend from other deployments, or both.Legacy DocumentationThe below documentation is mostly applicable to Docker deployment of the Diana
backend and is no longer fully-supported. Documentation is retained here for
reference.Orchestrator ConfigurationThe following sections describe how to initialize a standard backend withDockerorKubernetes.Docker ComposeFor testing or running on a dedicated host,Docker Composeoffers a simple method for starting a set of services.
This deployment assumes all services will run a single instance on a shared host with any configuration or other files
saved to the host filesystem or a configured NFS share. The configuration filesgenerated earlierare all that is necessary to start the backend with Docker ComposeRunning Configured Backend ServicesAfter a backend is configured, it can be started withdiana start-backend. A standard example is included here, but
a description of config options is available via:diana start-backend --help.Note: If running private containers, you will need to authenticate with Docker.
Documentation is availablefrom docker.
Containers from NeonGecko are published to theghcr.ioserverdianastart-backend~/neon_diana~/neon_dianaspecifies the path to backend configurationStopping a Running BackendAfter a backend is started, it can be stopped withdiana stop-backend. A standard example is included here, but
a description of config options is available via:diana stop-backend --help.dianastop-backend~/neon_diana~/neon_dianaspecifies the path to backend configurationKubernetesFor deployment, Kubernetes provides a managed solution that can handle scaling, rolling updates, and other benefits.
This deployment assumes you have an existing cluster; it is assumed that the Cluster or system administrator will manage
creation ofPersistentVolumeandLoadBalancerobjects as necessary.Cluster PreparationThe config generation in this project assumes your cluster has theNGINX Ingress Controllerdeployed.
Installation instructions are availablefrom Kubernetes.Theingress-nginx-controllerservice should have External Endpoints exposed. If you are deploying locally, you may useMetalLBto configure aLoadBalancer.TheKubernets Cluser References section belowcontains references to documentation and guides used to configure a cluster.Providing GitHub Image Pull SecretsFor private container images, you will need to specify GitHub credentials. Documentation for creating GitHub Personal
Access Tokens can be foundin the GitHub docs.
The configured token must have the permission:read:packages.dianamake-api-secrets-u<github_username>-t<github_pat>~/neon_dianaProviding Backend Service CredentialsKubernetes usessecretsto store sensitive data in a cluster.
Generate a Kubernetes secret spec withngi_auth_vars.yml(k8s_secret_ngi-auth.yml).dianamake-api-secrets-p~/.config/neon~/neon_diana-pspecifies the path to the directory containingngi_auth_vars.yml~/neon_dianaspecifies the output path for configuration filesDefining IngressTCP Servicesdianaincludes cli utilities for generating ingress definitions for non-http services.
In general, ingress definitions will be created or updated when relevant backend services are configured, but
thediana add-tcp-serviceentrypoint is also available to define these manually. Note that adding configuration
will modify existing spec files in the configured path.HTTP Servicesdianaincludes cli utilities for generating ingress rules for http services when usingingress-nginx.
It is assumed that theingress-nginxandcert-managernamespaced services are deployed as describedbelowand that A Records are defined for all configured subdomains.HTTPIngressis namespaced, so the configurations generated here must be applied to the same namespace
as the HTTPServices they forward to. The commands in this guide will assume everything is in the "default"
namespace unless otherwise specified.# Create a certificate issuer (must be deployed to each namespace)dianamake-cert-issuer-e<email_address>~/neon_diana# Update an Ingress configuration for every HTTP servicedianaadd-ingress-s<service_name>-p<service_http_port>-h<url_for_service>~/neon_dianaApplying Configuration to a Clusterkubectlshould be configured to reference the Kubernetes cluster you are deploying to.
If you are accessing private repositories, you will also need to configure the secretgithub-auth. Documentation
can be foundin the Kubernetes docs.# Apply configuration and secretskubectlapply-f~/neon_diana/config/k8s_secret_mq-config.yml-f~/neon_diana/config/k8s_config_rabbitmq.yml-f~/neon_diana/k8s_secret_ngi-auth.yml# If using ingress-nginx, apply those configurationskubectlapply-f~/neon_diana/ingress/k8s_config_tcp_services.yml
kubectlpatch-ningress-nginxserviceingress-nginx-controller--patch-file~/neon_diana/ingress/k8s_patch_nginx_service.yml# If using HTTP services, apply ingress ruleskubectlapply-f~/neon_diana/ingress/k8s_config_cert_issuer.yml-f~/neon_diana/ingress/k8s_config_ingress.yml# If using private imageskubectlapply-f~/neon_diana/k8s_secret_github.yml# Start backend serviceskubectlapply-f~/neon_diana/services/k8s_diana_backend.ymlKubernetes Cluster ReferencesThe following configurations were used at the time of writing this document:ingress-nginxcert-managerThese guides also may be useful for configuration that isn't handled in this repository:NGINX Ingress Controllercert-managerMetalLBGitHub Token AuthCertbot SSLThe definition below can be used to configure LetsEncryptapiVersion:cert-manager.io/v1kind:Issuermetadata:name:letsencrypt-prodspec:acme:# The ACME server URLserver:https://acme-v02.api.letsencrypt.org/directory# Email address used for ACME registrationemail:${CERT_EMAIL}# Name of a secret used to store the ACME account private keyprivateKeySecretRef:name:letsencrypt-prod# Enable the HTTP-01 challenge providersolvers:-http01:ingress:class:nginxIngress DefinitionsThe definition below can be used to configure ingressapiVersion:networking.k8s.io/v1kind:Ingressmetadata:name:ingress-backendannotations:cert-manager.io/issuer:"letsencrypt-prod"spec:tls:-hosts:-mqadmin.${domain}secretName:${domain}-tlsingressClassName:nginxrules:-host:"mqadmin.${domain}"http:paths:-path:/pathType:Prefixbackend:service:name:neon-rabbitmqport:number:15672