Kubernetes + Helm Deployment

Warning

Enterprise Only: This deployment guide is exclusively for Enterprise customers. Self-hosting requires an Enterprise license and access to our private Helm chart repository. Contact us to discuss your self-hosting requirements and get access.

Kubernetes + Helm Deployment Guide

This guide provides the complete installation checklist for deploying Promptless on Kubernetes using Helm charts. Everything is parameterized through values.yaml—you should never need to edit the Helm chart itself.

Quick Start Checklist

This is the happy-path installation checklist for prospects:

Prerequisites

• AWS account with EKS cluster version 1.27+, IRSA enabled
• kubectl, helm, and aws-cli installed locally
• Route 53 hosted zone for promptless.<corp>.com

Provision Infrastructure

• EKS cluster & node groups
• RDS PostgreSQL
• S3-compatibile document store (e.g. a bucket named promptless-doc-store)
• VPC Endpoints for RDS, S3, Bedrock (if using language models restricted within your AWS VPC)
• IAM roles with scoped policies

Configure Container Images

Choose Option A (direct pull) or Option B (private registry)

Create Kubernetes Secrets

Set up database credentials and authentication secrets

Configure values.yaml

Customize deployment settings for your environment

Install Dependencies

Install cert-manager if not already present

Deploy Promptless

Install via Helm chart

Post-Installation

Verify deployment and configure user access

Architecture

The self-hosted deployment uses a microservices architecture running on Kubernetes:

•API Server

Handles REST API requests, authentication, and core business logic

•Worker Processes

Processes documentation generation jobs and integrations

•Web Dashboard

User interface for project management and configuration

Prerequisites

Before installing Promptless, ensure you have the following:

Infrastructure Requirements

AWS Account & EKS Cluster

• AWS account with EKS cluster version 1.27 or higher
• IRSA (IAM Roles for Service Accounts) enabled
• Node groups configured (including GPU nodes if using local LLMs)

Database Services

• RDS PostgreSQL instance (recommended: Aurora PostgreSQL)

Storage & Networking

• S3 bucket for document storage (e.g., promptless-doc-store)
• Route 53 hosted zone for your domain (e.g., promptless.corp.com)
• VPC Endpoints for AWS services: STS, Bedrock, S3, Secrets Manager (plus GitHub Enterprise if applicable)

IAM Roles

Create the following IAM roles with scoped policies:

• promptless-api: Access to Bedrock, S3, and Secrets Manager
• promptless-worker: Background job processing permissions
• promptless-dashboard: Web interface permissions

Tip

We can provide Terraform modules to provision the baseline infrastructure. Contact our support team at help@gopromptless.ai for infrastructure templates and IAM policy examples.

Installation Guide

Follow these steps to install Promptless on your Kubernetes cluster:

Provision Infrastructure

Set up the baseline AWS infrastructure. You can use the Terraform modules we provide or create resources manually.

Required Resources:

• EKS cluster with node groups (including GPU nodes if using local LLMs)
• RDS PostgreSQL
• S3 bucket promptless-doc-store
• VPC Endpoints for: STS, Bedrock, S3, Secrets Manager (plus GitHub Enterprise if applicable)
• IAM roles: promptless-api, promptless-worker, promptless-dashboard with scoped policies for Bedrock, S3, RDS

Tip

Contact our support team for Terraform modules and infrastructure templates.

Configure Container Images

Choose your container image strategy:

Option A: Direct Pull (Recommended)

# Allow EKS to pull directly from our public registry
# No additional configuration needed - images pulled from:
# public.ecr.aws/promptless/*

Option B: Private Registry

# Import images to your private ECR and configure values.yaml:
image:
  registry: <account-id>.dkr.ecr.<region>.amazonaws.com

Create Kubernetes Secrets

Create a secret containing your database credentials and other sensitive configuration:

kubectl create secret generic promptless-secrets \
  --from-literal=POSTGRES_URL="postgresql://user:password@host:5432/promptless" \
  --from-literal=JWT_SECRET="your-jwt-secret-key" \
  --from-literal=OIDC_CLIENT_SECRET="your-oidc-client-secret"

Configure values.yaml

Create a values.yaml file with your deployment configuration:

values.yaml

global:
  domain: promptless.corp.acme.com

auth:
  provider: oidc
  oidcIssuerURL: https://sso.acme.com

llm:
  provider: bedrock
  model: anthropic.claude-3-sonnet-20240229-v1:0

observability:
  mode: cloudwatch

integrations:
  github:
    enabled: true
    apiBaseURL: https://github.acme.com/api/v3

# Resource configuration
api:
  replicas: 2
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"

Configuration Options

Authentication Providers:

• oidc: OpenID Connect (recommended for enterprise)
• saml: SAML 2.0
• oauth: OAuth 2.0 with various providers

LLM Providers:

• bedrock: AWS Bedrock (recommended)
• openai: OpenAI API
• anthropic: Anthropic Claude API
• local: Self-hosted models

Observability:

• cloudwatch: AWS CloudWatch
• datadog: DataDog
• prometheus: Prometheus + Grafana

Install cert-manager

If you don’t already have cert-manager installed:

helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Install Promptless

Add the Promptless Helm repository and install:

# Add Helm repository
helm repo add promptless https://charts.promptless.com
helm repo update

# Install Promptless
helm upgrade --install promptless promptless/server \
  --namespace promptless \
  --create-namespace \
  -f values.yaml

The installation typically takes 3-5 minutes. Monitor the deployment with:

kubectl get pods -n promptless -w

Post-Installation Verification

After installation, verify your deployment:

# Check pod status
kubectl get pods -n promptless

# Verify database migrations succeeded
kubectl logs -l app=promptless-api -n promptless

# Check service endpoints
kubectl get services -n promptless

Verification Checklist:

• All pods are running and ready
• Database migrations completed successfully
• Services are accessible
• SSL certificates are issued

Configure User Access

Set up user access through your identity provider:

1. Invite Users: Use your IdP group mapping to grant access
2. Verify Authentication: Test that users can log in successfully

Example IdP Configuration

auth:
  provider: oidc
  oidcIssuerURL: https://sso.acme.com
  groupMappings:
    - idpGroup: "promptless-admins"
      role: "admin"
    - idpGroup: "promptless-users"
      role: "user"

Test Documentation Generation

Verify the system is working by:

1. Access Dashboard: Navigate to your Promptless domain
2. Create Project: Set up a test project with integrations
3. Trigger Test Ingestion: Test documentation generation via UI
4. Validate S3 Objects: Check S3 bucket for generated assets
5. Validate Bedrock Calls: Ensure LLM integration is working
6. Monitor Logs: Check CloudWatch logs for any errors

Success

If documentation generation completes successfully, your installation is ready for production use!

Configuration Reference

Environment Variables

Key environment variables for customizing your deployment:

POSTGRES_URL type: string • required

PostgreSQL connection string for the application database

JWT_SECRET type: string • required

Secret key for JWT token signing and verification

S3_BUCKET type: string • required

S3 bucket name for document and asset storage

AWS_REGION type: string • required

AWS region for Bedrock and other AWS services

Helm Chart Values

The Promptless Helm chart supports extensive customization through values.yaml:

Global Configuration

global:
  domain: promptless.example.com
  environment: production
  imageRegistry: public.ecr.aws/promptless

Authentication Settings

auth:
  provider: oidc
  oidcIssuerURL: https://auth.example.com
  sessionTimeout: 24h
  mfaRequired: true

Resource Limits

api:
  replicas: 2
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"

Integration Configuration

integrations:
  github:
    enabled: true
    apiBaseURL: https://api.github.com
  slack:
    enabled: true
  linear:
    enabled: true

Maintenance & Operations

Upgrades

Keep your Promptless installation up to date:

# Update Helm repository
helm repo update

# Upgrade to latest version
helm upgrade promptless promptless/server \
  --namespace promptless \

Warning

Always review the changelog before upgrading and test in a staging environment first.

Troubleshooting

Common Issues

Pods Not Starting

Symptoms: Pods stuck in Pending or CrashLoopBackOff state

Solutions:

1. Check resource availability: kubectl describe nodes
2. Verify secrets exist: kubectl get secrets -n promptless
3. Check pod logs: kubectl logs <pod-name> -n promptless
4. Validate values.yaml configuration

Database Connection Issues

Symptoms: API server logs show database connection errors

Solutions:

1. Verify PostgreSQL URL in secrets
2. Check RDS security groups and network connectivity
3. Ensure database exists and migrations can run
4. Test connection from a debug pod

Authentication Problems

Symptoms: Users cannot log in or receive authentication errors

Solutions:

1. Verify OIDC/SAML configuration in values.yaml
2. Check IdP connectivity and certificate validity
3. Review authentication provider logs
4. Validate redirect URLs and client secrets

Documentation Generation Failures

Symptoms: Jobs fail or documents are not generated

Solutions:

1. Check worker pod logs for errors
2. Verify Bedrock/LLM provider connectivity
3. Ensure S3 bucket permissions are correct

Getting Help

If you encounter issues not covered in this guide:

1. Check Logs: Review CloudWatch logs for error messages
2. Contact Support: Email help@gopromptless.ai with:
   • Deployment configuration (sanitized)
   • Error logs and symptoms
   • Steps to reproduce the issue

Our support team typically responds within 1 business hour for self-hosted deployments.

Security Considerations

Network Security

• Use private subnets for database instances
• Configure security groups to restrict access to necessary ports only
• Enable VPC Flow Logs for network monitoring
• Use AWS PrivateLink/VPC Endpoints for AWS service access

Data Protection

• Enable encryption at rest for RDS and S3
• Use TLS 1.2+ for all communications
• Implement proper IAM roles with least privilege access
• Regular security updates and vulnerability scanning

Compliance

Self-hosted Promptless supports various compliance requirements:

• SOC 2: Audit logging and access controls
• GDPR: Data residency and privacy controls
• HIPAA: Enhanced encryption and access logging
• FedRAMP: Government cloud deployment options

Contact our team to discuss specific compliance requirements for your deployment.

Example Architecture Diagram

The following diagram illustrates a typical EKS + Bedrock deployment architecture with self-hosted GitHub Enterprise and Slack integrations:

Architecture Components

•Kubernetes Deployments

• Backend API: Handles REST requests and core business logic
• Frontend Dashboard: Web interface served at promptless.corp.com
• Worker Processes: Background jobs for documentation generation

•AWS Services

• RDS PostgreSQL: Application database with VPC endpoint
• S3 Bucket: Document and asset storage with VPC endpoint
• Bedrock: LLM service for AI-powered documentation generation

🔌External Integrations

• GitHub Enterprise: Self-hosted Git platform integration
• Slack: Corporate messaging platform integration
• VPC Connectivity: Secure connections via VPC endpoints

🛡Security Features

• VPC Endpoints: Private connectivity to AWS services
• Security Groups: Network-level access controls
• IAM Roles: Service-specific permissions with IRSA

Key Architectural Benefits

• Data Sovereignty: All data remains within your AWS VPC
• Secure Connectivity: VPC endpoints eliminate internet traffic for AWS services
• Scalable Design: Kubernetes deployments can scale based on demand
• Enterprise Integration: Direct connectivity to self-hosted GitHub and Slack
• Compliance Ready: Architecture supports SOC 2, GDPR, HIPAA, and FedRAMP requirements