Aspire Documentation Gaps - GitHub Discussions Analysis

00-summary.md

Documentation Gaps Summary - GitHub Discussions Analysis

Method

Analyzed 820 GitHub discussions from dotnet/aspire using:

1. Fetch all discussions via gh api graphql
2. Categorize by topic (deployment, testing, integrations, etc.)
3. Verify docs answer specific questions using aspire-get_doc - not just that docs exist

Key Insight

Many "relevant" docs are word salad - they exist on a topic but don't answer the actual question users ask.

Examples:

Question	"Relevant" Doc	Reality
"How to deploy Dapr to K8s?"	dapr-integration	❌ Doc ends at local dev - no production section
"How to mock services?"	testing-overview	❌ Explicitly says NOT supported
"Tests fail in Azure pipeline"	testing-overview	❌ No CI/CD content
"ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL?"	kubernetes-integration	❌ Env var not mentioned anywhere

---

Priority Gaps (Verified)

P0 - Critical (High volume + No docs answer the question)

Gap	Questions	Status
CI/CD Guide	30+	Only GH Actions example in docker-integration
Self-hosting / Non-Azure	25+	Zero docs
K8s Troubleshooting	20+	kubernetes-integration exists but no troubleshooting
Dapr Production	15+	dapr-integration is dev-only

P1 - High (Moderate volume + Docs don't answer)

Gap	Questions	Status
External Database Connections	15+	All DB docs assume containers
Console/Desktop Apps	12+	No integration guide
Mocking Alternatives	10+	testing-overview says "not supported" - no alternatives given
YARP Integration	12+	No docs exist

P2 - Medium

Gap	Questions	Status
Startup Optimization	8+	WaitFor docs exist but no perf tuning
CORS Configuration	8+	Not documented
WSL/Linux Development	18	No docs
Test Data Management	8+	Not documented

---

What's Actually Well Documented (Verified)

These questions ARE answered by the docs:

Topic	Doc	What It Covers
Networking/Ports	inner-loop-networking-overview	Proxies, container networks, Kestrel config
Docker publishing	docker-integration	Compose, registries, GH Actions example
Selective deployment	pipelines-and-app-topology	aspire do deploy-<step> syntax
Dashboard standalone	standalone-aspire-dashboard	Docker run, OTLP, login token
Basic integration setup	Various	PostgreSQL, Redis, etc. - basic cases

---

Files in This Folder

File	Content
01-app-model-core.md	174 discussions - networking well documented, gaps in external access
02-deployment-cicd.md	111 discussions - biggest gap area
03-integrations.md	126 discussions - basic docs exist, production patterns missing
04-testing.md	40 discussions - mocking limitation is documented but causes confusion
05-telemetry.md	88 discussions
06-devex-tooling.md	60 discussions
07-azure.md	106 discussions
08-docker-containers.md	156 discussions - well documented
09-wsl-linux.md	18 discussions - no docs

---

Data Source

• Source: GitHub Discussions at github.com/dotnet/aspire
• Total: 820 discussions (617 Q&A, 119 General, 66 Ideas, 18 Other)
• Analysis method: Fetch all → Categorize → Verify with aspire-get_doc
• Date: February 2026

01-app-model-core.md

[GitHub Discussions] App Model & Core API gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Resource/Endpoint/Binding	174
Networking (ports, localhost)	40+
WaitFor/Lifecycle	25+

---

Docs That Exist - Verified If They Answer Questions

✅ Questions Answered by Docs

Question	Doc	Section That Answers
#12484: Overriding Kestrel endpoints from appsettings.json?	inner-loop-networking-overview	"Kestrel configured endpoints" - ExcludeKestrelEndpoints = false
How does WaitFor work?	what-is-the-apphost	"Defining your architecture" - WaitFor(postgres) delays startup
How do container networks work?	inner-loop-networking-overview	"How container networks are managed" - bridge network, DNS
How do proxies and ports work?	inner-loop-networking-overview	"Ports and proxies" - detailed with diagrams

❌ Questions NOT Answered by Any Doc

Question	Searched Docs	What's Missing
#14003: Endpoint different from localhost (LAN access)	inner-loop-networking-overview	No 0.0.0.0 binding for external access
#13840: Optimizing app host start up time	what-is-the-apphost	Explains WaitFor but no performance optimization
#13670: Launching Desktop Applications	None	No console/desktop app integration docs
How to bind to 0.0.0.0 for LAN?	inner-loop-networking-overview	Not covered - only localhost scenarios
CORS configuration	None	No CORS documentation exists

---

Detailed Doc Review

inner-loop-networking-overview - MOSTLY COMPREHENSIVE

What it covers (verified by reading):

• ✅ Launch profiles and applicationUrl
• ✅ Kestrel endpoint configuration from appsettings.json
• ✅ Proxies - how they work, port assignment
• ✅ Replicas with random ports
• ✅ Container bridge networks and DNS service discovery
• ✅ WithEndpoint callback for custom configuration
• ✅ WithEndpointsInEnvironment filtering
• ✅ Container ports with targetPort
• ✅ host.docker.internal mentioned

What users ask that it DOESN'T cover:

• Binding to 0.0.0.0 for LAN/external access
• Container-to-localhost SQL Server (specific scenario)
• Troubleshooting networking issues

what-is-the-apphost - COVERS BASICS

What it covers:

• ✅ WaitFor usage and purpose
• ✅ WithReference for dependencies
• ✅ Resource naming and service discovery

What users ask that it DOESN'T cover:

• Startup optimization/performance
• WaitFor behavior differences: local vs deployment

---

Critical Gaps - No Documentation Exists

❌ P1: Console/Desktop App Integration

Questions: #13670, plus many Discord questions Status: No docs exist Missing:

• Console app integration guide
• Background worker patterns
• Non-HTTP service patterns
• WPF/WinForms (MAUI exists, but not WPF)

❌ P1: External Network Access (0.0.0.0)

Questions: #14003, plus Discord questions about LAN access Status: Not in inner-loop-networking-overview Missing:

• Binding to 0.0.0.0
• LAN development scenarios
• External access patterns

❌ P2: CORS Configuration

Questions: ~3 GitHub, 10+ Discord Status: No docs exist Missing:

• When CORS is needed with Aspire
• CORS dev vs prod configuration
• Common CORS troubleshooting

❌ P2: Startup Performance

Questions: #13840, #12518 Status: WaitFor documented but not optimization Missing:

• Startup optimization patterns
• Reducing container pull time
• Parallel startup options

---

Data Source

• GitHub Discussions: 820 total, 174 app-model related
• Verification method: aspire-get_doc to read actual doc content
• Date: February 2026

02-deployment-cicd.md

[GitHub Discussions] Deployment & CI/CD documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Deployment (general)	111
Kubernetes/Helm	25+
CI/CD Pipelines	20+
aspire deploy CLI	15+

---

Docs That Exist - Verified If They Answer Questions

✅ Questions Answered by Docs

Question	Doc	Section That Answers
#14092: Can you specify which project(s) to deploy?	pipelines-and-app-topology	"Running specific steps" - aspire do deploy-apiservice
#12484: Overriding Kestrel endpoints from appsettings.json?	inner-loop-networking-overview	"Kestrel configured endpoints" - ExcludeKestrelEndpoints = false

❌ Questions NOT Answered by Any Doc

Question	Searched Docs	What's Missing
#12612: ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL in Kubernetes	kubernetes-integration	No mention of this env var anywhere
#9380: Database ConnectionString all Empty inside K8s	kubernetes-integration	No troubleshooting, only says "Connection strings → ConfigMaps and Secrets"
#9372: PgSql Invalid Password in K8s	kubernetes-integration, postgresql-*	No K8s-specific password troubleshooting
#13840: Optimizing app host start up time	what-is-the-apphost	Explains WaitFor but no optimization guidance
#13911: How to debug "aspire publish" and "aspire deploy"	deploy-using-the-aspire-cli	No debugging/verbose output section
#11127: Tests fail in Azure pipeline but pass locally	None	No CI/CD testing guide exists
#10927: Deploy from on-premises Devops Server	None	No on-prem deployment docs
#13694: Self-hosting on Linux VPS	None	No self-hosting docs

---

Detailed Doc Review

kubernetes-integration - GAPS IDENTIFIED

What it covers:

• AddKubernetesEnvironment method
• aspire publish -o k8s-artifacts for manifest generation
• Helm chart name configuration
• Resource type mappings (Projects → Deployments, etc.)

What users ask that it DOESN'T cover:

• ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL - not mentioned at all
• Connection string troubleshooting in K8s
• Database password issues
• K8s secrets (external, not generated)
• Service discovery differences in K8s vs local
• CRD/Custom Resource support
• Ingress configuration
• Actually deploying to K8s cluster (only manifest generation)

pipelines-and-app-topology - WELL DOCUMENTED

Answers these questions:

• ✅ Selective deployment: aspire do deploy-apiservice
• ✅ Pipeline step customization
• ✅ Dependency management

deploy-using-the-aspire-cli - GAPS IDENTIFIED

What it covers:

• Basic aspire deploy to ACA
• Authentication with az login
• Interactive prompts
• Resource naming
• Troubleshooting: auth errors, naming conflicts, build failures

What users ask that it DOESN'T cover:

• Debugging CLI commands (verbose logging)
• Comparing azd vs aspire CLI
• Dev-only resources during deploy

---

Critical Gaps - No Documentation Exists

❌ P0: CI/CD Integration Guide

Questions: #11127, #10927, #9899, #9057 Status: Only GitHub Actions example in docker-integration Missing:

• Azure DevOps pipeline setup
• GitLab CI setup
• Service Principal vs User auth in CI
• Test failures in CI troubleshooting
• Multi-environment CI workflows

❌ P0: Self-Hosting / Non-Azure

Questions: #13694, #12204, #10657, #6690 Status: No docs exist Missing:

• Linux VPS deployment
• On-premises patterns
• AWS/GCP deployment
• Air-gapped environments

❌ P1: Kubernetes Troubleshooting

Questions: #12612, #9380, #9372 Status: kubernetes-integration exists but lacks troubleshooting Missing:

• ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL docs
• Connection string debugging
• Password/secrets issues

---

Data Source

• GitHub Discussions: 820 total, 111 deployment-related
• Verification method: aspire-get_doc to read actual doc content
• Date: February 2026

03-integrations.md

[GitHub Discussions] Integrations documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Integration	Questions
PostgreSQL/SQL Server/MySQL	45+
Redis	15+
Dapr	20+
YARP	12+
Orleans	8+
Custom integrations	25+

---

Docs That Exist - Verified If They Answer Questions

✅ Questions Answered by Docs

Question	Doc	Section That Answers
How to add PostgreSQL?	postgresql-integration	Full guide with hosting + client
Redis caching setup	redis-integration	Hosting + caching client
Basic Dapr sidecar	dapr-integration	WithDaprSidecar() usage

❌ Questions NOT Answered by Any Doc

Question	Searched Docs	What's Missing
#9925: How to deploy Dapr to production?	dapr-integration	No production/deployment section - ends at client integration
#13542: YARP with Azure Container Apps	None	No YARP integration doc exists
#10841: External PostgreSQL connection	postgresql-integration	Only covers container, not external DBs
#9812: Orleans with Aspire clustering	orleans-integration	Basic setup only, no clustering
#13123: Custom health check intervals	Various	No health check customization docs

---

Detailed Doc Review

dapr-integration - GAP: NO PRODUCTION GUIDANCE

What it covers (verified by reading full doc):

• ✅ WithDaprSidecar() extension method
• ✅ DaprSidecarOptions (ports, app ID)
• ✅ Dashboard integration
• ✅ Client integration with AddDaprClient()
• ✅ Service-to-service invocation

What users ask that it DOESN'T cover:

• Deploying Dapr sidecars to Kubernetes
• Azure Container Apps with Dapr
• Dapr state store configuration
• Pub/Sub component integration
• Production configuration

postgresql-integration - GAP: EXTERNAL DATABASES

What it covers:

• ✅ AddPostgres() container
• ✅ AddDatabase() for databases
• ✅ Client integration with EF Core
• ✅ Health checks
• ✅ Tracing and metrics

What users ask that it DOESN'T cover:

• Connecting to external/existing PostgreSQL server
• Azure PostgreSQL Flexible Server
• Connection pooling (pgBouncer)
• SSL/TLS configuration

redis-integration - MOSTLY COMPLETE

What it covers:

• ✅ Basic hosting
• ✅ Caching client
• ✅ StackExchange.Redis client
• ✅ Health checks

What users ask that it DOESN'T cover:

• Redis Cluster
• Azure Cache for Redis (separate doc exists)
• Sentinel configuration

---

Critical Gaps - No Documentation Exists

❌ P0: YARP Integration

Questions: #13542, #11234, #10432 Status: No YARP documentation Missing:

• YARP reverse proxy with Aspire
• YARP routes for microservices
• YARP on Azure Container Apps

❌ P1: External Database Connections

Questions: #10841, #9578, #8432 Status: All DB docs focus on containers only Missing:

• Connecting to existing databases
• Azure managed databases (Flexible Server, etc.)
• Production database patterns

❌ P1: Dapr Production Deployment

Questions: #9925, #8234 Status: dapr-integration is dev-only Missing:

• K8s with Dapr sidecars
• ACA with Dapr components
• Dapr component configuration

❌ P2: Custom Health Checks

Questions: #13123, #11892 Status: Health checks mentioned but not configurable Missing:

• Custom health check intervals
• Health check endpoints customization
• Conditional health checks

---

Data Source

• GitHub Discussions: 820 total, 126 integration-related
• Verification method: aspire-get_doc to read actual doc content
• Date: February 2026

04-testing.md

[GitHub Discussions] Testing documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Integration testing	20+
Mocking/stubbing	10+
CI/CD test failures	8+

---

Docs That Exist - Verified If They Answer Questions

✅ Questions Answered by Docs

Question	Doc	Section That Answers
How to test Aspire apps?	testing-overview	DistributedApplicationTestingBuilder full guide
Randomize ports for parallel tests?	testing-overview	"Disable port randomization" - DcpPublisher:RandomizePorts=false
Enable dashboard during tests?	testing-overview	"Enable the dashboard" - DisableDashboard = false

❌ Questions NOT Answered by Any Doc

Question	Searched Docs	What's Missing
#11127: Tests fail in Azure pipeline	testing-overview	No CI/CD troubleshooting
#10423: How to mock a database?	testing-overview	Explicitly says NOT supported - "doesn't enable scenarios for mocking"
#9834: Seed test data before tests	testing-overview	No database seeding patterns
#9234: Container cleanup after tests	testing-overview	Not covered

---

Detailed Doc Review

testing-overview - GAP: CI/CD + MOCKING ALTERNATIVES

What it covers (verified by reading full doc):

• ✅ DistributedApplicationTestingBuilder setup
• ✅ Port randomization (default on, can disable)
• ✅ Dashboard toggle
• ✅ Clear diagram of how tests work
• ✅ When to use (vs WebApplicationFactory)
• ✅ Explicit about limitations: "doesn't enable scenarios for mocking, substituting, or replacing services—as the tests run in a separate process"

What users ask that it DOESN'T cover:

• CI/CD pipeline configuration (Docker-in-Docker, etc.)
• Tests passing locally but failing in CI
• Database seeding and cleanup
• Alternatives when mocking is needed
• Parallel test execution patterns
• Test data isolation

---

Critical Gaps

❌ P0: CI/CD Testing Guide

Questions: #11127, #10234, #9899 Status: No CI/CD testing docs Missing:

• Azure DevOps pipeline for Aspire tests
• GitHub Actions for Aspire tests
• Docker-in-Docker requirements
• Container registry auth in CI
• Resource limits (memory, timeout)
• "Works locally, fails in CI" troubleshooting

❌ P1: When Mocking is Needed - Alternatives

Questions: #10423, #9234 Status: Doc says "not supported" but gives no alternatives Missing:

• What to do when you need isolated unit tests
• WebApplicationFactory patterns for single services
• Test containers as "mock" alternatives
• Hybrid testing strategies

❌ P2: Test Data Management

Questions: #9834, #8765 Status: Not documented Missing:

• Database seeding before tests
• Container cleanup after tests
• Test data isolation patterns

---

Key Finding

The docs explicitly state mocking is NOT supported, but many users ask about mocking anyway. This means:

1. Users don't read this section
2. Users need the capability and are confused why it's missing
3. Docs should explain ALTERNATIVES to mocking

---

Data Source

• GitHub Discussions: 820 total, 40 testing-related
• Verification method: aspire-get_doc to read actual doc content
• Date: February 2026

05-telemetry.md

[GitHub Discussions] Telemetry & Dashboard documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Dashboard	88 total
Dashboard in Production	15+
OpenTelemetry Config	20+
Logging	15+
Metrics	10+

---

Docs That Exist (verified via get_doc)

Slug	Title	Coverage
aspire-dashboard-overview	Dashboard overview	✅ Introduction, features
aspire-dashboard-configuration	Dashboard configuration	✅ Configuration options, telemetry limits
explore-aspire-dashboard	Explore dashboard	✅ UI walkthrough, authentication
standalone-aspire-dashboard	Standalone dashboard	✅ Docker run command, OTLP port config, login token, OpenTelemetry SDK setup
aspire-dashboard-security-considerations	Dashboard security	✅ Security posture
enable-browser-telemetry	Browser telemetry	✅ Frontend OTEL
use-the-aspire-dashboard-with-nodejs-apps	Dashboard with Node.js	✅ Node.js OTEL
use-the-aspire-dashboard-with-python-apps	Dashboard with Python	✅ Python OTEL
telemetry	Telemetry	✅ OTEL basics

---

Gaps in Existing Docs

1. ⚠️ Dashboard in Production (15+ questions)

Docs exist: standalone-aspire-dashboard ✅ covers:

• Docker run command with port mapping
• OTLP port configuration (4317 → 18889)
• Login token retrieval from logs
• OpenTelemetry SDK configuration (OTEL_EXPORTER_OTLP_ENDPOINT)
• Limitations: in-memory only, no persistence, no GitHub Copilot

Explicit warning in doc: "The dashboard is designed as a development and short-term diagnostic tool"

Discussions still asking about:

• #12933: Dashboard In Production
• #10243: Dashboard via Kubernetes Ingress
• #9353: Dashboard Error 404 on Azure
• #8277: Dashboard Behind a Proxy

What's missing from standalone-aspire-dashboard:

• Production deployment patterns (when appropriate)
• Dashboard behind proxy/ingress (nginx, K8s ingress)
• Azure-specific deployment troubleshooting
• Persistent telemetry alternatives (Azure Monitor, etc.)

---

2. ⚠️ Custom OTEL Configuration (20+ questions)

Docs exist: telemetry, standalone-aspire-dashboard ✅ cover basics

Discussions still asking about:

• #13707: Dynamically generate prometheus configuration
• #12338: OTLP exporter failures silently swallowed
• #10405: Java OTel Agent configuration
• #10043: Pull-based logs and metrics
• #9470: Connect existing OTEL config to AppHost collector
• #9167: Consume 3rd party metrics

What's missing:

• Custom OTEL collector configuration (config.yaml examples)
• Third-party metrics integration
• Pull-based metrics patterns (Prometheus scrape)
• Java/JVM OTEL configuration
• OTEL exporter error handling/visibility

---

3. ✅ Browser/Frontend Telemetry - DOCUMENTED

Docs exist: enable-browser-telemetry ✅

Remaining questions:

• #11129: Post OpenTelemetry from Vite app

What might be missing:

• Vite/React-specific patterns

---

4. ⚠️ Logging Configuration

Discussions:

• #12503: Excessive logging from Azure Functions
• #9406: Logging with scopes
• #9164: Redirect logs to console window

What's missing:

• Log filtering/reduction patterns
• Scoped logging configuration
• Azure Functions logging noise reduction

---

Data Source

• GitHub Discussions: 820 total
• Telemetry-related: 88 discussions
• Date range: Project inception - February 2026
• Verified against: aspire-list_docs (9 dashboard/telemetry docs), aspire-get_doc for detailed review

06-devex-tooling.md

[GitHub Discussions] Developer Experience & Tooling gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
DevEx/Tooling	60 total
Performance/Slow	15+
Debugging	10+
IDE Issues	10+
CLI	15+

---

Critical Gaps

1. ❌ Debugging Guide (CRITICAL)

Discussions:

• #12561: Allow running and debugging a Linux-only project on aspire
• #12039: .Net Aspire Single Service Nvim Debugging
• #9846: Is this a bug?

Customer Questions:

• Debugging specific services
• Selective debugging (debug some, not others)
• Linux-only project debugging
• Non-VS debugging (Neovim, etc.)

Action Items:

• Debugging guide (all IDEs)
• Selective service debugging
• Linux debugging patterns
• Non-VS IDE debugging

---

2. ❌ Performance/Slow Startup (15+ questions)

Discussions:

• #12518: Why are Aspire projects taking so long to be restored? It's more than 2 mins every single time
• #13840: Optimizing app host start up time

Customer Questions:

• NuGet restore taking too long
• App host startup optimization
• Container pull slowness

Action Items:

• Performance optimization guide
• NuGet restore troubleshooting
• Startup optimization patterns

---

3. ⚠️ IDE-Specific Issues

Discussions:

• #10168: Using GH Copilot in Aspire in Rider and other IDEs
• Rider, VS Code extension issues mentioned across discussions

Customer Questions:

• Rider integration
• VS Code extension issues
• GitHub Copilot integration

Action Items:

• IDE comparison guide
• Rider-specific documentation
• VS Code troubleshooting

---

4. ⚠️ Watch Mode / Hot Reload

No dedicated discussions, but Discord shows high demand (42 questions)

Action Items:

• Watch mode current status
• Hot reload limitations
• Workarounds

---

Data Source

• GitHub Discussions: 820 total
• DevEx-related: 60 discussions
• Date range: Project inception - February 2026

07-azure.md

[GitHub Discussions] Azure-specific documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Azure (total)	106
Azure Container Apps	30+
Azure Functions	15+
Azure Storage	10+
Azure PostgreSQL	10+
RBAC/Permissions	10+

---

Docs That Exist (38 Azure-related docs)

Slug	Title	Coverage
azure-integrations-overview	Azure integrations overview	✅ Overview
azure-functions-integration	Azure Functions integration	✅ Hosting + triggers
azure-blob-storage	Azure Blob Storage	✅ Hosting + client
azure-queue-storage	Azure Queue Storage	✅ Hosting + client
azure-key-vault	Azure Key Vault	✅ Secrets
azure-service-bus-integration	Azure Service Bus	✅ Messaging
azure-cosmos-db-integration	Azure Cosmos DB	✅ Hosting + client
azure-postgresql-*	Azure PostgreSQL	✅ Hosting + EF
azure-sql-database-integration	Azure SQL Database	✅ Hosting + EF
azure-container-registry-integration	Azure Container Registry	✅ ACR
azure-container-app-jobs	Azure Container App Jobs	✅ Jobs
azure-security-best-practices-for-aspire-deployments	Azure security	✅ Security posture
manage-azure-role-assignments	Manage Azure role assignments	✅ RBAC basics

---

Gaps in Existing Docs

1. ⚠️ Azure Container Apps Customization

Docs exist: Various ACA docs ✅ but limited customization guidance

Discussions:

• #11600: Deployment of single project on Azure Container Apps
• #10976: Deploy container app with a custom domain
• #9353: Aspire Dashboard return Error 404 on Azure
• #6400: Customization of Azure Container Apps on Npm Apps

What's missing:

• Custom domain configuration for ACA
• Selective resource deployment to ACA
• ACA customization for JavaScript apps
• Service discovery behavior on ACA (https+http)

---

2. ❌ Cross-Subscription Resources

Docs exist: None for cross-subscription patterns

Discussions:

• #13029: azd up - cross subscription resource
• #9343: Questions around deploying to existing resources

What's needed:

• AsExisting from different subscriptions
• Multi-resource-group deployments
• Existing resource integration patterns

---

3. ⚠️ Azure Functions Deployment

Docs exist: azure-functions-integration ✅ but deployment gaps

Discussions:

• #9829: Cosmos DB & Azure Functions differences
• #12503: Excessive logging from storage blob/queue triggers
• #8375: Azure Functions does not start via AddAzureFunctionsProject on macOS

What's missing from azure-functions-integration:

• Worker runtime configuration for deployment
• Deployment prompts and pre-configuration
• KEDA scaling configuration
• macOS troubleshooting

---

4. ⚠️ RBAC/Permissions

Docs exist: manage-azure-role-assignments ✅ but deployment permissions unclear

Discussions:

• #14108: Transition to Azure RBAC
• #12877: Issue with AppConfig - Roles deployment
• #10819: AzureBicepResource.KnownParameters.PrincipalId removed

What's missing from manage-azure-role-assignments:

• Required Azure permissions for aspire deploy
• Troubleshooting permission errors
• Minimal RBAC requirements
• Breaking changes for RBAC (migration guide)

---

5. ⚠️ Azure Storage SAS Patterns

Docs exist: azure-blob-storage ✅ but SAS patterns missing

Discussions:

• #8402: Is it intended that the Azure Storage provider create containers like blobs?
• SAS URI questions (from Discord analysis)

What's missing from azure-blob-storage:

• SAS URI generation permissions
• User delegation vs account SAS
• Local vs deployed authentication differences

---

Data Source

• GitHub Discussions: 820 total
• Azure-related: 106 discussions
• Date range: Project inception - February 2026
• Verified against: aspire-list_docs (38 Azure docs)

08-docker-containers.md

[GitHub Discussions] Docker & Container documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
Docker/Containers	156 total
Container Build	40+
Volumes/Persistence	25+
Docker Compose	20+
Registry	15+
Networking	20+

---

Docs That Exist (verified via get_doc)

Slug	Title	Coverage
docker-integration	Docker integration	✅ Docker Compose publishing, AddDockerComposeEnvironment, PublishAsDockerComposeService, GitHub Actions workflow, registry push
add-dockerfiles-to-your-app-model	Add Dockerfiles	✅ Custom Dockerfile
docker-compose-to-aspire-apphost	Docker Compose to Aspire	✅ Migration guide
migrate-from-docker-compose-to-aspire	Migrate from Docker Compose	✅ Migration patterns
persist-aspire-project-data-using-volumes-or-bind-mounts	Persist data with volumes	✅ Volume/bind mount patterns
persistent-container-lifetimes	Persistent container lifetimes	✅ Container persistence
azure-container-registry-integration	Azure Container Registry	✅ ACR integration
inner-loop-networking-overview	Inner loop networking	✅ Container networking, bridge network, DNS

---

Gaps in Existing Docs

1. ✅ Docker Compose Publishing - WELL DOCUMENTED

Docs exist: docker-integration ✅ comprehensive coverage

The doc covers:

• AddDockerComposeEnvironment and PublishAsDockerComposeService
• aspire publish, aspire do prepare-{name}, aspire deploy
• Environment file customization
• Container registry configuration (AddContainerRegistry)
• GitHub Actions workflow example
• Image push with aspire do push

Remaining questions:

• #14008: Container images different across Windows and Linux

What might be missing:

• Cross-platform build consistency troubleshooting
• Platform architecture configuration details

---

2. ⚠️ Container Build Troubleshooting

Docs exist: docker-integration, add-dockerfiles-to-your-app-model ✅

Discussions:

• #14008: Container images different across Windows and Linux
• #10949: Aspire CLI not include Docker Container when take build
• #8278: SqlServer container rebuilt every run

What's missing:

• Cross-platform container build troubleshooting
• Container inclusion/exclusion configuration
• Rebuild behavior control (avoiding unwanted rebuilds)

---

3. ✅ Volume/Persistence - WELL DOCUMENTED

Docs exist: persist-aspire-project-data-using-volumes-or-bind-mounts, persistent-container-lifetimes ✅

Remaining questions:

• #12393: WithDataVolume Key Collision with AddDockerComposeEnvironment
• #12906: Ability to restore a backup to a postgres container?

What might be missing:

• Volume naming conflict resolution
• Database backup/restore with volumes

---

4. ✅ Container Networking - WELL DOCUMENTED

Docs exist: inner-loop-networking-overview ✅ comprehensive

The doc covers:

• Container bridge networks (aspire-session-network, aspire-persistent-network)
• DNS-based service discovery between containers
• host.docker.internal behavior
• Container-to-container communication

Remaining questions:

• #14003: Using resources with endpoint different from localhost

What might be missing:

• Container-to-localhost SQL Server specific patterns
• External network exposure (0.0.0.0 binding)

---

5. ⚠️ Alternative Runtimes

Docs exist: None for Podman or alternative runtimes

Discussions:

• #6445: Run .NET Aspire without Docker/Podman? (Kaniko/Skaffold)
• #12204: Run in .NET SDK container without docker client

What's needed:

• Podman support documentation
• Running without Docker scenarios
• Alternative container runtime support status

---

Data Source

• GitHub Discussions: 820 total
• Docker/Container-related: 156 discussions
• Date range: Project inception - February 2026
• Verified against: aspire-list_docs (12 container/docker docs), aspire-get_doc for detailed review

09-wsl-linux.md

[GitHub Discussions] WSL & Linux documentation gaps

Summary

Based on analysis of 820 GitHub discussions from dotnet/aspire.

Question counts:

Topic	Questions
WSL/Linux	18
WSL Mixed Development	6+
Linux-only	5+
macOS	5+

---

Gaps Identified

1. ❌ WSL Mixed Development (No docs)

Discussions:

• #13453: How to start aspire in WSL?
• #13429: How to run aspire python in wsl while aspnet in windows

Customer Questions:

• Running Aspire in WSL
• Mixed WSL/Windows development
• Python in WSL + .NET on Windows

Action Items:

• WSL development guide
• Mixed platform patterns (WSL + Windows)
• Cross-platform debugging

---

2. ❌ Linux Development

Discussions:

• #12561: Allow running and debugging a Linux-only project on aspire
• #1381: Problem with running .net aspire project on linux
• #5859: Error with npm on ubuntu: executable file not found in $PATH

Customer Questions:

• Linux-only project debugging
• npm path issues on Linux
• General Linux troubleshooting

Action Items:

• Linux setup guide
• Linux troubleshooting
• npm/Node.js on Linux

---

3. ⚠️ macOS Issues

Discussions:

• #8375: Azure Functions does not start via AddAzureFunctionsProject on macOS

Customer Questions:

• macOS-specific issues
• Azure Functions on macOS

Action Items:

• macOS troubleshooting
• Platform-specific limitations

---

Data Source

• GitHub Discussions: 820 total
• WSL/Linux-related: 18 discussions
• Date range: Project inception - February 2026