Stardog Installer

A deployment tool for Stardog knowledge graph platform on Kubernetes. This project provides scripts and configurations to deploy Stardog on AWS EKS or Azure AKS clusters.

Overview

This tool automates the process of:

• Setting up Kubernetes infrastructure on AWS or Azure
• Deploying Stardog core components
• Optionally deploying Voicebox AI and Launchpad UI components
• Providing access information for all deployed services

Requirements

• Python 3.10+
• kubectl command-line tool
• helm command-line tool (v3+)
• AWS CLI or Azure CLI (depending on your target cloud)
• Terraform 1.0+
• TLS Certificate and Private Key files for your domain name (required for all deployments). This cannot be a self signed certificate.
• Domain name and the ability to modify your DNS records

Provider-Specific Requirements

AWS

• AWS CLI configured with appropriate permissions (EKS, IAM, VPC)
• For Voicebox AI: Access to AWS Bedrock service in your target region
• IAM permissions to create roles, policies, and OIDC providers (for IRSA)

Azure

• Azure CLI authenticated with your subscription
• For Voicebox AI: Access to Azure AI Foundry service

Installation

1. Clone this repository with its submodules:

   git clone --recurse-submodules https://github.com/stardog-union/stardog-installer.git
   cd stardog-installer

   If you already cloned the repository without submodules, or the submodules have an update, initialize them:

   git submodule update --init --recursive

   If you would like to use a different, not yet supported commit for the helm-charts, you can cd into the helm-charts directory and git checkout the desired commit.

2. Set up Python virtual environment and install dependencies:

   # Create virtual environment
   python3 -m venv scripts/venv
   
   # Activate virtual environment
   source scripts/venv/bin/activate
   
   # Install dependencies
   pip install -r scripts/requirements.txt

3. Ensure you're authenticated with your cloud provider:

   • For AWS: aws configure
   • For Azure: Install Azure CLI and authenticate:

     # Install Azure CLI (macOS)
     brew install azure-cli
     
     # Login to Azure
     az login

4. Verify Helm charts are available:

   # The helm-charts submodule needs to be cloned, see step 1
   # Verify the charts are present:
   ls helm-charts/

5. Ensure Helm chart dependencies are installed:

   cd helm-charts/charts/stardog
   helm dependency update

   The helm-charts directory is managed as a Git submodule and contains all necessary Helm charts for deployment.

6. Ensure you have a full-chain TLS certificate. If you are not familar with this concept, see this section of the NGINX documentation.

Usage

License Configuration

Before deploying Stardog, you need to put your license file in the root directory of the installer and name it stardog-license-key.bin.

SSO Configuration

Set up the SSO provider of your choice for use with Stardog. For complete documentation on configuring your SSO provider and setting these values, see the Launchpad Documentation.

Customizing Helm Charts

Before deploying components, you will need to set up values.yaml files for each of the components you want installed. By default, deploy.py will look for these files in the root of the project with the names stardog-values.yaml for Stardog, launchpad-values.yaml for Launchpad, and voicebox-values.yaml for Voicebox. Start by copying the values files from helm-charts/charts/<Component>/values.yaml to the root of the project and naming them <Component>-values.yaml. You can customize the deployment by modifying the values files in the root directory:

There are a few fields to pay particular attention to:

• stardog-values.yaml

Warning

The number of replicas and CPU, RAM, and storage requests for Stardog are controlled by the arguments --stardog-replicas, --stardog-cpu, --stardog-memory, and --stardog-storage respectively. This will override whatever you put in stardog-values.yaml

• zookeeper.persistence.storageclass and persistence.storageclass: These should be set to a valid storageclass in your kubernetes cluster. Valid values can be found with kubectl get storageclass.

• securityContext: set enabled to true and runAsUser, runAsGroup, and fsGroup to 1000.

• ingress: enable it with enabled: true and follow instructions in the helm-charts documentation to set the correct values

  • You will need a configuration like the following. Note that you do not need to create the TLS secret, since terraform will create that from your certificate and key file. The hostname you chose will be where the Stardog database will be accessible.

  ingress:
    enabled: true
    className: "nginx"
    tls:
    - hosts: ["stardog.yourdomain.com"]
      # This secret will be created by terraform
      secretName: stardog-tls
    hosts:
      - host: stardog.yourdomain.com
        paths:
          - path: /
            pathType: Prefix

• jwtConfig: set enabled: true to enable it, then set azureClientId and azureTenantId to your Entra ID values.

• launchpad-values.yaml

  • persistence.storageclass: This should be set to a valid storageclass in your kubernetes cluster. Valid values can be found with kubectl get storageclass.
  • env: This is where you will set the environment variables for your SSO configuration.
  • ingress: enable it with enabled: true and follow instructions in the helm-charts documentation to set the correct values. This should be similar to the configuration in the Stardog section above, but the host should be launchpad.yourdomain.com, or whatever else you prefer. This URL is where you will access Launchpad, which contains the Stardog frontend apps.

• voicebox-values.yaml

  • image.username and image.password: This should be configured to be your credentials for downloading Voicebox Service from Jfrog.

The deploy script will automatically use these values files if they exist in the root directory. You can also specify custom values files using the --stardog-values-file, --voicebox-values-file, and --launchpad-values-file options.

Voicebox AI Configuration

Voicebox AI integration differs depending on your cloud provider:

AWS Bedrock Integration

When deploying on AWS with --deploy-voicebox, the installer automatically:

• Creates IAM roles and policies for secure access to AWS Bedrock
• Configures IRSA (IAM Roles for Service Accounts) for the voicebox service account
• Generates voicebox configuration to use AWS Bedrock foundation models
• Sets up cross-region model access for Bedrock models

Supported Bedrock Models:

• meta.llama4-maverick-17b-instruct-v1:0 (default)

Security: Uses IRSA for secure, temporary credentials without storing long-lived API keys.

Azure AI Foundry Integration

When deploying on Azure with --deploy-voicebox, the installer:

• Creates Azure AI Foundry workspace and AI Services
• Deploys foundation models to the AI Services resource
• Configures voicebox to use Azure AI Foundry endpoints

Configuration Options:

• Command line: --azure-ai-endpoint and --azure-ai-key
• Environment variables: AZURE_AI_ENDPOINT and AZURE_AI_KEY
• Terraform outputs: Automatically retrieved if infrastructure was created by this tool

Basic Deployment

For a basic Stardog deployment (requires TLS certificates):

./scripts/deploy.py \
    --name my-stardog \
    --provider provider-name-here \
    --namespace stardog \
    --tls-cert-file /path/to/certificate.crt \
    --tls-key-file /path/to/private.key

This will create a Kubernetes cluster and deploy Stardog with default settings.

Stardog, Launchpad, and Voicebox Deployment

AWS Example:

./scripts/deploy.py \
    --provider aws \
    --region us-east-1 \
    --instance-type m5.xlarge \
    --node-count 3 \
    --name my-stardog \
    --namespace stardog \
    --tls-cert-file /path/to/certificate.crt \
    --tls-key-file /path/to/private.key \
    --deploy-voicebox \
    --deploy-launchpad \
    --stardog-replicas 3 \
    --stardog-cpu 2 \
    --stardog-memory 8Gi \
    --stardog-storage 100Gi

Azure Example (creates new AKS cluster):

./scripts/deploy.py \
    --provider azure \
    --region eastus \
    --name my-stardog \
    --namespace stardog \
    --tls-cert-file /path/to/certificate.crt \
    --tls-key-file /path/to/private.key \
    --deploy-voicebox \
    --deploy-launchpad

Using an Existing Cluster

To use an existing Kubernetes cluster, add the --use-existing-cluster flag:

Note for Voicebox: When using an existing cluster with --deploy-voicebox:

• AWS: Requires existing EKS cluster with OIDC provider enabled for IRSA
• Azure: Requires external Azure AI Foundry setup if not using terraform-managed infrastructure

./scripts/deploy.py \
    --provider azure \
    --use-existing-cluster \
    --name my-stardog \
    --namespace stardog \
    --tls-cert-file /path/to/certificate.crt \
    --tls-key-file /path/to/private.key \
    --deploy-voicebox \
    --deploy-launchpad

This is useful when you have already deployed the infrastructure with deploy.py and only want to make changes to the components you have deployed in kubernetes. For example, increasing the amount of CPU requests for one of the components.

Launchpad with Shared User Authentication

To deploy Launchpad with shared user authentication enabled:

./scripts/deploy.py \
    --deploy-launchpad \
    --shared-user-enabled \
    --shared-user-username myuser \
    --shared-user-password mypassword

This will enable shared user authentication in Launchpad with the specified username and password. If you don't specify --shared-user-username and --shared-user-password, it will default to admin/admin.

Access Services

DNS Setup

1. Find the IP being used by the Ingress objects in your cluster.

kubectl -n <your-namespace> get ingress
kubectl get ingress
NAME                             CLASS   HOSTS                   ADDRESS          PORTS     AGE
my-stardog-launchpad-launchpad   nginx   launchpad.example.com   123.123.123.123  80, 443   5d2h
my-stardog-stardog-stardog       nginx   stardog.example.com     123.123.123.123  80, 443   5d6h

From the above output, we want the value of ADDRESS.

2. In your DNS provider, create an A record for the subdomain that you specified that points to the IP address you just found. Using the above example, I would want to create an A record where the host is launchpad.example.com and the address is 123.123.123.123 and a second A record where the host is stardog.example.com and the address is 123.123.123.123.

Port Forwarding for Local Testing

After deployment:

1. For ClusterIP services (default), use kubectl port-forward:

   kubectl port-forward -n stardog svc/my-stardog-stardog 5820:5820
   

   Then access Stardog at http://localhost:5820

2. For LoadBalancer services, the script will display the external endpoint URLs.

Configuration Options

Option	Description	Default
--provider	Cloud provider (aws or azure)	aws
--use-existing-cluster	Use existing Kubernetes cluster	False
--region	Cloud provider region	us-east-1 (AWS), east us 2 (Azure)
--instance-type	Instance type for K8s nodes	m5.xlarge (AWS), Standard_E2ads_v6 (Azure)
--node-count	Number of K8s worker nodes	3
--name	Name prefix for the deployment	stardog
--namespace	Kubernetes namespace	stardog
--tls-cert-file	Path to TLS certificate file (required for deploy)	None
--tls-key-file	Path to TLS private key file (required for deploy)	None
--deploy-voicebox	Deploy Voicebox AI component	False
--deploy-launchpad	Deploy Launchpad UI component	False
--stardog-replicas	Number of Stardog replicas	1
--stardog-cpu	CPU request for Stardog	2
--stardog-memory	Memory request for Stardog	8Gi
--stardog-storage	Storage size for Stardog	100Gi
--charts-dir	Path to Helm charts directory	./helm-charts/charts
--shared-user-enabled	Enable shared user authentication for Launchpad	False
--shared-user-username	Username for shared user authentication	admin
--shared-user-password	Password for shared user authentication	admin

Recommended Instance Types

The default instance types listed above are known good configurations for all of the components. If you would like to increase the performance of your instance, we recommend staying within these instance families and choosing a larger type.

Security Considerations

• By default, Stardog is deployed with basic authentication (admin/admin)
• For production deployments:
  • Change default credentials immediately
  • Implement network policies to restrict access
  • Configure RBAC for Kubernetes resources

Voicebox Security

AWS Bedrock

• Uses IRSA (IAM Roles for Service Accounts) for secure authentication
• No long-lived API keys stored in the cluster
• Temporary, scoped credentials automatically rotated by AWS STS
• IAM policies follow least-privilege access (only Bedrock model invocation)

Azure AI Foundry

• API keys managed through Azure Key Vault or environment variables
• Recommend using Azure Managed Identity for production deployments
• Monitor API key rotation and access patterns

Uninstallation

To uninstall the resources created by the installer, run the command with the cleanup command. For example:

./scripts/deploy.py cleanup \
     --provider azure \
     --name my-stardog \
     --namespace stardog \
     --deploy-launchpad  \
     --deploy-voicebox \
     --stardog-cpu 1 \
     --stardog-memory 2Gi

Backup and Maintenance

TODO

Troubleshooting

TODO