Skip to content

docs: modernize deployment and operations guidance - #10327

Merged
ReubenBond merged 19 commits into
dotnet:mainfrom
ReubenBond:reubenbond-modernize-deployment-docs
Aug 6, 2026
Merged

ReubenBond merged 19 commits into
dotnet:mainfrom
ReubenBond:reubenbond-modernize-deployment-docs

Conversation

@ReubenBond

@ReubenBond ReubenBond commented Aug 2, 2026 •

Copy link
Copy Markdown
Member

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
Copilot AI review requested due to automatic review settings August 2, 2026 15:59

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copilot AI review requested due to automatic review settings August 2, 2026 21:03

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 typical WebApplication project won’t compile this snippet without adding using Orleans.Configuration; and using 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
Copilot AI review requested due to automatic review settings August 3, 2026 17:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot's findings

  • Files reviewed: 48/62 changed files
  • Comments generated: 0 new

ReubenBond and others added 2 commits August 3, 2026 12:13
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
Copilot AI review requested due to automatic review settings August 3, 2026 19:13
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 using directive (\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 normal using keyword.
  • Files reviewed: 73/87 changed files
  • Comments generated: 0 new

Copilot AI review requested due to automatic review settings August 3, 2026 19:17
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot's findings

Suppressed comments (1)

samples/Deployment/AzureAppService/Silo/Program.cs:139

  • GetRequiredSetting treats whitespace-only values as configured (it checks Length > 0). That can lead to harder-to-diagnose failures later (for example new 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

Copilot AI review requested due to automatic review settings August 3, 2026 19:21

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 normal using statement.
  • 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
Copilot AI review requested due to automatic review settings August 3, 2026 20:08

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot's findings

Suppressed comments (1)

samples/Deployment/AzureAppService/Silo/StartupTasks/ProductStoreSeeder.cs:4

  • Line contains an embedded BOM/zero-width character before the using directive ("using"), which can cause build errors like CS1056: Unexpected character on some toolchains/editors. Remove the hidden character so this is a normal using directive.
  • 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
Copilot AI review requested due to automatic review settings August 6, 2026 19:10
ReubenBond added a commit to ReubenBond/orleans that referenced this pull request Aug 6, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@ReubenBond
ReubenBond merged commit 5db2434 into dotnet:main Aug 6, 2026
1 check passed
@ReubenBond
ReubenBond deleted the reubenbond-modernize-deployment-docs branch August 6, 2026 21:07
ReubenBond added a commit to ReubenBond/orleans that referenced this pull request Aug 7, 2026
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
This was referenced Aug 28, 2026
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 6, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants