From 90ff13a6b5060d37d41d9f2be64cfd48a9f30d52 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 18:49:26 +0800 Subject: [PATCH 01/10] doc: architecture for US and EU cloud --- docs/docs.json | 64 ++++---- docs/internals/architecture/cloud.mdx | 142 ++++++++++++++++++ .../{ => architecture}/components.mdx | 0 3 files changed, 170 insertions(+), 36 deletions(-) create mode 100644 docs/internals/architecture/cloud.mdx rename docs/internals/{ => architecture}/components.mdx (100%) diff --git a/docs/docs.json b/docs/docs.json index cb6aaa0a1..1d57c9951 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -22,9 +22,7 @@ "documentation/getting-started/introduction", { "group": "Quickstart", - "pages": [ - "documentation/guides/local-development" - ] + "pages": ["documentation/guides/local-development"] }, { "group": "Guides", @@ -39,9 +37,7 @@ }, { "group": "Setup", - "pages": [ - "documentation/setup/networking" - ] + "pages": ["documentation/setup/networking"] } ] }, @@ -378,7 +374,22 @@ "internals/permissions/migration" ] }, - "internals/components", + { + "group": "Permissions", + "pages": [ + "internals/permissions/overview", + "internals/permissions/project-permissions", + "internals/permissions/organization-permissions", + "internals/permissions/migration" + ] + }, + { + "group": "Architecture", + "pages": [ + "internals/architecture/components", + "internals/architecture/cloud" + ] + }, "internals/security", "internals/service-tokens" ] @@ -405,9 +416,7 @@ }, { "group": "Contributing to SDK", - "pages": [ - "contributing/sdk/developing" - ] + "pages": ["contributing/sdk/developing"] } ] } @@ -621,15 +630,11 @@ }, { "group": "Build Tool Integrations", - "pages": [ - "integrations/build-tools/gradle" - ] + "pages": ["integrations/build-tools/gradle"] }, { "group": "Others", - "pages": [ - "integrations/external/backstage" - ] + "pages": ["integrations/external/backstage"] } ] }, @@ -685,9 +690,7 @@ "api-reference/overview/authentication", { "group": "Examples", - "pages": [ - "api-reference/overview/examples/integration" - ] + "pages": ["api-reference/overview/examples/integration"] } ] }, @@ -1787,15 +1790,11 @@ }, { "group": "Service Tokens", - "pages": [ - "api-reference/endpoints/service-tokens/get" - ] + "pages": ["api-reference/endpoints/service-tokens/get"] }, { "group": "Audit Logs", - "pages": [ - "api-reference/endpoints/audit-logs/export-audit-log" - ] + "pages": ["api-reference/endpoints/audit-logs/export-audit-log"] } ] }, @@ -2002,9 +2001,7 @@ "groups": [ { "group": "", - "pages": [ - "sdks/overview" - ] + "pages": ["sdks/overview"] }, { "group": "SDK's", @@ -2024,9 +2021,7 @@ "groups": [ { "group": "", - "pages": [ - "changelog/overview" - ] + "pages": ["changelog/overview"] } ] } @@ -2040,10 +2035,7 @@ "api": { "openapi": "https://app.infisical.com/api/docs/json", "mdx": { - "server": [ - "https://app.infisical.com", - "http://localhost:8080" - ] + "server": ["https://app.infisical.com", "http://localhost:8080"] } }, "appearance": { @@ -2244,4 +2236,4 @@ "publicApiKey": "pk_b50d7184e0e39ddd5cdb43cf6abeadd9b97d" } } -} \ No newline at end of file +} diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx new file mode 100644 index 000000000..895c2fe9e --- /dev/null +++ b/docs/internals/architecture/cloud.mdx @@ -0,0 +1,142 @@ +--- +title: "Infisical Cloud Architecture" +description: "Architecture overview for Infisical's US and EU cloud deployments" +--- + +This document provides an overview of Infisical's cloud architecture for our US and EU deployments, detailing the core components and how they interact to provide security and infrastructure services. + +## Overview + +Infisical Cloud operates on AWS infrastructure using containerized services deployed via Amazon ECS (Elastic Container Service). Our US and EU deployments use identical architectural patterns to ensure consistency and reliability across regions. + +![Infisical Cloud Architecture](/images/self-hosting/reference-architectures/Infisical-AWS-ECS-architecture.jpeg) + +## Components + +A typical Infisical Cloud deployment consists of the following components: + +### Application Services + +- **Infisical Core**: Main application server running the Infisical backend API +- **License API**: Dedicated API service for license management with separate database (shared between US/EU) +- **Application Load Balancer**: Routes incoming traffic to application containers with SSL termination and host-based routing + +### Data Layer + +- **Amazon RDS (PostgreSQL)**: + - **Main Database**: Primary database for secrets, users, and metadata (Multi-AZ, encryption enabled) + - **License API Database**: Dedicated database for license management services +- **Amazon ElastiCache (Redis)**: + - **Main Redis Cluster**: Multi-AZ replication group for core application caching and queuing + - **License API Redis**: Dedicated cache for license services + - Redis 7 engine with CloudWatch logging and snapshot backups + +### Infrastructure + +- **ECS Fargate**: Serverless container platform running application services +- **AWS Global Accelerator**: Global traffic routing and performance optimization +- **Cloudflare**: DNS management and routing +- **AWS SSM Parameter Store**: Stores application configuration and secrets +- **CloudWatch**: Centralized logging and monitoring + +## System Layout + +### Service Architecture + +The Infisical application runs as multiple containerized services on ECS: + +- **Main Server**: 10-30 instances (2048 CPU, 4096 MB memory) with auto-scaling +- **License API**: 2-4 instances (2048 CPU, 4096 MB memory) with dedicated infrastructure (shared globally) +- **Monitoring**: AWS OTel Collector and Datadog Agent sidecars + +Container images are pulled from Docker Hub and managed via GitHub Actions for deployments. + +### Network Configuration + +Services are deployed in private subnets with the following connectivity: + +- External traffic → Application Load Balancer → ECS Services +- Main server exposes port 8080 +- License API exposes port 4000 (portal.infisical.com, license.infisical.com) +- Service-to-service communication via AWS Service Connect + +### Data Flow + +1. **DNS resolution** via Cloudflare routes traffic to AWS Global Accelerator +2. **Global Accelerator** optimizes routing to the nearest AWS region +3. **Client requests** are routed through the Application Load Balancer to ECS containers +4. **Application logic** processes requests in the Infisical Core service +5. **Data persistence** occurs via encrypted connections to PostgreSQL +6. **Caching** utilizes Redis for performance optimization +7. **Configuration** is retrieved from AWS SSM Parameter Store + +## Regional Deployments + +### US Cloud (us.infisical.com or app.infisical.com) + +- **Cluster**: `infisical-core-platform` ECS cluster +- **Scaling**: 10-30 main server instances, 2-4 license server instances +- **Monitoring**: Integrated with Datadog + +### EU Cloud (eu.infisical.com) + +- **Cluster**: `infisical-core-platform` ECS cluster +- **Scaling**: 15-30 main server instances, 2-4 license server instances +- **Monitoring**: Integrated with Datadog +- **Compliance**: GDPR compliant with data residency within EU + +## Configuration Management + +Application configuration and secrets are managed through AWS SSM Parameter Store, with deployment automation handled via GitHub Actions. + +## Monitoring and Observability + +### Logging + +- **CloudWatch**: 365-day retention for application logs +- **Health Checks**: HTTP endpoint monitoring for service health + +### Metrics + +- **AWS OTel Collector**: Prometheus metrics collection +- **Datadog Agent**: Application performance monitoring and infrastructure metrics +- **Auto Scaling**: CPU and memory-based scaling triggers at 60% utilization + +## Container Management + +- **Images**: `infisical/staging_infisical` and `infisical/license-server` from Docker Hub +- **Deployment**: Automated via GitHub Actions updating SSM parameter for image tags +- **Registry Access**: Docker Hub credentials stored in AWS Secrets Manager +- **Platform**: ECS Fargate with 70% standard capacity, 30% Spot instances + +## Security Overview + +### Data Protection + +- **Encryption**: All secrets encrypted at rest and in transit +- **Network Isolation**: Services deployed in private subnets with controlled access +- **Authentication**: API tokens and service accounts for secure access +- **Audit Logging**: Comprehensive audit trails for all secret operations + +### Network Architecture + +- **Load Balancing**: Application Load Balancer with SSL termination and health checks +- **Service Communication**: AWS Service Connect for internal service discovery +- **Security Groups**: Restrictive firewall rules (port 8080 for main server, 4000 for license API) +- **High Availability**: Multi-AZ deployment with automatic failover + +## Troubleshooting + +### Common Issues + +**Service Health**: Check ECS service status and CloudWatch logs for application errors + +**Scaling Issues**: Monitor CPU/memory utilization and auto-scaling policies + +**Database Connectivity**: Verify security group rules and database availability + +### Log Locations + +- **Application Logs**: CloudWatch log groups with 365-day retention +- **ECS Task Logs**: Available through ECS console or CloudWatch +- **Load Balancer**: Access logs and health check status diff --git a/docs/internals/components.mdx b/docs/internals/architecture/components.mdx similarity index 100% rename from docs/internals/components.mdx rename to docs/internals/architecture/components.mdx From 67e57d8993c5a06d6628dc2ab4a5ea2de3f04721 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:00:45 +0800 Subject: [PATCH 02/10] doc: added mention of NAT --- docs/internals/architecture/cloud.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index 895c2fe9e..96244cb49 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -120,10 +120,13 @@ Application configuration and secrets are managed through AWS SSM Parameter Stor ### Network Architecture +- **VPC Design**: Dedicated VPC with public and private subnets across multiple Availability Zones +- **NAT Gateway**: All outbound traffic from private subnets routes through NAT Gateway for external connectivity - **Load Balancing**: Application Load Balancer with SSL termination and health checks - **Service Communication**: AWS Service Connect for internal service discovery - **Security Groups**: Restrictive firewall rules (port 8080 for main server, 4000 for license API) - **High Availability**: Multi-AZ deployment with automatic failover +- **Network Monitoring**: VPC Flow Logs with 365-day retention for traffic analysis ## Troubleshooting From 58705ffc3f23c2005336b6302b4456bf545688ec Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:03:50 +0800 Subject: [PATCH 03/10] doc: removed duplicate permission block --- docs/docs.json | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 1d57c9951..2d0417778 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -374,15 +374,6 @@ "internals/permissions/migration" ] }, - { - "group": "Permissions", - "pages": [ - "internals/permissions/overview", - "internals/permissions/project-permissions", - "internals/permissions/organization-permissions", - "internals/permissions/migration" - ] - }, { "group": "Architecture", "pages": [ From cb3365afd45ef9fbcf3ff28723ec6496945a774b Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:08:36 +0800 Subject: [PATCH 04/10] misc: removed troubleshooting section --- docs/internals/architecture/cloud.mdx | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index 96244cb49..7bae7b2d7 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -127,19 +127,3 @@ Application configuration and secrets are managed through AWS SSM Parameter Stor - **Security Groups**: Restrictive firewall rules (port 8080 for main server, 4000 for license API) - **High Availability**: Multi-AZ deployment with automatic failover - **Network Monitoring**: VPC Flow Logs with 365-day retention for traffic analysis - -## Troubleshooting - -### Common Issues - -**Service Health**: Check ECS service status and CloudWatch logs for application errors - -**Scaling Issues**: Monitor CPU/memory utilization and auto-scaling policies - -**Database Connectivity**: Verify security group rules and database availability - -### Log Locations - -- **Application Logs**: CloudWatch log groups with 365-day retention -- **ECS Task Logs**: Available through ECS console or CloudWatch -- **Load Balancer**: Access logs and health check status From 7764f632997832ee32d2c1fc400e821ed45960cf Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:12:09 +0800 Subject: [PATCH 05/10] misc: made terms consistent --- docs/internals/architecture/cloud.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index 7bae7b2d7..a78d8d2c1 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -18,14 +18,14 @@ A typical Infisical Cloud deployment consists of the following components: ### Application Services - **Infisical Core**: Main application server running the Infisical backend API -- **License API**: Dedicated API service for license management with separate database (shared between US/EU) +- **License API**: Dedicated API service for license management with separate RDS instance (shared between US/EU) - **Application Load Balancer**: Routes incoming traffic to application containers with SSL termination and host-based routing ### Data Layer - **Amazon RDS (PostgreSQL)**: - - **Main Database**: Primary database for secrets, users, and metadata (Multi-AZ, encryption enabled) - - **License API Database**: Dedicated database for license management services + - **Main RDS Instance**: Primary database for secrets, users, and metadata (Multi-AZ, encryption enabled) + - **License API RDS Instance**: Dedicated database for license management services - **Amazon ElastiCache (Redis)**: - **Main Redis Cluster**: Multi-AZ replication group for core application caching and queuing - **License API Redis**: Dedicated cache for license services @@ -66,8 +66,8 @@ Services are deployed in private subnets with the following connectivity: 2. **Global Accelerator** optimizes routing to the nearest AWS region 3. **Client requests** are routed through the Application Load Balancer to ECS containers 4. **Application logic** processes requests in the Infisical Core service -5. **Data persistence** occurs via encrypted connections to PostgreSQL -6. **Caching** utilizes Redis for performance optimization +5. **Data persistence** occurs via encrypted connections to RDS +6. **Caching** utilizes ElastiCache for performance optimization 7. **Configuration** is retrieved from AWS SSM Parameter Store ## Regional Deployments From 23f1888123dd725005d64c06b93507b9c561878d Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:16:08 +0800 Subject: [PATCH 06/10] misc: added mention of separated AWS accounts --- docs/internals/architecture/cloud.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index a78d8d2c1..07a8a71e9 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -72,14 +72,18 @@ Services are deployed in private subnets with the following connectivity: ## Regional Deployments +Each region operates in a separate AWS account, providing strong isolation boundaries for security, compliance, and operational independence. + ### US Cloud (us.infisical.com or app.infisical.com) +- **AWS Account**: Dedicated US AWS account - **Cluster**: `infisical-core-platform` ECS cluster - **Scaling**: 10-30 main server instances, 2-4 license server instances - **Monitoring**: Integrated with Datadog ### EU Cloud (eu.infisical.com) +- **AWS Account**: Dedicated EU AWS account - **Cluster**: `infisical-core-platform` ECS cluster - **Scaling**: 15-30 main server instances, 2-4 license server instances - **Monitoring**: Integrated with Datadog From b4ff620b442bc16de79462ab2b04fe636133d239 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:28:05 +0800 Subject: [PATCH 07/10] doc: removed specifics --- docs/internals/architecture/cloud.mdx | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index 07a8a71e9..b376df1f9 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -45,8 +45,8 @@ A typical Infisical Cloud deployment consists of the following components: The Infisical application runs as multiple containerized services on ECS: -- **Main Server**: 10-30 instances (2048 CPU, 4096 MB memory) with auto-scaling -- **License API**: 2-4 instances (2048 CPU, 4096 MB memory) with dedicated infrastructure (shared globally) +- **Main Server**: Auto-scaling containerized application services +- **License API**: Dedicated service with separate infrastructure (shared globally) - **Monitoring**: AWS OTel Collector and Datadog Agent sidecars Container images are pulled from Docker Hub and managed via GitHub Actions for deployments. @@ -77,17 +77,15 @@ Each region operates in a separate AWS account, providing strong isolation bound ### US Cloud (us.infisical.com or app.infisical.com) - **AWS Account**: Dedicated US AWS account -- **Cluster**: `infisical-core-platform` ECS cluster -- **Scaling**: 10-30 main server instances, 2-4 license server instances -- **Monitoring**: Integrated with Datadog +- **Infrastructure**: ECS-based containerized deployment +- **Monitoring**: Integrated with Datadog for observability and security monitoring ### EU Cloud (eu.infisical.com) - **AWS Account**: Dedicated EU AWS account -- **Cluster**: `infisical-core-platform` ECS cluster -- **Scaling**: 15-30 main server instances, 2-4 license server instances -- **Monitoring**: Integrated with Datadog +- **Infrastructure**: ECS-based containerized deployment - **Compliance**: GDPR compliant with data residency within EU +- **Monitoring**: Integrated with Datadog for observability and security monitoring ## Configuration Management @@ -104,14 +102,13 @@ Application configuration and secrets are managed through AWS SSM Parameter Stor - **AWS OTel Collector**: Prometheus metrics collection - **Datadog Agent**: Application performance monitoring and infrastructure metrics -- **Auto Scaling**: CPU and memory-based scaling triggers at 60% utilization ## Container Management - **Images**: `infisical/staging_infisical` and `infisical/license-server` from Docker Hub - **Deployment**: Automated via GitHub Actions updating SSM parameter for image tags - **Registry Access**: Docker Hub credentials stored in AWS Secrets Manager -- **Platform**: ECS Fargate with 70% standard capacity, 30% Spot instances +- **Platform**: ECS Fargate serverless container platform ## Security Overview @@ -125,9 +122,8 @@ Application configuration and secrets are managed through AWS SSM Parameter Stor ### Network Architecture - **VPC Design**: Dedicated VPC with public and private subnets across multiple Availability Zones -- **NAT Gateway**: All outbound traffic from private subnets routes through NAT Gateway for external connectivity +- **NAT Gateway**: Controlled outbound connectivity from private subnets - **Load Balancing**: Application Load Balancer with SSL termination and health checks -- **Service Communication**: AWS Service Connect for internal service discovery -- **Security Groups**: Restrictive firewall rules (port 8080 for main server, 4000 for license API) +- **Security Groups**: Restrictive firewall rules and controlled network access - **High Availability**: Multi-AZ deployment with automatic failover - **Network Monitoring**: VPC Flow Logs with 365-day retention for traffic analysis From 2a3d19dcb2ddc42dac21e9bd2a340336f1444a5d Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 19:31:19 +0800 Subject: [PATCH 08/10] misc: finalized title --- docs/internals/architecture/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index b376df1f9..106f1c9d2 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -1,5 +1,5 @@ --- -title: "Infisical Cloud Architecture" +title: "Infisical Cloud" description: "Architecture overview for Infisical's US and EU cloud deployments" --- From b30706607f5f9665a9f907d191200cf41478ca2f Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 23 Jun 2025 21:13:59 +0800 Subject: [PATCH 09/10] misc: changed from for to of --- docs/internals/architecture/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index 106f1c9d2..fe750aae2 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -1,6 +1,6 @@ --- title: "Infisical Cloud" -description: "Architecture overview for Infisical's US and EU cloud deployments" +description: "Architecture overview of Infisical's US and EU cloud deployments" --- This document provides an overview of Infisical's cloud architecture for our US and EU deployments, detailing the core components and how they interact to provide security and infrastructure services. From f0ec8c883f59171e51f4f646a36d8509520fa2b6 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Tue, 24 Jun 2025 00:52:18 +0800 Subject: [PATCH 10/10] misc: addressed comments --- docs/internals/architecture/cloud.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/internals/architecture/cloud.mdx b/docs/internals/architecture/cloud.mdx index fe750aae2..381e93d33 100644 --- a/docs/internals/architecture/cloud.mdx +++ b/docs/internals/architecture/cloud.mdx @@ -84,7 +84,6 @@ Each region operates in a separate AWS account, providing strong isolation bound - **AWS Account**: Dedicated EU AWS account - **Infrastructure**: ECS-based containerized deployment -- **Compliance**: GDPR compliant with data residency within EU - **Monitoring**: Integrated with Datadog for observability and security monitoring ## Configuration Management @@ -105,7 +104,7 @@ Application configuration and secrets are managed through AWS SSM Parameter Stor ## Container Management -- **Images**: `infisical/staging_infisical` and `infisical/license-server` from Docker Hub +- **Images**: `infisical/staging_infisical` and `infisical/license-api` from Docker Hub - **Deployment**: Automated via GitHub Actions updating SSM parameter for image tags - **Registry Access**: Docker Hub credentials stored in AWS Secrets Manager - **Platform**: ECS Fargate serverless container platform