Kubernetes + Helm deployment

Caution

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 is part of the Self-Hosting Overview. If you’re still evaluating whether to self-host, start there.

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:

1. 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

2. 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

3. Configure Container Images. Choose Option A (direct pull) or Option B (private registry)

4. Create Kubernetes Secrets. Set up database credentials and authentication secrets

5. Configure values.yaml. Customize deployment settings for your environment

6. Install Dependencies. Install cert-manager if not already present

7. Deploy Promptless. Install via Helm chart

8. 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:

1. 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.

2. 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

3. 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"

4. 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

5. 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

6. 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

   Note

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

   kubectl get pods -n promptless -w

7. 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

8. 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"

9. 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

   Tip

   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 — string, required

PostgreSQL connection string for the application database

JWT_SECRET — string, required

Secret key for JWT token signing and verification

S3_BUCKET — string, required

S3 bucket name for document and asset storage

AWS_REGION — 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 \
  -f values.yaml

Caution

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

Get 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

Note

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