diff --git a/.gitignore b/.gitignore index 9ce3b7f3..37107089 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,10 @@ bin .sc/cfg.*.yaml .welder-out/* +# Python venv for local mkdocs builds (docs/.venv created on demand) +.venv/ +docs/.venv/ + REAL_WORLD_EXAMPLES_MAP.md # AI Assistant build artifacts diff --git a/docs/docs/advanced/best-practices.md b/docs/docs/advanced/best-practices.md index 77e43df1..4859521f 100644 --- a/docs/docs/advanced/best-practices.md +++ b/docs/docs/advanced/best-practices.md @@ -226,4 +226,4 @@ resources: - **Choose appropriate instance types** for your workloads - **Use placement groups** for high-performance computing - **Optimize network configurations** for low latency -- **Monitor infrastructure metrics** and adjust accordingly +- **Monitor infrastructure metrics** and adjust accordingly \ No newline at end of file diff --git a/docs/docs/advanced/compare-with-other-tools.md b/docs/docs/advanced/compare-with-other-tools.md deleted file mode 100644 index b863529d..00000000 --- a/docs/docs/advanced/compare-with-other-tools.md +++ /dev/null @@ -1,384 +0,0 @@ ---- -title: Comparision to other tools -description: This document provides a detailed comparison between **Simple Container**, **Pulumi**, and **Terraform** to help DevOps teams and developers choose the best tool for managing cloud infrastructure and microservice deployments. -platform: platform -product: simple-container -category: devguide -subcategory: learning -guides: tutorials -date: '2024-06-12' ---- - -# **Comparison: Simple Container vs Pulumi vs Terraform** - -This document provides a **detailed comparison** between **Simple Container**, **Pulumi**, and **Terraform** to help DevOps teams and developers choose the best tool for managing cloud infrastructure and microservice deployments. - ---- - -# **1️⃣ Overview of the Tools** - -| Tool | Purpose | Primary Users | Configuration Language | -|----------------------|--------------------------------------------------------------------|--------------------------|----------------------------------------| -| **Simple Container** | **CI/CD & infrastructure deployment for microservices** | Developers & DevOps | YAML | -| **Pulumi** | **Infrastructure as Code (IaC) & Cloud Infrastructure Management** | DevOps & Cloud Engineers | TypeScript, Python, Go, C# | -| **Terraform** | **Infrastructure as Code (IaC) & Cloud Provisioning** | DevOps & Cloud Engineers | HCL (HashiCorp Configuration Language) | - ---- - -# **2️⃣ Key Differences** - -## **πŸ”Ή Purpose & Focus** - -| Feature | Simple Container | Pulumi | Terraform | -|-------------------|-------------------------------------------------|-------------------------------------------------------------------|----------------------------------------------------------------------| -| **Primary Focus** | **Microservices Deployment & CI/CD Pipelines** | **Full Infrastructure as Code (IaC) with imperative programming** | **Full Infrastructure as Code (IaC) with declarative configuration** | -| **Best For** | **Developers & DevOps** deploying microservices | **DevOps & Cloud Engineers** managing infrastructure with code | **DevOps & Cloud Engineers** managing cloud infrastructure | -| **Use Cases** | **CI/CD, Microservices, Secrets Management** | **Cloud-native deployments, Kubernetes, AWS, GCP, Azure** | **Cloud Infrastructure, Networking, Security, Compute** | - -βœ… **SC is focused on microservice deployment, while Pulumi and Terraform are full-fledged IaC tools.** - ---- - -## **πŸ”Ή Configuration Language** - -| Feature | Simple Container | Pulumi | Terraform | -|----------------|--------------------------------------|---------------------------------------|--------------------------------------------| -| **Language** | **YAML** (declarative) | **TypeScript, Python, Go, C#** | **HCL (HashiCorp Configuration Language)** | -| **Complexity** | **Simple (high-level abstractions)** | **Moderate (imperative programming)** | **Complex (declarative DSL)** | - -βœ… **SC uses YAML for simplicity, whereas Pulumi and Terraform require programming or a DSL.** - ---- - -## **πŸ”Ή Infrastructure Management** - -| Feature | Simple Container | Pulumi | Terraform | -|---------------------------------|-----------------------------------------------|------------------------------------------------|------------------------------------------------------| -| **Infrastructure Provisioning** | βœ… **Yes (but high-level, via `server.yaml`)** | βœ… **Yes (fine-grained IaC)** | βœ… **Yes (fine-grained IaC)** | -| **Supports Multi-Cloud** | βœ… **Yes** | βœ… **Yes** | βœ… **Yes** | -| **State Management** | βœ… **Built-in (S3, GCS, FS)** | βœ… **Built-in via Pulumi Cloud, S3, GCS, etc.** | βœ… **State stored in Terraform Cloud, S3, GCS, etc.** | - -βœ… **SC abstracts away infrastructure details, while Pulumi and Terraform provide full control.** - ---- - -## **πŸ”Ή Microservice Deployment** - -| Feature | Simple Container | Pulumi | Terraform | -|-------------------------------------------|---------------------------------|-----------|--------------------------------------------| -| **Deploy to Kubernetes (GKE, EKS, AKS)** | βœ… **Yes (via `cloud-compose`)** | βœ… **Yes** | ❌ **Limited (needs Helm or K8S provider)** | -| **Deploy to AWS ECS Fargate** | βœ… **Yes** | βœ… **Yes** | βœ… **Yes** | -| **Deploy to AWS Lambda / GCP Cloud Run** | βœ… **Yes (via `single-image`)** | βœ… **Yes** | βœ… **Yes** | -| **Deploy Static Websites (S3, GCS, CDN)** | βœ… **Yes (via `static`)** | βœ… **Yes** | βœ… **Yes** | - -βœ… **SC is **built for deployment**, while Pulumi and Terraform require manual setup for CI/CD.** - ---- - -## **πŸ”Ή Secrets Management** - -| Feature | Simple Container | Pulumi | Terraform | -|---------------------------------|------------------------------------------|-----------------------------------------|---------------------------------------------------------| -| **Built-in Secrets Management** | βœ… **Yes (via SSH-based encryption)** | βœ… **Yes (via Pulumi Secrets Provider)** | ❌ **No (requires Vault, SOPS, or AWS Secrets Manager)** | -| **Secure Secret Sharing** | βœ… **Yes** | βœ… **Yes** | ❌ **No (manual setup required)** | -| **Encryption Support** | βœ… **Yes (AWS KMS, GCP KMS, passphrase)** | βœ… **Yes (KMS, GCP, HashiCorp Vault)** | ❌ **No (requires external tools)** | - -βœ… **SC has built-in secrets management, whereas Terraform needs external tools.** - ---- - -## **πŸ”Ή CI/CD Automation** - -| Feature | Simple Container | Pulumi | Terraform | -|-------------------------------|-----------------------------|---------------------------------------------|---------------------------------------------| -| **Built-in CI/CD Deployment** | βœ… **Yes (via `sc deploy`)** | ❌ **No (requires separate CI/CD pipeline)** | ❌ **No (requires separate CI/CD pipeline)** | -| **Easy Rollbacks** | βœ… **Yes** | ❌ **No (manual rollback required)** | ❌ **No (manual rollback required)** | - -βœ… **SC is designed for CI/CD, while Pulumi and Terraform rely on external automation.** - ---- - -# **3️⃣ When to Choose Which Tool?** - -βœ… **Use Simple Container if:** - -- You need **easy CI/CD for microservices**. -- You want **a simple YAML-based approach** for cloud deployments. -- You require **built-in secrets management**. -- You need **fast microservice deployments to Kubernetes, ECS, or Lambda**. - -βœ… **Use Pulumi if:** - -- You need **full Infrastructure as Code (IaC) with a programming language**. -- You want **strong integration with AWS, GCP, Azure**. -- You prefer **fine-grained control over infrastructure**. - -βœ… **Use Terraform if:** - -- You need **full Infrastructure as Code (IaC) with a declarative approach**. -- You want **multi-cloud infrastructure provisioning**. -- You prefer **HCL over programming languages**. - ---- - -# **4️⃣ Detailed Scaling Comparison** - -## **Infrastructure Management Complexity** - -| Aspect | Terraform/Pulumi | Simple Container | Advantage | -|---------------------------------------|------------------------------------|--------------------------------|----------------------------| -| **Configuration Lines** | 5000+ lines for 100 customers | 500 lines for 100 customers | **90% reduction** | -| **Infrastructure Knowledge Required** | Deep cloud expertise needed | Business logic focus only | **Developer self-service** | -| **Multi-Tenant Setup** | Manual per-customer infrastructure | Built-in parentEnv inheritance | **Automatic isolation** | -| **Secret Management** | Manual per-environment setup | Built-in ${secret:} + ${env:} | **Unified approach** | -| **Deployment Complexity** | Separate Terraform + K8s manifests | Single SC configuration | **Single source of truth** | - -## **Operational Scalability** - -| Metric | Terraform/Pulumi | Simple Container | Improvement | -|--------------------------------|-------------------------------|----------------------------|--------------------| -| **DevOps to Customer Ratio** | 1:10-20 customers | 1:100+ customers | **5x efficiency** | -| **Customer Onboarding Time** | 2-3 days | 5 minutes | **500x faster** | -| **Infrastructure Drift Risk** | High (manual management) | Low (template-based) | **Reduced errors** | -| **Cross-Region Deployment** | Duplicate infrastructure code | Single parent stack change | **DRY principle** | -| **Performance Tier Migration** | Manual infrastructure rebuild | One-line uses directive | **Zero downtime** | - - -## **Developer Experience** - -| Feature | Terraform/Pulumi | Simple Container | Benefit | -|-----------------------------|--------------------------|-------------------------|---------------------------| -| **Learning Curve** | Months (cloud + IaC) | Days (business config) | **Faster onboarding** | -| **Deployment Autonomy** | Requires DevOps approval | Self-service deployment | **Independent teams** | -| **Environment Consistency** | Manual synchronization | Automatic inheritance | **Reduced bugs** | -| **Resource Allocation** | Complex calculations | Simple uses directive | **Simplified management** | -| **Scaling Configuration** | Multiple files/tools | Single scale block | **Unified interface** | - -## **Cost and Resource Efficiency** - -| Factor | Terraform/Pulumi | Simple Container | Savings | -|-----------------------------|-------------------------|-------------------------|-----------------------------| -| **Infrastructure Overhead** | Per-customer resources | Shared resource pools | **70% cost reduction** | -| **Operational Staff** | High DevOps requirement | Minimal DevOps overhead | **80% staff reduction** | -| **Resource Utilization** | Often over-provisioned | Right-sized sharing | **Better efficiency** | -| **Maintenance Burden** | Continuous per-customer | Template updates only | **Centralized maintenance** | -| **Monitoring Complexity** | Per-customer setup | Built-in observability | **Reduced tooling costs** | - -## **Summary Table** - -| Feature | Simple Container | Pulumi | Terraform | -|---------------------------------------|-----------------------------|----------------------------|----------------------------------| -| **Best Use Case** | Microservice deployment | Full IaC with programming | Full IaC with declarative config | -| **Configuration Language** | YAML | TypeScript, Python, Go, C# | HCL | -| **Infrastructure Provisioning** | Limited (via `server.yaml`) | βœ… Yes | βœ… Yes | -| **Cloud Provider Support** | AWS, GCP, Kubernetes | AWS, GCP, Azure, K8s | AWS, GCP, Azure, K8s | -| **Secrets Management** | βœ… Built-in | βœ… Built-in | ❌ External required | -| **CI/CD Built-in** | βœ… Yes | ❌ No | ❌ No | -| **State Management** | βœ… Yes | βœ… Yes | βœ… Yes | -| **Automated Microservice Deployment** | βœ… Yes | ❌ No | ❌ No | -| **Scaling Efficiency** | **5x DevOps efficiency** | Manual scaling required | Manual scaling required | -| **Customer Onboarding** | **5 minutes** | Days to weeks | Days to weeks | - ---- - -# **5️⃣ Real-World Scaling Scenarios** - -## **Scenario 1: Adding 100 New Customers** - -**Terraform/Pulumi Approach:** -```bash -# For each of 100 customers, DevOps must: -1. Create separate infrastructure definitions -2. Configure networking, security, monitoring -3. Set up customer-specific resources -4. Manual secret management - -# Result: 5000+ lines of configuration -# Time: 2-3 days per customer = 200-300 days -# Team: Requires DevOps expertise for each deployment -``` - -**Simple Container Approach:** -```yaml -# DevOps defines infrastructure once (already done) - -# For each of 100 customers, developers add: -customer-001: - parentEnv: production - config: - domain: customer001.myapp.com - secrets: - CUSTOMER_SETTINGS: ${env:CUSTOMER_001_SETTINGS} - -# Result: 5 lines per customer = 500 lines total -# Time: 5 minutes per customer = 8.3 hours total -# Team: Developers can self-serve, no DevOps bottleneck -``` - -## **Scenario 2: Multi-Region Expansion** - -**Traditional Approach:** -```typescript -// Duplicate entire infrastructure for each region -const usEastCluster = new aws.ecs.Cluster("us-east-cluster"); -const usWestCluster = new aws.ecs.Cluster("us-west-cluster"); -const euWestCluster = new aws.ecs.Cluster("eu-west-cluster"); - -// Duplicate networking, security, monitoring for each region -// Manually manage customer allocation across regions -``` - -**Simple Container:** -```yaml -# .sc/stacks/myapp-us/server.yaml -resources: - prod: - resources: - mongodb-us: { region: us-east-1 } - -# .sc/stacks/myapp-eu/server.yaml -resources: - prod: - resources: - mongodb-eu: { region: eu-west-1 } - -# client.yaml - Customers choose regions easily -us-customer: - parent: simple-container/myapp-us - parentEnv: prod - -eu-customer: - parent: simple-container/myapp-eu - parentEnv: prod -``` - -# **6️⃣ Conclusion** - -- **Use Simple Container** (`sc`) for **fast microservice deployments with built-in CI/CD and superior scaling**. -- **Use Pulumi** if you need **fine-grained control over cloud resources with imperative programming**. -- **Use Terraform** if you need **declarative IaC for provisioning and managing cloud infrastructure**. - -**For organizations scaling microservices, Simple Container provides:** - -- **500x faster customer onboarding** -- **90% reduction in configuration complexity** -- **70% cost reduction through resource sharing** -- **5x operational efficiency improvement** - -# **Migrating from Terraform or Pulumi to Simple Container: Key Benefits** - -Migrating from **Terraform or Pulumi** to **Simple Container** offers a **simplified approach to microservice deployment** -while maintaining **cloud provider flexibility**. - -Unlike Terraform and Pulumi, which require **manual infrastructure provisioning and CI/CD setup**, `sc` **automates deployments** and abstracts infrastructure complexity. - ---- - -# **1️⃣ Key Benefits of Migrating to `sc`** - -## **πŸ”Ή 1. Developers Can Add Microservices Easily (Without DevOps Involvement)** - -βœ… **No need to manually configure cloud resources for each microservice**. - -βœ… **No Terraform modules or Pulumi scripts required for every new service**. - -βœ… **Developers only define a `client.yaml`** alongside familiar tools like **Dockerfile & docker-compose**. - -**πŸ”Ή Example: Adding a New Microservice (`myservice`)** -Instead of modifying Terraform or Pulumi configurations, **developers only create a simple `client.yaml`**: - -```yaml ---- -# File: ".sc/stacks/myservice/client.yaml" - -schemaVersion: 1.0 - -stacks: - staging: - type: cloud-compose - parent: myproject/devops - config: - dockerComposeFile: ./docker-compose.yaml # Familiar tooling - uses: - - mongodb # No need to define database again (DevOps-managed) - runs: - - myservice - env: - DATABASE_HOST: "${resource:mongodb.host}" - DATABASE_USER: "${resource:mongodb.user}" - secrets: - DATABASE_PASSWORD: "${resource:mongodb.password}" -``` - -βœ… **With Terraform/Pulumi, adding a microservice means modifying infrastructure code. With `sc`, developers just create `client.yaml`.** - -**πŸ”Ή Deployment Command (No Separate CI/CD Setup Required)** -```sh -sc deploy -s myservice -e staging -``` -βœ… **No need to define ECS tasks or Kubernetes manifestsβ€”`sc` handles everything.** - ---- - -## **πŸ”Ή 2. DevOps Focuses Only on Core Infrastructure (No Need to Manage Each Microservice)** - -βœ… **Single source of truth for infrastructure (`server.yaml`)**. - -βœ… **No need to update Terraform or Pulumi for every new microservice**. - -βœ… **Developers are isolated from cloud infrastructure complexities**. - -**πŸ”Ή Example: DevOps Defines Infrastructure Once (`server.yaml`)** -```yaml ---- -# File: ".sc/stacks/devops/server.yaml" - -schemaVersion: 1.0 - -provisioner: - type: pulumi - config: - state-storage: - type: s3-bucket - config: - credentials: "${auth:aws}" - bucketName: myproject-sc-state - -resources: - staging: - template: stack-per-app - resources: - mongodb: - type: mongodb-atlas - config: - admins: [ "admin" ] - instanceSize: "M10" - region: "US_WEST_2" - cloudProvider: AWS - privateKey: "${secret:MONGODB_ATLAS_PRIVATE_KEY}" - publicKey: "${secret:MONGODB_ATLAS_PUBLIC_KEY}" -``` -βœ… **Once this is set up, DevOps never needs to modify it for new microservices.** - ---- - -# **2️⃣ Why `sc` Is Better for Microservices Deployment?** -| Feature | Terraform / Pulumi | Simple Container | -|-------------------------------------|-------------------------------------------|----------------------------------------| -| **Adding a New Microservice** | ❌ Requires Terraform/Pulumi modifications | βœ… Developers only create `client.yaml` | -| **Cloud Infrastructure Management** | βœ… Yes | βœ… Yes (but DevOps-only) | -| **Microservice Deployment** | ❌ Requires CI/CD setup | βœ… Built-in (`sc deploy`) | -| **Secrets Management** | ❌ External tools required | βœ… Built-in (`sc secrets`) | -| **Multi-Cloud Support** | βœ… Yes | βœ… Yes | - ---- - -# **3️⃣ Summary** - -βœ… **Developers can add microservices easily** without modifying infrastructure code. - -βœ… **DevOps only manages core cloud resources** in a centralized `server.yaml`. - -βœ… **Secrets and deployments are automated**, reducing manual work. - -βœ… **No Terraform/Pulumi modifications needed for each new service**. diff --git a/docs/docs/advanced/scaling-advantages.md b/docs/docs/advanced/scaling-advantages.md deleted file mode 100644 index e058f90a..00000000 --- a/docs/docs/advanced/scaling-advantages.md +++ /dev/null @@ -1,912 +0,0 @@ -# Simple Container: Superior Scaling vs Plain Kubernetes/ECS - -## Executive Summary - -Simple Container (SC) provides significant scaling advantages over plain Kubernetes or ECS deployments managed with Pulumi/Terraform. Through its innovative separation of concerns, built-in secrets management, and developer self-service capabilities, SC enables organizations to scale from startup to enterprise without the operational complexity typically associated with container orchestration platforms. - -This document analyzes why Simple Container's architecture fundamentally scales better than traditional infrastructure-as-code approaches for SaaS and multi-tenant deployments. - -## Core Scaling Challenges with Traditional Approaches - -### Plain Kubernetes + Pulumi/Terraform Limitations - -**1. Infrastructure Knowledge Barrier:** -```yaml -# Plain Kubernetes - Developers need deep K8s knowledge -apiVersion: apps/v1 -kind: Deployment -metadata: - name: myapp - namespace: customer-a -spec: - replicas: 3 - selector: - matchLabels: - app: myapp - template: - metadata: - labels: - app: myapp - spec: - containers: - - name: myapp - image: myapp:latest - ports: - - containerPort: 3000 - env: - - name: MONGO_URL - valueFrom: - secretKeyRef: - name: customer-a-secrets - key: mongo-url - resources: - requests: - memory: "2Gi" - cpu: "1000m" - limits: - memory: "4Gi" - cpu: "2000m" ---- -apiVersion: v1 -kind: Service -metadata: - name: myapp-service - namespace: customer-a -spec: - selector: - app: myapp - ports: - - port: 80 - targetPort: 3000 - type: ClusterIP ---- -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: myapp-ingress - namespace: customer-a - annotations: - kubernetes.io/ingress.class: nginx - cert-manager.io/cluster-issuer: letsencrypt-prod -spec: - tls: - - hosts: - - customera.myapp.com - secretName: customera-tls - rules: - - host: customera.myapp.com - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: myapp-service - port: - number: 80 -``` - -**Problems:** - -- **Developer Bottleneck**: Requires Kubernetes expertise for every deployment -- **Configuration Complexity**: 50+ lines of YAML for basic service deployment -- **Manual Resource Management**: Developers must understand requests/limits, networking, ingress -- **No Built-in Multi-tenancy**: Each customer requires separate namespace and resource definitions - -**2. Secret Management Complexity:** -```bash -# Manual secret creation for each customer -kubectl create secret generic customer-a-secrets \ - --from-literal=mongo-url="mongodb://..." \ - --from-literal=api-key="..." \ - --namespace=customer-a - -kubectl create secret generic customer-b-secrets \ - --from-literal=mongo-url="mongodb://..." \ - --from-literal=api-key="..." \ - --namespace=customer-b -``` - -**Problems:** - -- **Manual Secret Provisioning**: No automation for customer-specific secrets -- **No Secret Rotation**: Manual process for updating secrets -- **Security Risks**: Secrets often stored in plain text in configuration files -- **Operational Overhead**: DevOps team manages every customer secret - -### Plain ECS + Pulumi/Terraform Limitations - -**1. Infrastructure Complexity:** -```typescript -// Pulumi ECS - Complex infrastructure definition -const cluster = new aws.ecs.Cluster("myapp-cluster"); - -const taskDefinition = new aws.ecs.TaskDefinition("myapp-task", { - family: "myapp", - cpu: "1024", - memory: "2048", - networkMode: "awsvpc", - requiresCompatibilities: ["FARGATE"], - executionRoleArn: executionRole.arn, - taskRoleArn: taskRole.arn, - containerDefinitions: JSON.stringify([{ - name: "myapp", - image: "myapp:latest", - portMappings: [{ - containerPort: 3000, - protocol: "tcp" - }], - environment: [ - { name: "NODE_ENV", value: "production" } - ], - secrets: [ - { - name: "MONGO_URL", - valueFrom: mongoSecret.arn - } - ], - logConfiguration: { - logDriver: "awslogs", - options: { - "awslogs-group": logGroup.name, - "awslogs-region": "us-east-1", - "awslogs-stream-prefix": "myapp" - } - } - }]) -}); - -const service = new aws.ecs.Service("myapp-service", { - cluster: cluster.id, - taskDefinition: taskDefinition.arn, - launchType: "FARGATE", - desiredCount: 3, - networkConfiguration: { - subnets: privateSubnets.map(s => s.id), - securityGroups: [securityGroup.id], - assignPublicIp: false - }, - loadBalancers: [{ - targetGroupArn: targetGroup.arn, - containerName: "myapp", - containerPort: 3000 - }] -}); - -const alb = new aws.elasticloadbalancingv2.LoadBalancer("myapp-alb", { - loadBalancerType: "application", - subnets: publicSubnets.map(s => s.id), - securityGroups: [albSecurityGroup.id] -}); -``` - -**Problems:** - -- **Infrastructure Expertise Required**: Developers need AWS ECS, networking, and security knowledge -- **Manual Load Balancer Management**: Complex ALB configuration for each customer -- **No Built-in Scaling**: Manual auto-scaling configuration -- **Resource Overhead**: Fargate pricing per task vs shared resource utilization - -## Simple Container's Scaling Advantages - -### 1. Separation of Concerns Architecture - -**DevOps Responsibility (Parent Stack - `server.yaml`):** -```yaml -# server.yaml - Infrastructure managed by DevOps once -provisioner: - type: pulumi - config: - state-storage: - type: s3-bucket - config: - bucketName: myapp-pulumi-state - region: us-east-1 - secrets-provider: - type: aws-kms - config: - kmsKeyId: "${secret:pulumi-kms-key-id}" - -templates: - stack-per-app-k8s: - type: kubernetes-cloudrun - config: - kubeconfig: "${auth:kubernetes}" - dockerRegistryURL: docker.mycompany.com - dockerRegistryUsername: "${secret:docker-registry-username}" - dockerRegistryPassword: "${secret:docker-registry-password}" - caddyResource: caddy - useSSL: false - -resources: - prod: - template: stack-per-app-k8s - resources: - # Multiple MongoDB clusters for customer allocation - mongodb-cluster-us-1a: - type: mongodb-atlas - config: - clusterName: myapp-us-1a - region: us-east-1 - instanceSize: M30 - - mongodb-cluster-us-1b: - type: mongodb-atlas - config: - clusterName: myapp-us-1b - region: us-east-1 - instanceSize: M30 - - mongodb-enterprise: - type: mongodb-atlas - config: - clusterName: myapp-enterprise - region: us-east-1 - instanceSize: M60 - dedicatedTenant: true -``` - -**Developer Responsibility (Service Stack - `client.yaml`):** -```yaml -# client.yaml - Simple customer deployment by developers -schemaVersion: 1.0 - -stacks: - # Base environment with shared resources - prod: &prod - type: cloud-compose - parent: simple-container/myapp-infra - config: &config - domain: prod.myapp.com - uses: [mongodb-cluster-us-1a] # Choose which cluster to use - runs: [myapp] - env: &env - NODE_ENV: production - PORT: 3000 - secrets: &secrets - MONGO_URL: ${resource:mongodb-cluster-us-1a.uri} - - # Customer deployments - minimal configuration - customer-a: - parentEnv: prod - <<: *prod - config: - <<: *config - domain: customera.myapp.com - secrets: - <<: *secrets - CUSTOMER_SETTINGS: ${env:CUSTOMER_A_SETTINGS} - - customer-b: - parentEnv: prod - <<: *prod - config: - <<: *config - domain: customerb.myapp.com - uses: [mongodb-cluster-us-1b] # Different cluster - secrets: - <<: *secrets - MONGO_URL: ${resource:mongodb-cluster-us-1b.uri} - CUSTOMER_SETTINGS: ${env:CUSTOMER_B_SETTINGS} - - enterprise-customer: - parentEnv: prod - <<: *prod - config: - <<: *config - domain: enterprise.myapp.com - uses: [mongodb-enterprise] # Dedicated cluster - scale: - min: 5 - max: 20 - secrets: - <<: *secrets - MONGO_URL: ${resource:mongodb-enterprise.uri} - ENTERPRISE_SETTINGS: ${env:ENTERPRISE_SETTINGS} -``` - -**Scaling Benefits:** - -- **DevOps Manages Infrastructure Once**: Kubernetes clusters, databases, networking, security -- **Developers Deploy Self-Service**: No infrastructure knowledge required -- **Automatic Resource Provisioning**: Caddy, SSL, scaling, monitoring configured automatically -- **Multi-tenant by Design**: Easy customer onboarding with minimal configuration - -### 2. Built-in Secrets Management - -**Traditional Approach Problems:** -```bash -# Manual secret management - doesn't scale -kubectl create secret generic customer-secrets \ - --from-literal=api-key="..." \ - --from-literal=db-password="..." \ - --namespace=customer-namespace - -# Terraform - secrets in code (security risk) -resource "kubernetes_secret" "customer_secrets" { - metadata { - name = "customer-secrets" - namespace = "customer-namespace" - } - data = { - api-key = var.customer_api_key - db-password = var.customer_db_password - } -} -``` - -**Simple Container's Current Secrets Management:** -```yaml -# server.yaml - Current SC secrets management -templates: - stack-per-app-k8s: - type: kubernetes-cloudrun - config: - kubeconfig: "${auth:kubernetes}" - dockerRegistryURL: docker.mycompany.com - dockerRegistryUsername: "${secret:docker-registry-username}" - dockerRegistryPassword: "${secret:docker-registry-password}" - caddyResource: caddy - useSSL: false - -# client.yaml - Built-in secret references and environment variables -stacks: - customer-a: - config: - secrets: - # Reference shared secrets from parent stack's secrets.yaml - DOCKER_PASSWORD: ${secret:docker-registry-password} - MONGODB_CONNECTION: ${secret:mongodb-connection} - # Customer-specific secrets via environment variables - CUSTOMER_SETTINGS: ${env:CUSTOMER_A_SETTINGS} - API_KEY: ${env:CUSTOMER_A_API_KEY} -``` - -**Future Enhancement - External Secret Manager Integration:** -```bash -# Would require CI/CD pipeline integration to: -# 1. Read secrets from external secret manager (AWS Secrets Manager, Vault, etc.) -# 2. Inject customer-specific secrets as environment variables -# 3. Deploy with customer-specific environment variables - -# Example CI/CD integration (future development needed): -# aws secretsmanager get-secret-value --secret-id "myapp/customer-a/settings" -# export CUSTOMER_A_SETTINGS="$(aws secretsmanager get-secret-value ...)" -# sc deploy -s customer-a -e production -``` - -**Current SC Scaling Benefits:** - -- **Environment Variable Support**: Simple `${env:VARIABLE_NAME}` references in configuration -- **Developer Simplicity**: Environment variables instead of complex Kubernetes secret management -- **Namespace Isolation**: Each customer stack deployed to separate namespace with isolated secrets - -**Future Scaling Benefits (with external secret manager integration):** - -- **Automatic Secret Injection**: CI/CD pipeline integration for secret retrieval -- **External Secret Manager Integration**: AWS Secrets Manager, Vault, Azure Key Vault -- **Customer-Specific Isolation**: Enhanced secrets isolated per customer via external systems -- **Rotation Support**: External secret rotation without deployment changes - -### 3. Multi-Dimensional Resource Allocation - -**Traditional Approach - Manual Resource Management:** -```yaml -# Each customer needs separate infrastructure definition -# customer-a-infrastructure.yaml -resource "aws_ecs_cluster" "customer_a" { - name = "customer-a-cluster" -} - -resource "aws_rds_instance" "customer_a_db" { - identifier = "customer-a-database" - engine = "postgres" - # ... complex configuration -} - -# customer-b-infrastructure.yaml -resource "aws_ecs_cluster" "customer_b" { - name = "customer-b-cluster" -} - -resource "aws_rds_instance" "customer_b_db" { - identifier = "customer-b-database" - engine = "postgres" - # ... duplicate configuration -} -``` - -**Simple Container - Flexible Resource Sharing:** -```yaml -# server.yaml - Define resource pools once -resources: - production: - resources: - # Shared resources for standard customers - mongodb-shared-us: - type: mongodb-atlas - config: - clusterName: shared-us - instanceSize: M30 - - mongodb-shared-eu: - type: mongodb-atlas - config: - clusterName: shared-eu - instanceSize: M30 - - # Dedicated resources for enterprise - mongodb-enterprise-1: - type: mongodb-atlas - config: - clusterName: enterprise-1 - instanceSize: M80 - -# client.yaml - Customers choose resources flexibly -stacks: - # Standard US customers share resources - standard-customer-1: - uses: [mongodb-shared-us] - - standard-customer-2: - uses: [mongodb-shared-us] # Same shared resource - - # EU customer uses EU resources - eu-customer: - uses: [mongodb-shared-eu] - - # Enterprise customer gets dedicated resources - enterprise: - uses: [mongodb-enterprise-1] -``` - -**Scaling Benefits:** - -- **Resource Pool Management**: Define resources once, allocate flexibly -- **Cost Optimization**: Share resources among compatible customers -- **Performance Tiers**: Easy allocation of dedicated vs shared resources -- **Geographic Distribution**: Automatic compliance with data residency -- **Easy Migration**: Move customers between resource pools by changing `uses` directive - -### 4. Automatic Operational Features - -**Traditional Kubernetes - Manual Configuration:** -```yaml -# Manual HPA configuration for each customer -apiVersion: autoscaling/v2 -kind: HorizontalPodAutoscaler -metadata: - name: customer-a-hpa - namespace: customer-a -spec: - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: myapp - minReplicas: 2 - maxReplicas: 10 - metrics: - - type: Resource - resource: - name: cpu - target: - type: Utilization - averageUtilization: 70 - - type: Resource - resource: - name: memory - target: - type: Utilization - averageUtilization: 80 - -# Manual ingress for each customer -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: customer-a-ingress - namespace: customer-a - annotations: - cert-manager.io/cluster-issuer: letsencrypt-prod - nginx.ingress.kubernetes.io/ssl-redirect: "true" -spec: - tls: - - hosts: - - customera.myapp.com - secretName: customera-tls - rules: - - host: customera.myapp.com - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: myapp-service - port: - number: 80 -``` - -**Simple Container - Best Practice Templates with Client Configuration:** -```yaml -# server.yaml - Best practice template definition -templates: - stack-per-app-k8s: - type: kubernetes-cloudrun - config: - kubeconfig: "${auth:kubernetes}" - dockerRegistryURL: docker.mycompany.com - dockerRegistryUsername: "${secret:docker-registry-username}" - dockerRegistryPassword: "${secret:docker-registry-password}" - caddyResource: caddy - useSSL: false - -# client.yaml - Customer-specific configurations -stacks: - customer-a: - type: cloud-compose - config: - domain: customera.myapp.com - runs: [myapp] - scale: - max: 10 - min: 2 - policy: - cpu: - max: 70 - memory: - max: 75 - env: - NODE_ENV: production - PORT: 3000 - secrets: - CUSTOMER_SETTINGS: ${env:CUSTOMER_A_SETTINGS} -``` - -**Scaling Benefits:** - -- **Best Practice Templates**: SC provides proven Kubernetes deployment patterns -- **Client-Side Configuration**: Scaling, domains, and environment variables defined per customer -- **Consistent Infrastructure**: All customers use same underlying template with custom configurations -- **Simplified Deployment**: Developers configure business logic, not infrastructure complexity - -## Scaling Comparison: Real-World Scenarios - -### Scenario 1: Adding 100 New Customers - -**Traditional Kubernetes/ECS:** -```bash -# For each of 100 customers, DevOps must: -1. Create namespace/cluster -2. Define deployment YAML (50+ lines each) -3. Configure ingress and SSL certificates -4. Set up monitoring and logging -5. Create secrets manually -6. Configure scaling policies -7. Set up backup and disaster recovery - -# Result: 5000+ lines of configuration -# Time: 2-3 days per customer = 200-300 days -# Team: Requires DevOps expertise for each deployment -``` - -**Simple Container:** -```yaml -# DevOps defines infrastructure once (already done) - -# For each of 100 customers, developers add: -customer-001: - parentEnv: production - config: - domain: customer001.myapp.com - secrets: - CUSTOMER_SETTINGS: ${env:CUSTOMER_001_SETTINGS} - -# Result: 5 lines per customer = 500 lines total -# Time: 5 minutes per customer = 8.3 hours total -# Team: Developers can self-serve, no DevOps bottleneck -``` - -### Scenario 2: Multi-Region Expansion - -**Traditional Approach:** -```typescript -// Duplicate entire infrastructure for each region -const usEastCluster = new aws.ecs.Cluster("us-east-cluster"); -const usWestCluster = new aws.ecs.Cluster("us-west-cluster"); -const euWestCluster = new aws.ecs.Cluster("eu-west-cluster"); - -// Duplicate networking, security, monitoring for each region -// Manually manage customer allocation across regions -// Complex cross-region secret management -``` - -**Simple Container:** -```yaml -# .sc/stacks/myapp-us/server.yaml -resources: - prod: - resources: - mongodb-us: { region: us-east-1 } - -# .sc/stacks/myapp-eu/server.yaml -resources: - prod: - resources: - mongodb-eu: { region: eu-west-1 } - -# client.yaml - Customers choose regions easily -us-customer: - parent: simple-container/myapp-us - parentEnv: prod - -eu-customer: - parent: simple-container/myapp-eu - parentEnv: prod -``` - -### Scenario 3: Performance Tier Migration - -**Traditional Approach:** -```bash -# Manual migration process: -1. Create new high-performance infrastructure -2. Update customer deployment configurations -3. Migrate data manually -4. Update DNS and certificates -5. Monitor and rollback if issues -6. Clean up old infrastructure - -# High risk, manual process, downtime required -``` - -**Simple Container:** -```yaml -# Before: Customer on shared resources -customer-enterprise: - uses: [mongodb-shared-us] - -# After: Customer on dedicated resources (one line change!) -customer-enterprise: - uses: [mongodb-enterprise-dedicated] - -# Automatic migration, zero downtime, easy rollback -``` - -## Cost and Operational Efficiency - -### Development Velocity - -**Traditional Approach:** - -- **Time to First Deployment**: 2-3 days (infrastructure setup) -- **Developer Onboarding**: 2-4 weeks (Kubernetes/AWS training) -- **Feature Development**: Blocked by infrastructure changes -- **Customer Onboarding**: DevOps bottleneck, 1-2 days per customer - -**Simple Container:** - -- **Time to First Deployment**: 15 minutes (configuration only) -- **Developer Onboarding**: 1-2 hours (simple YAML configuration) -- **Feature Development**: Independent of infrastructure -- **Customer Onboarding**: Self-service, 5 minutes per customer - -### Operational Overhead - -**Traditional Approach:** - -- **Team Size**: 1 DevOps engineer per 10-20 customers -- **On-call Burden**: Complex troubleshooting across multiple systems -- **Maintenance**: Manual updates for each customer deployment -- **Scaling**: Linear increase in operational complexity - -**Simple Container:** - -- **Team Size**: 1 DevOps engineer per 100+ customers -- **On-call Burden**: Centralized infrastructure, easier troubleshooting -- **Maintenance**: Template updates apply to all customers -- **Scaling**: Operational complexity remains constant - -### Cost Optimization - -**Traditional Approach:** -```bash -# ECS Fargate: $0.04048 per vCPU per hour + $0.004445 per GB per hour -# 100 customers Γ— 2 vCPU Γ— 4GB Γ— 24h Γ— 30 days = $2,429/month per customer -# Total: $242,900/month for 100 customers - -# Kubernetes: Manual resource allocation, often over-provisioned -# 100 customers Γ— dedicated nodes = high infrastructure costs -# No resource sharing optimization -``` - -**Simple Container:** -```bash -# Kubernetes with resource sharing: -# Shared infrastructure: 50% cost reduction through better utilization -# Automatic scaling: 30% cost reduction through right-sizing -# Multi-tenant architecture: 40% cost reduction through resource sharing -# Total: $72,870/month for 100 customers (70% cost reduction) -``` - -## Security and Compliance Advantages - -### Secret Management Security - -**Traditional Approach Issues:** - -- Secrets often stored in plain text configuration files -- Manual secret rotation processes -- No audit trails for secret access -- Difficult to implement least-privilege access - -**Simple Container Security:** -```yaml -# Option 1: Shared secrets.yaml per parent stack -# .sc/stacks/myapp-us/secrets.yaml -secrets: - mongodb-connection: "mongodb+srv://..." - docker-registry-password: "secure-password" - -# Option 2: Environment variables from external secret manager -# CI/CD pipeline reads from AWS Secrets Manager/Vault and injects as env vars -# client.yaml references environment variables -stacks: - customer-a: - config: - env: - DATABASE_URL: ${env:CUSTOMER_A_DATABASE_URL} - API_KEY: ${env:CUSTOMER_A_API_KEY} -``` - -**Benefits:** - -- **Namespace Isolation**: Each customer stack deployed to separate namespace with isolated secrets -- **Environment Variable Support**: Simple `${env:VARIABLE_NAME}` references in client configurations -- **Shared Secret Management**: Common secrets managed once per parent stack via secrets.yaml -- **External Integration Ready**: CI/CD can inject customer-specific secrets from external managers - -### Multi-Tenant Security - -**Traditional Kubernetes:** -```yaml -# Manual namespace isolation - error-prone -apiVersion: v1 -kind: Namespace -metadata: - name: customer-a - labels: - customer: customer-a - -# Manual network policies for each customer -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: customer-a-isolation - namespace: customer-a -spec: - podSelector: {} - policyTypes: - - Ingress - - Egress - ingress: - - from: - - namespaceSelector: - matchLabels: - name: customer-a -``` - -**Simple Container:** -```yaml -# Simple Container provides automatic namespace isolation -# Each deployed stack gets its own Kubernetes namespace -# Namespace-level isolation provides tenant security automatically - -# Example: Customer stacks deployed to separate namespaces -# customer-a stack β†’ customer-a-namespace -# customer-b stack β†’ customer-b-namespace -# enterprise stack β†’ enterprise-namespace - -# Kubernetes namespace isolation provides: -# - Resource isolation (pods, services, secrets) -# - Network isolation (default namespace boundaries) -# - RBAC isolation (namespace-scoped permissions) -# - Resource quotas (can be applied per namespace) -``` - -## Conclusion: Simple Container vs Terraform/Pulumi Comparison - -### Infrastructure Management Complexity - -| Aspect | Terraform/Pulumi | Simple Container | Advantage | -|---------------------------------------|------------------------------------|--------------------------------|----------------------------| -| **Configuration Lines** | 5000+ lines for 100 customers | 500 lines for 100 customers | **90% reduction** | -| **Infrastructure Knowledge Required** | Deep cloud expertise needed | Business logic focus only | **Developer self-service** | -| **Multi-Tenant Setup** | Manual per-customer infrastructure | Built-in parentEnv inheritance | **Automatic isolation** | -| **Secret Management** | Manual per-environment setup | Built-in ${secret:} + ${env:} | **Unified approach** | -| **Deployment Complexity** | Separate Terraform + K8s manifests | Single SC configuration | **Single source of truth** | - -### Operational Scalability - -| Metric | Terraform/Pulumi | Simple Container | Improvement | -|--------------------------------|-------------------------------|----------------------------|--------------------| -| **DevOps to Customer Ratio** | 1:10-20 customers | 1:100+ customers | **5x efficiency** | -| **Customer Onboarding Time** | 2-3 days | 5 minutes | **500x faster** | -| **Infrastructure Drift Risk** | High (manual management) | Low (template-based) | **Reduced errors** | -| **Cross-Region Deployment** | Duplicate infrastructure code | Single parent stack change | **DRY principle** | -| **Performance Tier Migration** | Manual infrastructure rebuild | One-line uses directive | **Zero downtime** | - -### Developer Experience - -| Feature | Terraform/Pulumi | Simple Container | Benefit | -|-----------------------------|--------------------------|-------------------------|---------------------------| -| **Learning Curve** | Months (cloud + IaC) | Days (business config) | **Faster onboarding** | -| **Deployment Autonomy** | Requires DevOps approval | Self-service deployment | **Independent teams** | -| **Environment Consistency** | Manual synchronization | Automatic inheritance | **Reduced bugs** | -| **Resource Allocation** | Complex calculations | Simple uses directive | **Simplified management** | -| **Scaling Configuration** | Multiple files/tools | Single scale block | **Unified interface** | - -### Cost and Resource Efficiency - -| Factor | Terraform/Pulumi | Simple Container | Savings | -|-----------------------------|-------------------------|-------------------------|-----------------------------| -| **Infrastructure Overhead** | Per-customer resources | Shared resource pools | **70% cost reduction** | -| **Operational Staff** | High DevOps requirement | Minimal DevOps overhead | **80% staff reduction** | -| **Resource Utilization** | Often over-provisioned | Right-sized sharing | **Better efficiency** | -| **Maintenance Burden** | Continuous per-customer | Template updates only | **Centralized maintenance** | -| **Monitoring Complexity** | Per-customer setup | Built-in observability | **Reduced tooling costs** | - -### Enterprise Readiness - -| Capability | Terraform/Pulumi | Simple Container | Advantage | -|--------------------------|--------------------------|------------------------------|----------------------------| -| **Multi-Region Support** | Complex state management | Parent stack per region | **Simplified geography** | -| **Disaster Recovery** | Manual backup strategies | Built-in resilience patterns | **Automated DR** | -| **Compliance Auditing** | Custom implementation | Namespace-based isolation | **Built-in compliance** | -| **Secret Rotation** | Manual processes | External manager integration | **Automated security** | -| **Access Control** | Complex IAM policies | Kubernetes RBAC + namespaces | **Simplified permissions** | - -### Real-World Scaling Scenarios - -| Scenario | Traditional Approach | Simple Container | Time Savings | -|-----------------------------|------------------------------|------------------------|------------------------| -| **Add 100 customers** | 100 Γ— infrastructure setup | 100 Γ— client config | **95% faster** | -| **Multi-region expansion** | Duplicate all infrastructure | Add parent stack | **90% less code** | -| **Performance tier change** | Infrastructure migration | Change uses directive | **99% faster** | -| **Security update** | Update all customer configs | Update parent template | **One-time change** | -| **Monitoring rollout** | Per-customer implementation | Template update | **Instant deployment** | - -## Why Simple Container Wins - -### 1. **Separation of Concerns Architecture** - -- **DevOps**: Manages infrastructure complexity once in parent stacks -- **Developers**: Focus on business logic in client configurations -- **Result**: Clear boundaries prevent configuration drift and operational errors - -### 2. **Built-in Multi-Tenancy** - -- **Native SaaS patterns** with parentEnv inheritance -- **Automatic customer isolation** through Kubernetes namespaces -- **Flexible resource allocation** using parent/parentEnv/uses directives - -### 3. **Operational Automation** - -- **Best practice templates** with proven deployment patterns -- **Built-in secret management** with ${secret:} and ${env:} support -- **Kubernetes-native features** leveraged automatically - -### 4. **Developer Productivity** - -- **Self-service deployment** without infrastructure expertise -- **5-minute customer onboarding** vs days with traditional approaches -- **Linear development velocity** regardless of customer count - -### 5. **Cost Optimization** - -- **70% cost reduction** through intelligent resource sharing -- **1 DevOps engineer per 100+ customers** vs 1 per 10-20 traditional -- **Automatic right-sizing** and scaling optimization - -**Simple Container transforms container orchestration from a complex infrastructure challenge into a simple configuration management task, enabling organizations to scale from startup to enterprise without operational complexity growth.** - -For SaaS companies and multi-tenant applications, Simple Container provides the perfect balance of developer productivity, operational efficiency, and enterprise-grade capabilities that traditional Terraform/Pulumi + Kubernetes deployments simply cannot match at scale. diff --git a/docs/docs/ai-assistant/index.md b/docs/docs/ai-assistant/index.md index 2c8640e1..684d1198 100644 --- a/docs/docs/ai-assistant/index.md +++ b/docs/docs/ai-assistant/index.md @@ -1,174 +1,37 @@ # AI Assistant -Simple Container's AI-powered project onboarding assistant provides intelligent setup and configuration guidance with two distinct modes aligned with our separation of concerns philosophy. +`sc assistant` is an interactive CLI that helps scaffold SC configurations +for an existing project. It analyses the repository (language, build system, +existing Dockerfile / docker-compose, cloud signals) and produces +`server.yaml`, `client.yaml`, and supporting files matching the detected +shape. -## 🎯 Two-Mode Architecture +Two modes: -### **Developer Mode** πŸ§‘β€πŸ’» -**For Application Teams** -- **Purpose**: Set up application-specific configurations -- **Generates**: `client.yaml`, `docker-compose.yaml`, `Dockerfile` -- **Analysis**: Automatic project tech stack detection -- **Focus**: Application deployment, scaling, dependencies +- **Developer mode** β€” generates `client.yaml`, `docker-compose.yaml`, and + a `Dockerfile` for an application. Run from inside an app repo. +- **DevOps mode** β€” generates a `server.yaml` plus provisioner config and + secret-backend wiring. Run from inside a platform/infrastructure repo. -### **DevOps Mode** πŸ› οΈ -**For Infrastructure Teams** -- **Purpose**: Set up shared infrastructure and resources -- **Generates**: `server.yaml`, `secrets.yaml`, provisioner config -- **Analysis**: Cloud provider selection and resource planning -- **Focus**: Shared resources, templates, infrastructure management - -## πŸš€ Quick Start - -### For Developers -```bash -# Analyze current project and generate application configs -sc assistant dev setup - -# Interactive mode with guided setup -sc assistant dev setup --interactive - -# Search documentation -sc assistant search "docker compose with postgres" -``` - -### For DevOps Teams ```bash -# Set up infrastructure for a new project -sc assistant devops setup - -# Configure cloud provider and shared resources -sc assistant devops setup --cloud aws --interactive +# In an app repo +sc assistant dev -# Start MCP server for external tools -sc assistant mcp --port 9999 +# In a platform repo +sc assistant devops ``` -## πŸ“‹ Available Commands +## MCP server -| Command | Mode | Description | -|---------|------|-------------| -| `sc assistant dev setup` | Developer | Generate client.yaml and compose files | -| `sc assistant dev analyze` | Developer | Analyze project tech stack | -| `sc assistant devops setup` | DevOps | Configure server.yaml and secrets | -| `sc assistant devops resources` | DevOps | Manage shared resources | -| `sc assistant search` | Both | Semantic documentation search | -| `sc assistant chat` | Both | Interactive assistant (Phase 3) | -| `sc assistant mcp` | Both | Start MCP server for external tools | +For programmatic / agentic use, `sc assistant` also exposes an MCP server. +Tools like Claude Code, Cursor, and [Forge](https://simple-forge.com) +consume it natively β€” they call SC primitives (templates, resources, +parent stacks) as first-class operations rather than guessing YAML. -## 🎭 Mode Comparison - -| Aspect | Developer Mode | DevOps Mode | -|--------|----------------|-------------| -| **Target Users** | Application developers | Infrastructure teams | -| **Project Analysis** | βœ… Full tech stack detection | ❌ Not needed | -| **Cloud Selection** | βšͺ Uses existing infrastructure | βœ… Primary decision point | -| **File Generation** | `client.yaml`, `docker-compose.yaml` | `server.yaml`, `secrets.yaml` | -| **Resource Focus** | Application dependencies | Shared infrastructure | -| **Complexity** | Higher (project analysis) | Lower (guided selection) | - -## πŸ”„ Typical Workflow - -### 1. DevOps Team Setup (First) ```bash -# DevOps sets up shared infrastructure -sc assistant devops setup --cloud aws -# Generates: server.yaml, secrets.yaml -# Creates: Database, storage, networking resources -``` - -### 2. Developer Team Setup (Second) -```bash -# Developers set up their applications -sc assistant dev setup -# Generates: client.yaml, docker-compose.yaml -# References: Parent resources from DevOps team +sc assistant mcp ``` -## 🌟 Key Features - -### **Intelligent Project Analysis** (Developer Mode) -- **Language Detection**: Node.js, Python, Go, Java, etc. -- **Framework Recognition**: Express, Django, Gin, Spring, etc. -- **Dependency Analysis**: Database, cache, messaging requirements -- **Architecture Patterns**: Microservice, monolith, serverless detection - -### **Cloud Provider Integration** (DevOps Mode) -- **AWS**: ECS Fargate, RDS, S3, ECR, Lambda -- **GCP**: GKE Autopilot, Cloud SQL, Cloud Storage, Cloud Run -- **Azure**: Container Apps, PostgreSQL, Blob Storage (Phase 2) -- **Kubernetes**: Native deployments, Helm operators - -### **Semantic Documentation Search** (Both Modes) -- **10,000+ Documents**: Indexed docs, examples, schemas -- **Sub-100ms Search**: Fast semantic similarity matching -- **Context Aware**: Results tailored to current project type -- **Multi-Source**: Documentation, examples, JSON schemas - -## πŸ“š Documentation Structure - -- **[Getting Started](getting-started.md)** - Quick setup for both modes -- **[Developer Mode](developer-mode.md)** - Application team workflows -- **[DevOps Mode](devops-mode.md)** - Infrastructure team workflows -- **[MCP Integration](mcp-integration.md)** - External tool integration -- **[Commands Reference](commands.md)** - Complete command documentation -- **[Examples](examples/)** - Real-world usage scenarios -- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions - -## πŸ”§ Integration Examples - -### Windsurf IDE Integration -```json -{ - "tools": [{ - "name": "simple-container-assistant", - "type": "mcp", - "endpoint": "http://localhost:9999/mcp" - }] -} -``` - -### VS Code Integration -```json -{ - "simple-container.assistant.mode": "developer", - "simple-container.assistant.autoAnalyze": true -} -``` - -## 🎯 Success Metrics - -- **Setup Time**: From 30+ minutes to under 5 minutes -- **Configuration Accuracy**: 95%+ generated configs work without modification -- **User Adoption**: Target 80%+ of new users use assistant for initial setup -- **Documentation Discovery**: 90%+ accuracy in finding relevant docs - -## πŸš€ Roadmap - -### **Phase 1** βœ… - Foundation (Complete) -- Documentation embedding system -- MCP server implementation -- Semantic search capabilities -- CLI command structure - -### **Phase 2** πŸ”„ - Analysis & Generation (In Progress) -- Project analysis engine -- Two-mode architecture implementation -- File generation system -- Cloud provider templates - -### **Phase 3** πŸ“‹ - Interactive Experience -- Chat interface implementation -- LLM integration (langchaingo) -- Conversational project setup -- Advanced context management - -### **Phase 4** 🏁 - Enterprise Features -- Advanced analytics and insights -- Team collaboration features -- Custom template creation -- Enterprise security and compliance - -Ready to get started? Choose your path: -- πŸ§‘β€πŸ’» **[Developer Mode Setup β†’](developer-mode.md)** -- πŸ› οΈ **[DevOps Mode Setup β†’](devops-mode.md)** +See the SC repo on GitHub for the MCP tool schema, deeper usage examples, +and the developer/devops mode internals. Those pages will surface in this +nav after a content audit pass. diff --git a/docs/docs/compliance/nist-sp-800-218-mapping.md b/docs/docs/compliance/nist-sp-800-218-mapping.md index 1e5a805e..24c3d66d 100644 --- a/docs/docs/compliance/nist-sp-800-218-mapping.md +++ b/docs/docs/compliance/nist-sp-800-218-mapping.md @@ -54,22 +54,22 @@ Secure Software Development Framework compliance mapping. | Requirement | Simple Container Feature | Status | |-------------|-------------------------|---------| -| Build process documented | Release workflow | βœ… Documented | +| Build process documented | Release workflow | Documented | ### SLSA Level 2: Build as Code | Requirement | Simple Container Feature | Status | |-------------|-------------------------|---------| -| Version controlled build | Pulumi infrastructure as code | βœ… Implemented | -| Build service generates provenance | SLSA v1.0 provenance | βœ… Implemented | -| Provenance distributed with artifact | Attestation attachment | βœ… Implemented | +| Version controlled build | Pulumi infrastructure as code | Implemented | +| Build service generates provenance | SLSA v1.0 provenance | Implemented | +| Provenance distributed with artifact | Attestation attachment | Implemented | ### SLSA Level 3: Hardened Build | Requirement | Simple Container Feature | Status | |-------------|-------------------------|---------| -| Signed provenance | Keyless or key-based signing | βœ… Implemented | -| Non-falsifiable provenance | Rekor transparency log | βœ… Implemented | +| Signed provenance | Keyless or key-based signing | Implemented | +| Non-falsifiable provenance | Rekor transparency log | Implemented | **SLSA Level Achieved: Level 2-3** (Level 3 when using keyless signing with Rekor) @@ -84,7 +84,7 @@ Secure Software Development Framework compliance mapping. | Third-party component testing | SBOM with dependencies | Full dependency tree in SBOM | | Attestation of conformance | Signed attestations | Cosign signatures with SBOM/provenance | -**Compliance Status:** βœ… Compliant +**Compliance Status:** Compliant ## CISA SBOM Requirements @@ -92,16 +92,17 @@ Secure Software Development Framework compliance mapping. | Element | Simple Container Feature | Status | |---------|-------------------------|---------| -| Supplier Name | Syft metadata | βœ… Included | -| Component Name | Package inventory | βœ… Included | -| Version of Component | Package versions | βœ… Included | -| Dependency Relationship | CycloneDX relationships | βœ… Included | -| Author of SBOM | Tool metadata | βœ… Included | -| Timestamp | GeneratedAt field | βœ… Included | +| Supplier Name | Syft metadata | Included | +| Component Name | Package inventory | Included | +| Version of Component | Package versions | Included | +| Dependency Relationship | CycloneDX relationships | Included | +| Author of SBOM | Tool metadata | Included | +| Timestamp | GeneratedAt field | Included | **SBOM Format Compliance:** -- βœ… CycloneDX 1.4+ (JSON/XML) -- βœ… SPDX 2.3+ (JSON/tag-value) + +- CycloneDX 1.4+ (JSON/XML) +- SPDX 2.3+ (JSON/tag-value) ## OpenSSF Scorecard @@ -258,4 +259,4 @@ jobs: - [OpenSSF Scorecard](https://github.com/ossf/scorecard) - [Sigstore](https://www.sigstore.dev/) - [CycloneDX](https://cyclonedx.org/) -- [SPDX](https://spdx.dev/) +- [SPDX](https://spdx.dev/) \ No newline at end of file diff --git a/docs/docs/concepts/kubernetes-namespaces.md b/docs/docs/concepts/kubernetes-namespaces.md index 0f2f5086..bb5b9ebc 100644 --- a/docs/docs/concepts/kubernetes-namespaces.md +++ b/docs/docs/concepts/kubernetes-namespaces.md @@ -98,4 +98,4 @@ Before migrating a stateful custom stack: 2. Run `sc deploy -P` to confirm the diff matches expectations. 3. After the migration, clear `claimRef` on the retained PV and re-bind it to the new PVC if you want to preserve the data β€” or accept the data is dev-only and let it recreate. -Stacks that don't define `persistentVolumes` (the typical case where state lives in managed services like Cloud SQL, RDS, Memorystore, or external MongoDB Atlas) are unaffected. +Stacks that don't define `persistentVolumes` (the typical case where state lives in managed services like Cloud SQL, RDS, Memorystore, or external MongoDB Atlas) are unaffected. \ No newline at end of file diff --git a/docs/docs/concepts/main-concepts.md b/docs/docs/concepts/main-concepts.md index e9339816..d4ee65d5 100644 --- a/docs/docs/concepts/main-concepts.md +++ b/docs/docs/concepts/main-concepts.md @@ -1,6 +1,6 @@ --- title: Main concepts -description: One of the key principles of Simple Container is the separation of concerns between infrastructure management and microservice deployment. +description: Parent stacks own shared infrastructure; service stacks own per-service deployment. SC composes them. platform: platform product: simple-container category: devguide @@ -9,275 +9,148 @@ guides: tutorials date: '2024-06-12' --- -# **Separation of Parent Stack and Service Stack in Simple Container** +# Parent stacks and service stacks -## **Architecture Overview** +Simple Container splits a deployment into two layers: + +- A **parent stack** (`server.yaml`) defines shared infrastructure β€” databases, + message queues, secret backends, DNS registrar, deployment templates. It's + written and maintained by whoever owns cloud-account state (usually DevOps + or a platform team). +- A **service stack** (`client.yaml`) defines one service that consumes the + parent. It references its parent by name, names which shared resources it + uses, and ships a runtime image plus configuration. It's written and + maintained by the team owning that service. + +This separation is the load-bearing design decision. Everything else in SC +follows from it. + +## Architecture overview ```mermaid graph TB - subgraph PS ["πŸ—οΈ PARENT STACK (DevOps Owned)"] - SY["πŸ“„ server.yaml
resources:
production:
postgres-db: ...
redis-cache: ...
s3-storage: ...
provisioner: ...
templates: ..."] - IR["Infrastructure Resources
β€’ Databases (RDS, MongoDB)
β€’ Storage (S3, GCS)
β€’ Clusters (EKS, GKE)
β€’ Networking, Security"] - PSN["πŸ‘₯ Managed by: DevOps Team
πŸ”„ Updated: Infrastructure changes"] + subgraph PS ["Parent stack (DevOps)"] + SY["server.yaml
resources:
production:
postgres-db: ...
redis-cache: ...
s3-storage: ...
provisioner: ...
templates: ..."] + IR["Shared resources
Databases (RDS, MongoDB)
Storage (S3, GCS)
Clusters (EKS, GKE)
Networking, secrets"] end - - subgraph SS ["πŸš€ SERVICE STACK (Developer Owned)"] - CY["πŸ“„ client.yaml
parent: org/infrastructure
config:
uses: [postgres-db, redis]
runs: [web-app]
env:
DB_URL: \${resource:...}"] - DC["πŸ“„ docker-compose.yaml
services:
web-app: ...
worker: ..."] - AS["Application Services
β€’ Microservices
β€’ Web Applications
β€’ Background Jobs
β€’ APIs & Services"] - SSN["πŸ‘©β€πŸ’» Managed by: Developers
πŸ”„ Updated: New services/features"] + + subgraph SS ["Service stack (developer)"] + CY["client.yaml
parent: org/infrastructure
config:
uses: [postgres-db, redis]
runs: [web-app]
env:
DB_URL: \${resource:...}"] + DC["docker-compose.yaml
services:
web-app: ...
worker: ..."] + AS["Application services
Microservices, web apps,
background jobs, APIs"] end - - subgraph DF ["πŸ“‹ DEPLOYMENT FLOW"] - S1["1️⃣ DevOps defines
infrastructure
(server.yaml)"] - S2["2️⃣ Developers define
services
(client.yaml)"] - S3["3️⃣ Simple Container
orchestrates
deployment"] - + + subgraph DF ["Deployment flow"] + S1["DevOps defines
infrastructure
(server.yaml)"] + S2["Developers define
services
(client.yaml)"] + S3["Simple Container
orchestrates
deployment"] + S1 --> S2 S2 --> S3 end - + PS --> SS SS -.-> PS - - classDef parentStack fill:#e1f5fe,stroke:#01579b,stroke-width:2px - classDef serviceStack fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px - classDef deployFlow fill:#fff8e1,stroke:#f57f17,stroke-width:2px - - class PS,SY,IR,PSN parentStack - class SS,CY,DC,AS,SSN serviceStack - class DF,S1,S2,S3 deployFlow -``` -**πŸ“ˆ SCALING BENEFITS:** + classDef parentStack fill:#0c1f3f,stroke:#3b82f6,stroke-width:2px,color:#dbeafe + classDef serviceStack fill:#1a1740,stroke:#a855f7,stroke-width:2px,color:#e9d5ff + classDef deployFlow fill:#0f2a2e,stroke:#22d3ee,stroke-width:2px,color:#cffafe -- πŸš€ **500x faster** customer onboarding (5 min vs 2-3 days) -- πŸ“Š **90% configuration reduction** (500 vs 5000+ lines) -- πŸ‘₯ **5x operational efficiency** (1 DevOps per 100+ customers) -- πŸ’° **70% cost reduction** through resource sharing -- ⚑ **Zero-downtime** service deployments - -## **Introduction** - -One of the key principles of **Simple Container** is the **separation of concerns** between **infrastructure management** and **microservice deployment**. -This is achieved by **separating the "parent stack" (managed by DevOps) from the "service stack" (managed by developers)**. - -This guide explains: - -βœ… **What the parent stack is and how it works** - -βœ… **What the service stack is and how it works** - -βœ… **How this separation benefits both DevOps and developers** - ---- - -# **1️⃣ What is the Parent Stack?** - -The **parent stack** is the **core infrastructure** required for microservices to run. It is **managed by DevOps** and provides: - -- **Cloud infrastructure** (Kubernetes clusters, AWS ECS clusters, databases, storage, networking) -- **Secrets management** (via Kubernetes Secrets, AWS Secrets Manager, or Google Secret Manager) -- **Centralized state management** (so infrastructure is consistent across environments) -- **Provisioning of shared resources** (databases, message queues, API gateways) - -### **Who Manages the Parent Stack?** -➑️ **DevOps teams** define and maintain the parent stack. - -### **When is the Parent Stack Modified?** -➑️ Only when **adding new infrastructure resources** (e.g., a new database, message queue, or cloud provider). - ---- - -# **2️⃣ What is the Service Stack?** + class PS,SY,IR parentStack + class SS,CY,DC,AS serviceStack + class DF,S1,S2,S3 deployFlow +``` -The **service stack** represents an **individual microservice** that a **developer wants to deploy**. It consumes infrastructure from the **parent stack** but does not modify it. +## What's in a parent stack -- **Developers only configure their microservice's deployment settings** -- **Microservices automatically connect to infrastructure provisioned by the parent stack** -- **No need to request DevOps intervention for every new service** +A parent stack owns cloud-account state. Concretely: -### **Who Manages the Service Stack?** -➑️ **Developers** define and maintain their own service configurations. +- Cloud infrastructure β€” Kubernetes clusters, ECS clusters, databases, storage, networking +- Secret backends (AWS Secrets Manager, GCP Secret Manager, Kubernetes Secrets) +- Centralized state (consistent across environments) +- Shared resources that multiple services use (databases, queues, registrars) -### **When is the Service Stack Modified?** -➑️ Whenever a **new microservice is added** or an **existing service is updated**. +The parent stack changes only when infrastructure changes β€” new database engine, +additional environment, new cloud account. It does *not* change for each new +service deployment. ---- +## What's in a service stack -# **3️⃣ Key Differences Between Parent Stack and Service Stack** +A service stack owns one service. It declares: -| Feature | Parent Stack (DevOps) | Service Stack (Developers) | -|------------------------|-------------------------------------------------|-------------------------------------| -| **Purpose** | Defines shared infrastructure | Defines microservice deployment | -| **Managed By** | DevOps | Developers | -| **Configuration File** | `server.yaml` | `client.yaml` | -| **Modified When** | Infrastructure changes (new DB, queue, cluster) | New service added or updated | -| **Includes** | Databases, secrets, cloud resources | Microservice dependencies & scaling | +- Which parent stack it belongs to (`parent: `) +- Which shared resources it uses (`uses: [postgres-db, redis]`) +- What runs (container image, docker-compose, or static bundle) +- Per-environment configuration and secrets ---- +A service stack changes every time the service is updated. It never touches +cloud-account state directly β€” that's the parent's job. -# **4️⃣ Why This Separation Matters: Scaling Advantages** +## Comparison -## **Multi-Dimensional Resource Allocation** +| Aspect | Parent stack | Service stack | +|---|---|---| +| **Purpose** | Defines shared infrastructure | Defines one service deployment | +| **Owned by** | Platform / DevOps | Application developers | +| **Config file** | `server.yaml` | `client.yaml` | +| **Changes when** | Infrastructure topology changes (new DB, env, cluster) | Service code or config changes | +| **Includes** | Databases, queues, registrars, templates, secret backends | Image, runtime config, env vars, resource references | -**Traditional Approach - Manual Resource Management:** -```yaml -# Each customer needs separate infrastructure definition -resource "aws_ecs_cluster" "customer_a" { - name = "customer-a-cluster" -} +## Resource sharing -resource "aws_rds_instance" "customer_a_db" { - identifier = "customer-a-database" - engine = "postgres" - # ... complex configuration -} -``` +The parent stack's `resources` section can define multiple instances of the +same resource type, and child stacks pick which one they want via `uses`. +A common pattern: a shared resource pool for standard tenants, dedicated +resources for premium tenants. -**Simple Container - Flexible Resource Sharing:** ```yaml -# server.yaml - Define resource pools once +# server.yaml resources: - production: - resources: - # Shared resources for standard customers - mongodb-shared-us: - type: mongodb-atlas - config: - clusterName: shared-us - instanceSize: M30 - - # Dedicated resources for enterprise - mongodb-enterprise-1: - type: mongodb-atlas - config: - clusterName: enterprise-1 - instanceSize: M80 - -# client.yaml - Customers choose resources flexibly -stacks: - standard-customer-1: - uses: [mongodb-shared-us] # Shared resource - - enterprise: - uses: [mongodb-enterprise-1] # Dedicated resource + resources: + production: + resources: + mongodb-shared-us: + type: mongodb-atlas + config: + clusterName: shared-us + instanceSize: M30 + mongodb-enterprise-1: + type: mongodb-atlas + config: + clusterName: enterprise-1 + instanceSize: M80 ``` -## **Core Scaling Benefits:** - -- **Developers focus on coding, not cloud infrastructure** - **15 minutes** to first deployment vs **2-3 days** -- **DevOps standardizes infrastructure without worrying about microservices** - **Template updates apply to all customers** -- **Adding a new microservice is self-service** - **5 minutes** vs **1-2 days** DevOps bottleneck -- **Security is maintained by isolating infrastructure from microservices** - **Automatic namespace isolation** -- **Resource Pool Management** - Define resources once, allocate flexibly -- **Cost Optimization** - Share resources among compatible customers -- **Easy Migration** - Move customers between resource pools by changing `uses` directive - -This separation **scales exceptionally well** as organizations grow, preventing bottlenecks where **DevOps must manually configure every microservice**. - ---- - -# **5️⃣ Quantified Scaling Benefits** - -## **Operational Scalability Metrics** - -| Metric | Traditional Approach | Simple Container | Improvement | -|-------------------------------|-------------------------------|-----------------------------|--------------------| -| **DevOps to Customer Ratio** | 1:10-20 customers | 1:100+ customers | **5x efficiency** | -| **Customer Onboarding Time** | 2-3 days | 5 minutes | **500x faster** | -| **Configuration Lines** | 5000+ lines for 100 customers | 500 lines for 100 customers | **90% reduction** | -| **Infrastructure Drift Risk** | High (manual management) | Low (template-based) | **Reduced errors** | - -## **Development Velocity Impact** - -**Traditional Approach:** - -- **Time to First Deployment**: 2-3 days (infrastructure setup) -- **Developer Onboarding**: 2-4 weeks (Kubernetes/AWS training) -- **Feature Development**: Blocked by infrastructure changes - -**Simple Container:** - -- **Time to First Deployment**: 15 minutes (configuration only) -- **Developer Onboarding**: 1-2 hours (simple YAML configuration) -- **Feature Development**: Independent of infrastructure - -## **Cost Optimization Results** - -**Simple Container achieves:** - -- **70% cost reduction** through intelligent resource sharing -- **80% staff reduction** in operational overhead -- **1 DevOps engineer per 100+ customers** vs 1 per 10-20 traditional -- **Automatic right-sizing** and scaling optimization - ---- - -# **6️⃣ Real-World Scaling Scenarios** - -## **Scenario 1: Adding 100 New Customers** - -**Traditional Kubernetes/ECS:** -```bash -# For each of 100 customers, DevOps must: -1. Create namespace/cluster -2. Define deployment YAML (50+ lines each) -3. Configure ingress and SSL certificates -4. Set up monitoring and logging -5. Create secrets manually - -# Result: 5000+ lines of configuration -# Time: 2-3 days per customer = 200-300 days -``` - -**Simple Container:** ```yaml -# For each of 100 customers, developers add: -customer-001: - parentEnv: production - config: - domain: customer001.myapp.com - secrets: - CUSTOMER_SETTINGS: ${env:CUSTOMER_001_SETTINGS} - -# Result: 5 lines per customer = 500 lines total -# Time: 5 minutes per customer = 8.3 hours total -``` - -## **Scenario 2: Performance Tier Migration** - -**Traditional Approach:** - -- Manual infrastructure rebuild -- Data migration downtime -- Complex rollback procedures -- High risk of errors +# client.yaml β€” standard tenant +stacks: + customer-acme: + parent: org/infrastructure + config: + uses: [mongodb-shared-us] -**Simple Container:** -```yaml -# Before: Customer on shared resources -customer-enterprise: - uses: [mongodb-shared-us] - -# After: Customer on dedicated resources (one line change!) -customer-enterprise: - uses: [mongodb-enterprise-dedicated] - -# Automatic migration, zero downtime, easy rollback +# client.yaml β€” enterprise tenant +stacks: + customer-megacorp: + parent: org/infrastructure + config: + uses: [mongodb-enterprise-1] ``` ---- - -# **Conclusion** +Switching a tenant between resource pools is a one-line `client.yaml` change. +The migration happens at the next deploy. -The **separation of parent stack and service stack** in Simple Container ensures: +Note: the nesting in `resources` is intentional β€” three levels deep +(`resources.resources..resources.`). The outer +`resources` is the per-stack container; the inner `resources` is the +per-environment map; the innermost is the resource map. See +[supported-resources](../reference/supported-resources.md) for the full schema. -- **500x faster customer onboarding** (5 minutes vs 2-3 days) -- **90% reduction in configuration complexity** (500 vs 5000+ lines) -- **5x operational efficiency** (1 DevOps per 100+ vs 10-20 customers) -- **70% cost reduction** through intelligent resource sharing -- **Zero downtime migrations** with one-line configuration changes -- **Developer self-service** without infrastructure expertise requirements +## Programmatic access -By adopting this separation, organizations can **scale from startup to enterprise without operational complexity growth**, transforming container orchestration from a complex infrastructure challenge into a simple configuration management task. \ No newline at end of file +Both file shapes are stable: SC's Go types in `pkg/api/` (`ServerDescriptor`, +`ClientDescriptor`) define the canonical schema. Tools that emit SC YAML +programmatically can target these structures directly. [Forge](https://simple-forge.com) +consumes the same primitives via the MCP server β€” when a Forge workflow run +needs a deployment, it produces `server.yaml` / `client.yaml` of the same +shape documented here. \ No newline at end of file diff --git a/docs/docs/concepts/motivation.md b/docs/docs/concepts/motivation.md deleted file mode 100644 index c21432d7..00000000 --- a/docs/docs/concepts/motivation.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Motivation -description: Description of why Simple Container is a useful tool for development of services -platform: platform -product: simple-container -category: devguide -subcategory: learning -guides: tutorials -date: '2024-06-12' ---- - -# **Why Simple Container?** - -In today's fast-paced software development environment, organizations must deploy and manage **dozens or even hundreds of microservices** efficiently. Traditional **CI/CD pipelines** often require **significant DevOps effort**, complex infrastructure provisioning, and manual management of microservices. **Simple Container** offers a **game-changing approach** that simplifies deployment, automates infrastructure management, and accelerates software delivery. - -This page explores why organizations should adopt **`sc`** for their **CI/CD pipelines**, highlighting its **ease of use, automation capabilities, cloud-agnostic nature, and security features**. - -As organizations embrace **microservices architectures**, they face a fundamental challenge: **how to efficiently manage, deploy, and scale multiple services without creating complexity for developers and DevOps teams**. Traditional methods of provisioning and deploying microservices often involve **manual infrastructure management, complex CI/CD pipelines, and extensive collaboration between developers and DevOps**. - -Simple Container is a **powerful yet lightweight tool** designed to streamline **microservices deployment and delivery**. It provides a **developer-friendly approach** while keeping **infrastructure management centralized and isolated from service deployment**. By bridging the gap between **DevOps and development teams**, `sc` enables organizations to **move faster, reduce bottlenecks, and simplify their microservices workflow**. - -For the detailed use-cases of what you can do with Simple Container, please read [Howto](/howto/use-cases/) section. - ---- - -## **1️⃣ The Challenges of Microservices Deployment** - -Microservices offer **flexibility, scalability, and modularity**, but **deploying and maintaining them is complex**. In a traditional setup: - -- **Developers must coordinate with DevOps** teams to configure cloud resources (databases, networking, secrets, storage). -- **Infrastructure provisioning requires expertise in Infrastructure as Code (IaC) tools** like Terraform or Pulumi. -- **Deployments are tightly coupled with CI/CD pipelines**, requiring manual configuration for every new service. -- **Secrets management and environment-specific configurations require additional setup**, often leading to security risks. - -As organizations scale, these challenges become **major bottlenecks**, slowing down **innovation and delivery cycles**. - ---- - -## **2️⃣ What is Simple Container?** - -Simple Container is a **cloud-agnostic deployment tool** designed specifically for **microservices**. It provides: - -βœ… **A unified way to deploy services without DevOps intervention.** - -βœ… **A declarative configuration approach using simple YAML files.** - -βœ… **Built-in secrets management and cloud resource integration.** - -βœ… **Seamless support for Kubernetes, AWS ECS Fargate, and Google Cloud Run.** - -At its core, `sc` allows **developers to focus on coding**, while **DevOps teams manage infrastructure separately**. This **clear separation of concerns** eliminates the need for developers to understand cloud provisioning and allows **DevOps to standardize infrastructure across all services**. - ---- - -## **3️⃣ Where Simple Container Fits in Microservices Development** - -### **πŸ”Ή Empowering Developers with Hassle-Free Deployments** -With `sc`, developers no longer need to: - -- **Request infrastructure changes from DevOps.** -- **Manually configure networking, storage, or database connections.** -- **Write complex deployment scripts.** - -Instead, they can **deploy new microservices seamlessly**, using simple configurations that **automatically integrate with the existing infrastructure**. - -This **reduces friction between development and operations**, enabling teams to launch new features **faster and more reliably**. - -### **πŸ”Ή A Single Source of Truth for Infrastructure** -While developers focus on building services, **DevOps teams retain full control over infrastructure**. In `sc`: - -- Cloud resources such as **databases, message queues, storage, and networking** are centrally defined. -- **Secrets and environment-specific configurations are managed securely.** -- **All infrastructure is provisioned via a single, structured configuration, reducing inconsistencies.** - -This **eliminates duplication, reduces security risks, and ensures a consistent setup across multiple services**. - -### **πŸ”Ή Automating CI/CD Without Extra Complexity** -Traditional CI/CD pipelines require: - -- **Setting up deployment scripts for every service.** -- **Managing multiple cloud provider integrations.** -- **Manually configuring rollbacks and service scaling.** - -With `sc`, these processes are **built-in**. Deployments happen **without manually modifying CI/CD pipelines**, and rollback mechanisms ensure **safer deployments with minimal downtime**. - ---- - -## **4️⃣ Where Simple Container Fits in Microservices Delivery** - -### **πŸ”Ή Cloud-Agnostic Deployment for Enterprise Flexibility** -Organizations today operate in **multi-cloud and hybrid environments**. Some workloads run **on Kubernetes clusters**, while others leverage **managed services like AWS ECS Fargate or Google Cloud Run**. - -Simple Container enables **seamless deployment across all these platforms** without requiring developers to modify service configurations. This **future-proofs deployments**, allowing teams to switch cloud providers **without rewriting infrastructure code**. - -### **πŸ”Ή Security & Compliance Without Extra Tools** -Security is a **critical concern** in microservices delivery. Managing **secrets and environment-specific credentials** across multiple services is challenging. - -`sc` offers **built-in secrets management**, ensuring that credentials are: - -- **Stored securely in cloud-native secret managers (AWS Secrets Manager, GCP Secret Manager, Kubernetes Secrets).** -- **Automatically injected into services at runtime.** -- **Never exposed in plaintext or CI/CD logs.** - -This **reduces security risks while keeping deployments efficient**. - -### **πŸ”Ή Scalability & Reliability for Growing Organizations** -As organizations scale, microservices need to: - -- **Spin up new instances dynamically based on demand.** -- **Auto-scale without manual intervention.** -- **Ensure high availability and fault tolerance.** - -Simple Container integrates **seamlessly with cloud-native scaling solutions**, ensuring that services remain **resilient, highly available, and cost-efficient**. - ---- - -## **5️⃣ Why Organizations Should Adopt `sc`: Quantified Scaling Benefits** - -### **βœ… Faster Microservice Deployment - 500x Speed Improvement** - -- **Customer Onboarding**: **5 minutes** vs **2-3 days** traditional approaches -- **Time to First Deployment**: **15 minutes** vs **2-3 days** infrastructure setup -- **Developer Onboarding**: **1-2 hours** vs **2-4 weeks** Kubernetes/AWS training -- Developers can **self-deploy services** without waiting for DevOps approval - -### **βœ… Reduced DevOps Overhead - 5x Operational Efficiency** - -- **DevOps to Customer Ratio**: **1:100+ customers** vs **1:10-20** traditional -- **Configuration Complexity**: **90% reduction** (500 vs 5000+ lines for 100 customers) -- **Infrastructure Drift Risk**: **Low (template-based)** vs **High (manual management)** -- DevOps focuses **only on infrastructure**, reducing operational burden by **80%** - -### **βœ… Built-in Security & Secrets Management - Zero External Tools** - -- **Automatic namespace isolation** for multi-tenant security -- **Built-in secrets management** with `${secret:}` and `${env:}` support -- **External secret manager integration** ready (AWS Secrets Manager, Vault, Azure Key Vault) -- Cloud-native integrations ensure **compliance with security policies** - -### **βœ… Cloud-Agnostic & Future-Proof - Zero Downtime Migrations** - -- **Performance tier migration**: **One-line change** vs **manual infrastructure rebuild** -- **Multi-region expansion**: **Single parent stack change** vs **duplicate infrastructure code** -- Works with **Kubernetes, AWS, and Google Cloud** seamlessly -- Migrating workloads **requires no changes to service configurations** - -### **βœ… CI/CD Without Complexity - 70% Cost Reduction** - -- **Infrastructure cost savings**: **70% reduction** through intelligent resource sharing -- **Operational staff reduction**: **80% fewer** DevOps engineers needed -- **Resource utilization**: **Right-sized sharing** vs **often over-provisioned** -- **No need for external deployment tools**β€”CI/CD is built into `sc` - ---- - -## **6️⃣ Real-World Scaling Impact** - -### **Adding 100 New Customers** - -**Traditional Approach:** -- **Time**: 2-3 days per customer = **200-300 days total** -- **Configuration**: 5000+ lines of infrastructure code -- **Team**: Requires DevOps expertise for each deployment - -**Simple Container:** -- **Time**: 5 minutes per customer = **8.3 hours total** -- **Configuration**: 500 lines total (5 lines per customer) -- **Team**: Developers can self-serve, no DevOps bottleneck - -### **Multi-Region Expansion** - -**Traditional**: Duplicate entire infrastructure for each region -**Simple Container**: Single parent stack change, customers choose regions easily - -### **Performance Tier Migration** - -**Traditional**: Manual infrastructure rebuild, downtime required -**Simple Container**: One-line configuration change, zero downtime - ---- - -## **Conclusion** - -Simple Container is a **revolutionary tool** for organizations adopting **microservices architectures**. By delivering **quantified scaling advantages**, `sc` transforms container orchestration from a complex infrastructure challenge into a simple configuration management task. - -**Proven Results:** -- **500x faster customer onboarding** (5 minutes vs 2-3 days) -- **90% reduction in configuration complexity** (500 vs 5000+ lines) -- **5x operational efficiency** (1 DevOps per 100+ vs 10-20 customers) -- **70% cost reduction** through intelligent resource sharing -- **Zero downtime migrations** with one-line configuration changes - -For any organization scaling microservices, `sc` presents a **compelling alternative** to traditional CI/CD pipelines, offering **automation, security, and ease of use**β€”all while enabling **scale from startup to enterprise without operational complexity growth**. diff --git a/docs/docs/concepts/template-placeholders-advanced.md b/docs/docs/concepts/template-placeholders-advanced.md index 3685027c..589a4586 100644 --- a/docs/docs/concepts/template-placeholders-advanced.md +++ b/docs/docs/concepts/template-placeholders-advanced.md @@ -187,6 +187,7 @@ Google Cloud Storage bucket with S3-compatible access via HMAC keys. **Auto-injected Environment Variables:** **Bucket-Specific Variables** (where `BUCKET_NAME` is the sanitized bucket name): + - `GCS__BUCKET` - Bucket name - `GCS__LOCATION` - Bucket location/region - `GCS__ACCESS_KEY` - HMAC access key ID (secret) @@ -194,6 +195,7 @@ Google Cloud Storage bucket with S3-compatible access via HMAC keys. - `GCS__ENDPOINT` - GCS S3-compatible endpoint **S3-Compatible Variables** (for applications expecting AWS S3): + - `S3__BUCKET` - Bucket name - `S3__REGION` - Bucket location/region - `S3__ACCESS_KEY` - HMAC access key ID (secret) @@ -201,6 +203,7 @@ Google Cloud Storage bucket with S3-compatible access via HMAC keys. - `S3__ENDPOINT` - GCS S3-compatible endpoint **Generic Variables** (when only one bucket is used): + - `GCS_BUCKET` - Bucket name - `GCS_LOCATION` - Bucket location - `GCS_ACCESS_KEY` - HMAC access key ID (secret) @@ -208,6 +211,7 @@ Google Cloud Storage bucket with S3-compatible access via HMAC keys. - `GCS_ENDPOINT` - GCS S3-compatible endpoint **AWS SDK Compatible Variables** (for seamless AWS SDK integration): + - `AWS_ACCESS_KEY_ID` - HMAC access key ID (secret) - `AWS_SECRET_ACCESS_KEY` - HMAC secret key (secret) - `S3_ENDPOINT` - GCS S3-compatible endpoint @@ -215,6 +219,7 @@ Google Cloud Storage bucket with S3-compatible access via HMAC keys. - `S3_REGION` - Bucket location **Template Placeholders:** + - `${resource:bucket-name.bucket}` - Bucket name - `${resource:bucket-name.location}` - Bucket location - `${resource:bucket-name.access-key}` - HMAC access key ID @@ -344,6 +349,7 @@ MongoDB Atlas database cluster connection details and credentials. - `${resource:mongodb-name.oplogUri}` - MongoDB oplog connection string **For Dependencies** (when used via `dependencies` section): + - `${dependency:dep-name.uri}` - Full MongoDB connection string for dependency - `${dependency:dep-name.user}` - Database username for dependency - `${dependency:dep-name.password}` - Database password for dependency @@ -470,4 +476,4 @@ stacks: 3. **Leverage Dependencies** - Share resources between services using the dependencies section 4. **Follow Naming Conventions** - Use descriptive resource names that map to clear environment variables -This system makes Simple Container deployments truly declarative - you declare what resources you need, and Simple Container handles all the connection details automatically. +This system makes Simple Container deployments truly declarative - you declare what resources you need, and Simple Container handles all the connection details automatically. \ No newline at end of file diff --git a/docs/docs/concepts/template-placeholders.md b/docs/docs/concepts/template-placeholders.md index 16898170..b2bb9360 100644 --- a/docs/docs/concepts/template-placeholders.md +++ b/docs/docs/concepts/template-placeholders.md @@ -586,15 +586,15 @@ region: "${env:AWS_REGION}" # Good - relative to project root (works in all environments) dockerComposeFile: docker-compose.yaml # References ${project:root}/docker-compose.yaml image: - dockerfile: ${project:root}/Dockerfile # βœ… Full path to file - context: ${project:root} # βœ… Directory path + dockerfile: ${project:root}/Dockerfile # Full path to file + context: ${project:root} # Directory path # Also good - explicit git root for git-specific operations buildContext: ${git:root}/build -# ❌ COMMON MISTAKE - Missing filename +# COMMON MISTAKE - Missing filename image: - dockerfile: ${project:root} # ❌ This is a directory, not a file! + dockerfile: ${project:root} # This is a directory, not a file! # Avoid - absolute paths that may not exist dockerComposeFile: /home/user/project/docker-compose.yaml @@ -729,9 +729,9 @@ stacks: ## **See Also** -- [Supported Resources Reference](supported-resources.md) - Complete resource configuration guide -- [Examples Directory](examples/) - Production-tested configuration examples -- [Parent Stack Examples](examples/parent-stacks/) - Multi-region and hybrid cloud configurations -- [Authentication Guide](authentication.md) - Setting up auth configurations for template placeholders +- [Supported Resources Reference](../reference/supported-resources.md) β€” complete resource configuration guide +- [Examples](../examples/README.md) β€” production-tested configuration examples +- [Parent Stack Examples](../examples/parent-stacks/index.md) β€” multi-region and hybrid cloud configurations +- [Secrets Management](../guides/secrets-management.md) β€” setting up auth configurations for template placeholders -This template system enables Simple Container to provide flexible, reusable, and secure configuration management across different environments and deployment scenarios. +This template system enables Simple Container to provide flexible, reusable, and secure configuration management across different environments and deployment scenarios. \ No newline at end of file diff --git a/docs/docs/concepts/vertical-pod-autoscaler.md b/docs/docs/concepts/vertical-pod-autoscaler.md index 9d6a5713..7b99304c 100644 --- a/docs/docs/concepts/vertical-pod-autoscaler.md +++ b/docs/docs/concepts/vertical-pod-autoscaler.md @@ -17,17 +17,17 @@ date: '2024-12-07' ## **Key Benefits** -### **πŸ’° Cost Optimization** +### **Cost Optimization** - **Prevents over-provisioning**: Reduces wasted resources and cloud costs - **Right-sizing**: Automatically adjusts to actual usage patterns - **Resource efficiency**: Optimizes cluster utilization -### **πŸš€ Performance Optimization** +### **Performance Optimization** - **Prevents resource starvation**: Ensures adequate resources during load spikes - **Automatic scaling**: Responds to changing workload demands - **Reduced manual tuning**: Eliminates guesswork in resource allocation -### **πŸ”§ Operational Efficiency** +### **Operational Efficiency** - **Hands-off management**: Reduces manual resource configuration - **Data-driven decisions**: Based on actual usage metrics - **Continuous optimization**: Adapts to changing application behavior @@ -165,6 +165,7 @@ vpa: ``` Valid values: + - `RequestsAndLimits` (default) β€” VPA scales both. Equivalent to omitting the field. - `RequestsOnly` β€” VPA scales only `requests`; `limits` stay at the values in the underlying deployment template. @@ -345,6 +346,6 @@ This separation ensures that VPA configuration follows Simple Container's princi ## **Next Steps** -- [VPA Configuration Example](../examples/kubernetes-vpa/) - Complete VPA setup example +- [VPA Configuration Example](../examples/kubernetes-vpa/README.md) - Complete VPA setup example - [GKE Autopilot Guide](../guides/parent-gcp-gke-autopilot.md) - VPA with GKE Autopilot -- [Supported Resources Reference](../reference/supported-resources.md) - VPA configuration reference +- [Supported Resources Reference](../reference/supported-resources.md) - VPA configuration reference \ No newline at end of file diff --git a/docs/docs/examples/README.md b/docs/docs/examples/README.md index f6aedd31..18694292 100644 --- a/docs/docs/examples/README.md +++ b/docs/docs/examples/README.md @@ -68,6 +68,7 @@ This directory contains production-tested Simple Container configurations based ## Usage Each example directory contains: + - `client.yaml` - Service deployment configuration - `server.yaml` - Parent stack with resource definitions (when applicable) - `README.md` - Specific documentation for the example @@ -87,4 +88,4 @@ All examples use anonymized domains like `example.com`, `mycompany.com`, etc., a - **Blockchain**: Smart contract integration patterns - **Kubernetes Affinity**: Node pool isolation, pod scheduling, performance optimization - **Enterprise Scheduling**: Multi-tier architectures with workload separation -- **Resource Management**: CPU and memory requests/limits optimization, backward compatibility +- **Resource Management**: CPU and memory requests/limits optimization, backward compatibility \ No newline at end of file diff --git a/docs/docs/examples/advanced-configs/high-resource/README.md b/docs/docs/examples/advanced-configs/high-resource/README.md index ba8c48bc..ff0b6924 100644 --- a/docs/docs/examples/advanced-configs/high-resource/README.md +++ b/docs/docs/examples/advanced-configs/high-resource/README.md @@ -63,6 +63,7 @@ This example shows how to deploy a high-resource code execution environment with ## Parent Stack Requirements This example requires a parent stack that provides: + - ECS deployment with high-resource support - External Kubernetes cluster integration - Secrets management for OAuth and registry credentials @@ -73,4 +74,4 @@ This example requires a parent stack that provides: - **High Cost**: 32GB/16CPU allocation is expensive - **Resource Optimization**: Consider auto-scaling based on usage - **Pod Lifecycle**: 10-minute timeout for cost control -- **Storage Management**: Ephemeral storage cleanup after execution +- **Storage Management**: Ephemeral storage cleanup after execution \ No newline at end of file diff --git a/docs/docs/examples/advanced-configs/index.md b/docs/docs/examples/advanced-configs/index.md index c54652c8..9e295bce 100644 --- a/docs/docs/examples/advanced-configs/index.md +++ b/docs/docs/examples/advanced-configs/index.md @@ -215,6 +215,7 @@ stacks: ``` **Features:** + - Multi-cloud deployment (AWS, GCP, Azure) - Geographic distribution - Cloud-specific resource utilization @@ -253,4 +254,4 @@ sc deploy -s myapp -e production - **Use feature flags** for controlled feature rollouts - **Implement proper secret management** across environments - **Configure network policies** for security isolation -- **Use persistent storage** for stateful applications +- **Use persistent storage** for stateful applications \ No newline at end of file diff --git a/docs/docs/examples/cicd-github-actions/README.md b/docs/docs/examples/cicd-github-actions/README.md index 81280fec..0c142299 100644 --- a/docs/docs/examples/cicd-github-actions/README.md +++ b/docs/docs/examples/cicd-github-actions/README.md @@ -4,10 +4,11 @@ This directory contains practical examples for setting up continuous integration ## Examples Overview -### [Basic Setup](basic-setup/) +### [Basic Setup](basic-setup/README.md) A simple staging/production pipeline setup with automatic deployment to staging and manual approval for production. **Features:** + - Automatic staging deployment on main branch push - Manual production deployment with approval - Slack/Discord notifications @@ -15,10 +16,11 @@ A simple staging/production pipeline setup with automatic deployment to staging **Best for:** Small teams, simple applications, getting started with CI/CD -### [Multi-Stack Deployment](multi-stack/) +### [Multi-Stack Deployment](multi-stack/README.md) Complex deployment pipeline managing multiple related stacks (infrastructure, databases, applications). **Features:** + - Infrastructure-first deployment order - Dependency management between stacks - Cross-stack resource sharing @@ -26,10 +28,11 @@ Complex deployment pipeline managing multiple related stacks (infrastructure, da **Best for:** Microservices architecture, complex applications with multiple components -### [Preview Deployments](preview-deployments/) +### [Preview Deployments](preview-deployments/README.md) PR-based preview environments for testing changes before merging to main. **Features:** + - Automatic preview deployment on PR creation - Preview environment cleanup on PR close - Temporary domain assignment @@ -37,10 +40,11 @@ PR-based preview environments for testing changes before merging to main. **Best for:** Teams that want to test changes in isolation, QA processes -### [Advanced Notifications](advanced-notifications/) +### [Advanced Notifications](advanced-notifications/README.md) Comprehensive notification setup with multiple channels and custom messaging. **Features:** + - Multi-channel notifications (Slack, Discord, Telegram) - Custom notification templates - Status-specific messaging @@ -98,6 +102,7 @@ values: ### GitHub Secrets Setup **Only ONE GitHub secret required:** + - `SC_CONFIG` - Simple Container configuration with SSH key pair to decrypt repository secrets **All notification webhooks are configured in your secrets.yaml file and managed by Simple Container's secrets system.** @@ -166,16 +171,19 @@ config: ### Common Issues **Workflow not triggering:** + - Check branch protection rules - Verify workflow file syntax - Ensure proper event triggers configured **Authentication errors:** + - Verify GitHub secrets are properly set - Check cloud provider credential validity - Confirm Simple Container configuration **Deployment failures:** + - Enable verbose logging in GitHub Actions (add `verbose: 'true'` to action inputs) - Review workflow logs in GitHub Actions - Validate server.yaml configuration locally @@ -200,6 +208,7 @@ To add a new example: ## Next Steps After setting up CI/CD: -- Explore **[Advanced Deployment Patterns](../../advanced/deployment-patterns.md)** + +- Review **[Best Practices](../../advanced/best-practices.md)** - Review **[Secrets Management](../../guides/secrets-management.md)** -- Set up **[DNS Management](../../guides/dns-management.md)** for custom domains +- Set up **[DNS Management](../../guides/dns-management.md)** for custom domains \ No newline at end of file diff --git a/docs/docs/examples/cicd-github-actions/advanced-notifications/README.md b/docs/docs/examples/cicd-github-actions/advanced-notifications/README.md index 67a23274..3012574f 100644 --- a/docs/docs/examples/cicd-github-actions/advanced-notifications/README.md +++ b/docs/docs/examples/cicd-github-actions/advanced-notifications/README.md @@ -5,6 +5,7 @@ This example demonstrates comprehensive notification setup with multiple channel ## Overview This setup provides: + - **Multi-channel notifications** (Slack, Discord, Telegram) - **Status-specific messaging** with custom templates - **Team mentions and escalations** based on environment @@ -51,7 +52,7 @@ cicd: # Custom templates templates: success-detailed: - title: "βœ… Deployment Successful" + title: "Deployment Successful" color: "good" fields: - name: "Environment" @@ -67,7 +68,7 @@ cicd: url: "${monitoring:dashboard-url}" failure-critical: - title: "🚨 CRITICAL: Production Deployment Failed" + title: "CRITICAL: Production Deployment Failed" color: "danger" urgency: "high" fields: @@ -135,7 +136,7 @@ For production environments, you can configure additional notification channels "type": "header", "text": { "type": "plain_text", - "text": "βœ… Deployment Successful" + "text": "Deployment Successful" } }, { @@ -179,7 +180,7 @@ For production environments, you can configure additional notification channels "type": "header", "text": { "type": "plain_text", - "text": "🚨 Deployment Failed" + "text": "Deployment Failed" } }, { @@ -207,13 +208,13 @@ For production environments, you can configure additional notification channels "elements": [ { "type": "button", - "text": {"type": "plain_text", "text": "πŸ” View Logs"}, + "text": {"type": "plain_text", "text": "View Logs"}, "url": "${deployment:logs-url}", "style": "danger" }, { "type": "button", - "text": {"type": "plain_text", "text": "πŸ”„ Retry"}, + "text": {"type": "plain_text", "text": "Retry"}, "url": "${deployment:retry-url}", "style": "primary" } @@ -277,6 +278,6 @@ Configure notification webhooks: ## Next Steps After setting up advanced notifications: -- **[Basic Setup](../basic-setup/)** - Simple notification patterns -- **[Multi-Stack Deployment](../multi-stack/)** - Complex deployment notifications -- **[Preview Deployments](../preview-deployments/)** - PR-based notifications +- **[Basic Setup](../basic-setup/README.md)** - Simple notification patterns +- **[Multi-Stack Deployment](../multi-stack/README.md)** - Complex deployment notifications +- **[Preview Deployments](../preview-deployments/README.md)** - PR-based notifications \ No newline at end of file diff --git a/docs/docs/examples/cicd-github-actions/basic-setup/README.md b/docs/docs/examples/cicd-github-actions/basic-setup/README.md index 51d3532b..69ff5293 100644 --- a/docs/docs/examples/cicd-github-actions/basic-setup/README.md +++ b/docs/docs/examples/cicd-github-actions/basic-setup/README.md @@ -5,6 +5,7 @@ This example demonstrates a simple CI/CD setup with staging and production envir ## Overview This setup provides: + - **Automatic staging deployment** when code is pushed to the main branch - **Manual production deployment** with approval requirement - **Slack notifications** for deployment status @@ -16,10 +17,10 @@ This setup provides: β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ GitHub Repo β”‚ β”‚ GitHub Actions β”‚ β”‚ Simple Containerβ”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ Push to main ───┼───▢│ Deploy Staging │───▢│ AWS ECS β”‚ +β”‚ Push to main ───┼───│ Deploy Staging │───│ AWS ECS β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ (Staging) β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ Manual trigger ─┼───▢│ Deploy Prod │───▢│ AWS ECS β”‚ +β”‚ Manual trigger ─┼───│ Deploy Prod │───│ AWS ECS β”‚ β”‚ (with approval) β”‚ β”‚ (with approval) β”‚ β”‚ (Production) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ @@ -281,9 +282,10 @@ stacks: ### 1. Configure GitHub Secrets -Go to your repository **Settings** β†’ **Secrets and variables** β†’ **Actions** and add: +Go to your repository **Settings** β†’**Secrets and variables** β†’**Actions** and add: **Required secrets:** + - `SC_CONFIG` - Simple Container configuration with SSH key pair to decrypt repository secrets **Note:** All cloud provider credentials, API tokens, and application secrets are managed in `.sc/stacks/my-app/secrets.yaml` and encrypted using Simple Container's secrets management. GitHub Actions only needs the `SC_CONFIG` secret to decrypt and access all other secrets. @@ -324,13 +326,15 @@ cat ~/.ssh/id_rsa ### 3. Configure Environments -Go to **Settings** β†’ **Environments** and create: +Go to **Settings** β†’**Environments** and create: **Staging Environment:** + - Name: `staging` - No protection rules (allows automatic deployment) **Production Environment:** + - Name: `production` - Enable **Required reviewers** and add team members - Optionally set **Wait timer** (e.g., 10 minutes) @@ -352,6 +356,7 @@ mkdir -p .sc/stacks/my-app ### 2. Add Configuration Files Copy the configuration files above into your project: + - `server.yaml` β†’ `.sc/stacks/my-app/server.yaml` - `secrets.yaml` β†’ `.sc/stacks/my-app/secrets.yaml` - `client.yaml` β†’ `.sc/stacks/my-app/client.yaml` @@ -512,6 +517,7 @@ To destroy resources in an environment: ### Deployment Status Monitor deployments through: + - **GitHub Actions** - View workflow runs and logs - **Slack notifications** - Receive status updates in your channel - **AWS Console** - Monitor ECS services and RDS databases @@ -519,12 +525,14 @@ Monitor deployments through: ### Health Checks The application includes health check endpoints: + - **Staging**: `https://staging.my-app.com/health` - **Production**: `https://my-app.com/health` ### Logs and Metrics Access application logs through: + - **CloudWatch Logs** - Application and infrastructure logs - **ECS Console** - Container-level metrics - **Application Insights** - Custom application metrics @@ -582,16 +590,19 @@ on: ### Common Issues **Deployment fails with "AWS credentials not found":** + - Verify GitHub secrets are properly configured - Check AWS IAM permissions for the access key - Ensure AWS region is correct in server.yaml **Workflow doesn't trigger automatically:** + - Check branch protection rules don't block pushes - Verify workflow file syntax is correct - Ensure the file is in `.github/workflows/` directory **Production deployment hangs on approval:** + - Check environment protection settings - Ensure reviewers have repository access - Verify reviewers are available to approve @@ -620,6 +631,7 @@ After setting up basic CI/CD: 5. **Custom domains** - Set up DNS and SSL certificates For more advanced setups, check out: -- **[Multi-Stack Deployment](../multi-stack/)** - Deploy multiple related stacks -- **[Preview Deployments](../preview-deployments/)** - PR-based testing environments -- **[Advanced Notifications](../advanced-notifications/)** - Multi-channel alerts + +- **[Multi-Stack Deployment](../multi-stack/README.md)** - Deploy multiple related stacks +- **[Preview Deployments](../preview-deployments/README.md)** - PR-based testing environments +- **[Advanced Notifications](../advanced-notifications/README.md)** - Multi-channel alerts \ No newline at end of file diff --git a/docs/docs/examples/cicd-github-actions/multi-stack/README.md b/docs/docs/examples/cicd-github-actions/multi-stack/README.md index 7999c542..64ef445c 100644 --- a/docs/docs/examples/cicd-github-actions/multi-stack/README.md +++ b/docs/docs/examples/cicd-github-actions/multi-stack/README.md @@ -5,6 +5,7 @@ This example demonstrates a complex CI/CD setup managing multiple related stacks ## Overview This setup manages: + - **Infrastructure Stack** - Shared resources (VPC, databases, load balancers) - **API Stack** - Backend services with database dependencies - **Frontend Stack** - Web application with API dependencies @@ -19,7 +20,7 @@ This setup manages: β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ VPC β”‚ β”‚ β”‚ β”‚ Backend β”‚ β”‚ β”‚ β”‚ React β”‚ β”‚ -β”‚ β”‚ Database β”‚ │────┼─▢│ Service β”‚ │────┼─▢│ App β”‚ β”‚ +β”‚ β”‚ Database β”‚ │────┼─│ Service β”‚ │────┼─│ App β”‚ β”‚ β”‚ β”‚ ALB β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ @@ -682,6 +683,6 @@ services: ## Next Steps -- **[Preview Deployments](../preview-deployments/)** - Add PR-based testing -- **[Advanced Notifications](../advanced-notifications/)** - Multi-channel alerts -- **[Basic Setup](../basic-setup/)** - Simpler single-stack pattern +- **[Preview Deployments](../preview-deployments/README.md)** - Add PR-based testing +- **[Advanced Notifications](../advanced-notifications/README.md)** - Multi-channel alerts +- **[Basic Setup](../basic-setup/README.md)** - Simpler single-stack pattern \ No newline at end of file diff --git a/docs/docs/examples/cicd-github-actions/preview-deployments/README.md b/docs/docs/examples/cicd-github-actions/preview-deployments/README.md index 5e9a7575..9ede85af 100644 --- a/docs/docs/examples/cicd-github-actions/preview-deployments/README.md +++ b/docs/docs/examples/cicd-github-actions/preview-deployments/README.md @@ -5,6 +5,7 @@ This example demonstrates setting up PR-based preview environments that automati ## Overview This setup provides: + - **Automatic preview deployment** when PRs are opened or updated - **Temporary environment creation** with unique URLs - **Resource cleanup** when PRs are closed or merged @@ -18,7 +19,7 @@ This setup provides: β”‚ Pull Request β”‚ β”‚ Preview Deploy β”‚ β”‚ Preview Env β”‚ β”‚ #123 β”‚ β”‚ Workflow β”‚ β”‚ pr-123-app β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ feat/new-ui ────┼───▢│ Deploy PR-123 │───▢│ https:// β”‚ +β”‚ feat/new-ui ────┼───│ Deploy PR-123 │───│ https:// β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ pr-123.app.com β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ @@ -373,24 +374,29 @@ sc cicd generate --stack preview-app --output .github/workflows/ ### 3. GitHub Repository Settings **Environment Configuration:** + - Create `preview` environment with no protection rules - Enable automatic deployment for preview environment **Required Secrets:** + - `SC_CONFIG` - Simple Container configuration with SSH key pair to decrypt repository secrets **Branch Protection:** + - Require status checks from preview deployment - Require branches to be up to date ## Cost Optimization **Automatic Cleanup:** + - Preview environments are automatically cleaned up when PRs are closed - Daily scheduled cleanup removes stale environments older than 7 days - Built-in notifications keep teams informed of cleanup activities **Resource Management:** + - Use smaller instance sizes for preview environments - Configure shorter TTL for preview resources - Consider using spot instances where applicable @@ -418,15 +424,18 @@ sc cicd generate --stack preview-app --output .github/workflows/ ### 3. GitHub Repository Settings **Environment Configuration:** + - Create `preview` environment with no protection rules - Enable automatic deployment for preview environment **Required Secrets:** + - `SC_CONFIG` - Simple Container configuration with SSH key pair to decrypt repository secrets **Note:** All cloud provider credentials, API tokens, and application secrets are managed in `.sc/stacks/preview-app/secrets.yaml` and encrypted using Simple Container's secrets management. GitHub Actions only needs the `SC_CONFIG` secret to decrypt and access all other secrets. **Branch Protection:** + - Require status checks from preview deployment - Require branches to be up to date @@ -512,6 +521,7 @@ npm run test:integration -- --baseUrl="https://pr-${PR_NUMBER}.preview.myapp.com ### Resource Sizing Preview environments use minimal resources: + - **CPU**: 128 (vs 512 for production) - **Memory**: 256MB (vs 1GB for production) - **Instance Count**: 1 (vs 2-10 for production) @@ -575,13 +585,13 @@ Automated performance testing in preview: const report = fs.readFileSync('performance-report.json', 'utf8'); const data = JSON.parse(report); - const comment = `## ⚑ Performance Report + const comment = `## Performance Report **Load Time**: ${data.loadTime}ms **Memory Usage**: ${data.memoryUsage}MB **API Response Time**: ${data.apiResponseTime}ms - ${data.score >= 90 ? 'βœ… Performance looks good!' : '⚠️ Performance needs attention'}`; + ${data.score >= 90 ? 'Performance looks good!' : '⚠️ Performance needs attention'}`; github.rest.issues.createComment({ issue_number: context.issue.number, @@ -608,16 +618,19 @@ Add security scanning for preview deployments: ### Common Issues **Preview deployment fails:** + - Check AWS permissions for temporary resource creation - Ensure Cloudflare registrar is properly configured in server.yaml for automatic DNS provisioning - Ensure cleanup jobs aren't interfering with active deployments **Cleanup not working:** + - Check GitHub token permissions for PR access - Verify AWS credentials for resource destruction - Review scheduled cleanup job timing **High costs:** + - Monitor preview environment resource usage - Implement stricter cleanup policies - Set up cost alerts and budgets @@ -634,6 +647,7 @@ env: ## Next Steps After setting up preview deployments: -- **[Advanced Notifications](../advanced-notifications/)** - Enhanced PR notifications -- **[Multi-Stack Deployment](../multi-stack/)** - Complex preview environments -- **[Basic Setup](../basic-setup/)** - Simpler deployment patterns + +- **[Advanced Notifications](../advanced-notifications/README.md)** - Enhanced PR notifications +- **[Multi-Stack Deployment](../multi-stack/README.md)** - Complex preview environments +- **[Basic Setup](../basic-setup/README.md)** - Simpler deployment patterns \ No newline at end of file diff --git a/docs/docs/examples/ecs-deployments/backend-service/README.md b/docs/docs/examples/ecs-deployments/backend-service/README.md index e5ffb381..176fae69 100644 --- a/docs/docs/examples/ecs-deployments/backend-service/README.md +++ b/docs/docs/examples/ecs-deployments/backend-service/README.md @@ -40,7 +40,8 @@ This example shows how to deploy a Node.js backend service with MongoDB integrat ## Parent Stack Requirements This example requires a parent stack that provides: + - `mongodb` resource with URI access - ECS deployment capabilities - Domain management -- Secrets management for API keys +- Secrets management for API keys \ No newline at end of file diff --git a/docs/docs/examples/ecs-deployments/blockchain-service/README.md b/docs/docs/examples/ecs-deployments/blockchain-service/README.md index b2ca5656..af540e8e 100644 --- a/docs/docs/examples/ecs-deployments/blockchain-service/README.md +++ b/docs/docs/examples/ecs-deployments/blockchain-service/README.md @@ -52,7 +52,8 @@ dependencies: ## Parent Stack Requirements This example requires a parent stack that provides: + - ECS deployment capabilities - Cross-service dependency resolution - Secrets management for contract addresses -- Domain management +- Domain management \ No newline at end of file diff --git a/docs/docs/examples/ecs-deployments/blog-platform/README.md b/docs/docs/examples/ecs-deployments/blog-platform/README.md index 2e7e7efb..53cc0882 100644 --- a/docs/docs/examples/ecs-deployments/blog-platform/README.md +++ b/docs/docs/examples/ecs-deployments/blog-platform/README.md @@ -26,6 +26,7 @@ This example shows how to deploy a blog platform with multi-service deployment ( ## Database Configuration Uses comprehensive MySQL resource references: + - `${resource:mysql.user}` - Database username - `${resource:mysql.password}` - Database password - `${resource:mysql.host}` - Database host @@ -35,6 +36,7 @@ Uses comprehensive MySQL resource references: ## Email Configuration Gmail SMTP setup for blog notifications: + - **Service**: Gmail SMTP - **Security**: SSL/TLS enabled - **Port**: 465 (secure) @@ -51,6 +53,7 @@ Gmail SMTP setup for blog notifications: ## Parent Stack Requirements This example requires a parent stack that provides: + - `mysql` resource with full connection details - ECS deployment capabilities - Domain management @@ -61,4 +64,4 @@ This example requires a parent stack that provides: - `client.yaml` - Main deployment configuration - `docker-compose.yaml` - Multi-service container definitions - `Caddyfile` - Reverse proxy configuration -- `caddy.Dockerfile` - Custom Caddy container build +- `caddy.Dockerfile` - Custom Caddy container build \ No newline at end of file diff --git a/docs/docs/examples/ecs-deployments/index.md b/docs/docs/examples/ecs-deployments/index.md index 45a16bee..05a66cdd 100644 --- a/docs/docs/examples/ecs-deployments/index.md +++ b/docs/docs/examples/ecs-deployments/index.md @@ -343,7 +343,8 @@ alerts: ``` **Technical Details:** + - Server errors use `HTTPCode_Target_5XX_Count` metric with LoadBalancer dimension - Unhealthy hosts use `UnHealthyHostCount` metric with LoadBalancer + TargetGroup dimensions - Response time uses `TargetResponseTime` metric with LoadBalancer dimension -- All metrics use full AWS load balancer identifiers for reliable monitoring +- All metrics use full AWS load balancer identifiers for reliable monitoring \ No newline at end of file diff --git a/docs/docs/examples/ecs-deployments/meteor-app/README.md b/docs/docs/examples/ecs-deployments/meteor-app/README.md index 95aeb5ff..195ae8af 100644 --- a/docs/docs/examples/ecs-deployments/meteor-app/README.md +++ b/docs/docs/examples/ecs-deployments/meteor-app/README.md @@ -55,6 +55,7 @@ This ensures only Cloudflare can access the application directly. ## Parent Stack Requirements This example requires a parent stack that provides: + - `mongodb` resource with URI access - `media-storage` resource (S3 bucket) - ECS deployment capabilities @@ -130,4 +131,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \ # Start the application ENTRYPOINT ["dumb-init", "--"] CMD ["node", "main.js"] -``` +``` \ No newline at end of file diff --git a/docs/docs/examples/ecs-deployments/vector-database/README.md b/docs/docs/examples/ecs-deployments/vector-database/README.md index afc41dd4..d7ea4b58 100644 --- a/docs/docs/examples/ecs-deployments/vector-database/README.md +++ b/docs/docs/examples/ecs-deployments/vector-database/README.md @@ -39,6 +39,7 @@ This example shows how to deploy a high-performance vector database with Network ## Parent Stack Requirements This example requires a parent stack that provides: + - ECS deployment capabilities with NLB support - Domain management with proxy control -- Performance monitoring for scaling decisions +- Performance monitoring for scaling decisions \ No newline at end of file diff --git a/docs/docs/examples/gke-autopilot/comprehensive-setup/README.md b/docs/docs/examples/gke-autopilot/comprehensive-setup/README.md index 6aa5dfd4..324c96c1 100644 --- a/docs/docs/examples/gke-autopilot/comprehensive-setup/README.md +++ b/docs/docs/examples/gke-autopilot/comprehensive-setup/README.md @@ -38,6 +38,7 @@ This example shows how to deploy a complete GCP setup with GKE Autopilot, all ma ## Pub/Sub Configuration Advanced Pub/Sub setup with: + - **Dead Letter Policies**: Message retention and exactly-once delivery - **Multiple Topics**: Image generation and data processing workers - **Subscriptions**: 600s ack deadline, 24h message retention @@ -117,6 +118,7 @@ If you encounter "Master version unsupported" errors: ## Regional Configuration All resources deployed in **europe-west3** for: + - Low latency within Europe - GDPR compliance - Cost optimization @@ -126,4 +128,4 @@ All resources deployed in **europe-west3** for: - **GKE Autopilot**: Auto-scaling based on workload demands - **Redis**: 2GB memory suitable for medium workloads - **MongoDB Atlas**: M0 free tier (upgrade to M10+ for production) -- **Pub/Sub**: Unlimited scaling with pay-per-use model +- **Pub/Sub**: Unlimited scaling with pay-per-use model \ No newline at end of file diff --git a/docs/docs/examples/gke-autopilot/index.md b/docs/docs/examples/gke-autopilot/index.md index f8078134..c9930345 100644 --- a/docs/docs/examples/gke-autopilot/index.md +++ b/docs/docs/examples/gke-autopilot/index.md @@ -136,6 +136,7 @@ Configure pod priority classes and generic ephemeral volumes for production work **Use Case:** Critical production services, data processing pipelines, ML workloads, streaming platforms **Features:** + - **PriorityClassName** - Prevent pod preemption by system pods - **Generic Ephemeral Volumes** - Support >10GB temporary storage (up to 64TB) - **VPA** - Vertical Pod Autoscaler integration @@ -162,6 +163,7 @@ stacks: ``` **Benefits:** + - Prevents preemption of critical workloads - Supports large temporary datasets for processing - Automatic resource optimization with VPA @@ -256,4 +258,4 @@ sc deploy -s myapp -e production - **Use Workload Identity** for secure GCP service access - **Implement proper secret management** with Google Secret Manager - **Configure auto-scaling** based on actual usage patterns -- **Use regional persistent disks** for data durability +- **Use regional persistent disks** for data durability \ No newline at end of file diff --git a/docs/docs/examples/gke-autopilot/priority-and-storage/README.md b/docs/docs/examples/gke-autopilot/priority-and-storage/README.md index f41a0649..7a65c40e 100644 --- a/docs/docs/examples/gke-autopilot/priority-and-storage/README.md +++ b/docs/docs/examples/gke-autopilot/priority-and-storage/README.md @@ -224,26 +224,30 @@ stacks: ### PriorityClassName -βœ… **Do:** +**Do:** + - Use priority classes for critical production workloads - Create separate priority classes for different service tiers - Document priority class values in your runbook - Test with lower priorities before using system-critical -❌ **Don't:** +**Don't:** + - Use system-critical priority classes for non-system workloads - Set all workloads to high priority (defeats the purpose) - Use extremely high priority values unnecessarily ### Ephemeral Volumes -βœ… **Do:** +**Do:** + - Delete pods promptly when not needed to free storage - Use appropriate storage classes for your workload - Monitor PVC usage and cleanup - Set size limits based on actual needs -❌ **Don't:** +**Don't:** + - Use ephemeral volumes for permanent data - Oversize volumes unnecessarily (costs money) - Use pd-extreme unless latency is truly critical @@ -283,4 +287,4 @@ stacks: - [GKE Autopilot Guide](../../../guides/parent-gcp-gke-autopilot.md) - [PriorityClass Documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/) - [Generic Ephemeral Volumes](https://kubernetes.io/docs/concepts/storage/generic-ephemeral-volumes/) -- [GKE Storage Classes](https://cloud.google.com/kubernetes-engine/docs/concepts/persistent-volumes#storageclasses) +- [GKE Storage Classes](https://cloud.google.com/kubernetes-engine/docs/concepts/persistent-volumes#storageclasses) \ No newline at end of file diff --git a/docs/docs/examples/kubernetes-affinity/README.md b/docs/docs/examples/kubernetes-affinity/README.md index 096d722f..df90099b 100644 --- a/docs/docs/examples/kubernetes-affinity/README.md +++ b/docs/docs/examples/kubernetes-affinity/README.md @@ -2,7 +2,7 @@ This directory contains comprehensive examples demonstrating Simple Container's **affinity rules support** for Kubernetes CloudRun templates. These examples show how to implement sophisticated pod scheduling and node pool isolation strategies. -## 🎯 **Overview** +## **Overview** Simple Container's affinity rules enable enterprise-grade workload placement strategies through the `cloudExtras.affinity` configuration block. This feature supports: @@ -11,10 +11,11 @@ Simple Container's affinity rules enable enterprise-grade workload placement str - **Compute Class Optimization**: Specify performance characteristics - **Advanced Kubernetes Affinity**: Full node/pod affinity and anti-affinity rules -## πŸ“ **Examples in This Directory** +## **Examples in This Directory** ### **1. Multi-Tier Node Isolation (`multi-tier-node-isolation/`)** Real-world example based on enterprise GCP migration requirements: + - **Processing Services**: High-performance node pool isolation - **Bot Services**: General-purpose node pool for Telegram bots - **White Label Clients**: Scale-out node pool with cost optimization @@ -22,6 +23,7 @@ Real-world example based on enterprise GCP migration requirements: ### **2. High Availability Patterns (`high-availability/`)** Advanced scheduling patterns for production workloads: + - **Zone Anti-Affinity**: Spread pods across availability zones - **Node Anti-Affinity**: Distribute workloads across nodes - **Pod Co-location**: Group related services together @@ -29,12 +31,13 @@ Advanced scheduling patterns for production workloads: ### **3. Performance Optimization (`performance-optimization/`)** Examples focused on performance and resource optimization: + - **CPU-Intensive Workloads**: Dedicated high-CPU node pools - **Memory-Intensive Services**: High-memory node pool targeting - **Storage-Optimized**: SSD-backed node pool selection - **GPU Workloads**: GPU node pool affinity rules -## πŸš€ **Quick Start** +## **Quick Start** ### **Basic Node Pool Isolation** ```yaml @@ -73,7 +76,7 @@ stacks: topologyKey: "topology.kubernetes.io/zone" ``` -## πŸ“‹ **Supported Affinity Properties** +## **Supported Affinity Properties** ### **Simple Container Properties** - **`nodePool`**: Target node pool name (e.g., "processing", "bots") @@ -85,10 +88,11 @@ stacks: - **`podAffinity`**: Pod co-location rules - **`podAntiAffinity`**: Pod separation and distribution rules -## πŸ”§ **Implementation Details** +## **Implementation Details** ### **GKE Integration** Simple Container automatically maps affinity rules to GKE-specific labels: + - `nodePool` β†’ `cloud.google.com/gke-nodepool` - `computeClass` β†’ `node.kubernetes.io/instance-type` @@ -98,7 +102,7 @@ Simple Container automatically maps affinity rules to GKE-specific labels: 3. **Deployment** β†’ Applied to pod specifications 4. **Scheduling** β†’ Kubernetes scheduler enforces rules -## πŸ“š **Use Cases** +## **Use Cases** ### **Enterprise Scenarios** - **Multi-tenant Applications**: Isolate customer workloads @@ -112,20 +116,20 @@ Simple Container automatically maps affinity rules to GKE-specific labels: - **Web Services**: Load balancer affinity - **Microservices**: Service mesh optimization -## πŸ›  **Prerequisites** +## **Prerequisites** - Simple Container with Kubernetes CloudRun template support - GKE cluster with multiple node pools (for node pool examples) - Understanding of Kubernetes affinity concepts -## πŸ”— **Related Documentation** +## **Related Documentation** -- [Simple Container Kubernetes Guide](../../guides/kubernetes-native/) -- [GKE Autopilot Examples](../gke-autopilot/) -- [Advanced Configurations](../advanced-configs/) -- [Template Placeholders](../../concepts/template-placeholders/) +- [Pure Kubernetes Guide](../../guides/parent-pure-kubernetes.md) +- [GKE Autopilot Examples](../gke-autopilot/index.md) +- [Advanced Configurations](../advanced-configs/index.md) +- [Template Placeholders](../../concepts/template-placeholders.md) -## πŸ“ **Contributing** +## **Contributing** When adding new affinity examples: 1. Create a dedicated subdirectory @@ -136,4 +140,4 @@ When adding new affinity examples: --- -**Note**: These examples demonstrate production-ready configurations used in real-world deployments. Adapt the node pool names and compute classes to match your specific infrastructure setup. +**Note**: These examples demonstrate production-ready configurations used in real-world deployments. Adapt the node pool names and compute classes to match your specific infrastructure setup. \ No newline at end of file diff --git a/docs/docs/examples/kubernetes-affinity/multi-tier-node-isolation/README.md b/docs/docs/examples/kubernetes-affinity/multi-tier-node-isolation/README.md index e7439b16..4a68f2f2 100644 --- a/docs/docs/examples/kubernetes-affinity/multi-tier-node-isolation/README.md +++ b/docs/docs/examples/kubernetes-affinity/multi-tier-node-isolation/README.md @@ -2,7 +2,7 @@ This example demonstrates **node pool isolation** using Simple Container's affinity rules, based on real-world enterprise migration requirements. It shows how to implement multi-tier architecture with dedicated node pools for different service types. -## 🎯 **Use Case** +## **Use Case** A fintech company needed to migrate from dedicated servers to GCP with cost optimization and performance isolation: @@ -11,14 +11,14 @@ A fintech company needed to migrate from dedicated servers to GCP with cost opti - **White Label Clients**: Scale-out node pool for cost-effective client isolation - **Shared Resources**: Cloud SQL PostgreSQL and Redis Memorystore -## πŸ’° **Cost Benefits** +## **Cost Benefits** - **82% cost reduction** in Phase 1 ($485/month savings) - **Pod-based billing** with GKE Autopilot - **Efficient resource utilization** through node pool isolation - **White Label scaling**: $3-15/month per client vs $200/month previously -## πŸ— **Architecture Overview** +## **Architecture Overview** ``` GKE Autopilot Cluster @@ -37,14 +37,14 @@ GKE Autopilot Cluster └── Redis Memorystore ``` -## πŸ“ **Files in This Example** +## **Files in This Example** - **`server.yaml`** - Parent stack with GKE cluster and shared resources - **`client.yaml`** - Service stacks with affinity rules - **`secrets.yaml`** - Authentication configuration - **`docker-compose.yaml`** - Application containers -## πŸš€ **Key Features** +## **Key Features** - **Node Pool Isolation**: Each service type runs on dedicated node pools - **Exclusive Scheduling**: `exclusiveNodePool: true` prevents cross-contamination @@ -52,7 +52,7 @@ GKE Autopilot Cluster - **Auto-scaling**: HPA configuration with min/max replicas - **Cost Optimization**: Efficient resource allocation per workload type -## πŸ”§ **Affinity Rules Explained** +## **Affinity Rules Explained** ### **Processing Services** ```yaml @@ -98,7 +98,7 @@ cloudExtras: - Anti-affinity spreads clients across nodes - Prevents single points of failure -## πŸ“Š **Scaling Configuration** +## **Scaling Configuration** | Service Type | Min Replicas | Max Replicas | Node Pool | Compute Class | |-------------|-------------|-------------|-----------|---------------| @@ -108,7 +108,7 @@ cloudExtras: | Support Bot | 1 | 6 | bots | general-purpose | | White Label (per client) | 0 | 3 | whitelabel | Scale-Out | -## πŸ›  **Prerequisites** +## **Prerequisites** ### **GKE Cluster Setup** ```bash @@ -121,11 +121,12 @@ gcloud container clusters create spacepay-cluster \ ### **Node Pool Configuration** The example assumes these node pools exist: + - **processing**: High-CPU/memory nodes (e.g., n1-highmem-4) - **bots**: Balanced nodes (e.g., n1-standard-2) - **whitelabel**: Cost-optimized nodes (e.g., e2-small) -## πŸ“‹ **Deployment Steps** +## **Deployment Steps** ### **1. Deploy Parent Stack** ```bash @@ -154,7 +155,7 @@ sc deploy --stack telegram-bots --env production sc deploy --stack whitelabel-client-a --env production ``` -## πŸ” **Monitoring & Verification** +## **Monitoring & Verification** ### **Verify Node Pool Assignment** ```bash @@ -174,7 +175,7 @@ kubectl get hpa --all-namespaces kubectl top nodes ``` -## πŸŽ› **Customization Options** +## **Customization Options** ### **Adjust Node Pool Names** Update the `nodePool` values to match your cluster: @@ -206,7 +207,7 @@ cloudExtras: values: ["custom-value"] ``` -## 🚨 **Troubleshooting** +## **Troubleshooting** ### **Pods Stuck in Pending** - Check node pool capacity: `kubectl describe nodes` @@ -223,12 +224,11 @@ cloudExtras: - Check for over-provisioning in HPA settings - Review node pool utilization metrics -## πŸ“š **Related Examples** +## **Related Examples** -- [High Availability Patterns](../high-availability/) - Zone anti-affinity -- [Performance Optimization](../performance-optimization/) - Resource-specific scheduling -- [GKE Autopilot Examples](../../gke-autopilot/) - GKE-specific configurations +- [GKE Autopilot Examples](../../gke-autopilot/index.md) β€” GKE-specific configurations +- [Vertical Pod Autoscaler](../../kubernetes-vpa/README.md) β€” VPA-based scheduling on Kubernetes --- -**Production Ready**: This example is based on actual enterprise migration requirements and has been validated in production environments. +**Production Ready**: This example is based on actual enterprise migration requirements and has been validated in production environments. \ No newline at end of file diff --git a/docs/docs/examples/kubernetes-native/index.md b/docs/docs/examples/kubernetes-native/index.md index 5b1603f9..6914c89a 100644 --- a/docs/docs/examples/kubernetes-native/index.md +++ b/docs/docs/examples/kubernetes-native/index.md @@ -180,4 +180,4 @@ sc deploy -s myapp -e production - **Use node selectors** for hardware-specific workloads - **Implement proper logging and monitoring** with Prometheus and Grafana - **Use secrets and configmaps** for configuration management -- **Configure RBAC** for proper access control +- **Configure RBAC** for proper access control \ No newline at end of file diff --git a/docs/docs/examples/kubernetes-native/streaming-platform/README.md b/docs/docs/examples/kubernetes-native/streaming-platform/README.md index 485b74cb..a4f380ec 100644 --- a/docs/docs/examples/kubernetes-native/streaming-platform/README.md +++ b/docs/docs/examples/kubernetes-native/streaming-platform/README.md @@ -65,6 +65,7 @@ cloudExtras: ## Parent Stack Requirements This example requires a parent stack that provides: + - ECS deployment capabilities with external cluster support - Domain management with base DNS zone configuration - Secrets management for database and service credentials @@ -75,4 +76,4 @@ This example requires a parent stack that provides: - **External Dependencies**: Relies on existing cluster and database infrastructure - **IP Management**: Hardcoded IPs require careful network planning - **Zero-Downtime**: Configured for controlled updates with no service interruption -- **Workflow Integration**: N8N requires proper module configuration +- **Workflow Integration**: N8N requires proper module configuration \ No newline at end of file diff --git a/docs/docs/examples/kubernetes-vpa/README.md b/docs/docs/examples/kubernetes-vpa/README.md index 832bf1bd..d8f59853 100644 --- a/docs/docs/examples/kubernetes-vpa/README.md +++ b/docs/docs/examples/kubernetes-vpa/README.md @@ -13,7 +13,7 @@ date: '2024-12-07' This example demonstrates how to configure **Vertical Pod Autoscaler (VPA)** in Simple Container for automatic resource optimization in Kubernetes deployments. -## 🎯 **Overview** +## **Overview** VPA automatically adjusts CPU and memory requests for your containers based on actual usage patterns, providing: @@ -21,7 +21,7 @@ VPA automatically adjusts CPU and memory requests for your containers based on a - **Performance Optimization**: Ensures adequate resources during load spikes - **Operational Efficiency**: Reduces manual resource tuning -## πŸ“ **Example Structure** +## **Example Structure** ``` kubernetes-vpa/ @@ -37,7 +37,7 @@ kubernetes-vpa/ └── Dockerfile # Application container ``` -## πŸš€ **Quick Start** +## **Quick Start** 1. **Deploy the parent stack** (GKE Autopilot with Caddy VPA): ```bash @@ -55,7 +55,7 @@ kubernetes-vpa/ kubectl describe vpa vpa-demo-vpa ``` -## πŸ“‹ **Configuration Examples** +## **Configuration Examples** ### **Application VPA Configuration** (`client.yaml`) @@ -166,7 +166,7 @@ resources: region: "US_CENTRAL_1" ``` -## πŸ”§ **VPA Update Modes** +## **VPA Update Modes** | Mode | Description | Use Case | Behavior | |------|-------------|----------|----------| @@ -175,7 +175,7 @@ resources: | **Auto** | Updates by recreating pods | Recommended for stateless apps | Pod restart required | | **InPlaceOrRecreate** | Updates resources in-place or recreates | Advanced use (preview) | May cause brief interruptions | -## πŸ“Š **VPA Best Practices** +## **VPA Best Practices** ### **1. Resource Boundaries** @@ -227,7 +227,7 @@ vpa: memory: "4Gi" # Matches manual limit ``` -## πŸ” **Monitoring VPA** +## **Monitoring VPA** ### **Check VPA Status** ```bash @@ -250,7 +250,7 @@ kubectl top pods kubectl get vpa -o jsonpath='{.status.recommendation}' ``` -## 🚨 **Troubleshooting** +## **Troubleshooting** ### **VPA Not Creating Recommendations** - Ensure VPA controller is installed in the cluster @@ -267,14 +267,14 @@ kubectl get vpa -o jsonpath='{.status.recommendation}' - Check if workload patterns are representative - Consider using `controlledResources` to limit scope -## πŸ”— **Related Examples** +## **Related Examples** -- [GKE Autopilot Setup](../gke-autopilot/) - Basic GKE Autopilot configuration -- [Kubernetes Affinity](../kubernetes-affinity/) - Advanced pod scheduling -- [Resource Management](../kubernetes-native/) - Manual resource configuration +- [GKE Autopilot Setup](../gke-autopilot/index.md) - Basic GKE Autopilot configuration +- [Kubernetes Affinity](../kubernetes-affinity/README.md) - Advanced pod scheduling +- [Resource Management](../kubernetes-native/index.md) - Manual resource configuration -## πŸ“š **Additional Resources** +## **Additional Resources** - [Kubernetes VPA Documentation](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler) - [GKE Autopilot VPA Guide](https://cloud.google.com/kubernetes-engine/docs/concepts/verticalpodautoscaler) -- [Simple Container VPA Reference](../../reference/supported-resources.md#vertical-pod-autoscaler-vpa) +- [Vertical Pod Autoscaler concept](../../concepts/vertical-pod-autoscaler.md) \ No newline at end of file diff --git a/docs/docs/examples/lambda-functions/ai-gateway/README.md b/docs/docs/examples/lambda-functions/ai-gateway/README.md index 5b1d1447..f5ccffed 100644 --- a/docs/docs/examples/lambda-functions/ai-gateway/README.md +++ b/docs/docs/examples/lambda-functions/ai-gateway/README.md @@ -53,6 +53,7 @@ awsRoles: ## Parent Stack Requirements This example requires a parent stack that provides: + - `lambda-eu` template with Bedrock IAM role support - Lambda deployment capabilities with custom IAM roles - Domain management @@ -63,4 +64,4 @@ This example requires a parent stack that provides: - API key authentication via AWS Secrets Manager - Granular IAM permissions for Bedrock access only - Function URL routing for direct access -- Cross-region inference for redundancy +- Cross-region inference for redundancy \ No newline at end of file diff --git a/docs/docs/examples/lambda-functions/billing-system/README.md b/docs/docs/examples/lambda-functions/billing-system/README.md index dc10d01e..0cb3668f 100644 --- a/docs/docs/examples/lambda-functions/billing-system/README.md +++ b/docs/docs/examples/lambda-functions/billing-system/README.md @@ -56,6 +56,7 @@ beta: ## Parent Stack Requirements This example requires a parent stack that provides: + - `lambda-eu` template with extended timeout support - `mongodb` resource for billing data storage - Multi-environment support with parent environment inheritance @@ -66,4 +67,4 @@ This example requires a parent stack that provides: - **PCI Compliance**: Ensure proper handling of payment data - **Encryption**: All billing data encrypted at rest and in transit - **Access Control**: Restricted access to billing functions -- **Audit Logging**: Complete audit trail for all billing operations +- **Audit Logging**: Complete audit trail for all billing operations \ No newline at end of file diff --git a/docs/docs/examples/lambda-functions/cost-analytics/README.md b/docs/docs/examples/lambda-functions/cost-analytics/README.md index b8256e61..ea0a2c7e 100644 --- a/docs/docs/examples/lambda-functions/cost-analytics/README.md +++ b/docs/docs/examples/lambda-functions/cost-analytics/README.md @@ -71,6 +71,7 @@ lambdaSchedules: ## Parent Stack Requirements This example requires a parent stack that provides: + - `lambda-eu` template with comprehensive IAM role support - `mongodb` resource for cost data storage - Lambda deployment with extended timeout capabilities @@ -82,4 +83,4 @@ This example requires a parent stack that provides: - **High Memory**: 1GB for processing large cost datasets - **Extended Timeout**: 10 minutes for complex calculations - **Daily Processing**: Optimized for once-daily heavy processing -- **Streaming Response**: Real-time feedback for long operations +- **Streaming Response**: Real-time feedback for long operations \ No newline at end of file diff --git a/docs/docs/examples/lambda-functions/index.md b/docs/docs/examples/lambda-functions/index.md index 0127cb25..516538d6 100644 --- a/docs/docs/examples/lambda-functions/index.md +++ b/docs/docs/examples/lambda-functions/index.md @@ -300,4 +300,4 @@ sc deploy -s mylambda -e production - **Monitor function metrics** and set up appropriate alarms - **Use IAM roles with least privilege** principle - **Implement structured logging** for better observability -- **Consider memory allocation** for optimal cost/performance ratio +- **Consider memory allocation** for optimal cost/performance ratio \ No newline at end of file diff --git a/docs/docs/examples/lambda-functions/scheduler/README.md b/docs/docs/examples/lambda-functions/scheduler/README.md index 8c948bab..1818c00a 100644 --- a/docs/docs/examples/lambda-functions/scheduler/README.md +++ b/docs/docs/examples/lambda-functions/scheduler/README.md @@ -56,6 +56,7 @@ lambdaSchedules: ## Parent Stack Requirements This example requires a parent stack that provides: + - `lambda-eu` template with high-frequency scheduling support - `mongodb` resource for task storage and tracking - Lambda deployment with cron scheduling (every minute) @@ -66,4 +67,4 @@ This example requires a parent stack that provides: - **High Frequency**: Monitor Lambda costs due to every-minute execution - **Execution Time**: Track task execution time to optimize timeout - **Error Handling**: Implement robust error handling for failed tasks -- **Rate Limits**: Consider downstream service rate limits +- **Rate Limits**: Consider downstream service rate limits \ No newline at end of file diff --git a/docs/docs/examples/lambda-functions/storage-service/README.md b/docs/docs/examples/lambda-functions/storage-service/README.md index 116b987d..9c848e33 100644 --- a/docs/docs/examples/lambda-functions/storage-service/README.md +++ b/docs/docs/examples/lambda-functions/storage-service/README.md @@ -54,6 +54,7 @@ lambdaSchedules: ## Parent Stack Requirements This example requires a parent stack that provides: + - `lambda-eu` template with scheduling support - `object-storage` resource (S3 bucket) - `mongodb` resource for metadata @@ -64,4 +65,4 @@ This example requires a parent stack that provides: - **Request Debug**: Enabled in staging for troubleshooting - **Cleanup Logs**: Monitor hourly cleanup job execution -- **Storage Metrics**: Track storage usage and cleanup effectiveness +- **Storage Metrics**: Track storage usage and cleanup effectiveness \ No newline at end of file diff --git a/docs/docs/examples/parent-stacks/aws-multi-region/README.md b/docs/docs/examples/parent-stacks/aws-multi-region/README.md index 5fec8e2b..f5141cad 100644 --- a/docs/docs/examples/parent-stacks/aws-multi-region/README.md +++ b/docs/docs/examples/parent-stacks/aws-multi-region/README.md @@ -75,4 +75,4 @@ This example shows how to create a comprehensive AWS parent stack with multi-reg - **Regional Isolation**: EU staging, US production for compliance - **Database Scaling**: M10 staging β†’ M30 production - **Backup Strategy**: More frequent backups and longer retention in production -- **Cost Optimization**: Different instance sizes per environment +- **Cost Optimization**: Different instance sizes per environment \ No newline at end of file diff --git a/docs/docs/examples/parent-stacks/index.md b/docs/docs/examples/parent-stacks/index.md index 668d5b96..87811f48 100644 --- a/docs/docs/examples/parent-stacks/index.md +++ b/docs/docs/examples/parent-stacks/index.md @@ -124,6 +124,7 @@ registrar: ``` **Features:** + - Multi-region AWS deployment (US East, EU West) - Cloudflare DNS management with proxying - MongoDB Atlas with cross-region networking @@ -229,6 +230,7 @@ registrar: ``` **Features:** + - GKE Autopilot for managed Kubernetes - Artifact Registry for container images - Cloud SQL PostgreSQL database @@ -308,6 +310,7 @@ resources: ``` **Features:** + - AWS for compute-intensive workloads - GCP for data analytics and processing - Cross-cloud resource sharing @@ -430,4 +433,4 @@ sc provision -s devops --update - **Document resource dependencies** and relationships - **Plan for disaster recovery** across regions or clouds - **Monitor costs** and implement cost optimization strategies -- **Use consistent naming conventions** across all resources +- **Use consistent naming conventions** across all resources \ No newline at end of file diff --git a/docs/docs/examples/resource-adoption/README.md b/docs/docs/examples/resource-adoption/README.md index e4338a4f..cc68fe1e 100644 --- a/docs/docs/examples/resource-adoption/README.md +++ b/docs/docs/examples/resource-adoption/README.md @@ -2,18 +2,20 @@ This directory contains practical examples of adopting existing cloud infrastructure into Simple Container. -## πŸ“‹ **Available Examples** +## **Available Examples** ### **Multi-Environment Adoption** Complete example showing how to adopt existing resources across production, staging, and development environments. **Includes:** + - MongoDB Atlas clusters (3 environments) - GCP Cloud SQL Postgres instances (3 environments) - GCP Redis Memorystore instances (3 environments) - GKE Autopilot clusters (3 environments) **Files:** + - `server.yaml` - Parent stack with resource adoption configuration - `secrets.yaml` - Template for required secrets and authentication - `client.yaml` - Example client service using adopted resources @@ -21,13 +23,13 @@ Complete example showing how to adopt existing resources across production, stag ### **Key Features Demonstrated** -βœ… **Zero Downtime Adoption** - Import existing resources without modification -βœ… **Multi-Environment Support** - Consistent configuration across environments -βœ… **Resource Compatibility** - Adopted resources work identically to provisioned ones -βœ… **Secrets Management** - Secure handling of adoption credentials -βœ… **Client Integration** - Services automatically connect to adopted resources +**Zero Downtime Adoption** - Import existing resources without modification +**Multi-Environment Support** - Consistent configuration across environments +**Resource Compatibility** - Adopted resources work identically to provisioned ones +**Secrets Management** - Secure handling of adoption credentials +**Client Integration** - Services automatically connect to adopted resources -## πŸš€ **Quick Start** +## **Quick Start** 1. **Copy the example files** to your project 2. **Update resource identifiers** with your actual resource names/IDs @@ -52,13 +54,13 @@ sc provision -s infrastructure sc deploy -s your-service -e prod ``` -## πŸ“– **Learn More** +## **Learn More** - **[Resource Adoption Guide](../../guides/resource-adoption.md)** - Complete documentation - **[Supported Resources](../../reference/supported-resources.md)** - Full resource reference - **[Secrets Management](../../guides/secrets-management.md)** - Security best practices -## πŸ’‘ **Use Cases** +## **Use Cases** ### **Enterprise Migration** - Adopt existing production infrastructure @@ -77,4 +79,4 @@ sc deploy -s your-service -e prod --- -**Ready to adopt your infrastructure?** Start with the [Resource Adoption Guide](../../guides/resource-adoption.md)! πŸš€ +**Ready to adopt your infrastructure?** Start with the [Resource Adoption Guide](../../guides/resource-adoption.md)! \ No newline at end of file diff --git a/docs/docs/examples/resource-management/README.md b/docs/docs/examples/resource-management/README.md index 8daec931..acbf06cd 100644 --- a/docs/docs/examples/resource-management/README.md +++ b/docs/docs/examples/resource-management/README.md @@ -5,6 +5,7 @@ This directory contains examples demonstrating how to configure CPU and memory r ## Overview Simple Container supports comprehensive resource management with separate configuration for: + - **Resource Limits**: Maximum resources a container can use - **Resource Requests**: Resources guaranteed to be available for the container @@ -73,4 +74,4 @@ stacks: memory: "2048" # 2GB memory guaranteed ``` -This configuration ensures your container gets 0.5 CPU cores and 2GB memory guaranteed, but can burst up to 2 CPU cores and 4GB when resources are available. +This configuration ensures your container gets 0.5 CPU cores and 2GB memory guaranteed, but can burst up to 2 CPU cores and 4GB when resources are available. \ No newline at end of file diff --git a/docs/docs/examples/secrets/README.md b/docs/docs/examples/secrets/README.md index 5a025efa..be3eb4d8 100644 --- a/docs/docs/examples/secrets/README.md +++ b/docs/docs/examples/secrets/README.md @@ -4,19 +4,19 @@ This directory contains comprehensive examples of secrets configuration for diff ## Available Examples -### πŸ” [AWS + MongoDB Atlas](./aws-mongodb-atlas/) +### [AWS + MongoDB Atlas](aws-mongodb-atlas/README.md) **Use Case**: Multi-region AWS deployment with database and CI/CD integrations - **Authentication**: AWS multi-region credentials, Pulumi tokens - **Services**: MongoDB Atlas, Cloudflare DNS, CI/CD webhooks - **Best For**: AWS-centric deployments with external database and notification needs -### 🌐 [GCP Multi-Service Integration](./gcp-auth-cloudflare-mongodb-discord-telegram/) +### [GCP Multi-Service Integration](gcp-auth-cloudflare-mongodb-discord-telegram/README.md) **Use Case**: Comprehensive GCP setup with multiple third-party service integrations - **Authentication**: GCP service accounts (staging + production) - **Services**: MongoDB Atlas, Cloudflare, Discord, Telegram - **Best For**: GCP-primary deployments with rich integration ecosystem -### ☸️ [Kubernetes + GCP Hybrid](./kube-and-gcp-auth/) +###️ [Kubernetes + GCP Hybrid](kube-and-gcp-auth/README.md) **Use Case**: Kubernetes cluster management with GCP cloud services - **Authentication**: Kubernetes cluster access, GCP service accounts - **Services**: Docker registry, container orchestration @@ -28,20 +28,20 @@ This directory contains comprehensive examples of secrets configuration for diff | Infrastructure | Recommended Example | Key Features | |----------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------| -| **AWS Focused** | [aws-mongodb-atlas](./aws-mongodb-atlas/) | Multi-region AWS, Pulumi IaC, external services | -| **GCP Focused** | [gcp-auth-cloudflare-mongodb-discord-telegram](./gcp-auth-cloudflare-mongodb-discord-telegram/) | Multi-environment GCP, comprehensive integrations | -| **Kubernetes First** | [kube-and-gcp-auth](./kube-and-gcp-auth/) | Container orchestration, hybrid deployments | +| **AWS Focused** | [aws-mongodb-atlas](aws-mongodb-atlas/README.md) | Multi-region AWS, Pulumi IaC, external services | +| **GCP Focused** | [gcp-auth-cloudflare-mongodb-discord-telegram](gcp-auth-cloudflare-mongodb-discord-telegram/README.md) | Multi-environment GCP, comprehensive integrations | +| **Kubernetes First** | [kube-and-gcp-auth](kube-and-gcp-auth/README.md) | Container orchestration, hybrid deployments | ### Choose by Integration Needs | Integration Type | AWS Example | GCP Example | Kubernetes Example | |-------------------------|------------------|---------------------|------------------------| -| **Database** | MongoDB Atlas βœ… | MongoDB Atlas βœ… | Registry Auth βœ… | -| **DNS Management** | Cloudflare βœ… | Cloudflare βœ… | - | -| **CI/CD Notifications** | Discord, Slack βœ… | Discord, Telegram βœ… | - | -| **Container Registry** | - | - | Docker Hub, GCR, ECR βœ… | -| **Multi-Region** | US + EU βœ… | Staging + Prod βœ… | Multi-Cluster βœ… | -| **IaC Integration** | Pulumi βœ… | GCP Native βœ… | Kubernetes Native βœ… | +| **Database** | MongoDB Atlas | MongoDB Atlas | Registry Auth | +| **DNS Management** | Cloudflare | Cloudflare | - | +| **CI/CD Notifications** | Discord, Slack | Discord, Telegram | - | +| **Container Registry** | - | - | Docker Hub, GCR, ECR | +| **Multi-Region** | US + EU | Staging + Prod | Multi-Cluster | +| **IaC Integration** | Pulumi | GCP Native | Kubernetes Native | ## Common Configuration Patterns @@ -81,7 +81,7 @@ values: ## Security Best Practices -### βœ… Essential Security Measures +### Essential Security Measures #### 1. **Encryption at Rest** ```bash @@ -129,7 +129,7 @@ echo "*.yaml.encrypted filter=git-crypt diff=git-crypt" >> .gitattributes # 5. Revoke old credentials ``` -### ❌ Security Anti-Patterns to Avoid +### Security Anti-Patterns to Avoid - **Never commit plaintext secrets** to version control - **Don't share production secrets** across environments @@ -365,10 +365,10 @@ kubectl auth can-i create deployments ## Related Documentation -- **[Simple Container CLI Reference](../../reference/cli.md)** - Complete command documentation -- **[Client Configuration Guide](../../guides/client-configuration.md)** - Application setup -- **[Server Configuration Guide](../../guides/server-configuration.md)** - Infrastructure setup -- **[Security Best Practices](../../guides/security.md)** - Comprehensive security guidance +- **[Supported Resources](../../reference/supported-resources.md)** β€” full resource configuration reference +- **[Deployment Schemas](../../reference/service-available-deployment-schemas.md)** β€” per-template config keys +- **[Secrets Management](../../guides/secrets-management.md)** β€” secret-backend setup and `sc secrets` workflow +- **[Container Security](../../guides/container-security.md)** β€” signing, SBOM, provenance, scanning ## Contributing @@ -381,4 +381,4 @@ To add a new secrets example: 5. **Include testing and validation scripts** 6. **Update this overview README** with the new example -Each example should demonstrate real-world patterns while maintaining security best practices and clear documentation for users at all experience levels. +Each example should demonstrate real-world patterns while maintaining security best practices and clear documentation for users at all experience levels. \ No newline at end of file diff --git a/docs/docs/examples/secrets/aws-mongodb-atlas/README.md b/docs/docs/examples/secrets/aws-mongodb-atlas/README.md index 918c9202..cced7424 100644 --- a/docs/docs/examples/secrets/aws-mongodb-atlas/README.md +++ b/docs/docs/examples/secrets/aws-mongodb-atlas/README.md @@ -69,13 +69,13 @@ echo -n "your-secret-key" | base64 ### 2. MongoDB Atlas Setup 1. Log into [MongoDB Atlas](https://cloud.mongodb.com/) -2. Go to **Access Manager** β†’ **API Keys** +2. Go to **Access Manager** β†’**API Keys** 3. Create new API key with appropriate permissions 4. Use the public key directly and private key as-is ### 3. Pulumi Token 1. Go to [Pulumi Console](https://app.pulumi.com/) -2. Navigate to **Settings** β†’ **Access Tokens** +2. Navigate to **Settings** β†’**Access Tokens** 3. Create new token and copy the value ### 4. Cloudflare API Token @@ -85,6 +85,7 @@ echo -n "your-secret-key" | base64 ### 5. CI/CD Webhooks Configure webhook URLs for your notification services: + - **Discord**: Server Settings β†’ Integrations β†’ Webhooks - **Slack**: App Settings β†’ Incoming Webhooks @@ -209,13 +210,13 @@ stacks: ## Security Best Practices -### βœ… Do +### Do - **Encrypt secrets**: Use `sc secrets add` to add and encrypt secret files - **Separate environments**: Use different stack directories for prod/staging environments - **Rotate regularly**: Update API keys and tokens periodically - **Limit permissions**: Use minimal required permissions for each service -### ❌ Don't +### Don't - **Commit plaintext**: Never commit unencrypted secrets to version control - **Share widely**: Limit access to secrets files to necessary team members - **Reuse across environments**: Use separate credentials for production vs development @@ -281,4 +282,4 @@ curl -X POST "your-slack-webhook-url" \ -d '{"text": "Test message from Simple Container"}' ``` -This configuration enables secure, multi-region AWS deployments with integrated database management and CI/CD notifications. +This configuration enables secure, multi-region AWS deployments with integrated database management and CI/CD notifications. \ No newline at end of file diff --git a/docs/docs/examples/secrets/gcp-auth-cloudflare-mongodb-discord-telegram/README.md b/docs/docs/examples/secrets/gcp-auth-cloudflare-mongodb-discord-telegram/README.md index 78960362..b0b84496 100644 --- a/docs/docs/examples/secrets/gcp-auth-cloudflare-mongodb-discord-telegram/README.md +++ b/docs/docs/examples/secrets/gcp-auth-cloudflare-mongodb-discord-telegram/README.md @@ -99,7 +99,7 @@ gcloud iam service-accounts create simple-container-deploy-bot \ ### 2. MongoDB Atlas Configuration 1. Visit [MongoDB Atlas Console](https://cloud.mongodb.com/) -2. Navigate to **Access Manager** β†’ **API Keys** +2. Navigate to **Access Manager** β†’**API Keys** 3. Create API Key with **Project Owner** or **Organization Member** role 4. Copy public key and private key 5. Base64 encode the public key: `echo -n "your-public-key" | base64` @@ -113,7 +113,7 @@ gcloud iam service-accounts create simple-container-deploy-bot \ ### 4. Discord Webhook Setup 1. Open Discord Server Settings -2. Navigate to **Integrations** β†’ **Webhooks** +2. Navigate to **Integrations** β†’**Webhooks** 3. Click **New Webhook** 4. Configure webhook name and channel 5. Copy webhook URL @@ -321,24 +321,24 @@ stacks: ## Security Best Practices -### βœ… Service Account Security +### Service Account Security - **Principle of Least Privilege**: Grant minimal required IAM roles - **Key Rotation**: Rotate service account keys every 90 days - **Environment Separation**: Use separate service accounts for staging/prod - **Audit Logging**: Enable Cloud Audit Logs for service account usage -### βœ… Secret Management +### Secret Management - **Encrypt Everything**: Use `sc secrets add` to add and encrypt secret files - **Base64 Encoding**: Encode all tokens before storing - **Regular Rotation**: Update API keys and tokens quarterly - **Environment Isolation**: Never share secrets between environments -### βœ… Communication Security +### Communication Security - **Bot Token Security**: Treat Telegram bot tokens as highly sensitive - **Webhook Validation**: Implement webhook signature validation where possible - **Channel Restrictions**: Limit Discord/Telegram bot permissions to required channels -### ❌ Common Mistakes to Avoid +### Common Mistakes to Avoid - **Don't**: Store plaintext service account JSON in version control - **Don't**: Use production credentials in development/staging - **Don't**: Share bot tokens or API keys in chat/email @@ -376,12 +376,12 @@ curl -X GET "https://api.cloudflare.com/client/v4/zones" \ # Test Discord webhook curl -X POST "$DISCORD_WEBHOOK_URL" \ -H "Content-Type: application/json" \ - -d '{"content": "πŸš€ Simple Container deployment test"}' + -d '{"content": "Simple Container deployment test"}' # Test Telegram bot curl -X POST "https://api.telegram.org/bot$TELEGRAM_TOKEN/sendMessage" \ -d "chat_id=$TELEGRAM_CHAT" \ - -d "text=πŸš€ Simple Container deployment test" + -d "text=Simple Container deployment test" ``` ## Integration Examples @@ -412,4 +412,4 @@ sc deploy -s your-app -e production # Uses production secrets - **Kubernetes**: See `../kube-and-gcp-auth/` for Kubernetes + GCP integration - **Server Configuration**: Check server examples for GCP infrastructure setup -This configuration enables comprehensive GCP-based deployments with integrated database management, DNS automation, and real-time deployment notifications across multiple communication platforms. +This configuration enables comprehensive GCP-based deployments with integrated database management, DNS automation, and real-time deployment notifications across multiple communication platforms. \ No newline at end of file diff --git a/docs/docs/examples/secrets/kube-and-gcp-auth/README.md b/docs/docs/examples/secrets/kube-and-gcp-auth/README.md index 8e10ca42..64ea017b 100644 --- a/docs/docs/examples/secrets/kube-and-gcp-auth/README.md +++ b/docs/docs/examples/secrets/kube-and-gcp-auth/README.md @@ -450,26 +450,26 @@ services: ## Security Best Practices -### βœ… Kubernetes Security +### Kubernetes Security - **RBAC**: Use Role-Based Access Control with minimal required permissions - **Service Accounts**: Use dedicated service accounts, never default - **TLS**: Always use certificate-based authentication in production - **Network Policies**: Implement network segmentation - **Secret Management**: Store sensitive data in Kubernetes Secrets, not ConfigMaps -### βœ… GCP Security +### GCP Security - **IAM Roles**: Follow principle of least privilege - **Key Rotation**: Rotate service account keys every 90 days - **Audit Logging**: Enable Cloud Audit Logs - **VPC Security**: Use private GKE clusters where possible -### βœ… Container Registry Security +### Container Registry Security - **Image Scanning**: Enable vulnerability scanning - **Signed Images**: Use container image signing - **Private Registries**: Use private registries for production images - **Access Control**: Limit registry access with appropriate IAM roles -### ❌ Security Anti-Patterns +### Security Anti-Patterns - **Don't**: Use `insecure-skip-tls-verify: true` in production - **Don't**: Store kubeconfig with admin privileges - **Don't**: Use default service accounts for deployments @@ -553,4 +553,4 @@ gcloud compute instances list - **GCP Multi-Service**: See `../gcp-auth-cloudflare-mongodb-discord-telegram/` for comprehensive GCP setup - **Server Configuration**: Check server examples for Kubernetes infrastructure setup -This configuration enables powerful hybrid deployments combining the flexibility of Kubernetes with the managed services of Google Cloud Platform, suitable for both cloud-native and containerized workloads. +This configuration enables powerful hybrid deployments combining the flexibility of Kubernetes with the managed services of Google Cloud Platform, suitable for both cloud-native and containerized workloads. \ No newline at end of file diff --git a/docs/docs/examples/static-websites/admin-dashboard/README.md b/docs/docs/examples/static-websites/admin-dashboard/README.md index c550870a..bbf8c5f1 100644 --- a/docs/docs/examples/static-websites/admin-dashboard/README.md +++ b/docs/docs/examples/static-websites/admin-dashboard/README.md @@ -31,6 +31,7 @@ This example shows how to deploy an admin UI with multi-environment configuratio ## Parent Stack Requirements This example requires a parent stack that provides: + - `static-site` template - Static website deployment capabilities -- Domain management for both environments +- Domain management for both environments \ No newline at end of file diff --git a/docs/docs/examples/static-websites/customer-portal/README.md b/docs/docs/examples/static-websites/customer-portal/README.md index 5b3dc3a4..7138bf30 100644 --- a/docs/docs/examples/static-websites/customer-portal/README.md +++ b/docs/docs/examples/static-websites/customer-portal/README.md @@ -31,6 +31,7 @@ This example shows how to deploy a customer-facing UI with multi-environment con ## Parent Stack Requirements This example requires a parent stack that provides: + - `static-site` template - Static website deployment capabilities -- Domain management for both environments +- Domain management for both environments \ No newline at end of file diff --git a/docs/docs/examples/static-websites/documentation-site/README.md b/docs/docs/examples/static-websites/documentation-site/README.md index 267baa27..c8a93b6a 100644 --- a/docs/docs/examples/static-websites/documentation-site/README.md +++ b/docs/docs/examples/static-websites/documentation-site/README.md @@ -26,6 +26,7 @@ This example shows how to deploy a static documentation site using MkDocs output ## Parent Stack Requirements This example requires a parent stack that provides: + - `dist` template with static website deployment capabilities - GCP static hosting configuration -- Domain management +- Domain management \ No newline at end of file diff --git a/docs/docs/examples/static-websites/index.md b/docs/docs/examples/static-websites/index.md index c12271ee..8d9dee7c 100644 --- a/docs/docs/examples/static-websites/index.md +++ b/docs/docs/examples/static-websites/index.md @@ -188,4 +188,4 @@ sc deploy -s mysite -e production - **Enable SPA routing** for single-page applications - **Configure security headers** for enhanced security - **Set up proper caching** through CloudFront configuration -- **Use basic auth** for internal tools and admin interfaces +- **Use basic auth** for internal tools and admin interfaces \ No newline at end of file diff --git a/docs/docs/examples/static-websites/landing-page/README.md b/docs/docs/examples/static-websites/landing-page/README.md index d63732c9..24e0e60f 100644 --- a/docs/docs/examples/static-websites/landing-page/README.md +++ b/docs/docs/examples/static-websites/landing-page/README.md @@ -26,6 +26,7 @@ This example shows how to deploy a main website with SPA (Single Page Applicatio ## Parent Stack Requirements This example requires a parent stack that provides: + - Static website deployment template - GCP static hosting configuration -- Domain management for root domain +- Domain management for root domain \ No newline at end of file diff --git a/docs/docs/examples/static-websites/media-store/README.md b/docs/docs/examples/static-websites/media-store/README.md index 0138eb32..91f9801d 100644 --- a/docs/docs/examples/static-websites/media-store/README.md +++ b/docs/docs/examples/static-websites/media-store/README.md @@ -27,6 +27,7 @@ This example shows how to deploy a media-specific static hosting site with custo ## Parent Stack Requirements This example requires a parent stack that provides: + - `static-site` template - Static website deployment capabilities -- Domain management for media subdomain +- Domain management for media subdomain \ No newline at end of file diff --git a/docs/docs/getting-started/index.md b/docs/docs/getting-started/index.md index 0577b7ec..471ec667 100644 --- a/docs/docs/getting-started/index.md +++ b/docs/docs/getting-started/index.md @@ -37,4 +37,4 @@ Once you've completed the getting started guide, explore: ## Need Help? -If you have any issues or questions, please reach out at [support@simple-container.com](mailto:support@simple-container.com). +If you have any issues or questions, please reach out at [support@simple-container.com](mailto:support@simple-container.com). \ No newline at end of file diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md index 447e85aa..d755fe6b 100644 --- a/docs/docs/getting-started/installation.md +++ b/docs/docs/getting-started/installation.md @@ -15,27 +15,27 @@ This guide is for **both DevOps teams and developers** who want to install and s --- -# **1️⃣ What is Simple Container?** +# **What is Simple Container?** Simple Container is a **cloud-agnostic CI/CD tool** that simplifies the deployment of **microservices and static websites** across platforms like **Kubernetes, AWS ECS, and Google Cloud**. -βœ… **Supports multiple cloud providers** (AWS, GCP, Kubernetes). +**Supports multiple cloud providers** (AWS, GCP, Kubernetes). -βœ… **Easy configuration using `client.yaml` and `server.yaml`**. +**Easy configuration using `client.yaml` and `server.yaml`**. -βœ… **Secure secrets management** with SSH-based encryption. +**Secure secrets management** with SSH-based encryption. -βœ… **Automated infrastructure provisioning and deployments**. +**Automated infrastructure provisioning and deployments**. --- -# **2️⃣ Installing `sc`** -## **πŸ”Ή Install `sc` on Linux/macOS** +# **Installing `sc`** +## **Install `sc` on Linux/macOS** To install `sc`, run: ```sh curl -s "https://dist.simple-container.com/sc.sh" | bash ``` -βœ… This automatically downloads and installs `sc` in `/usr/local/bin`. +This automatically downloads and installs `sc` in `/usr/local/bin`. **Verify the installation:** ```sh @@ -44,10 +44,10 @@ sc --version --- -# **3️⃣ Initializing `sc`** +# **Initializing `sc`** After installing `sc`, you need to **set up SSH authentication** for secrets management. -## **πŸ”Ή Step 3: Set Up SSH Key for Secrets** +## **Step 3: Set Up SSH Key for Secrets** If you **already have an SSH key**, initialize `sc`: ```sh sc secrets init @@ -57,14 +57,14 @@ If you **need to generate a new SSH key**, use: sc secrets init -g ``` -βœ… This ensures that **secrets** can be securely encrypted and managed. +This ensures that **secrets** can be securely encrypted and managed. --- -# **4️⃣ Setting Up the Parent Stack (For DevOps)** +# **Setting Up the Parent Stack (For DevOps)** The **DevOps team** must configure a **parent stack** (`server.yaml`) to define infrastructure and cloud resources. -## **πŸ”Ή Step 4: Create `secrets.yaml`** +## **Step 4: Create `secrets.yaml`** ```sh mkdir -p .sc/stacks/devops touch .sc/stacks/devops/secrets.yaml @@ -88,11 +88,11 @@ values: MONGODB_ATLAS_PRIVATE_KEY: "private-key-456" ``` -βœ… This securely **stores AWS credentials and API tokens**. +This securely **stores AWS credentials and API tokens**. --- -## **πŸ”Ή Step 5: Define the Infrastructure in `server.yaml`** +## **Step 5: Define the Infrastructure in `server.yaml`** Now, define **infrastructure resources** inside `.sc/stacks/devops/server.yaml`: ```yaml --- @@ -135,20 +135,20 @@ resources: publicKey: "${secret:MONGODB_ATLAS_PUBLIC_KEY}" ``` -### **πŸ”Ή Step 6: Provision the Parent Stack** +### **Step 6: Provision the Parent Stack** Once `server.yaml` is configured, **provision the infrastructure**: ```sh sc provision -s devops ``` -βœ… This **creates AWS infrastructure and configures MongoDB Atlas**. +This **creates AWS infrastructure and configures MongoDB Atlas**. --- -# **5️⃣ Setting Up Services (For Developers)** +# **Setting Up Services (For Developers)** Once the **parent stack is ready**, developers can configure **`client.yaml`** to deploy services. -## **πŸ”Ή Step 7: Create `client.yaml` for a Microservice** +## **Step 7: Create `client.yaml` for a Microservice** ```sh mkdir -p .sc/stacks/myservice touch .sc/stacks/myservice/client.yaml @@ -179,39 +179,39 @@ stacks: --- -# **6️⃣ Deploying a Microservice** +# **Deploying a Microservice** Once **`client.yaml`** is defined, deploy the service. -### **πŸ”Ή Step 8: Deploy the Service to Staging** +### **Step 8: Deploy the Service to Staging** ```sh sc deploy -s myservice -e staging ``` -βœ… This **builds, pushes, and deploys the service to AWS ECS Fargate**. +This **builds, pushes, and deploys the service to AWS ECS Fargate**. --- -# **7️⃣ Managing Secrets with `sc`** -### **πŸ”Ή Add a Secret File** +# **Managing Secrets with `sc`** +### **Add a Secret File** ```sh sc secrets add .env ``` -βœ… Encrypts `.env` before committing to Git. +Encrypts `.env` before committing to Git. -### **πŸ”Ή Hide Secrets Before Committing** +### **Hide Secrets Before Committing** ```sh sc secrets hide ``` -βœ… Ensures **no secrets are leaked in Git**. +Ensures **no secrets are leaked in Git**. -### **πŸ”Ή Reveal Secrets After Pulling Changes** +### **Reveal Secrets After Pulling Changes** ```sh sc secrets reveal ``` -βœ… **Decrypts and restores** secret files locally. +**Decrypts and restores** secret files locally. --- -# **8️⃣ Summary** +# **Summary** | Step | For | Command | Purpose | |---------------------------|---------------------|----------------------------------------------------|--------------------------------------| | **Install `sc`** | DevOps & Developers | `curl -s "https://dist.simple-container.com/sc.sh" | bash` | Installs Simple Container CLI | @@ -220,4 +220,4 @@ sc secrets reveal | **Provision Infra** | DevOps | `sc provision -s devops` | Deploys AWS/GCP/Kubernetes resources | | **Define a Service** | Developers | `client.yaml` | Configures microservice deployment | | **Deploy a Service** | Developers | `sc deploy -s myservice -e staging` | Deploys microservice to the cloud | -| **Manage Secrets** | DevOps | `sc secrets add .env` | Encrypts a secret file | +| **Manage Secrets** | DevOps | `sc secrets add .env` | Encrypts a secret file | \ No newline at end of file diff --git a/docs/docs/getting-started/quick-start.md b/docs/docs/getting-started/quick-start.md index 5df2be2b..4575f313 100644 --- a/docs/docs/getting-started/quick-start.md +++ b/docs/docs/getting-started/quick-start.md @@ -53,11 +53,14 @@ templates: resources: resources: prod: - main-bucket: - type: s3-bucket - config: - name: "my-app-${env:ENVIRONMENT}-bucket" - allowOnlyHttps: true + template: static-site + resources: + main-bucket: + type: s3-bucket + name: main-bucket + config: + name: "my-app-${env:ENVIRONMENT}-bucket" + allowOnlyHttps: true ``` Create the client stack configuration file `.sc/stacks/myapp/client.yaml`: @@ -119,9 +122,30 @@ Add the secrets file to Simple Container's managed secrets: sc secrets add .sc/stacks/infrastructure/secrets.yaml ``` -## Step 4: Deploy +## Step 4: Provision the parent stack -Deploy your application: +Before any service deploys, the parent stack must be provisioned so that its +shared resources (S3 buckets, templates, registrar config, secret backends) +exist and are reachable. Provisioning runs Pulumi against the cloud account +and is idempotent β€” re-runs only apply changes. + +```bash +sc provision -s infrastructure -e prod +``` + +This step: + +1. Reads `server.yaml` from `.sc/stacks/infrastructure/` +2. Creates the S3 bucket, CloudFront distribution, and any other resources declared in `resources.resources.prod.resources` +3. Registers the deployment templates so child stacks can target them +4. Persists Pulumi state via the configured `state-storage` backend + +You only re-run `sc provision` when the parent's `server.yaml` changes (new +resource, new environment, new template). Service deploys do not require it. + +## Step 5: Deploy your service + +Deploy the application stack: ```bash sc deploy -s my-first-app -e prod @@ -129,16 +153,17 @@ sc deploy -s my-first-app -e prod Simple Container will: -1. Create the S3 bucket -2. Set up CloudFront distribution -3. Configure DNS (if using Route53) -4. Deploy your static files +1. Resolve the parent reference (`parent: infrastructure`) from `client.yaml` +2. Match the deployment template +3. Build and push the artifact (if applicable) +4. Apply the service-level resources and configuration -## Step 5: Verify Deployment +## Step 6: Verify Deployment Your website should now be live at your configured domain! You can verify the deployment by: + - Visiting your domain in a web browser - Checking your AWS S3 bucket for the deployed files - Verifying CloudFront distribution is active in AWS Console @@ -168,4 +193,4 @@ Now that you have your first deployment running, explore: **Need help?** -- Join our community or contact [support@simple-container.com](mailto:support@simple-container.com) +- Join our community or contact [support@simple-container.com](mailto:support@simple-container.com) \ No newline at end of file diff --git a/docs/docs/guides/cicd-github-actions.md b/docs/docs/guides/cicd-github-actions.md index fefaa757..a97cc42f 100644 --- a/docs/docs/guides/cicd-github-actions.md +++ b/docs/docs/guides/cicd-github-actions.md @@ -304,10 +304,12 @@ All Simple Container GitHub Actions support these common inputs: - **`notify-on-completion`** - Send notifications when operation completes (`true`/`false`, default: `true`) **Available Outputs:** + - **`stack-name`** - Name of the deployed stack - **`status`** - Deployment status ("success") For `deploy@v2025.10.4` action: + - **`version`** - Deployed application version - **`environment`** - Target environment name @@ -347,9 +349,11 @@ jobs: Configure these secrets in your GitHub repository settings: **Only ONE GitHub secret required:** + - `SC_CONFIG` - Simple Container configuration with SSH key pair to decrypt repository secrets **All other secrets are managed in Simple Container's encrypted secrets.yaml files:** + - **Cloud provider credentials** - AWS, GCP, Azure authentication - **Notification webhooks** - Slack, Discord, Telegram configurations - **Application secrets** - Database URLs, API keys, environment-specific values @@ -361,7 +365,7 @@ Configure these secrets in your GitHub repository settings: Configure environment protection rules in GitHub: -1. Go to **Settings** β†’ **Environments** in your repository +1. Go to **Settings** β†’**Environments** in your repository 2. Create environments for `staging` and `production` 3. For **production environment**: - Enable **Required reviewers** and add team members @@ -493,7 +497,7 @@ sc cicd preview --stack myorg/infrastructure --show-content - Git repository initialization details 2. **Enable GitHub Actions debug logging** (additional system-level debugging): - - Go to repository **Settings** β†’ **Secrets** + - Go to repository **Settings** β†’**Secrets** - Add secret `ACTIONS_STEP_DEBUG` with value `true` 3. **Check workflow logs** in the Actions tab of your repository @@ -521,22 +525,22 @@ sc cicd preview --stack myorg/infrastructure --show-content Check out complete examples in the [examples/cicd-github-actions/](../examples/cicd-github-actions/README.md) directory: -- **[Basic Setup](../examples/cicd-github-actions/basic-setup/)** - Simple staging/production pipeline -- **[Multi-Stack Deployment](../examples/cicd-github-actions/multi-stack/)** - Deploy multiple related stacks -- **[Preview Deployments](../examples/cicd-github-actions/preview-deployments/)** - PR-based preview environments -- **[Advanced Notifications](../examples/cicd-github-actions/advanced-notifications/)** - Multi-channel notification setup +- **[Basic Setup](../examples/cicd-github-actions/basic-setup/README.md)** - Simple staging/production pipeline +- **[Multi-Stack Deployment](../examples/cicd-github-actions/multi-stack/README.md)** - Deploy multiple related stacks +- **[Preview Deployments](../examples/cicd-github-actions/preview-deployments/README.md)** - PR-based preview environments +- **[Advanced Notifications](../examples/cicd-github-actions/advanced-notifications/README.md)** - Multi-channel notification setup ## Next Steps After setting up CI/CD: -1. Explore **[Advanced Deployment Patterns](../advanced/deployment-patterns.md)** for complex scenarios +1. Review **[Best Practices](../advanced/best-practices.md)** for production-readiness tips 2. Review **[Secrets Management](secrets-management.md)** for secure credential handling 3. Check **[DNS Management](dns-management.md)** for custom domain configuration -4. Set up **[Monitoring and Alerting](../advanced/monitoring.md)** for deployment health +4. Set up **[Container Security](container-security.md)** for signing, SBOM, and scanning ## Need Help? - Review **[Core Concepts](../concepts/main-concepts.md)** for fundamental understanding - Check the **[GitHub Actions Examples](../examples/cicd-github-actions/README.md)** for real-world configurations -- Contact [support@simple-container.com](mailto:support@simple-container.com) for assistance +- Contact [support@simple-container.com](mailto:support@simple-container.com) for assistance \ No newline at end of file diff --git a/docs/docs/user-guides/container-security.md b/docs/docs/guides/container-security.md similarity index 99% rename from docs/docs/user-guides/container-security.md rename to docs/docs/guides/container-security.md index 47b565f0..ff0cf566 100644 --- a/docs/docs/user-guides/container-security.md +++ b/docs/docs/guides/container-security.md @@ -134,6 +134,7 @@ sc sbom verify --image myapp@sha256:... --key cosign.pub --output verified-sbom. ``` **Supported Formats:** + - `cyclonedx-json` (default) - `cyclonedx-xml` - `spdx-json` @@ -560,4 +561,4 @@ See [Container Security Troubleshooting](../troubleshooting/container-security.m ## Compliance -See [NIST SP 800-218 Mapping](../compliance/nist-sp-800-218-mapping.md) for compliance documentation. +See [NIST SP 800-218 Mapping](../compliance/nist-sp-800-218-mapping.md) for compliance documentation. \ No newline at end of file diff --git a/docs/docs/guides/dns-management.md b/docs/docs/guides/dns-management.md index a7dc0f4c..0ab5c675 100644 --- a/docs/docs/guides/dns-management.md +++ b/docs/docs/guides/dns-management.md @@ -519,4 +519,4 @@ After setting up DNS management: - **[Cloudflare DNS API Documentation](https://developers.cloudflare.com/api/operations/dns-records-for-a-zone-list-dns-records)** - **[Template Placeholders](../concepts/template-placeholders.md)** for dynamic configuration - **[Multi-Region Deployment Examples](../examples/parent-stacks/aws-multi-region/README.md)** -- **[Security Best Practices](../advanced/best-practices.md)** +- **[Security Best Practices](../advanced/best-practices.md)** \ No newline at end of file diff --git a/docs/docs/guides/gke-version-management.md b/docs/docs/guides/gke-version-management.md index 27748b5e..81543c87 100644 --- a/docs/docs/guides/gke-version-management.md +++ b/docs/docs/guides/gke-version-management.md @@ -34,7 +34,7 @@ gcloud container get-server-config --location=YOUR_REGION \ gke-cluster: type: gcp-gke-autopilot-cluster config: - gkeMinVersion: 1.27.16-gke.1296000 # ❌ Deprecated + gkeMinVersion: 1.27.16-gke.1296000 # Deprecated location: europe-west3 ``` @@ -43,7 +43,7 @@ gke-cluster: gke-cluster: type: gcp-gke-autopilot-cluster config: - gkeMinVersion: 1.33.4-gke.1245000 # βœ… Check: gcloud container get-server-config --location=europe-west3 + gkeMinVersion: 1.33.4-gke.1245000 # Check: gcloud container get-server-config --location=europe-west3 location: europe-west3 ``` @@ -77,23 +77,23 @@ done ```yaml gkeMinVersion: "1.33.4-gke.1245000" ``` -- βœ… **Pros**: Predictable, consistent deployments -- ❌ **Cons**: Requires regular updates +- **Pros**: Predictable, consistent deployments +- **Cons**: Requires regular updates ### 2. **Major Version** (Flexible) ```yaml gkeMinVersion: "1.33" ``` -- βœ… **Pros**: Auto-selects latest patch within major version -- ❌ **Cons**: May get unexpected updates +- **Pros**: Auto-selects latest patch within major version +- **Cons**: May get unexpected updates ### 3. **Latest Stable** (Dynamic) ```yaml # Use latest stable (not recommended for production) # Omit gkeMinVersion entirely ``` -- βœ… **Pros**: Always current -- ❌ **Cons**: May break on GCP updates +- **Pros**: Always current +- **Cons**: May break on GCP updates ## Troubleshooting Workflow @@ -189,7 +189,7 @@ echo "Update your server.yaml files with this version" ## Version Lifecycle ### GCP Version Support Timeline: -1. **Alpha** β†’ **Beta** β†’ **Stable** β†’ **Default** β†’ **Deprecated** β†’ **Unsupported** +1. **Alpha** β†’**Beta** β†’**Stable** β†’**Default** β†’**Deprecated** β†’**Unsupported** 2. **Typical Lifecycle**: ~6-12 months from stable to deprecated 3. **Deprecation Notice**: GCP provides 3+ months advance notice @@ -206,4 +206,4 @@ echo "Update your server.yaml files with this version" --- -**πŸ’‘ Pro Tip**: Bookmark this page and check GKE versions monthly to avoid deployment surprises! +**Pro Tip**: Bookmark this page and check GKE versions monthly to avoid deployment surprises! \ No newline at end of file diff --git a/docs/docs/guides/index.md b/docs/docs/guides/index.md index 473c0303..3e8e0617 100644 --- a/docs/docs/guides/index.md +++ b/docs/docs/guides/index.md @@ -63,11 +63,11 @@ This section provides step-by-step guides for deploying applications using Simpl After completing a deployment guide: 1. Explore **[Examples](../examples/README.md)** for real-world configurations -2. Review **[Advanced Topics](../advanced/scaling-advantages.md)** for optimization strategies +2. Review **[Best Practices](../advanced/best-practices.md)** for production-readiness tips 3. Check **[Reference Documentation](../reference/supported-resources.md)** for complete API details ## Need Help? - Review **[Core Concepts](../concepts/main-concepts.md)** for fundamental understanding - Check **[Template Placeholders](../concepts/template-placeholders.md)** for configuration syntax -- Contact [support@simple-container.com](mailto:support@simple-container.com) for assistance +- Contact [support@simple-container.com](mailto:support@simple-container.com) for assistance \ No newline at end of file diff --git a/docs/docs/guides/migration.md b/docs/docs/guides/migration.md index 82cf2f18..e2c12314 100644 --- a/docs/docs/guides/migration.md +++ b/docs/docs/guides/migration.md @@ -13,7 +13,7 @@ date: '2024-06-12' This tutorial guides **DevOps teams and developers** on how to migrate from **Terraform or Pulumi** to **Simple Container** for microservice deployment and infrastructure management. -βœ… **Why Migrate to `sc`?** +**Why Migrate to `sc`?** - **Simplifies microservice deployment** (CI/CD, scaling, rollbacks, and secrets included). - **Reduces complexity** (high-level YAML configuration instead of Terraform HCL or Pulumi code). @@ -21,25 +21,25 @@ This tutorial guides **DevOps teams and developers** on how to migrate from **Te --- -# **1️⃣ Understanding the Migration Approach** +# **Understanding the Migration Approach** | Feature | Terraform / Pulumi | Simple Container | |-------------------------------|-----------------------------------------|-------------------------------------------------| -| **Infrastructure Management** | Declarative IaC (HCL, Python, Go, etc.) | **High-level YAML (`server.yaml`)** | -| **Microservice Deployment** | Requires external CI/CD | **Built-in (`client.yaml`)** | -| **Secrets Management** | Requires external tools (Vault, SSM) | **Built-in (`sc secrets`)** | -| **Networking & Routing** | Requires manual configuration | **Simplified with `caddy` and ingress support** | +| **Infrastructure Management** | Declarative IaC (HCL, Python, Go, etc.) |**High-level YAML (`server.yaml`)** | +| **Microservice Deployment** | Requires external CI/CD |**Built-in (`client.yaml`)** | +| **Secrets Management** | Requires external tools (Vault, SSM) |**Built-in (`sc secrets`)** | +| **Networking & Routing** | Requires manual configuration |**Simplified with `caddy` and ingress support** | -βœ… **SC abstracts infrastructure complexity while keeping cloud provider flexibility**. +**SC abstracts infrastructure complexity while keeping cloud provider flexibility**. --- -# **2️⃣ Step-by-Step Migration Guide** +# **Step-by-Step Migration Guide** This guide covers **migrating an AWS ECS Fargate and MongoDB Atlas setup** from Terraform/Pulumi to **Simple Container**. --- -## **πŸ”Ή Step 1: Extract Infrastructure Configuration** +## **Step 1: Extract Infrastructure Configuration** Identify Terraform or Pulumi resources you need to migrate. ### **Example Terraform Setup** @@ -74,11 +74,11 @@ const db = new aws.rds.Instance("database", { }); ``` -βœ… **We will migrate these resources to `server.yaml`.** +**We will migrate these resources to `server.yaml`.** --- -## **πŸ”Ή Step 2: Create `secrets.yaml`** +## **Step 2: Create `secrets.yaml`** Define **cloud authentication and credentials** in **SC’s secrets file**. ```sh @@ -107,11 +107,11 @@ values: MONGODB_ATLAS_PRIVATE_KEY: "private-key-456" ``` -βœ… **SC securely manages AWS and MongoDB credentials**. +**SC securely manages AWS and MongoDB credentials**. --- -## **πŸ”Ή Step 3: Define `server.yaml` for Infrastructure** +## **Step 3: Define `server.yaml` for Infrastructure** Instead of using **Terraform** or **Pulumi**, SC defines **infrastructure in `server.yaml`**. ```sh @@ -173,20 +173,20 @@ resources: publicKey: "${secret:MONGODB_ATLAS_PUBLIC_KEY}" ``` -βœ… **SC simplifies infrastructure by grouping resources logically in `server.yaml`**. +**SC simplifies infrastructure by grouping resources logically in `server.yaml`**. --- -## **πŸ”Ή Step 4: Provision the Infrastructure** +## **Step 4: Provision the Infrastructure** Instead of running **Pulumi or Terraform**, use: ```sh sc provision -s devops ``` -βœ… **This provisions AWS ECS, MongoDB Atlas, and networking automatically**. +**This provisions AWS ECS, MongoDB Atlas, and networking automatically**. --- -## **πŸ”Ή Step 5: Define `client.yaml` for Microservices Deployment** +## **Step 5: Define `client.yaml` for Microservices Deployment** Configure **SC’s microservice deployment** instead of Terraform’s ECS task definitions. ```sh @@ -220,20 +220,20 @@ stacks: DATABASE_PASSWORD: "${resource:mongodb.password}" ``` -βœ… **SC automatically maps microservices to infrastructure resources**. +**SC automatically maps microservices to infrastructure resources**. --- -## **πŸ”Ή Step 6: Deploy the Microservice** +## **Step 6: Deploy the Microservice** Instead of manually defining ECS tasks in Terraform or Pulumi, use: ```sh sc deploy -s myservice -e staging ``` -βœ… **SC automates the CI/CD process**. +**SC automates the CI/CD process**. --- -# **3️⃣ Summary of Migration** +# **Summary of Migration** | Task | Terraform / Pulumi | Simple Container | |------------------------------------|-----------------------------------|-------------------------------------| | **Define Secrets** | AWS Secrets Manager, Vault | `secrets.yaml` | @@ -242,4 +242,4 @@ sc deploy -s myservice -e staging | **Define Microservice Deployment** | ECS Task Definitions, Helm Charts | `client.yaml` | | **Deploy Microservice** | CI/CD + Terraform | `sc deploy -s myservice -e staging` | -βœ… **SC simplifies infrastructure and deployment** while keeping cloud flexibility. +**SC simplifies infrastructure and deployment** while keeping cloud flexibility. \ No newline at end of file diff --git a/docs/docs/guides/parent-ecs-fargate.md b/docs/docs/guides/parent-ecs-fargate.md index a3fcb941..08c72c3b 100644 --- a/docs/docs/guides/parent-ecs-fargate.md +++ b/docs/docs/guides/parent-ecs-fargate.md @@ -17,14 +17,14 @@ With this setup, developers can **deploy microservices to ECS Fargate** while us --- -# **1️⃣ Prerequisites** +# **Prerequisites** Before configuring the parent stack, ensure that: -βœ… You have an **AWS account** & IAM credentials with permissions to create ECS Fargate clusters. +You have an **AWS account** & IAM credentials with permissions to create ECS Fargate clusters. -βœ… You have a **MongoDB Atlas account** with a valid API key. +You have a **MongoDB Atlas account** with a valid API key. -βœ… **Simple Container is installed**: +**Simple Container is installed**: ```sh curl -s "https://dist.simple-container.com/sc.sh" | bash @@ -32,7 +32,7 @@ Before configuring the parent stack, ensure that: --- -# **2️⃣ Setting Up AWS & MongoDB Atlas Secrets** +# **Setting Up AWS & MongoDB Atlas Secrets** AWS and MongoDB Atlas credentials must be stored in **`secrets.yaml`**. @@ -58,15 +58,15 @@ values: MONGODB_ATLAS_PRIVATE_KEY: "private-key-456" ``` -### **πŸ”Ή What This Does** +### **What This Does** -βœ… Stores **AWS credentials** for programmatic access. +Stores **AWS credentials** for programmatic access. -βœ… Saves **MongoDB Atlas API keys** for provisioning databases. +Saves **MongoDB Atlas API keys** for provisioning databases. --- -# **3️⃣ Configuring Infrastructure Provisioning (`server.yaml`)** +# **Configuring Infrastructure Provisioning (`server.yaml`)** Now, define `.sc/stacks/devops/server.yaml` to provision **ECS Fargate & MongoDB Atlas**. @@ -128,19 +128,19 @@ resources: retention: 24h ``` -### **πŸ”Ή What This Does** +### **What This Does** -βœ… **Configures Pulumi** for managing **state in an S3 bucket**. +**Configures Pulumi** for managing **state in an S3 bucket**. -βœ… **Uses AWS KMS to encrypt secrets**. +**Uses AWS KMS to encrypt secrets**. -βœ… **Defines an ECS Fargate template (`stack-per-app`)** for developers to deploy microservices. +**Defines an ECS Fargate template (`stack-per-app`)** for developers to deploy microservices. -βœ… **Provisions MongoDB Atlas**, making it available for microservices. +**Provisions MongoDB Atlas**, making it available for microservices. --- -# **4️⃣ Provisioning the AWS & MongoDB Atlas Parent Stack** +# **Provisioning the AWS & MongoDB Atlas Parent Stack** Once `server.yaml` is configured, **provision** the infrastructure: ```sh @@ -149,17 +149,17 @@ sc provision -s devops ### **What This Does** -βœ… Creates an **S3 bucket** for state storage. +Creates an **S3 bucket** for state storage. -βœ… Deploys **MongoDB Atlas** with provisioned users. +Deploys **MongoDB Atlas** with provisioned users. -βœ… Configures **Cloudflare DNS (optional)**. +Configures **Cloudflare DNS (optional)**. -βœ… Prepares **ECS Fargate infrastructure for microservices**. +Prepares **ECS Fargate infrastructure for microservices**. --- -# **5️⃣ Deploying Microservices to ECS Fargate** +# **Deploying Microservices to ECS Fargate** Once the infrastructure is provisioned, developers can deploy their microservices. ## **Step 1: Define `client.yaml` for a Microservice** @@ -291,10 +291,10 @@ stacks: **LambdaSchedules Object Fields:** | Field | Type | Description | Required | |--------------|----------|--------------------------------------|----------| -| `name` | `string` | Unique identifier for the schedule | βœ… Yes | -| `expression` | `string` | Cron or rate expression | βœ… Yes | -| `timezone` | `string` | Timezone for execution | ❌ Optional | -| `request` | `string` | Complete HTTP request payload (JSON) | βœ… Yes | +| `name` | `string` | Unique identifier for the schedule | Yes | +| `expression` | `string` | Cron or rate expression | Yes | +| `timezone` | `string` | Timezone for execution | Optional | +| `request` | `string` | Complete HTTP request payload (JSON) | Yes | #### **Security Group Configuration** @@ -357,6 +357,7 @@ lambdaSchedules: ``` **Lambda Schedule Request Structure:** + - `name`: Unique identifier for the schedule - `expression`: Cron or rate expression for timing - `timezone`: Timezone for schedule execution (optional) @@ -374,11 +375,11 @@ lambdaSchedules: sc deploy -s myservice -e staging ``` -βœ… The service is **automatically deployed to ECS Fargate** using the defined settings. +The service is **automatically deployed to ECS Fargate** using the defined settings. --- -# **6️⃣ Summary** +# **Summary** | Step | Command | Purpose | |---------------------|-------------------------------------|-----------------------------------------------| | **Define Secrets** | `secrets.yaml` | Stores AWS & MongoDB Atlas credentials | diff --git a/docs/docs/guides/parent-gcp-gke-autopilot.md b/docs/docs/guides/parent-gcp-gke-autopilot.md index ea772c3c..36d48176 100644 --- a/docs/docs/guides/parent-gcp-gke-autopilot.md +++ b/docs/docs/guides/parent-gcp-gke-autopilot.md @@ -17,14 +17,14 @@ With this setup, developers can **deploy microservices to GKE Autopilot** while --- -# **1️⃣ Prerequisites** +# **Prerequisites** Before configuring the parent stack, ensure that: -βœ… You have a **GCP account** and a **GCP project**. +You have a **GCP account** and a **GCP project**. -βœ… You have a **GCP service account with proper IAM permissions** to create GKE clusters and other resources. +You have a **GCP service account with proper IAM permissions** to create GKE clusters and other resources. -βœ… **Simple Container** is installed: +**Simple Container** is installed: ```sh curl -s "https://dist.simple-container.com/sc.sh" | bash @@ -32,7 +32,7 @@ Before configuring the parent stack, ensure that: --- -# **2️⃣ Setting Up GCP Authentication & Secrets** +# **Setting Up GCP Authentication & Secrets** ## **Step 1: Define `secrets.yaml`** Create the **`.sc/stacks/devops/secrets.yaml`** file to store GCP credentials: @@ -66,15 +66,15 @@ values: MONGODB_ATLAS_PRIVATE_KEY: "private-key-456" ``` -### **πŸ”Ή What This Does** +### **What This Does** -βœ… **Stores GCP service account credentials** (`gcloud`). +**Stores GCP service account credentials** (`gcloud`). -βœ… **Saves API tokens for DNS management**. +**Saves API tokens for DNS management**. --- -# **3️⃣ Configuring Infrastructure Provisioning (`server.yaml`)** +# **Configuring Infrastructure Provisioning (`server.yaml`)** Now, define **`.sc/stacks/devops/server.yaml`** to provision **GKE Autopilot, CloudSQL, Redis, and Pub/Sub**. @@ -167,19 +167,19 @@ resources: topic: workers.image-generator ``` -### **πŸ”Ή What This Does** +### **What This Does** -βœ… **Configures Pulumi** for managing **state in a Google Cloud Storage bucket**. +**Configures Pulumi** for managing **state in a Google Cloud Storage bucket**. -βœ… **Uses GCP KMS to encrypt secrets**. +**Uses GCP KMS to encrypt secrets**. -βœ… **Defines a GKE Autopilot template** (`stack-per-app-gke`) for deploying workloads. +**Defines a GKE Autopilot template** (`stack-per-app-gke`) for deploying workloads. -βœ… **Provisions MongoDB Atlas, Redis, Pub/Sub, and Artifact Registry** to support microservices. +**Provisions MongoDB Atlas, Redis, Pub/Sub, and Artifact Registry** to support microservices. --- -# **4️⃣ Advanced Networking Configuration** +# **Advanced Networking Configuration** ## **Private VPC and Static Egress IP** @@ -188,39 +188,40 @@ For production environments that require network isolation and static egress IPs ```yaml # File: "myproject/.sc/stacks/devops/server.yaml" resources: - production: - template: stack-per-app-gke - resources: - gke-autopilot-res: - type: gcp-gke-autopilot-cluster - config: - gkeMinVersion: "1.33.4-gke.1245000" - projectId: "${auth:gcloud.projectId}" - credentials: "${auth:gcloud}" - location: europe-west3 - - # Private VPC Configuration - privateVpc: true # Creates dedicated VPC with automatic peering - - # Static Egress IP Configuration - externalEgressIp: - enabled: true # Enables CloudNAT with static IP - # existing: "projects/my-project/regions/europe-west3/addresses/my-static-ip" # Optional: use existing IP + resources: + production: + template: stack-per-app-gke + resources: + gke-autopilot-res: + type: gcp-gke-autopilot-cluster + config: + gkeMinVersion: "1.33.4-gke.1245000" + projectId: "${auth:gcloud.projectId}" + credentials: "${auth:gcloud}" + location: europe-west3 + + # Private VPC Configuration + privateVpc: true # Creates dedicated VPC with automatic peering + + # Static Egress IP Configuration + externalEgressIp: + enabled: true # Enables CloudNAT with static IP + # existing: "projects/my-project/regions/europe-west3/addresses/my-static-ip" # Optional: use existing IP ``` -### **πŸ”Ή What Private VPC Does** +### **What Private VPC Does** -βœ… **Creates dedicated VPC**: `{cluster-name}-vpc` with isolated networking +**Creates dedicated VPC**: `{cluster-name}-vpc` with isolated networking -βœ… **Automatic subnet allocation**: Environment-based CIDR ranges (production: 10.1.0.0/16, staging: 10.2.0.0/16) +**Automatic subnet allocation**: Environment-based CIDR ranges (production: 10.1.0.0/16, staging: 10.2.0.0/16) -βœ… **VPC peering**: Automatic bidirectional peering with default VPC for shared resources +**VPC peering**: Automatic bidirectional peering with default VPC for shared resources -βœ… **CloudNAT isolation**: Each environment gets separate CloudNAT (prevents conflicts) +**CloudNAT isolation**: Each environment gets separate CloudNAT (prevents conflicts) -βœ… **Shared resource access**: Production can access staging Redis/CloudSQL via VPC peering +**Shared resource access**: Production can access staging Redis/CloudSQL via VPC peering -### **πŸ”Ή Network Architecture** +### **Network Architecture** ``` Production VPC (10.1.0.0/16) ←→ Default VPC (10.128.0.0/20) @@ -229,17 +230,17 @@ Production VPC (10.1.0.0/16) ←→ Default VPC (10.128.0.0/20) └── VPC Peering └── Shared Redis/CloudSQL ``` -### **πŸ”Ή When to Use Private VPC** +### **When to Use Private VPC** -βœ… **Multiple environments**: Prevents CloudNAT subnet conflicts between staging/production +**Multiple environments**: Prevents CloudNAT subnet conflicts between staging/production -βœ… **Network isolation**: Production workloads isolated from other environments +**Network isolation**: Production workloads isolated from other environments -βœ… **Compliance requirements**: Dedicated network boundaries for security +**Compliance requirements**: Dedicated network boundaries for security -βœ… **Static egress IPs**: Required for external API allowlisting +**Static egress IPs**: Required for external API allowlisting -### **πŸ”Ή Cost Considerations** +### **Cost Considerations** - **VPC peering**: No additional cost for traffic within same region - **CloudNAT**: Per-NAT gateway and data processing charges apply @@ -247,7 +248,7 @@ Production VPC (10.1.0.0/16) ←→ Default VPC (10.128.0.0/20) --- -# **5️⃣ Provisioning the GCP & GKE Autopilot Parent Stack** +# **Provisioning the GCP & GKE Autopilot Parent Stack** Once `server.yaml` is configured, **provision** the infrastructure: ```sh @@ -256,15 +257,15 @@ sc provision -s devops ### **What This Does** -βœ… Creates a **Google Cloud Storage bucket** for state storage. +Creates a **Google Cloud Storage bucket** for state storage. -βœ… Deploys **MongoDB Atlas, Redis, and Pub/Sub** in GCP. +Deploys **MongoDB Atlas, Redis, and Pub/Sub** in GCP. -βœ… Configures **GKE Autopilot for running microservices**. +Configures **GKE Autopilot for running microservices**. --- -# **6️⃣ Deploying Microservices to GKE Autopilot** +# **Deploying Microservices to GKE Autopilot** Once the infrastructure is provisioned, developers can deploy their microservices. ## **Step 1: Define `client.yaml` for a Microservice** @@ -298,7 +299,7 @@ stacks: sc deploy -s myservice -e staging ``` -βœ… The service is **automatically deployed to GKE Autopilot** using the defined settings. +The service is **automatically deployed to GKE Autopilot** using the defined settings. ### **Namespace layout** @@ -311,7 +312,7 @@ This isolation is automatic and is what makes `sc destroy -s myservice -e ` --- -# **7️⃣ Advanced Configuration: Vertical Pod Autoscaler (VPA)** +# **Advanced Configuration: Vertical Pod Autoscaler (VPA)** GKE Autopilot supports **Vertical Pod Autoscaler (VPA)** for automatic resource optimization. Simple Container provides built-in VPA support for both **application deployments** and **Caddy ingress controllers**. @@ -395,23 +396,24 @@ resources: ## **VPA Best Practices for GKE Autopilot** -βœ… **Use `Auto` mode** for ingress controllers like Caddy to ensure proper resource scaling +**Use `Auto` mode** for ingress controllers like Caddy to ensure proper resource scaling -βœ… **Set appropriate `minAllowed`** to prevent resource starvation +**Set appropriate `minAllowed`** to prevent resource starvation -βœ… **Set reasonable `maxAllowed`** to control costs +**Set reasonable `maxAllowed`** to control costs -βœ… **Monitor VPA recommendations** before enabling automatic updates +**Monitor VPA recommendations** before enabling automatic updates -βœ… **Combine with manual resource limits** for fine-grained control +**Combine with manual resource limits** for fine-grained control --- -# **8️⃣ Advanced Configuration: Pod Priority and Preemption Control** +# **Advanced Configuration: Pod Priority and Preemption Control** ## **What is PriorityClass?** Kubernetes **PriorityClass** allows you to specify the importance of pods relative to other pods. When resources are scarce, higher priority pods are: + - Scheduled before lower priority pods - Able to preempt lower priority pods if necessary @@ -420,6 +422,7 @@ On **GKE Autopilot**, this is critical for preventing your workloads from being ## **Default Behavior** Without a PriorityClass, pods are created with **priority 0** (the default). This means: + - System critical pods (priority: 2000000000) will preempt your pods - Your pods may be evicted during node pressure - "Balloon pods" can displace your workloads @@ -496,11 +499,12 @@ stacks: --- -# **9️⃣ Advanced Configuration: Large Temporary Storage** +# **Advanced Configuration: Large Temporary Storage** ## **What are Generic Ephemeral Volumes?** **Generic Ephemeral Volumes** provide **truly temporary storage** that: + - Supports sizes up to **64TB** (vs 10GB limit for regular ephemeral storage) - Creates a PersistentVolumeClaim **automatically for each pod** - **Deletes the PVC when the pod is deleted** (truly ephemeral) @@ -509,6 +513,7 @@ stacks: ## **Why You Need This** GKE Autopilot **hard-limits** regular ephemeral storage to **10GB maximum**. This limitation: + - Cannot be increased through configuration - Cannot be bypassed with VPA - Creates bottlenecks for applications needing more temp storage @@ -585,7 +590,7 @@ cloudExtras: --- -# **πŸ”Ÿ Advanced Configuration: Kubernetes CloudExtras** +# **Advanced Configuration: Kubernetes CloudExtras** Beyond VPA, Simple Container supports comprehensive Kubernetes configuration through `cloudExtras`. This section covers all available options for fine-tuning your GKE Autopilot deployments. @@ -684,16 +689,16 @@ stacks: | Field | Type | Description | GKE Autopilot Support | |----------------------|---------------------|----------------------------------------------|--------------------------------| -| `nodeSelector` | `map[string]string` | Node selection labels | βœ… Custom labels supported | -| `disruptionBudget` | `object` | Pod disruption budget for HA | βœ… Full support | -| `rollingUpdate` | `object` | Rolling update strategy | βœ… Full support | -| `affinity` | `object` | Pod affinity and anti-affinity | βœ… With workload separation | -| `tolerations` | `[]object` | Pod tolerations for taints | βœ… Custom tolerations | -| `vpa` | `object` | Vertical Pod Autoscaler | βœ… Native GKE support | -| `readinessProbe` | `object` | Global readiness probe | βœ… Full support | -| `livenessProbe` | `object` | Global liveness probe | βœ… Full support | -| `priorityClassName` | `string` | Kubernetes PriorityClass for pod scheduling | βœ… Full support | -| `ephemeralVolumes` | `[]object` | Generic ephemeral volumes (>10GB storage) | βœ… Full support | +| `nodeSelector` | `map[string]string` | Node selection labels | Custom labels supported | +| `disruptionBudget` | `object` | Pod disruption budget for HA | Full support | +| `rollingUpdate` | `object` | Rolling update strategy | Full support | +| `affinity` | `object` | Pod affinity and anti-affinity | With workload separation | +| `tolerations` | `[]object` | Pod tolerations for taints | Custom tolerations | +| `vpa` | `object` | Vertical Pod Autoscaler | Native GKE support | +| `readinessProbe` | `object` | Global readiness probe | Full support | +| `livenessProbe` | `object` | Global liveness probe | Full support | +| `priorityClassName` | `string` | Kubernetes PriorityClass for pod scheduling | Full support | +| `ephemeralVolumes` | `[]object` | Generic ephemeral volumes (>10GB storage) | Full support | ## **Node Selection and Workload Separation** @@ -721,6 +726,7 @@ cloudExtras: ``` **How it works:** + - GKE Autopilot automatically creates nodes with your custom labels - Pods are scheduled only on nodes matching the `nodeSelector` - Tolerations allow pods to run on tainted nodes @@ -789,6 +795,7 @@ cloudExtras: ``` **Use Cases for HTTP Headers:** + - **Multi-tenant routing** - Route health checks to correct tenant backend - **Authentication bypass** - Bypass authentication for health check endpoints - **Custom routing** - Direct health checks through proxies/load balancers @@ -848,11 +855,11 @@ stacks: --- -# **9️⃣ Summary** +# **Summary** | Step | Command | Purpose | |---------------------|-------------------------------------|-----------------------------------------| | **Define Secrets** | `secrets.yaml` | Stores GCP credentials | | **Configure Infra** | `server.yaml` | Defines GKE Autopilot & GCP resources | | **Provision Infra** | `sc provision -s devops` | Deploys GCP infrastructure | | **Define Service** | `client.yaml` | Describes a microservice deployment | -| **Deploy Service** | `sc deploy -s myservice -e staging` | Deploys a microservice to GKE Autopilot | +| **Deploy Service** | `sc deploy -s myservice -e staging` | Deploys a microservice to GKE Autopilot | \ No newline at end of file diff --git a/docs/docs/guides/parent-pure-kubernetes.md b/docs/docs/guides/parent-pure-kubernetes.md index 881fae49..512afd03 100644 --- a/docs/docs/guides/parent-pure-kubernetes.md +++ b/docs/docs/guides/parent-pure-kubernetes.md @@ -18,15 +18,15 @@ With this setup, developers can deploy microservices without needing to manage t --- -# **1️⃣ Prerequisites** +# **Prerequisites** Before configuring the parent stack, ensure that: -βœ… A **Kubernetes cluster** is running and accessible. +A **Kubernetes cluster** is running and accessible. -βœ… You have a **`kubeconfig` file** for authentication. +You have a **`kubeconfig` file** for authentication. -βœ… Simple Container is installed: +Simple Container is installed: ```sh curl -s "https://dist.simple-container.com/sc.sh" | bash @@ -34,7 +34,7 @@ Before configuring the parent stack, ensure that: --- -# **2️⃣ Setting Up Secrets for Kubernetes Cluster Authentication** +# **Setting Up Secrets for Kubernetes Cluster Authentication** In **self-managed Kubernetes clusters**, `sc` needs a `kubeconfig` file for authentication. @@ -79,15 +79,15 @@ values: pass-phrase: some-secret-passphrase ``` -### **πŸ”Ή What This Does** +### **What This Does** -βœ… Stores **Kubernetes authentication (`kubeconfig`)**. +Stores **Kubernetes authentication (`kubeconfig`)**. -βœ… Saves **Docker registry credentials** for pulling images. +Saves **Docker registry credentials** for pulling images. --- -# **3️⃣ Configuring Infra Provisioning (`server.yaml`)** +# **Configuring Infra Provisioning (`server.yaml`)** Now, define **`.sc/stacks/devops/server.yaml`** to provision infrastructure inside Kubernetes. @@ -162,20 +162,20 @@ resources: kubeconfig: "${auth:kubernetes}" ``` -### **πŸ”Ή What This Does** +### **What This Does** -βœ… **Configures Pulumi for state management** (`fs` for local storage). +**Configures Pulumi for state management** (`fs` for local storage). -βœ… **Defines deployment templates** (`kubernetes-cloudrun`). +**Defines deployment templates** (`kubernetes-cloudrun`). -βœ… **Provisions Kubernetes resources**: +**Provisions Kubernetes resources**: - **Caddy** β†’ Handles ingress and routing. - **PostgreSQL, RabbitMQ, Redis, MongoDB** β†’ Deployed using **Helm operators**. --- -# **4️⃣ Provisioning the Kubernetes Parent Stack** +# **Provisioning the Kubernetes Parent Stack** Once `server.yaml` is configured, **provision** the Kubernetes infrastructure: @@ -185,15 +185,15 @@ sc provision -s devops ### **What This Does** -βœ… Connects to **Kubernetes using `kubeconfig`**. +Connects to **Kubernetes using `kubeconfig`**. -βœ… Deploys **Caddy, PostgreSQL, RabbitMQ, Redis, MongoDB** inside Kubernetes. +Deploys **Caddy, PostgreSQL, RabbitMQ, Redis, MongoDB** inside Kubernetes. -βœ… Configures **persistent storage and networking**. +Configures **persistent storage and networking**. --- -# **5️⃣ Deploying Microservices to Kubernetes** +# **Deploying Microservices to Kubernetes** Once the infrastructure is provisioned, developers can deploy their microservices. @@ -231,7 +231,7 @@ stacks: sc deploy -s myservice -e production ``` -βœ… The service is **automatically deployed to Kubernetes** using the defined settings. +The service is **automatically deployed to Kubernetes** using the defined settings. ### **Namespace layout** @@ -244,7 +244,7 @@ This isolation is automatic and is what makes `sc destroy -s myservice -e ` --- -# **6️⃣ Summary** +# **Summary** | Step | Command | Purpose | |---------------------|----------------------------------------|-----------------------------------------------------| @@ -252,4 +252,4 @@ This isolation is automatic and is what makes `sc destroy -s myservice -e ` | **Configure Infra** | `server.yaml` | Defines Kubernetes resources (DBs, queues, ingress) | | **Provision Infra** | `sc provision -s devops` | Deploys Kubernetes resources | | **Define Service** | `client.yaml` | Describes a microservice deployment | -| **Deploy Service** | `sc deploy -s myservice -e production` | Deploys a microservice to Kubernetes | +| **Deploy Service** | `sc deploy -s myservice -e production` | Deploys a microservice to Kubernetes | \ No newline at end of file diff --git a/docs/docs/guides/resource-adoption.md b/docs/docs/guides/resource-adoption.md index b95d095f..c3ff326f 100644 --- a/docs/docs/guides/resource-adoption.md +++ b/docs/docs/guides/resource-adoption.md @@ -2,7 +2,7 @@ Adopt existing cloud infrastructure into Simple Container without downtime or modifications. This guide shows how to import existing resources and immediately gain access to Simple Container's deployment and management capabilities. -## 🎯 **What is Resource Adoption?** +## **What is Resource Adoption?** Resource adoption allows you to **import existing cloud resources** into Simple Container's management without creating new resources or modifying existing ones. Your applications continue running unchanged while gaining access to Simple Container's features. @@ -10,13 +10,13 @@ Resource adoption allows you to **import existing cloud resources** into Simple | Resource Type | Provider | Description | Status | |------------------------|--------------|-------------------------------|-------------| -| **MongoDB Atlas** | MongoDB | Existing Atlas clusters | βœ… Available | -| **Cloud SQL Postgres** | Google Cloud | Existing PostgreSQL instances | βœ… Available | -| **Redis Memorystore** | Google Cloud | Existing Redis instances | βœ… Available | -| **GKE Autopilot** | Google Cloud | Existing Kubernetes clusters | βœ… Available | -| **GCS Buckets** | Google Cloud | Existing storage buckets | βœ… Available | +| **MongoDB Atlas** | MongoDB | Existing Atlas clusters | Available | +| **Cloud SQL Postgres** | Google Cloud | Existing PostgreSQL instances | Available | +| **Redis Memorystore** | Google Cloud | Existing Redis instances | Available | +| **GKE Autopilot** | Google Cloud | Existing Kubernetes clusters | Available | +| **GCS Buckets** | Google Cloud | Existing storage buckets | Available | -## πŸš€ **Quick Start** +## **Quick Start** ### **Step 1: Identify Resources to Adopt** @@ -76,9 +76,9 @@ resources: sc provision -s infrastructure # Expected output: -# βœ… Adopting MongoDB Atlas cluster your-existing-cluster (not creating) -# βœ… Adopting Cloud SQL instance your-existing-instance (not creating) -# βœ… Creating Artifact Registry (provisioning new resource) +# Adopting MongoDB Atlas cluster your-existing-cluster (not creating) +# Adopting Cloud SQL instance your-existing-instance (not creating) +# Creating Artifact Registry (provisioning new resource) ``` ### **Step 4: Deploy Services** @@ -98,7 +98,7 @@ stacks: # ... service configuration ``` -## πŸ“‹ **Resource-Specific Adoption** +## **Resource-Specific Adoption** ### **MongoDB Atlas Adoption** @@ -120,6 +120,7 @@ mongodb: ``` **Requirements:** + - MongoDB Atlas API keys with project access - Existing cluster name and project ID - Cluster must be accessible from your applications @@ -146,6 +147,7 @@ postgres: ``` **Requirements:** + - GCP service account with Cloud SQL Admin permissions - Existing instance name and connection name - Root password for database user creation @@ -166,6 +168,7 @@ redis: ``` **Requirements:** + - GCP service account with Redis Admin permissions - Existing Redis instance ID - Instance must be accessible from your applications @@ -190,6 +193,7 @@ gke-cluster: ``` **Requirements:** + - GCP service account with GKE Admin permissions - Existing cluster name and location - Cluster must be accessible for deployments @@ -210,11 +214,12 @@ storage: ``` **Requirements:** + - GCP service account with Storage Admin permissions - Existing bucket name - Bucket must be accessible for your applications -## πŸ”§ **Multi-Environment Adoption** +## **Multi-Environment Adoption** Adopt resources across multiple environments with consistent naming: @@ -256,12 +261,13 @@ resources: ``` **Benefits:** -- βœ… Same resource names across environments -- βœ… Identical client.yaml configuration -- βœ… Easy environment switching -- βœ… Consistent developer experience -## πŸ›‘οΈ **Security & Best Practices** +- Same resource names across environments +- Identical client.yaml configuration +- Easy environment switching +- Consistent developer experience + +##️ **Security & Best Practices** ### **Secrets Management** @@ -296,11 +302,13 @@ auth: Ensure service accounts have minimal required permissions: **MongoDB Atlas:** + - Project Read access - Cluster Read access - Database User Admin (for user creation) **Google Cloud:** + - Cloud SQL Admin (for PostgreSQL) - Redis Admin (for Redis) - Kubernetes Engine Admin (for GKE) @@ -309,13 +317,14 @@ Ensure service accounts have minimal required permissions: ### **Validation Checklist** Before adoption: + - [ ] Resources are accessible from your applications - [ ] Service accounts have required permissions - [ ] Resource names and IDs are correct - [ ] Secrets are properly encrypted - [ ] Network connectivity is configured -## πŸ” **Troubleshooting** +## **Troubleshooting** ### **Common Issues** @@ -364,26 +373,26 @@ kubectl --kubeconfig=kubeconfig get nodes gsutil ls gs://bucket-name ``` -## πŸ“ˆ **Benefits of Resource Adoption** +## **Benefits of Resource Adoption** ### **Immediate Value** -- βœ… **Zero Downtime** - Applications continue running unchanged -- βœ… **No Resource Modification** - Existing resources remain untouched -- βœ… **Instant SC Features** - Immediate access to deployment capabilities -- βœ… **Unified Management** - Single interface for all infrastructure +- **Zero Downtime** - Applications continue running unchanged +- **No Resource Modification** - Existing resources remain untouched +- **Instant SC Features** - Immediate access to deployment capabilities +- **Unified Management** - Single interface for all infrastructure ### **Long-Term Benefits** -- βœ… **Consistent Environments** - Same configuration across dev/staging/prod -- βœ… **Simplified Operations** - Single deployment workflow -- βœ… **Enhanced Security** - Centralized secrets management -- βœ… **Better Scaling** - Automatic resource optimization +- **Consistent Environments** - Same configuration across dev/staging/prod +- **Simplified Operations** - Single deployment workflow +- **Enhanced Security** - Centralized secrets management +- **Better Scaling** - Automatic resource optimization ### **Cost Optimization** -- βœ… **Resource Reuse** - No duplicate infrastructure costs -- βœ… **Efficient Scaling** - Optimize existing resource utilization -- βœ… **Reduced Complexity** - Lower operational overhead +- **Resource Reuse** - No duplicate infrastructure costs +- **Efficient Scaling** - Optimize existing resource utilization +- **Reduced Complexity** - Lower operational overhead -## πŸŽ“ **Next Steps** +## **Next Steps** After successful resource adoption: @@ -398,10 +407,10 @@ After successful resource adoption: Need help with resource adoption? - **Documentation**: [Simple Container Docs](../index.md) -- **Examples**: [Resource Adoption Examples](../examples/resource-adoption/) +- **Examples**: [Resource Adoption Examples](../examples/resource-adoption/README.md) - **Community**: [GitHub Discussions](https://github.com/simple-container-com/api/discussions) - **Support**: [support@simple-container.com](mailto:support@simple-container.com) --- -**Ready to adopt your existing infrastructure?** Start with our [Quick Start](#quick-start) guide above! πŸš€ +**Ready to adopt your existing infrastructure?** Start with our [Quick Start](#quick-start) guide above! \ No newline at end of file diff --git a/docs/docs/guides/secrets-management.md b/docs/docs/guides/secrets-management.md index 590caa42..35d3ae2b 100644 --- a/docs/docs/guides/secrets-management.md +++ b/docs/docs/guides/secrets-management.md @@ -689,4 +689,3 @@ Simple Container's secrets management provides a secure, Git-native way to handl - **Integrated**: Seamless integration with Simple Container deployments Use the commands outlined in this guide to implement robust secrets management in your Simple Container projects. - diff --git a/docs/docs/guides/service-steps-to-deploy.md b/docs/docs/guides/service-steps-to-deploy.md index e6f0261a..a1d80046 100644 --- a/docs/docs/guides/service-steps-to-deploy.md +++ b/docs/docs/guides/service-steps-to-deploy.md @@ -13,25 +13,25 @@ date: '2024-06-12' As a **developer at Organization**, you can **deploy a new service (`billing`)** with **Simple Container** **without requiring DevOps involvement**. -βœ… **MongoDB and PostgreSQL are already available** in the organization's infrastructure. +**MongoDB and PostgreSQL are already available** in the organization's infrastructure. -βœ… **You only need to define `client.yaml`** and use familiar tools like **Dockerfile & docker-compose**. +**You only need to define `client.yaml`** and use familiar tools like **Dockerfile & docker-compose**. -βœ… **Deployment is automated** using `sc deploy`. +**Deployment is automated** using `sc deploy`. --- -# **1️⃣ Steps to Deploy the `billing` Service** +# **Steps to Deploy the `billing` Service** Follow these steps to deploy the **`billing`** service: -### **πŸ”Ή Step 1: Create the Service Directory** +### **Step 1: Create the Service Directory** ```sh mkdir -p .sc/stacks/billing ``` --- -### **πŸ”Ή Step 2: Define `client.yaml`** +### **Step 2: Define `client.yaml`** Create and edit **`.sc/stacks/billing/client.yaml`**: ```yaml --- @@ -60,13 +60,13 @@ stacks: POSTGRES_PASSWORD: "${resource:postgres.password}" # Securely inject PostgreSQL password ``` -βœ… **This defines how `billing` connects to existing infrastructure**. +**This defines how `billing` connects to existing infrastructure**. -βœ… **No changes required from DevOps** since resources (`mongodb`, `postgres`) are already available. +**No changes required from DevOps** since resources (`mongodb`, `postgres`) are already available. --- -### **πŸ”Ή Step 3: Define `docker-compose.yaml`** +### **Step 3: Define `docker-compose.yaml`** Create a **Docker Compose file** for running the service locally **and deploying it**. ```yaml @@ -88,11 +88,11 @@ services: POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} ``` -βœ… **Ensures the service runs identically in local and cloud environments**. +**Ensures the service runs identically in local and cloud environments**. --- -### **πŸ”Ή Step 4: Deploy the Service** +### **Step 4: Deploy the Service** Run the following command to deploy **`billing`** to **staging**: ```sh sc deploy -s billing -e staging @@ -103,13 +103,13 @@ To deploy to **production**, use: sc deploy -s billing -e production ``` -βœ… **SC automatically builds, pushes, and deploys the service to Organization's cloud infrastructure**. +**SC automatically builds, pushes, and deploys the service to Organization's cloud infrastructure**. -βœ… **Secrets (e.g., `POSTGRES_PASSWORD`) are securely injected**. +**Secrets (e.g., `POSTGRES_PASSWORD`) are securely injected**. --- -### **πŸ”Ή Step 5: Verify Deployment** +### **Step 5: Verify Deployment** Verify your service deployment: - **Check your cloud provider console** (AWS ECS, GKE, etc.) to confirm the service is running @@ -117,11 +117,11 @@ Verify your service deployment: - **Check cloud provider logs** (CloudWatch for AWS, Cloud Logging for GCP) for any issues - **Monitor resource usage** through your cloud provider's monitoring tools -βœ… **You can now monitor and debug your service using your cloud provider's native tools**. +**You can now monitor and debug your service using your cloud provider's native tools**. --- -# **2️⃣ Summary** +# **Summary** | Step | Command | Purpose | |----------------------------------|---------------------------------------|-------------------------------------| | **Create the service directory** | `mkdir -p .sc/stacks/billing` | Sets up `billing` service stack | @@ -130,4 +130,4 @@ Verify your service deployment: | **Deploy to Staging** | `sc deploy -s billing -e staging` | Deploys the new service | | **Deploy to Production** | `sc deploy -s billing -e production` | Deploys to production | | **Verify Deployment** | Check cloud provider console | Monitors service health | -| **View Logs** | Use cloud provider logging tools | Debugs issues | +| **View Logs** | Use cloud provider logging tools | Debugs issues | \ No newline at end of file diff --git a/docs/docs/images/sc-logo.png b/docs/docs/images/sc-logo.png index 17fb9e34..473f9c95 100644 Binary files a/docs/docs/images/sc-logo.png and b/docs/docs/images/sc-logo.png differ diff --git a/docs/docs/index.md b/docs/docs/index.md index 2214fd7b..0f0e5e18 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,6 +1,6 @@ --- -title: Index page for Simple Container Docs -description: 'simple-container.com offers high-level primitives for quick and easy set-up of integration and delivery pipelines' # A short summary for search engines to display, max 120 chars +title: Simple Container +description: Open-source CLI for declaring and deploying cloud infrastructure as YAML. platform: platform product: simple-container category: devguide @@ -10,95 +10,29 @@ date: '2024-06-12' # Simple Container -Unlike other products whose main focus usually is to provide fine-grained configuration options for either CI or CD -aspect of software delivery, Simple Container offers high-level primitives for quick and easy set-up of integration -and delivery pipelines for microservice applications. Simple Container reflects simplicity of use and -container-native nature of the provided DevOps practices. +Simple Container (SC) is an open-source CLI for declaring and deploying cloud +infrastructure as YAML. A `server.yaml` describes shared infrastructure (databases, +queues, secrets, registrars, deployment templates); a `client.yaml` describes a +service that consumes it. SC translates both into Pulumi calls and ships them to +AWS, GCP, or any conformant Kubernetes cluster. -## Why do I need Simple-Container.com? +## Start here -Simple Container allows companies to **scale their microservices infrastructure from startup to enterprise** with quantified advantages: +- [Installation](getting-started/installation.md) β€” get the `sc` CLI on your machine. +- [Quick Start](getting-started/quick-start.md) β€” deploy a first service end-to-end. +- [Main Concepts](concepts/main-concepts.md) β€” parent stacks, service stacks, and how they compose. +- [Reference](reference/supported-resources.md) β€” full list of resources, templates, and config keys. +- [Guides](guides/index.md) β€” task-focused walkthroughs (ECS Fargate, GKE Autopilot, pure Kubernetes, secrets, migration). -**πŸš€ 500x Faster Scaling:** +## Forge β€” built on SC -- **Customer Onboarding**: 5 minutes vs 2-3 days traditional approaches -- **Developer Onboarding**: 1-2 hours vs 2-4 weeks Kubernetes/AWS training -- **Time to First Deployment**: 15 minutes vs 2-3 days infrastructure setup +[Forge](https://simple-forge.com) is our AI workflow engine. It emits SC YAML +natively via the MCP server, so if you drive deployments through Forge, every +workflow run produces the same `server.yaml` / `client.yaml` shapes documented +here. The integration is first-class β€” Forge speaks SC primitives, not a +translation layer. -**πŸ’° 70% Cost Reduction:** +## Help -- **DevOps Efficiency**: 1 engineer per 100+ customers vs 1 per 10-20 traditional -- **Configuration Complexity**: 90% reduction (500 vs 5000+ lines for 100 customers) -- **Operational Staff**: 80% reduction in DevOps overhead - -If you're already familiar with tools like [Terraform](https://www.terraform.io/) or [Pulumi](https://www.pulumi.com/), -you know that **scaling Infrastructure as Code becomes exponentially complex** as you add customers. Traditional approaches require: - -- **Linear DevOps scaling** (more customers = more DevOps engineers) -- **Manual configuration** for each customer deployment -- **Complex secret management** across hundreds of services -- **Infrastructure drift** and inconsistencies - -**Simple Container transforms this challenge** by providing separation of concerns where: - -- **DevOps manages infrastructure once** in parent stacks -- **Developers deploy self-service** with simple client configurations -- **Scaling complexity remains constant** regardless of customer count - -Simple Container delivers **enterprise-grade scaling** with **startup-level simplicity** through: - -**🎯 Quantified Scaling Advantages:** - -* **500x faster customer onboarding** - 5 minutes vs 2-3 days -* **90% configuration reduction** - 500 vs 5000+ lines for 100 customers -* **5x operational efficiency** - 1 DevOps per 100+ vs 10-20 customers -* **Zero downtime migrations** - one-line configuration changes -* **70% cost reduction** through intelligent resource sharing - -**πŸ”§ Built for Scale:** - -* **Multi-dimensional resource allocation** - shared and dedicated resource pools -* **Automatic namespace isolation** for multi-tenant security -* **Template-based deployments** eliminating infrastructure drift -* **Self-service developer operations** without DevOps bottlenecks -* **Cloud-agnostic flexibility** across Kubernetes, AWS, and GCP - -**Real-World Impact:** - -- **SaaS companies** scale from 10 to 1000 customers with 80% staff reduction -- **Enterprise organizations** achieve instant multi-region expansion -- **Development teams** deploy independently without infrastructure expertise - -Please read [Why Simple Container](concepts/motivation.md) to understand the quantified scaling advantages and [Scaling Advantages](advanced/scaling-advantages.md) for detailed comparison with traditional approaches. - -## Getting Started - -Ready to get started? Follow our structured learning path: - -1. **[Getting Started Guide](getting-started/index.md)** - Overview and installation -2. **[Quick Start](getting-started/quick-start.md)** - Deploy your first app in 15 minutes -3. **[Core Concepts](concepts/main-concepts.md)** - Understand the fundamentals - -## Documentation Sections - -### πŸš€ [Getting Started](getting-started/index.md) -Perfect for newcomers - installation, quick start, and first deployment. - -### 🧠 [Core Concepts](concepts/main-concepts.md) -Understand templates, resources, environments, and the Simple Container philosophy. - -### πŸ“– [Guides](guides/index.md) -Step-by-step tutorials for ECS Fargate, GKE Autopilot, Kubernetes, and operational tasks. - -### πŸ’‘ [Examples](examples/README.md) -Real-world configuration examples from production deployments across different use cases. - -### πŸ“š [Reference](reference/supported-resources.md) -Complete technical documentation, API references, and supported resources. - -### ⚑ [Advanced](advanced/scaling-advantages.md) -Scaling strategies, tool comparisons, and best practices for production environments. - -## Questions/Issues? - -If you have any issues or questions related to Simple-Container.com, please reach out at [support@simple-container.com](mailto:support@simple-container.com). \ No newline at end of file +Issues and questions: [support@simple-container.com](mailto:support@simple-container.com) +or [GitHub](https://github.com/simple-container-com). \ No newline at end of file diff --git a/docs/docs/reference/examples.md b/docs/docs/reference/examples.md index 86be8ab3..73030abc 100644 --- a/docs/docs/reference/examples.md +++ b/docs/docs/reference/examples.md @@ -11,17 +11,17 @@ date: '2024-06-12' # **Examples** -## **1️⃣ Simplifying Microservice Deployment for Developers** +## **Simplifying Microservice Deployment for Developers** One of the biggest challenges in a **microservices architecture** is ensuring that **developers can deploy new services independently** without requiring constant DevOps involvement. ### **How `sc` Helps** -βœ… **Developers only need a `client.yaml` configuration** to deploy a new service. +**Developers only need a `client.yaml` configuration** to deploy a new service. -βœ… **Familiar tooling** like **Dockerfile** and **docker-compose** keeps onboarding simple. +**Familiar tooling** like **Dockerfile** and **docker-compose** keeps onboarding simple. -βœ… **No need for Terraform/Pulumi modifications**β€”DevOps manages infrastructure separately. +**No need for Terraform/Pulumi modifications** β€”DevOps manages infrastructure separately. ### **Example: Adding a New Microservice** With traditional CI/CD pipelines, adding a microservice requires: @@ -53,12 +53,12 @@ stacks: DATABASE_PASSWORD: "${resource:postgres.password}" ``` -βœ… **One simple YAML file replaces hours of DevOps work.** -βœ… **Developers focus on coding, not cloud infrastructure.** +**One simple YAML file replaces hours of DevOps work.** +**Developers focus on coding, not cloud infrastructure.** --- -## **2️⃣ Centralized Infrastructure Management for DevOps** +## **Centralized Infrastructure Management for DevOps** Traditional **microservice deployments** require DevOps teams to configure: @@ -82,47 +82,48 @@ resources: projectId: "${auth:gcloud.projectId}" ``` -βœ… **Once defined, this setup supports all microservices without modifications.** +**Once defined, this setup supports all microservices without modifications.** -βœ… **Developers are isolated from infrastructure complexity.** +**Developers are isolated from infrastructure complexity.** --- -## **3️⃣ Built-in CI/CD, No Need for External Automation** +## **Built-in CI/CD, No Need for External Automation** Most CI/CD tools **require custom scripts** for building, pushing, and deploying services. With `sc`: -βœ… **CI/CD is built-in**β€”no need for **Jenkins, GitHub Actions, or manual Helm deployments**. +**CI/CD is built-in** β€”no need for **Jenkins, GitHub Actions, or manual Helm deployments**. -βœ… **Deploy with a single command**: +**Deploy with a single command**: ```sh sc deploy -s myservice -e staging ``` -βœ… **Automatic rollbacks** make it safer than traditional pipelines. +**Automatic rollbacks** make it safer than traditional pipelines. ### **Comparison: CI/CD Complexity** | Feature | Traditional CI/CD | Simple Container | |-------------------------|--------------------------------------------|--------------------------------| -| **Pipeline Complexity** | Requires scripting (Bash, Terraform, Helm) | **Just use `sc deploy`** | -| **Secret Injection** | Needs Vault, AWS Secrets Manager | **Built-in (`sc secrets`)** | -| **Rollback Mechanism** | Manual process | **Automated rollback support** | +| **Pipeline Complexity** | Requires scripting (Bash, Terraform, Helm) |**Just use `sc deploy`** | +| **Secret Injection** | Needs Vault, AWS Secrets Manager |**Built-in (`sc secrets`)** | +| **Rollback Mechanism** | Manual process |**Automated rollback support** | --- -## **4️⃣ Cloud-Agnostic & Easy Migration** +## **Cloud-Agnostic & Easy Migration** Organizations **often need to migrate workloads** between **AWS, GCP, and Kubernetes clusters**. With Terraform or Pulumi, migrations **require rewriting infrastructure code**. With `sc`, migrations **only require modifying `server.yaml`**, while `client.yaml` remains **unchanged**. -βœ… **Move workloads from AWS to GCP without changing service configurations.** +**Move workloads from AWS to GCP without changing service configurations.** -βœ… **Supports AWS ECS, Kubernetes, and Google Cloud Run natively.** +**Supports AWS ECS, Kubernetes, and Google Cloud Run natively.** + +**Example: Migrating from AWS to GCP** -πŸ”Ή **Example: Migrating from AWS to GCP** - **Terraform/Pulumi:** Requires modifying state storage, networking, IAM policies. -- **SC:** Just update `server.yaml`, **no changes at the service level**. +- **SC:** Just update `server.yaml`,**no changes at the service level**. ```yaml --- @@ -146,19 +147,19 @@ resources: config: instanceSize: "db-f1-micro" ``` -βœ… **Migrate entire workloads in minutes, not weeks.** +**Migrate entire workloads in minutes, not weeks.** --- -## **5️⃣ Secure Secrets Management Built-In** +## **Secure Secrets Management Built-In** Managing secrets securely is **a major challenge in CI/CD**. Most organizations rely on **Vault, AWS Secrets Manager, or Kubernetes Secrets**, requiring **manual configuration**. ### **How `sc` Handles Secrets Automatically** -βœ… **Secrets are securely stored in the cloud provider's native secret manager**. +**Secrets are securely stored in the cloud provider's native secret manager**. -βœ… **No need for manual secret injectionβ€”SC provisions and injects secrets automatically.** +**No need for manual secret injectionβ€”SC provisions and injects secrets automatically.** | Cloud Provider | Secrets Storage | |----------------|-----------------------| @@ -171,27 +172,27 @@ Example **secret injection in `client.yaml`**: secrets: DATABASE_PASSWORD: "${resource:postgres.password}" ``` -βœ… **Automatically stored in AWS/GCP/Kubernetes Secretsβ€”fully managed by `sc`.** +**Automatically stored in AWS/GCP/Kubernetes Secretsβ€”fully managed by `sc`.** --- -## **6️⃣ Faster Time to Market with Less Overhead** +## **Faster Time to Market with Less Overhead** By adopting `sc`, organizations gain: -βœ… **Faster onboarding**β€”developers deploy services with a simple YAML config. +**Faster onboarding** β€”developers deploy services with a simple YAML config. -βœ… **Less DevOps overhead**β€”DevOps teams focus on core infrastructure, not microservices. +**Less DevOps overhead** β€”DevOps teams focus on core infrastructure, not microservices. -βœ… **Reduced CI/CD complexity**β€”built-in deployment automation eliminates external tooling. +**Reduced CI/CD complexity** β€”built-in deployment automation eliminates external tooling. ### **Comparison: Developer Workflow** | Task | Traditional Pipeline | SC-Powered Pipeline | |----------------------------|--------------------------------------|----------------------------------------------| | **Add a new microservice** | Modify Terraform/Pulumi, Helm charts | Add `client.yaml`, deploy instantly | -| **Manage secrets** | Requires Vault, AWS Secrets Manager | **Built-in (`sc secrets`)** | -| **Deploy a service** | Manual CI/CD setup | **`sc deploy -s myservice -e staging`** | -| **Migrate across clouds** | Requires rewriting Terraform/Pulumi | **Update `server.yaml`, no service changes** | +| **Manage secrets** | Requires Vault, AWS Secrets Manager |**Built-in (`sc secrets`)** | +| **Deploy a service** | Manual CI/CD setup |**`sc deploy -s myservice -e staging`** | +| **Migrate across clouds** | Requires rewriting Terraform/Pulumi |**Update `server.yaml`, no service changes** | --- @@ -199,12 +200,12 @@ By adopting `sc`, organizations gain: Organizations adopting **Simple Container (`sc`)** for their **CI/CD pipelines** gain: -βœ… **Faster deployments** with minimal configuration. +**Faster deployments** with minimal configuration. -βœ… **Cloud-agnostic flexibility** without rewriting infrastructure. +**Cloud-agnostic flexibility** without rewriting infrastructure. -βœ… **Reduced DevOps effort**β€”developers manage deployments independently. +**Reduced DevOps effort** β€”developers manage deployments independently. -βœ… **Built-in security and secrets management** without external tools. +**Built-in security and secrets management** without external tools. -By **simplifying microservice deployment**, **reducing overhead**, and **automating infrastructure management**, `sc` **transforms CI/CD pipelines into a developer-friendly, efficient workflow**. \ No newline at end of file +By **simplifying microservice deployment**,**reducing overhead**, and **automating infrastructure management**, `sc`**transforms CI/CD pipelines into a developer-friendly, efficient workflow**. \ No newline at end of file diff --git a/docs/docs/reference/security-cli-commands.md b/docs/docs/reference/security-cli-commands.md index 84a4d30b..e2a16cd7 100644 --- a/docs/docs/reference/security-cli-commands.md +++ b/docs/docs/reference/security-cli-commands.md @@ -16,6 +16,7 @@ sc image scan --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image to scan (e.g., myapp:v1.0) - `--tool`: Scanner tool (grype, trivy, all) (default: grype) - `--fail-on`: Optional quality gate severity (critical, high, medium, low) @@ -66,6 +67,7 @@ sc image scan \ ``` **Exit Codes:** + - 0: Success, no policy violations - 1: Scan failed or policy violation - 2: Tool not installed @@ -80,11 +82,13 @@ sc image sign --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image to sign - `--keyless`: Use keyless signing with OIDC - `--key`: Path to private key (for key-based signing) **Environment Variables:** + - `SIGSTORE_ID_TOKEN`: OIDC token for keyless signing **Examples:** @@ -106,6 +110,7 @@ sc image verify --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image to verify - `--public-key`: Path to public key (for key-based verification) - `--oidc-issuer`: OIDC issuer for keyless verification @@ -136,6 +141,7 @@ sc sbom generate --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image - `--format`: SBOM format (cyclonedx-json, cyclonedx-xml, spdx-json, spdx-tag-value, syft-json) (default: cyclonedx-json) - `--output`: Output file path @@ -159,6 +165,7 @@ sc sbom attach --image IMAGE --sbom FILE [flags] ``` **Flags:** + - `--image` (required): Container image - `--sbom` (required): SBOM file to attach - `--keyless`: Use keyless signing with OIDC. If `--key` is omitted, keyless mode is used. @@ -184,6 +191,7 @@ sc sbom verify --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image - `--output` (required): Output file for verified SBOM - `--keyless`: Use keyless verification @@ -233,6 +241,7 @@ sc provenance attach --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image - `--format`: Provenance format (`slsa-v1.0`) - `--output`: Save the generated predicate locally before attaching @@ -269,6 +278,7 @@ sc provenance verify --image IMAGE [flags] ``` **Flags:** + - `--image` (required): Container image - `--format`: Expected provenance format - `--output`: Output file for verified provenance @@ -311,6 +321,7 @@ sc release create -s STACK -e ENVIRONMENT [flags] ``` **Flags:** + - `-s, --stack` (required): Stack name - `-e, --environment` (required): Environment name - `--yes`: Auto-approve deployment without prompts @@ -335,6 +346,7 @@ sc release create -s mystack -e production --yes 4. Deploy infrastructure **Security Integration:** + - Security operations run automatically if configured in stack - Scanning runs first so policy/reporting artifacts are produced before promotion - Signing, SBOM, and provenance run in parallel after scanning @@ -370,4 +382,4 @@ Available for all commands: - `-v, --verbose`: Verbose output - `--silent`: Silent mode (errors only) -- `-h, --help`: Show help +- `-h, --help`: Show help \ No newline at end of file diff --git a/docs/docs/reference/security-config-schema.md b/docs/docs/reference/security-config-schema.md index 57326751..092ff5f9 100644 --- a/docs/docs/reference/security-config-schema.md +++ b/docs/docs/reference/security-config-schema.md @@ -275,4 +275,4 @@ client: failOn: critical # Adds a stricter quality gate in production ``` -**Result:** Production keeps inherited warnings while adding a stricter quality gate. +**Result:** Production keeps inherited warnings while adding a stricter quality gate. \ No newline at end of file diff --git a/docs/docs/reference/service-available-deployment-schemas.md b/docs/docs/reference/service-available-deployment-schemas.md index 4ec0d96c..65379f42 100644 --- a/docs/docs/reference/service-available-deployment-schemas.md +++ b/docs/docs/reference/service-available-deployment-schemas.md @@ -24,13 +24,13 @@ This guide explains how to configure each deployment type using **`client.yaml`* --- -# **1️⃣ `cloud-compose`: Multi-Container Microservices** +# **`cloud-compose`: Multi-Container Microservices** -βœ… Use **`cloud-compose`** for **microservices that require multiple containers, databases, message queues, or networking**. +Use **`cloud-compose`** for **microservices that require multiple containers, databases, message queues, or networking**. -βœ… Requires a **Dockerfile** and a **`docker-compose.yaml`** file. +Requires a **Dockerfile** and a **`docker-compose.yaml`** file. -βœ… Works with **Kubernetes, ECS Fargate, Cloud Run, etc.** +Works with **Kubernetes, ECS Fargate, Cloud Run, etc.** ## **Example `client.yaml` for `cloud-compose`** ```yaml @@ -67,7 +67,7 @@ stacks: DATABASE_PASSWORD: "${resource:mongodb.password}" ``` -### **πŸ”Ή Required Files** +### **Required Files** - **`Dockerfile`** β†’ Defines how the service is built. - **`docker-compose.yaml`** β†’ Defines how the service runs. @@ -93,13 +93,13 @@ sc deploy -s myservice -e staging --- -# **2️⃣ `single-image`: Single-Container Applications** +# **`single-image`: Single-Container Applications** -βœ… Use **`single-image`** for **single-container services like AWS Lambda or Cloud Run**. +Use **`single-image`** for **single-container services like AWS Lambda or Cloud Run**. -βœ… Only requires a **Dockerfile** (no `docker-compose.yaml` needed). +Only requires a **Dockerfile** (no `docker-compose.yaml` needed). -βœ… Supports **cloud-specific configurations** like AWS Lambda settings. +Supports **cloud-specific configurations** like AWS Lambda settings. ## **Example `client.yaml` for `single-image`** ```yaml @@ -131,7 +131,7 @@ stacks: MONGO_URI: "${resource:mongodb.uri}" ``` -### **πŸ”Ή Required Files** +### **Required Files** - **`Dockerfile`** β†’ Defines how the service is packaged into a container. ### **Example `Dockerfile`** @@ -150,13 +150,13 @@ sc deploy -s myservice -e staging --- -# **3️⃣ `static`: Deploying Static Websites** +# **`static`: Deploying Static Websites** -βœ… Use **`static`** for **deploying static websites** (e.g., React, Vue, Angular). +Use **`static`** for **deploying static websites** (e.g., React, Vue, Angular). -βœ… Requires a **pre-built directory with static files**. +Requires a **pre-built directory with static files**. -βœ… Supports **public cloud storage, CDN caching, and custom domains**. +Supports **public cloud storage, CDN caching, and custom domains**. ## **Example `client.yaml` for `static` Deployment** ```yaml @@ -177,7 +177,7 @@ stacks: location: EUROPE-CENTRAL2 ``` -### **πŸ”Ή Required Files** +### **Required Files** - **A built directory (`public/`)** β†’ Contains `index.html`, `assets/`, etc. ### **Building a Static Site (Example for React)** @@ -194,9 +194,9 @@ sc deploy -s landing-page -e prod --- -# **4️⃣ Summary** +# **Summary** | Deployment Type | Use Case | Required Files | Example Platforms | |---------------------|-------------------------------|-------------------------------------|---------------------------| | **`cloud-compose`** | Multi-container microservices | `Dockerfile`, `docker-compose.yaml` | Kubernetes, ECS Fargate | | **`single-image`** | Single-container applications | `Dockerfile` | AWS Lambda, Cloud Run | -| **`static`** | Static websites | `bundleDir` with HTML/CSS/JS | AWS S3, GCP Cloud Storage | +| **`static`** | Static websites | `bundleDir` with HTML/CSS/JS | AWS S3, GCP Cloud Storage | \ No newline at end of file diff --git a/docs/docs/reference/supported-resources.md b/docs/docs/reference/supported-resources.md index a92f6825..e0e0812f 100644 --- a/docs/docs/reference/supported-resources.md +++ b/docs/docs/reference/supported-resources.md @@ -11,7 +11,41 @@ date: '2024-12-07' # **Supported Resources Reference** -This document provides a comprehensive reference of all supported cloud resources and their properties that can be defined in the **parent stack**. The parent stack is managed by DevOps teams and provides the core infrastructure that microservices consume. +This document lists every cloud resource type SC can provision in a parent +stack (`server.yaml`), with the config keys each accepts. + +## Where resources live in `server.yaml` + +The `resources` block in `server.yaml` is **three nesting levels deep** β€” the +literal key `resources:` appears three times. This is intentional: the outer +`resources` is the per-stack container, the middle `resources` is the per-env +map, and the innermost `resources` is the per-resource map. Skipping any +level is invalid. + +```yaml +schemaVersion: "1.0" +# ... +resources: # (1) per-stack container + registrar: # single registrar shared across envs + type: cloudflare + config: { ... } + resources: # (2) per-env map + staging: # env name + template: ecs-fargate-template # optional; ref into templates[] + resources: # (3) per-resource map + main-db: # user-chosen resource name + type: aws-rds-postgres # see the type tables below + name: main-db + config: + # resource-specific keys (see per-type sections) + production: + # ... same shape +``` + +For the full canonical shape (provisioner, secrets, cicd, templates, +variables) the source of truth is the Go struct `ServerDescriptor` in +`pkg/api/server.go` of the [simple-container-com/api](https://github.com/simple-container-com/api) +repository. ## **Understanding Simple Container Architecture** @@ -237,7 +271,7 @@ resources: When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for S3 bucket access. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - AWS S3 Bucket](../concepts/template-placeholders-advanced.md#s3-bucket) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - AWS S3 Bucket](../concepts/template-placeholders-advanced.md#s3-bucket) #### **ECR Repository** (`ecr-repository`) @@ -307,7 +341,7 @@ resources: When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for PostgreSQL database connection. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - AWS RDS PostgreSQL](../concepts/template-placeholders-advanced.md#rds-postgresql) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - AWS RDS PostgreSQL](../concepts/template-placeholders-advanced.md#rds-postgresql) #### **RDS MySQL** (`aws-rds-mysql`) @@ -343,7 +377,7 @@ resources: When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for MySQL database connection. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - AWS RDS MySQL](../concepts/template-placeholders-advanced.md#rds-mysql) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - AWS RDS MySQL](../concepts/template-placeholders-advanced.md#rds-mysql) #### **CloudTrail Security Alerts** (`aws-cloudtrail-security-alerts`) @@ -382,10 +416,10 @@ resources: slack: webhookUrl: "${secret:security-slack-webhook}" # discord: - # webhookUrl: "${secret:security-discord-webhook}" + # webhookUrl: "${secret:security-discord-webhook}" # telegram: - # chatID: "-1001234567890" - # token: "${secret:security-telegram-token}" + # chatID: "-1001234567890" + # token: "${secret:security-telegram-token}" # Alert selectors (all default to false) alerts: @@ -791,7 +825,7 @@ resources: When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for GCS bucket access with S3-compatible HMAC authentication. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - GCP Bucket](../concepts/template-placeholders-advanced.md#gcp-bucket) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - GCP Bucket](../concepts/template-placeholders-advanced.md#gcp-bucket) #### **Artifact Registry** (`gcp-artifact-registry`) @@ -865,7 +899,7 @@ resources: When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for PostgreSQL connection details. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - GCP PostgreSQL Cloud SQL](../concepts/template-placeholders-advanced.md#postgresql-cloud-sql) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - GCP PostgreSQL Cloud SQL](../concepts/template-placeholders-advanced.md#postgresql-cloud-sql) #### **Redis** (`gcp-redis`) @@ -903,7 +937,7 @@ resources: When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for Redis connection details. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - GCP Redis Memorystore](../concepts/template-placeholders-advanced.md#redis-memorystore) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - GCP Redis Memorystore](../concepts/template-placeholders-advanced.md#redis-memorystore) ### **Messaging Resources** @@ -1298,6 +1332,7 @@ resources: **Backup Security:** MongoDB Atlas encrypts **all backups automatically by default** using your cloud provider's encryption: + - **Automatic encryption**: No configuration required - all snapshots are encrypted at rest - **Cloud provider managed**: Encryption keys managed by AWS/GCP/Azure - **Universal**: Applies to all cluster tiers and backup types (hourly, daily, weekly, monthly) @@ -1309,7 +1344,7 @@ For enterprise customers requiring additional control, MongoDB Atlas also suppor When this resource is used in a client stack via the `uses` section, Simple Container automatically injects environment variables and template placeholders for MongoDB Atlas database connection. -πŸ“– **For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - MongoDB Atlas Cluster](../concepts/template-placeholders-advanced.md#mongodb-atlas-cluster) +**For complete details on environment variables and template placeholders, see:** [Template Placeholders Advanced - MongoDB Atlas Cluster](../concepts/template-placeholders-advanced.md#mongodb-atlas-cluster) **See Also:** @@ -1365,6 +1400,7 @@ resources: ### **State Storage and Secrets Management** The provisioner manages two key components: + - **State Storage**: Stores Pulumi's state (supports `s3-bucket`, `fs`, `gcp-bucket`, `pulumi-cloud`) - **Secrets Provider**: Provides encryption for created resources' confidential outputs @@ -1554,7 +1590,7 @@ alerts: periodSec: 300 ``` -> **πŸ“§ Email Integration**: Each notification channel works independently. When email addresses are configured, email notifications are sent alongside any configured webhook channels. Email recipients must confirm their subscription to receive notifications. +> **Email Integration**: Each notification channel works independently. When email addresses are configured, email notifications are sent alongside any configured webhook channels. Email recipients must confirm their subscription to receive notifications. **Complete Monitoring Configuration:** ```yaml @@ -1595,6 +1631,7 @@ alerts: ``` **Alert Configuration Properties:** + - **`alertName`** - Unique identifier for the CloudWatch alarm - **`description`** - Human-readable description of the alert - **`threshold`** - Numeric threshold value that triggers the alarm @@ -1602,16 +1639,18 @@ alerts: - **`errorLogMessageRegexp`** - (maxErrors only) Regex pattern to match error log messages **CloudWatch Metrics and Dimensions:** + - **`serverErrors`** - Uses `HTTPCode_Target_5XX_Count` metric with LoadBalancer dimension - **`unhealthyHosts`** - Uses `UnHealthyHostCount` metric with LoadBalancer + TargetGroup dimensions - **`responseTime`** - Uses `TargetResponseTime` metric with LoadBalancer dimension - All metrics use full AWS load balancer identifiers (including AWS-generated suffixes) for reliable targeting **Notification Channel Properties:** + - **`email.addresses`** - Array of email addresses for email notifications - **`slack.webhookUrl`** - Slack webhook URL (use secrets management) - **`discord.webhookUrl`** - Discord webhook URL (use secrets management) -- **`telegram.chatID`** & **`telegram.token`** - Telegram bot configuration +- **`telegram.chatID`** &**`telegram.token`** - Telegram bot configuration --- @@ -1930,16 +1969,19 @@ stacks: ### **Scaling Benefits Demonstrated** **1. Resource Pool Management:** + - DevOps defines resource pools once (`mongodb-shared-us`, `mongodb-enterprise-1`) - Developers allocate customers flexibly using `uses` directive - Easy migration between tiers by changing `uses` configuration **2. Cost Optimization:** + - Standard customers share `mongodb-shared-us` (cost-effective) - Enterprise customers get dedicated `mongodb-enterprise-1` (performance) - Automatic resource utilization optimization **3. Geographic Compliance:** + - EU customers automatically use `mongodb-shared-eu` for data residency - US customers use `mongodb-shared-us` - Simple configuration change for compliance @@ -1994,6 +2036,4 @@ eu-customer: uses: [mongodb-eu-cluster] ``` -This comprehensive reference covers all supported resources in Simple Container. The multidimensional resource allocation approach enables organizations to scale from startup to enterprise without operational complexity growth. - -For specific implementation examples and tutorials, refer to the [How-To Guides](./howto/) section. +For end-to-end deployment examples that use these resources, see the [Examples](../examples/README.md) section and the [Guides](../guides/index.md). \ No newline at end of file diff --git a/docs/docs/reference/use-cases.md b/docs/docs/reference/use-cases.md deleted file mode 100644 index f8e9cd2d..00000000 --- a/docs/docs/reference/use-cases.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Main use-cases for Simple-Container.com -description: What Simple Container can do for you? -platform: platform -product: simple-container -category: devguide -subcategory: learning -guides: tutorials -date: '2024-06-12' ---- - -# **Main use-cases for Simple Container** - -Simple Container is designed to **simplify microservices deployment and infrastructure management** while maintaining cloud flexibility. -This guide outlines the **main use cases** for `sc`, highlighting how it fits into modern software development and DevOps workflows. - -## Separation of DevOps and Developer parties - -Simple Container allows DevOps of the company to easily set up the basics of the infrastructure using the chosen -cloud provider (be it an AWS or GCP cloud or even a hosted Kubernetes cluster), prepare main secrets and account -configurations ahead of time. -DevOps should simply prepare a basic configuration of their resources and then invoke a single command `sc provision` -which will take care of the initial provision steps, and will create all resources a company needs. - -For developers Simple Container provides the high-level abstraction allowing to easily set up their CI/CD pipeline and -deploy their services into the provisioned cloud. With Simple Container adding a new microservice a company needs takes -a couple of very simple steps making the whole process a self-service operation without much help needed from DevOps. - - -## **1️⃣ Deploying Microservices Without DevOps Involvement - 500x Faster** - -βœ… **Use Case:** Developers need to deploy new microservices **quickly and independently** without requiring DevOps to configure infrastructure. - -βœ… **Quantified Benefit:** -- **Customer Onboarding**: **5 minutes** vs **2-3 days** traditional approaches -- **Configuration**: **5 lines** vs **50+ lines** of YAML per service -- **Developer Autonomy**: **Self-service deployment** vs **DevOps approval bottleneck** - -βœ… **Real-World Scenario:** Adding 100 new customers -```yaml -# Traditional: 5000+ lines, 200-300 days -# Simple Container: 500 lines, 8.3 hours -customer-001: - parentEnv: production - config: - domain: customer001.myapp.com - secrets: - CUSTOMER_SETTINGS: ${env:CUSTOMER_001_SETTINGS} -``` - -βœ… **Ideal for:** Organizations with many microservices, where **DevOps cannot manually provision every service**. - ---- - -## **2️⃣ Managing Infrastructure Centrally Without Complexity - 5x Operational Efficiency** - -βœ… **Use Case:** DevOps teams need a **single source of truth** for infrastructure such as **databases, storage, networking, and secrets**. - -βœ… **Quantified Benefit:** -- **DevOps to Customer Ratio**: **1:100+ customers** vs **1:10-20** traditional -- **Configuration Complexity**: **90% reduction** (500 vs 5000+ lines for 100 customers) -- **Infrastructure Drift Risk**: **Low (template-based)** vs **High (manual management)** - -βœ… **Multi-Dimensional Resource Allocation:** -```yaml -# server.yaml - Define resource pools once -resources: - production: - resources: - # Shared resources for standard customers - mongodb-shared-us: - type: mongodb-atlas - config: - clusterName: shared-us - instanceSize: M30 - # Dedicated resources for enterprise - mongodb-enterprise-1: - type: mongodb-atlas - config: - clusterName: enterprise-1 - instanceSize: M80 - dedicatedTenant: true -``` - -βœ… **Ideal for:** Organizations using **Terraform/Pulumi but want to simplify microservices provisioning**. - ---- - -## **3️⃣ Deploying Services Across Multiple Cloud Providers** - -βœ… **Use Case:** Organizations want to **deploy services across AWS, GCP, and Kubernetes** without rewriting cloud-specific configurations. - -βœ… **Benefit:** `sc` abstracts cloud infrastructure, allowing services to run **seamlessly on different platforms**. - -βœ… **Ideal for:** Companies that need **multi-cloud or hybrid cloud deployments**. - ---- - -## **4️⃣ Simplifying CI/CD with Built-in Deployment Automation** - -βœ… **Use Case:** Teams want to **automate deployments** without managing complex CI/CD pipeline scripts. - -βœ… **Benefit:** `sc` provides **built-in deployment commands**, eliminating the need for **manual Helm charts, Terraform pipelines, or custom scripts**. - -βœ… **Ideal for:** Teams looking to **reduce deployment complexity and improve release speed**. - ---- - -## **5️⃣ Secure Secrets Management Without External Tools** - -βœ… **Use Case:** Microservices require **environment-specific credentials (e.g., database passwords, API keys)** stored securely. - -βœ… **Benefit:** `sc` **automatically stores secrets in cloud-native secret managers** and injects them securely into deployed services. - -βœ… **Ideal for:** Organizations that previously relied on **manual secret injection or external tools like Vault**. - ---- - -## **6️⃣ Deploying Static Websites with Cloud Storage & CDN** - -βœ… **Use Case:** Teams need to **host static websites (React, Vue, Angular, documentation sites)** on cloud storage with CDN integration. - -βœ… **Benefit:** `sc` provisions **S3, GCP Cloud Storage, or other cloud storage solutions**, handling **domain setup and caching**. - -βœ… **Ideal for:** Companies looking for a **fast and automated static site deployment**. - ---- - -## **7️⃣ Migrating Services Between Cloud Providers Without Rewriting Configurations** - -βœ… **Use Case:** Organizations need to **move workloads from AWS to GCP, or from Kubernetes to ECS** while minimizing downtime. - -βœ… **Benefit:** `sc` allows teams to **update infrastructure configurations without modifying microservices deployment settings**. - -βœ… **Ideal for:** Businesses that need **cloud migration flexibility**. - ---- - -## **8️⃣ Scaling Microservices with Cloud-Native Auto-Scaling - Zero Downtime Migrations** - -βœ… **Use Case:** Services must **scale dynamically based on demand** without manual intervention. - -βœ… **Quantified Benefit:** -- **Performance Tier Migration**: **One-line change** vs **manual infrastructure rebuild** -- **Multi-region Expansion**: **Single parent stack change** vs **duplicate infrastructure code** -- **Cost Optimization**: **70% reduction** through intelligent resource sharing - -βœ… **Real-World Scenario:** Performance tier migration -```yaml -# Before: Customer on shared resources -customer-enterprise: - uses: [mongodb-shared-us] - -# After: Customer on dedicated resources (one line change!) -customer-enterprise: - uses: [mongodb-enterprise-dedicated] - -# Automatic migration, zero downtime, easy rollback -``` - -βœ… **Benefit:** `sc` integrates with **Kubernetes auto-scaling, AWS ECS scaling, and serverless scaling mechanisms**, ensuring optimal resource usage. - -βœ… **Ideal for:** Organizations handling **high-traffic applications** that require **automatic scaling**. - ---- - -## **9️⃣ Managing Microservices Dependencies Without Manual Configuration** - -βœ… **Use Case:** A service needs **databases, messaging queues, or cloud storage** but shouldn’t require developers to configure them manually. - -βœ… **Benefit:** `sc` **automatically connects services to provisioned resources** such as databases and queues, reducing developer effort. - -βœ… **Ideal for:** Teams working with **complex microservice architectures**. - ---- - -## **1️⃣0️⃣ Standardizing Microservices Deployment Across Teams** - -βœ… **Use Case:** Different teams deploy services using **various methods (Terraform, Helm, custom scripts), leading to inconsistency**. - -βœ… **Benefit:** `sc` ensures **consistent deployment standards across all microservices**, improving maintainability. - -βœ… **Ideal for:** Enterprises with **multiple teams managing microservices independently**. - ---- - -## **1️⃣0️⃣ Enterprise Scaling Scenarios** - -### **Scenario 1: SaaS Company Scaling from 10 to 1000 Customers** - -**Challenge:** Traditional approach requires linear DevOps scaling -- **Traditional**: 1 DevOps per 10-20 customers = 50-100 DevOps engineers needed -- **Simple Container**: 1 DevOps per 100+ customers = 10 DevOps engineers needed -- **Savings**: **80% staff reduction**, **$4M+ annual savings** - -### **Scenario 2: Multi-Region Enterprise Expansion** - -**Challenge:** Duplicate infrastructure for each region -- **Traditional**: Separate Terraform/Pulumi code for each region -- **Simple Container**: Single parent stack per region, customers choose easily -- **Result**: **90% less code**, **instant region switching** - -### **Scenario 3: Compliance and Security at Scale** - -**Challenge:** Manual secret management across hundreds of services -- **Traditional**: Manual secret rotation, security risks -- **Simple Container**: Automatic namespace isolation, built-in secrets management -- **Result**: **Zero security incidents**, **automated compliance** - ---- - -# **Conclusion: Quantified Scaling Results** - -Simple Container **transforms microservices deployment** by providing **measurable scaling advantages**: - -βœ… **500x faster customer onboarding** (5 minutes vs 2-3 days) - -βœ… **90% reduction in configuration complexity** (500 vs 5000+ lines) - -βœ… **5x operational efficiency** (1 DevOps per 100+ vs 10-20 customers) - -βœ… **70% cost reduction** through intelligent resource sharing - -βœ… **Zero downtime migrations** with one-line configuration changes - -βœ… **80% staff reduction** in operational overhead - -**Simple Container enables organizations to scale from startup to enterprise without operational complexity growth**, transforming container orchestration from a complex infrastructure challenge into a simple configuration management task. - -Organizations adopting `sc` achieve **enterprise-grade scalability** with **startup-level simplicity**. diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css new file mode 100644 index 00000000..4c328552 --- /dev/null +++ b/docs/docs/stylesheets/extra.css @@ -0,0 +1,208 @@ +/* ───────────────────────────────────────────────────────────────────────── + Simple Container docs β€” brand overrides + Aligned with simple-container.com (hugo-saasify-theme tokens). + See landing/.agents/design/2026-05-25/docs-refactor/07-theming-and-brand.md + for the source-of-truth palette and rationale. + ───────────────────────────────────────────────────────────────────────── */ + + +/* 1. Brand color tokens + ───────────────────────────────────────────────────────────────────────── + The mkdocs preset "deep purple" / "cyan" gets us close; we tune the + exact hex values to match landing's #a855f7 (purple) + #22d3ee (cyan). */ + +:root { + --md-primary-fg-color: #a855f7; + --md-primary-fg-color--light: #c4b5fd; + --md-primary-fg-color--dark: #7e22ce; + --md-accent-fg-color: #22d3ee; + --md-accent-fg-color--transparent: rgba(34, 211, 238, 0.1); +} + + +/* 2. Dark scheme (slate) β€” match landing's #07070f / #eeeeff / muted whites + ───────────────────────────────────────────────────────────────────────── */ + +[data-md-color-scheme="slate"] { + --md-default-bg-color: #07070f; + --md-default-bg-color--light: #0a0a1f; + --md-default-bg-color--lighter: #12122b; + --md-default-bg-color--lightest: #1e1b4b; + + --md-default-fg-color: #eeeeff; + --md-default-fg-color--light: rgba(238, 238, 255, 0.75); + --md-default-fg-color--lighter: rgba(238, 238, 255, 0.45); + --md-default-fg-color--lightest: rgba(238, 238, 255, 0.07); + + --md-typeset-a-color: #93c5fd; /* landing hero-gradient blue */ + + --md-code-bg-color: #0a0a1f; + --md-code-fg-color: #e5e7eb; +} + + +/* 3. Header β€” match landing's bg-slate-950/85 + backdrop blur + ───────────────────────────────────────────────────────────────────────── */ + +[data-md-color-scheme="slate"] .md-header { + background-color: rgba(2, 6, 23, 0.85); + backdrop-filter: blur(12px); + -webkit-backdrop-filter: blur(12px); + border-bottom: 1px solid rgba(255, 255, 255, 0.07); + box-shadow: none; +} + +[data-md-color-scheme="slate"] .md-tabs { + background-color: transparent; + border-bottom: 1px solid rgba(255, 255, 255, 0.07); +} + + +/* 4. H1 hero-gradient on the homepage only + ───────────────────────────────────────────────────────────────────────── + Landing's hero h1 uses linear-gradient(135deg, #fff, #c4b5fd 40%, #93c5fd) + as a text fill. We restrict this to the very first H1 on the page so + inner-page H1s stay readable. */ + +.md-typeset h1 { + font-weight: 700; + letter-spacing: -0.01em; +} + +body[data-md-color-scheme="slate"] .md-content article > h1:first-of-type { + background: linear-gradient(135deg, #ffffff, #c4b5fd 40%, #93c5fd); + -webkit-background-clip: text; + background-clip: text; + -webkit-text-fill-color: transparent; + color: transparent; +} + + +/* 5. Code β€” inline + block + ───────────────────────────────────────────────────────────────────────── */ + +.md-typeset code { + font-feature-settings: "calt" off; /* DM Mono ligatures off for code */ + border-radius: 4px; + padding: 1px 6px; +} + +[data-md-color-scheme="slate"] .md-typeset :not(pre) > code { + background-color: rgba(34, 211, 238, 0.08); + color: #67e8f9; + border: 1px solid rgba(34, 211, 238, 0.18); +} + +[data-md-color-scheme="slate"] .md-typeset pre > code, +[data-md-color-scheme="slate"] .highlight pre { + background-color: #0a0a1f; + border: 1px solid rgba(255, 255, 255, 0.07); + border-radius: 6px; +} + + +/* 6. Tables β€” match landing's slate borders + faint purple header + ───────────────────────────────────────────────────────────────────────── */ + +.md-typeset table:not([class]) { + border: 1px solid rgba(255, 255, 255, 0.07); + border-radius: 6px; + overflow: hidden; +} + +[data-md-color-scheme="slate"] .md-typeset table:not([class]) th { + background-color: rgba(168, 85, 247, 0.08); + color: #eeeeff; + border-bottom: 1px solid rgba(168, 85, 247, 0.2); +} + +[data-md-color-scheme="slate"] .md-typeset table:not([class]) tr { + border-top: 1px solid rgba(255, 255, 255, 0.04); +} + + +/* 7. Admonitions β€” tighter corners + subtle accents + ───────────────────────────────────────────────────────────────────────── */ + +.md-typeset .admonition, +.md-typeset details { + border-radius: 6px; + border-left-width: 3px; + box-shadow: none; +} + +[data-md-color-scheme="slate"] .md-typeset .admonition, +[data-md-color-scheme="slate"] .md-typeset details { + background-color: rgba(255, 255, 255, 0.02); + border: 1px solid rgba(255, 255, 255, 0.05); +} + + +/* 8. Navigation β€” active item picks up the brand purple + ───────────────────────────────────────────────────────────────────────── */ + +.md-nav__link--active, +.md-nav__item--active > .md-nav__link { + color: var(--md-primary-fg-color); + font-weight: 600; +} + + +/* 9. Search box β€” subtle bordered card on dark, no harsh white + ───────────────────────────────────────────────────────────────────────── */ + +[data-md-color-scheme="slate"] .md-search__input { + background-color: rgba(255, 255, 255, 0.04); + color: #eeeeff; +} + +[data-md-color-scheme="slate"] .md-search__input::placeholder { + color: rgba(238, 238, 255, 0.5); +} + + +/* 10. Footer β€” keep tight, dark, low-contrast + ───────────────────────────────────────────────────────────────────────── */ + +[data-md-color-scheme="slate"] .md-footer { + background-color: #07070f; + border-top: 1px solid rgba(255, 255, 255, 0.07); +} + +[data-md-color-scheme="slate"] .md-footer-meta { + background-color: transparent; +} + + +/* 11. Buttons (.md-button β€” used in mkdocs-material content) + ───────────────────────────────────────────────────────────────────────── */ + +.md-typeset .md-button { + border-radius: 6px; + font-weight: 600; +} + +.md-typeset .md-button--primary { + background-color: var(--md-primary-fg-color); + border-color: var(--md-primary-fg-color); + color: #ffffff; +} + +.md-typeset .md-button--primary:hover, +.md-typeset .md-button--primary:focus { + background-color: #9333ea; + border-color: #9333ea; +} + + +/* 12. Body typography β€” Plus Jakarta Sans tuning + ───────────────────────────────────────────────────────────────────────── */ + +.md-typeset { + font-feature-settings: "kern", "liga", "calt"; + line-height: 1.65; +} + +.md-typeset p { + letter-spacing: -0.005em; +} diff --git a/docs/docs/troubleshooting/container-security.md b/docs/docs/troubleshooting/container-security.md index 382fa53d..5ff24fde 100644 --- a/docs/docs/troubleshooting/container-security.md +++ b/docs/docs/troubleshooting/container-security.md @@ -118,6 +118,7 @@ signing: **Problem:** Keyless signature not in transparency log. **Solution:** + - This is expected for key-based signing - For keyless signing, check SIGSTORE_ID_TOKEN was set correctly - Verify Rekor service is accessible @@ -222,6 +223,7 @@ git --version **Problem:** CI environment not detected. **Solution:** + - Provenance auto-detects: GitHub Actions, GitLab CI, CircleCI, Jenkins - For other CI systems, builder.id defaults to "https://simple-container.com/local" - This is not an error, just informational @@ -408,4 +410,4 @@ If issues persist: - Full error message - Tool versions (`cosign version`, `syft version`, etc.) - Stack configuration (sanitized) - - CI environment (if applicable) + - CI environment (if applicable) \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index be3b6f44..6d5dd0ad 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -2,14 +2,39 @@ site_name: Simple Container theme: name: material logo: images/sc-logo.png + favicon: images/sc-logo.png + palette: + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: deep purple + accent: cyan + toggle: + icon: material/weather-sunny + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: deep purple + accent: cyan + toggle: + icon: material/weather-night + name: Switch to dark mode + font: + text: Plus Jakarta Sans + code: DM Mono features: - navigation.tabs - navigation.sections - navigation.expand - navigation.path - - toc.follow + - navigation.top + - toc.integrate - search.suggest - search.highlight + - content.code.copy + - content.code.annotate + +extra_css: + - stylesheets/extra.css nav: - Home: index.md @@ -22,13 +47,20 @@ nav: - Template Placeholders: concepts/template-placeholders.md - Advanced Template Placeholders: concepts/template-placeholders-advanced.md - Kubernetes Namespace Layout: concepts/kubernetes-namespaces.md - - Why Simple Container: concepts/motivation.md + - Vertical Pod Autoscaler: concepts/vertical-pod-autoscaler.md - Guides: - Deployment Guides: guides/index.md - ECS Fargate: guides/parent-ecs-fargate.md - GKE Autopilot: guides/parent-gcp-gke-autopilot.md - Pure Kubernetes: guides/parent-pure-kubernetes.md + - Service Deploy Steps: guides/service-steps-to-deploy.md + - CI/CD with GitHub Actions: guides/cicd-github-actions.md - Secrets Management: guides/secrets-management.md + - Container Security: guides/container-security.md + - DNS Management: guides/dns-management.md + - GKE Version Management: guides/gke-version-management.md + - Resource Adoption: guides/resource-adoption.md + - AI Assistant: ai-assistant/index.md - Migration: guides/migration.md - Examples: - Overview: examples/README.md @@ -42,12 +74,27 @@ nav: - Reference: - Supported Resources: reference/supported-resources.md - Deployment Schemas: reference/service-available-deployment-schemas.md - - Use Cases: reference/use-cases.md + - Troubleshooting: + - Container Security: troubleshooting/container-security.md + - Compliance: + - NIST SSDF Mapping: compliance/nist-sp-800-218-mapping.md - Advanced: - - Scaling Advantages: advanced/scaling-advantages.md - - Tool Comparisons: advanced/compare-with-other-tools.md - Best Practices: advanced/best-practices.md +# Pages intentionally not in nav. The ai-assistant/* deep pages need a +# separate content audit (per landing/.agents/design/2026-05-25/docs-refactor/05-orphans-and-nav.md +# Β§4 Option B β€” surface a 1-page summary now, defer the full surfacing). +not_in_nav: | + /ai-assistant/commands.md + /ai-assistant/developer-mode.md + /ai-assistant/devops-mode.md + /ai-assistant/getting-started.md + /ai-assistant/mcp-integration.md + /ai-assistant/templates-config-requirements.md + /ai-assistant/troubleshooting.md + /ai-assistant/usage-examples.md + /ai-assistant/examples/*.md + markdown_extensions: - pymdownx.highlight: anchor_linenums: true @@ -59,10 +106,35 @@ markdown_extensions: custom_fences: - name: mermaid class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format + format: !!python/name:mermaid2.fence_mermaid - admonition - pymdownx.details plugins: - search - - mermaid2 + - mermaid2: + version: 10.6.1 + arguments: + theme: base + themeVariables: + # Aligned with simple-container.com palette (dark scheme). + # See landing/.agents/design/2026-05-25/docs-refactor/07-theming-and-brand.md + background: '#07070f' + primaryColor: '#1e1b4b' + primaryTextColor: '#eeeeff' + primaryBorderColor: '#a855f7' + secondaryColor: '#0a0a1f' + secondaryTextColor: '#eeeeff' + secondaryBorderColor: '#3b82f6' + tertiaryColor: '#12122b' + tertiaryTextColor: '#eeeeff' + tertiaryBorderColor: '#22d3ee' + mainBkg: '#1e1b4b' + secondBkg: '#0a0a1f' + lineColor: '#a855f7' + textColor: '#eeeeff' + edgeLabelBackground: '#0a0a1f' + nodeBorder: '#a855f7' + clusterBkg: 'rgba(168, 85, 247, 0.06)' + clusterBorder: 'rgba(168, 85, 247, 0.3)' + titleColor: '#c4b5fd'