improvement(helm): helm chart updates with security, ESO, and docs overhaul

helm/sim/Chart.yaml

@@ -1,9 +1,10 @@
 apiVersion: v2
 name: sim
-description: A Helm chart for Sim - AI agent workflow platform
+description: A Helm chart for Sim - the open-source AI workspace where teams build, deploy, and manage AI agents
 type: application
-version: 0.1.0
-appVersion: "1.0.0"
+version: 1.0.0
+appVersion: "0.6.73"
+kubeVersion: ">=1.25.0-0"
 home: https://sim.ai
 icon: https://raw.githubusercontent.com/simstudioai/sim/main/apps/sim/public/logo/primary/primary.svg
 sources:
@@ -19,5 +20,14 @@ keywords:
   - agents
   - nextjs
 annotations:
-  category: AI/ML Platform
-  licenses: Apache-2.0
+  category: developer-tools
+  artifacthub.io/license: Apache-2.0
+  artifacthub.io/links: |
+    - name: Homepage
+      url: https://sim.ai
+    - name: Documentation
+      url: https://docs.sim.ai
+    - name: Source
+      url: https://github.com/simstudioai/sim
+    - name: Discord
+      url: https://discord.gg/Hr4UWYEcTT

helm/sim/examples/values-aws.yaml

@@ -1,10 +1,51 @@
-# AWS-specific values for Sim
-# Example configuration for Amazon EKS deployment
+# values-aws.yaml
+#
+# When to use: Amazon EKS. Configures EBS GP3 storage, ALB ingress with
+# AWS Certificate Manager, IRSA-style ServiceAccount annotations, and
+# GPU-instance node selectors for Ollama.
+#
+# Prerequisites:
+#   - EKS cluster (Kubernetes 1.25+)
+#   - EBS CSI driver add-on (aws eks create-addon --addon-name aws-ebs-csi-driver)
+#   - AWS Load Balancer Controller (for ALB ingress)
+#   - (recommended) cert-manager OR an ACM certificate ARN for the ingress
+#
+# Install:
+#   helm install sim ./helm/sim \
+#     --namespace sim --create-namespace \
+#     --values ./helm/sim/examples/values-aws.yaml \
+#     --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+#     --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
+#     --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
+#     --set postgresql.auth.password="$POSTGRES_PASSWORD"
+#
+# Choosing a secret strategy
+# --------------------------
+# Pick one of three modes — see helm/sim/README.md for details.
+#
+#   1. Inline (default below): set sensitive keys directly in app.env.
+#      The chart writes them into a chart-managed Secret. Simplest, but
+#      stores plaintext in your values file.
+#
+#   2. existingSecret: pre-create a Kubernetes Secret out-of-band and
+#      reference it via app.secrets.existingSecret.name. You are
+#      responsible for ensuring the Secret contains every sensitive key
+#      your app needs (BETTER_AUTH_SECRET, ENCRYPTION_KEY,
+#      INTERNAL_API_SECRET, AWS_SECRET_ACCESS_KEY, OPENAI_API_KEY, ...).
+#      The chart filters sensitive keys out of inline env, so anything
+#      missing from your Secret will be empty at runtime.
+#
+#   3. External Secrets Operator (ESO): sync from AWS Secrets Manager /
+#      Parameter Store via the External Secrets Operator. Map each
+#      sensitive key via externalSecrets.remoteRefs.app.<KEY>. The chart
+#      fails template rendering if a sensitive key is set in app.env but
+#      not mapped — see the commented ESO block at the bottom of this
+#      file.
 
 # Global configuration
 global:
   imageRegistry: "ghcr.io"
-  storageClass: "gp2"  # Use gp2 (default on EKS) or create gp3 StorageClass for better performance
+  storageClass: "gp3"  # gp3 is the recommended EBS type (cheaper + faster than gp2). Requires a gp3 StorageClass — create one if your cluster only ships gp2.
 
 # Main application
 app:
@@ -255,4 +296,36 @@ affinity:
 serviceAccount:
   create: true
   annotations:
-    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/SimStudioServiceRole"
+    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/SimStudioServiceRole"
+# -----------------------------------------------------------------------------
+# External Secrets Operator (ESO) — recommended for production on AWS
+# -----------------------------------------------------------------------------
+# To switch from inline secrets to ESO:
+#   1. Install external-secrets in the cluster (https://external-secrets.io).
+#   2. Create a ClusterSecretStore backed by AWS Secrets Manager or
+#      SSM Parameter Store and grant IRSA access from this namespace.
+#   3. Remove the sensitive entries from app.env above (or leave them and the
+#      chart will fail-fast naming each unmapped key).
+#   4. Uncomment the block below and replace the paths with the names of the
+#      secrets in your store.
+#
+# externalSecrets:
+#   enabled: true
+#   secretStoreRef:
+#     name: "aws-secret-store"        # name of your ClusterSecretStore
+#     kind: "ClusterSecretStore"
+#   remoteRefs:
+#     app:
+#       BETTER_AUTH_SECRET:    "sim/app/better-auth-secret"
+#       ENCRYPTION_KEY:        "sim/app/encryption-key"
+#       INTERNAL_API_SECRET:   "sim/app/internal-api-secret"
+#       CRON_SECRET:           "sim/app/cron-secret"
+#       API_ENCRYPTION_KEY:    "sim/app/api-encryption-key"
+#       # AWS provider keys — required when not using IRSA for S3/Bedrock.
+#       AWS_ACCESS_KEY_ID:     "sim/aws/access-key-id"
+#       AWS_SECRET_ACCESS_KEY: "sim/aws/secret-access-key"
+#       # Add any other sensitive keys your deployment needs:
+#       OPENAI_API_KEY:        "sim/providers/openai-api-key"
+#       # ANTHROPIC_API_KEY:   "sim/providers/anthropic-api-key"
+#     postgresql:
+#       password: "sim/postgresql/password"

helm/sim/examples/values-azure.yaml

@@ -1,5 +1,45 @@
-# Azure-specific values for Sim
-# Example configuration for Azure AKS deployment
+# values-azure.yaml
+#
+# When to use: Azure Kubernetes Service (AKS). Configures managed-csi /
+# managed-csi-premium storage, NGINX ingress, role-based node targeting,
+# and NVIDIA GPU node pool tolerations for Ollama.
+#
+# Prerequisites:
+#   - AKS cluster (Kubernetes 1.25+)
+#   - NGINX ingress controller installed
+#   - (optional) cert-manager for TLS
+#   - (optional) GPU node pool labeled with role: datalake / accelerator: nvidia
+#
+# Install:
+#   helm install sim ./helm/sim \
+#     --namespace sim --create-namespace \
+#     --values ./helm/sim/examples/values-azure.yaml \
+#     --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+#     --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
+#     --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
+#     --set postgresql.auth.password="$POSTGRES_PASSWORD"
+#
+# Choosing a secret strategy
+# --------------------------
+# Pick one of three modes — see helm/sim/README.md for details.
+#
+#   1. Inline (default below): set sensitive keys directly in app.env.
+#      The chart writes them into a chart-managed Secret. Simplest, but
+#      stores plaintext in your values file.
+#
+#   2. existingSecret: pre-create a Kubernetes Secret out-of-band and
+#      reference it via app.secrets.existingSecret.name. You are
+#      responsible for ensuring the Secret contains every sensitive key
+#      your app needs (BETTER_AUTH_SECRET, ENCRYPTION_KEY,
+#      INTERNAL_API_SECRET, AZURE_OPENAI_API_KEY, AZURE_ACCOUNT_KEY, ...).
+#      The chart filters sensitive keys out of inline env, so anything
+#      missing from your Secret will be empty at runtime.
+#
+#   3. External Secrets Operator (ESO): sync from Azure Key Vault via
+#      the External Secrets Operator. Map each sensitive key via
+#      externalSecrets.remoteRefs.app.<KEY>. The chart fails template
+#      rendering if a sensitive key is set in app.env but not mapped
+#      — see the commented ESO block at the bottom of this file.
 
 # Global configuration
 global:
@@ -236,4 +276,36 @@ ingressInternal:
   # TLS configuration
   tls:
     enabled: true
-    secretName: simstudio-internal-tls-secret
+    secretName: simstudio-internal-tls-secret
+# -----------------------------------------------------------------------------
+# External Secrets Operator (ESO) — recommended for production on Azure
+# -----------------------------------------------------------------------------
+# To switch from inline secrets to ESO:
+#   1. Install external-secrets in the cluster (https://external-secrets.io).
+#   2. Create a ClusterSecretStore backed by Azure Key Vault and grant
+#      Workload Identity / managed-identity access from this namespace.
+#   3. Remove the sensitive entries from app.env above (or leave them and the
+#      chart will fail-fast naming each unmapped key).
+#   4. Uncomment the block below and replace the paths with the names of the
+#      secrets in your Key Vault.
+#
+# externalSecrets:
+#   enabled: true
+#   secretStoreRef:
+#     name: "azure-keyvault-store"      # name of your ClusterSecretStore
+#     kind: "ClusterSecretStore"
+#   remoteRefs:
+#     app:
+#       BETTER_AUTH_SECRET:      "sim-better-auth-secret"
+#       ENCRYPTION_KEY:          "sim-encryption-key"
+#       INTERNAL_API_SECRET:     "sim-internal-api-secret"
+#       CRON_SECRET:             "sim-cron-secret"
+#       API_ENCRYPTION_KEY:      "sim-api-encryption-key"
+#       # Azure provider keys
+#       AZURE_OPENAI_API_KEY:    "sim-azure-openai-api-key"
+#       AZURE_ANTHROPIC_API_KEY: "sim-azure-anthropic-api-key"
+#       AZURE_ACCOUNT_KEY:       "sim-azure-storage-account-key"
+#       # Use AZURE_CONNECTION_STRING instead if you prefer a single connection string:
+#       # AZURE_CONNECTION_STRING: "sim-azure-storage-connection-string"
+#     postgresql:
+#       password: "sim-postgresql-password"

helm/sim/examples/values-copilot.yaml

@@ -1,3 +1,22 @@
+# values-copilot.yaml
+#
+# When to use: enable the Sim Copilot service (the chat / Mothership backend)
+# alongside the main app. Provisions a dedicated Copilot Deployment, its own
+# Postgres StatefulSet, and a migration Job for the Copilot schema.
+#
+# Prerequisites: same as the base install. Merge this file with your main
+# values file (e.g. values-production.yaml) using multiple --values flags.
+#
+# Install:
+#   helm install sim ./helm/sim \
+#     --namespace sim --create-namespace \
+#     --values ./helm/sim/examples/values-production.yaml \
+#     --values ./helm/sim/examples/values-copilot.yaml \
+#     --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+#     --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
+#     --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
+#     --set postgresql.auth.password="$POSTGRES_PASSWORD"
+
 # Enable the copilot service
 copilot:
   enabled: true
@@ -6,8 +25,8 @@ copilot:
   server:
     image:
       repository: simstudioai/copilot
-      tag: latest
-      pullPolicy: Always
+      tag: ""  # defaults to Chart.AppVersion; override to pin a specific release
+      pullPolicy: IfNotPresent
 
     replicaCount: 2
 

helm/sim/examples/values-development.yaml

@@ -1,5 +1,19 @@
-# Development values for Sim
-# This configuration is suitable for development and testing
+# values-development.yaml
+#
+# When to use: local development on kind / minikube / Docker Desktop, or any
+# throwaway cluster where you don't need HA, TLS, or persistence guarantees.
+# Minimal resource requests, single replica, no ingress.
+#
+# Prerequisites: a working kubectl context.
+#
+# Install:
+#   helm install sim-dev ./helm/sim \
+#     --namespace sim-dev --create-namespace \
+#     --values ./helm/sim/examples/values-development.yaml \
+#     --set app.env.BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
+#     --set app.env.ENCRYPTION_KEY=$(openssl rand -hex 32) \
+#     --set app.env.INTERNAL_API_SECRET=$(openssl rand -hex 32) \
+#     --set postgresql.auth.password=$(openssl rand -base64 24 | tr -d '/+=')
 
 # Global configuration
 global:

helm/sim/examples/values-existing-secret.yaml

@@ -1,8 +1,23 @@
-# Using pre-existing Kubernetes secrets for Sim
-# For GitOps, Sealed Secrets, or manual secret management
-
+# values-existing-secret.yaml
+#
+# When to use: GitOps workflows where secrets are managed outside Helm via
+# Sealed Secrets, SOPS, kubeseal, or manual `kubectl create secret`. The
+# chart references your pre-created Kubernetes Secret objects by name
+# instead of templating values into a chart-managed Secret.
+#
 # Prerequisites:
-# Create your secrets before installing (see examples at bottom of file)
+#   Create the Secret objects before `helm install`. Example:
+#     kubectl create secret generic my-app-secrets --namespace sim \
+#       --from-literal=BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
+#       --from-literal=ENCRYPTION_KEY=$(openssl rand -hex 32) \
+#       --from-literal=INTERNAL_API_SECRET=$(openssl rand -hex 32) \
+#       --from-literal=CRON_SECRET=$(openssl rand -hex 32)
+#   Full Secret manifests are at the bottom of this file.
+#
+# Install:
+#   helm install sim ./helm/sim \
+#     --namespace sim --create-namespace \
+#     --values ./helm/sim/examples/values-existing-secret.yaml
 
 app:
   enabled: true

helm/sim/examples/values-external-db.yaml

@@ -1,6 +1,27 @@
-# External Database Example for Sim
-# Use this configuration when connecting to a managed database service
-# (AWS RDS, Azure Database, Google Cloud SQL, etc.)
+# values-external-db.yaml
+#
+# When to use: production deployments that use a managed Postgres service
+# (AWS RDS, Azure Database for PostgreSQL, Google Cloud SQL, Neon, Supabase)
+# instead of the chart's in-cluster Postgres StatefulSet. The in-cluster
+# Postgres is disabled (postgresql.enabled=false).
+#
+# Prerequisites:
+#   - A reachable managed Postgres instance with pgvector extension available
+#   - DB credentials provisioned (user, password, database)
+#   - Network reachability from the cluster (peering, private link, or public
+#     endpoint with TLS)
+#
+# Install:
+#   helm install sim ./helm/sim \
+#     --namespace sim --create-namespace \
+#     --values ./helm/sim/examples/values-external-db.yaml \
+#     --set externalDatabase.host=your-db.example.com \
+#     --set externalDatabase.username=simstudio_user \
+#     --set externalDatabase.password="$DB_PASSWORD" \
+#     --set externalDatabase.database=simstudio_prod \
+#     --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+#     --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
+#     --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET"
 
 # Global configuration
 global:

helm/sim/examples/values-external-secrets.yaml

@@ -1,9 +1,24 @@
-# External Secrets Operator integration for Sim
-# Syncs secrets from Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, etc.
-
+# values-external-secrets.yaml
+#
+# When to use: production deployments where secrets live in an external store
+# (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager)
+# and you want External Secrets Operator (ESO) to sync them into Kubernetes
+# Secrets that the chart consumes.
+#
 # Prerequisites:
-# 1. Install ESO: helm install external-secrets external-secrets/external-secrets -n external-secrets --create-namespace
-# 2. Create a SecretStore/ClusterSecretStore for your provider (see examples at bottom of file)
+#   1. Install ESO once per cluster:
+#        helm repo add external-secrets https://charts.external-secrets.io
+#        helm install external-secrets external-secrets/external-secrets \
+#          -n external-secrets --create-namespace
+#   2. Create a SecretStore or ClusterSecretStore for your provider — see
+#      example manifests at the bottom of this file.
+#   3. Pre-populate your remote store with the secret keys referenced in
+#      externalSecrets.remoteRefs below.
+#
+# Install:
+#   helm install sim ./helm/sim \
+#     --namespace sim --create-namespace \
+#     --values ./helm/sim/examples/values-external-secrets.yaml
 
 externalSecrets:
   enabled: true