Repository navigation
docs: modernize deployment and operations guidance - #10327
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
There was a problem hiding this comment.
Pull request overview
This PR modernizes the Orleans deployment documentation into an Orleans 10-focused production operations track, replacing older platform tutorials/samples with operational requirements, incident triage guidance, and safer upgrade/networking/health recommendations.
Changes:
- Adds new Orleans 10 production operations articles (readiness, networking, health/observability, upgrades, capacity planning, disaster recovery).
- Rewrites deployment troubleshooting guidance around incident triage, membership/network/provider diagnosis, and safer retry/telemetry practices.
- Retires and removes unmaintained/unsafe legacy deployment tutorials and samples (Service Fabric snippets, Consul snippet, CI secret-based deployment includes).
Show a summary per file
| File | Description |
|---|---|
| docs/site/src/content/docs/deployment/upgrades.md | Adds Orleans 10 guidance for graceful shutdown, rolling/blue-green upgrades, and rollback planning. |
| docs/site/src/content/docs/deployment/troubleshooting-deployments.md | Reframes troubleshooting into production incident triage and stabilization steps. |
| docs/site/src/content/docs/deployment/troubleshooting-azure-cloud-services-deployments.md | Replaces legacy Cloud Services troubleshooting with a retirement/redirect page. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/ServiceEventSource.cs | Removes retired Service Fabric sample code. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/Program.cs | Removes retired Service Fabric sample code. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/PackageRoot/ServiceManifest.xml | Removes retired Service Fabric sample manifest. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/PackageRoot/Config/Settings.xml | Removes retired Service Fabric sample config. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/OrleansHostedStatelessService.cs | Removes retired Service Fabric sample code. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj | Removes retired Service Fabric sample project. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/HostedServiceCommunicationListener.cs | Removes retired Service Fabric sample code. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/snippets.5000.json | Removes retired Service Fabric snippet metadata. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/service-fabric.sln | Removes retired Service Fabric sample solution. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/Scripts/Deploy-FabricApplication.ps1 | Removes retired Service Fabric deployment script. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Local.5Node.xml | Removes retired Service Fabric publish profile. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Local.1Node.xml | Removes retired Service Fabric publish profile. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Cloud.xml | Removes retired Service Fabric publish profile. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/packages.config | Removes retired Service Fabric packages config. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/Orleans.ServiceFabric.App.sfproj | Removes retired Service Fabric application project. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Local.5Node.xml | Removes retired Service Fabric application parameters. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Local.1Node.xml | Removes retired Service Fabric application parameters. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Cloud.xml | Removes retired Service Fabric application parameters. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationPackageRoot/ApplicationManifest.xml | Removes retired Service Fabric application manifest. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/.gitignore | Removes retired Service Fabric sample repo .gitignore. |
| docs/site/src/content/docs/deployment/snippets/consul/Silo/Silo.csproj | Removes retired Consul snippet project file. |
| docs/site/src/content/docs/deployment/snippets/consul/Silo/Properties/launchSettings.json | Removes retired Consul snippet launch settings. |
| docs/site/src/content/docs/deployment/snippets/consul/Silo/Program.cs | Removes retired Consul snippet code. |
| docs/site/src/content/docs/deployment/service-fabric.md | Replaces Service Fabric hosting article with retirement notice and pointers to current guidance. |
| docs/site/src/content/docs/deployment/production-readiness.md | Adds an Orleans 10 production-readiness checklist page. |
| docs/site/src/content/docs/deployment/platform-guides.md | Adds a platform capability/requirements page for Orleans production hosting. |
| docs/site/src/content/docs/deployment/networking.md | Adds Orleans topology/networking/clustering guidance, including endpoint and provider selection. |
| docs/site/src/content/docs/deployment/kubernetes.md | Modernizes Kubernetes hosting guidance for Orleans 10, including RBAC/probes/rollout baselines. |
| docs/site/src/content/docs/deployment/index.md | Restructures the deployment landing page into an Orleans 10 operations track and links new pages. |
| docs/site/src/content/docs/deployment/includes/deployment/create-service-principal.md | Removes legacy secret-based CI/service principal guidance include. |
| docs/site/src/content/docs/deployment/includes/deployment/create-github-secret.md | Removes legacy GitHub secret setup include. |
| docs/site/src/content/docs/deployment/includes/deployment/create-azure-resources.md | Removes legacy resource creation include. |
| docs/site/src/content/docs/deployment/health-and-observability.md | Adds guidance on startup/readiness/liveness semantics and telemetry practices. |
| docs/site/src/content/docs/deployment/handling-failures.md | Rewrites failure-handling guidance around unknown outcomes, idempotency, and bounded retries. |
| docs/site/src/content/docs/deployment/disaster-recovery.md | Adds Orleans 10 backup/restore/disaster recovery guidance and data inventory framing. |
| docs/site/src/content/docs/deployment/deploy-to-azure-container-apps.md | Retires the ACA tutorial and replaces it with platform qualification requirements/warnings. |
| docs/site/src/content/docs/deployment/deploy-to-azure-app-service.md | Retires the App Service tutorial and replaces it with platform qualification requirements/warnings. |
| docs/site/src/content/docs/deployment/consul-deployment.md | Replaces Consul walkthrough/snippets with current “provider selection + config” pointers. |
| docs/site/src/content/docs/deployment/capacity-planning.md | Adds capacity planning and scaling guidance centered on measured saturation and failure modes. |
Copilot's findings
- Files reviewed: 42/56 changed files
- Comments generated: 1
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
There was a problem hiding this comment.
Copilot's findings
Suppressed comments (1)
docs/site/src/content/docs/deployment/kubernetes.md:20
- The C# snippet is intended to be copyable, but it uses Orleans types/extension methods (
ClusterOptions,SiloOptions,UseOrleans,ConfigureEndpoints) without importing the required namespaces. As written, a typicalWebApplicationproject won’t compile this snippet without addingusing Orleans.Configuration;andusing Orleans.Hosting;(or fully-qualifying the types/methods).
using System.Net;
var builder = WebApplication.CreateBuilder(args);
- Files reviewed: 42/56 changed files
- Comments generated: 0 new
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
There was a problem hiding this comment.
Copilot's findings
Suppressed comments (1)
samples/Deployment/AzureAppService/Silo/StartupTasks/ProductStoreSeeder.cs:4
- Line contains a stray Unicode BOM/zero-width no-break space character before the
usingdirective (\uFEFFusing ...). This invisible character can cause inconsistent diffs and may break compilation or analyzers depending on tooling/encoding. Remove the extra BOM so the line starts with a normalusingkeyword.
- Files reviewed: 73/87 changed files
- Comments generated: 0 new
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
There was a problem hiding this comment.
Copilot's findings
Suppressed comments (1)
samples/Deployment/AzureAppService/Silo/Program.cs:139
GetRequiredSettingtreats whitespace-only values as configured (it checksLength > 0). That can lead to harder-to-diagnose failures later (for examplenew Uri(" ")) while the error message claims the setting is configured. Treat null/empty/whitespace as missing.
- Files reviewed: 73/87 changed files
- Comments generated: 1
There was a problem hiding this comment.
Copilot's findings
Suppressed comments (1)
samples/Deployment/AzureAppService/Silo/StartupTasks/ProductStoreSeeder.cs:4
- Line begins with an extra UTF-8 BOM/zero-width no-break space (shown as
using), which can cause compilation errors (invalid character) depending on editor/encoding. Remove the hidden character so the directive is a normalusingstatement.
- Files reviewed: 73/87 changed files
- Comments generated: 0 new
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
There was a problem hiding this comment.
Copilot's findings
Suppressed comments (1)
samples/Deployment/AzureAppService/Silo/StartupTasks/ProductStoreSeeder.cs:4
- Line contains an embedded BOM/zero-width character before the
usingdirective ("using"), which can cause build errors likeCS1056: Unexpected characteron some toolchains/editors. Remove the hidden character so this is a normalusingdirective.
- Files reviewed: 73/87 changed files
- Comments generated: 0 new
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472 # Conflicts: # docs/site/src/content/docs/index.yml
Modernizes the deployment documentation into an Orleans 10 production operations track covering readiness, networking, health, upgrades, capacity, disaster recovery, failure handling, and incident response.
Replaces unsafe or retired platform tutorials with validated requirements and migration prerequisites, corrects Kubernetes networking/RBAC/probe guidance, and removes obsolete samples, secrets-based CI snippets, and media.
Microsoft Reviewers: Open in CodeFlow