Skip to content

docs: add local execution journey - #1211

Merged
devanshjainms merged 17 commits into
Azure:release/july-2026from
devanshjainms:docs/local-execution-journey
Jul 28, 2026
Merged

docs: add local execution journey#1211
devanshjainms merged 17 commits into
Azure:release/july-2026from
devanshjainms:docs/local-execution-journey

Conversation

@devanshjainms

@devanshjainms devanshjainms commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Problem

Local scripted execution is a first-class SDAF deployment model, but the central repository did not provide an end-to-end journey equivalent to the GitHub Actions and Azure DevOps paths.

Solution

  • Add an ordered local-execution journey covering prerequisites, host preparation, control plane, workload zone, SAP system, software and installation, operations, and troubleshooting.
  • Document established and v2 script families without assigning an unsupported preference.
  • Explain configuration ownership, Terraform state, validation evidence, retry behavior, and destructive-operation safeguards at each stage.
  • Add the journey to the central documentation index and deployment-options page.

Tests

  • Validated all relative Markdown links and heading anchors in the changed documentation.
  • Validated referenced repository paths and script entry points against the release/july-2026 source baseline.
  • Ran git diff --check.
  • Confirmed the change set contains documentation only.

Notes

This is phase 2 of the repository documentation modernization. It follows merged PR #1205 and does not change scripts, Terraform, Ansible, pipelines, support policy, or Microsoft Learn content.

@devanshjainms
devanshjainms requested a review from a team as a code owner July 24, 2026 20:43
@devanshjainms
devanshjainms requested review from Copilot and nnoaman July 24, 2026 20:43
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Adds an end-to-end local SDAF deployment journey to the central documentation hub.

Changes:

  • Documents prerequisites, deployment, installation, operations, and troubleshooting.
  • Covers established and v2 script families and operational safeguards.
  • Links the journey from central documentation pages.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
docs/local/README.md Introduces the journey and script families.
docs/local/01-00-prerequisites.md Documents prerequisites and version requirements.
docs/local/02-00-prepare-execution-environment.md Covers host and configuration preparation.
docs/local/03-00-control-plane.md Documents control-plane deployment.
docs/local/04-00-workload-zone.md Documents workload-zone deployment.
docs/local/05-00-sap-system.md Documents SAP-system deployment.
docs/local/06-00-software-and-installation.md Covers software download and Ansible installation.
docs/local/07-00-operations.md Covers changes, recovery, state, and removal.
docs/local/troubleshooting.md Adds local-execution troubleshooting guidance.
docs/index.md Links to the local journey.
docs/deployment-options.md Adds the journey to local deployment options.
Comments suppressed due to low confidence (1)

docs/local/06-00-software-and-installation.md:170

  • The menu does not stop after every failure: custom pre- and post-playbook failures are logged and the sequence continues. The retry guidance should warn operators to check those hook results explicitly rather than relying on the wrapper to stop.
Correct the failed prerequisite or task, then rerun the smallest applicable
playbook. The menu stops after a failure, so do not restart a grouped sequence
without identifying the failed playbook and reviewing its progress marker and
idempotence.

Comment thread docs/local/06-00-software-and-installation.md Outdated
Comment thread docs/local/03-00-control-plane.md Outdated
Comment thread docs/local/04-00-workload-zone.md Outdated
Comment thread docs/local/05-00-sap-system.md Outdated
Comment thread docs/local/07-00-operations.md Outdated
Copilot AI review requested due to automatic review settings July 24, 2026 21:01
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Comment thread docs/local/02-00-prepare-execution-environment.md
Comment thread docs/local/01-00-prerequisites.md Outdated
Copilot AI review requested due to automatic review settings July 24, 2026 21:17
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Copilot AI review requested due to automatic review settings July 24, 2026 21:30
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

docs/local/02-00-prepare-execution-environment.md:131

  • The strict-checking override documented here is ineffective: configuration_menu.sh:82 unconditionally exports ANSIBLE_HOST_KEY_CHECKING=False after the operator launches it, overriding the True value set in this step. This can make an operator believe policy-required host-key enforcement is active when the installation wrapper has disabled it. Document the limitation and require an approved wrapper change for strict checking.
   The generated profile also sets `ANSIBLE_HOST_KEY_CHECKING=False`. Before
   running configuration, verify each target host key through an approved
   out-of-band source. If your security policy requires strict checking,
   populate the approved `known_hosts` file and export
   `ANSIBLE_HOST_KEY_CHECKING=True` after loading the profile.

Comment thread docs/local/02-00-prepare-execution-environment.md
Copilot AI review requested due to automatic review settings July 24, 2026 21:44
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Comment thread docs/local/07-00-operations.md Outdated
Copilot AI review requested due to automatic review settings July 24, 2026 21:58
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Comment thread docs/local/04-00-workload-zone.md Outdated
Comment thread docs/local/04-00-workload-zone.md Outdated
Comment thread docs/local/troubleshooting.md Outdated
Comment thread docs/local/07-00-operations.md Outdated
Copilot AI review requested due to automatic review settings July 24, 2026 22:11
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Comment thread docs/local/02-00-prepare-execution-environment.md Outdated
Comment thread docs/local/03-00-control-plane.md Outdated
Comment thread docs/local/01-00-prerequisites.md
Copilot AI review requested due to automatic review settings July 24, 2026 22:25
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Comment thread docs/local/04-00-workload-zone.md Outdated
Comment thread docs/local/01-00-prerequisites.md Outdated
Comment thread docs/local/06-00-software-and-installation.md
Copilot AI review requested due to automatic review settings July 24, 2026 22:39
Copilot AI reviewed Jul 24, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comment thread docs/local/06-00-software-and-installation.md Outdated
Copilot AI review requested due to automatic review settings July 24, 2026 22:52
Copilot AI reviewed Jul 28, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

hdamecharla
hdamecharla previously approved these changes Jul 28, 2026
View reviewed changes

@hdamecharla hdamecharla left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Approved

Comment thread docs/local/03-00-control-plane.md Outdated
Comment thread docs/local/03-00-control-plane.md Outdated
Comment thread docs/local/05-00-sap-system.md Outdated
Comment thread docs/local/05-00-sap-system.md Outdated
Comment thread docs/local/05-00-sap-system.md Outdated
Comment thread docs/local/05-00-sap-system.md Outdated
Comment thread docs/local/04-00-workload-zone.md Outdated
Comment thread docs/local/06-00-software-and-installation.md Outdated
Comment thread docs/local/06-00-software-and-installation.md
Comment thread docs/local/06-00-software-and-installation.md
Copilot AI review requested due to automatic review settings July 28, 2026 04:07
Copilot AI reviewed Jul 28, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

hdamecharla
hdamecharla approved these changes Jul 28, 2026
View reviewed changes

@hdamecharla hdamecharla left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Approved

@devanshjainms
docs: add local execution journey
1886e89 
Document the end-to-end local scripted deployment path, including prerequisites, environment preparation, lifecycle stages, operations, and troubleshooting.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: address local journey review
2083de6 
Clarify retained Terraform apply artifacts and distinguish numbered playbook failures from customer hook failures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: align local host preparation paths
df22c2b 
Use the checkout consumed by configure_deployer.sh, verify the approved commit after clone, and restore reviewed environment values after loading the generated profile.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: document host setup side effects
0a242d3 
Clarify version resolution, operating-system changes, generated SSH policy, and the maintenance review required before rerunning host preparation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: authenticate before local host setup
7ea6767 
Require an installed authenticated Azure CLI before configure_deployer queries account state, and document its managed-identity host requirement.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: clarify wrapper and state risks
bd88168 
Document the Ansible wrapper's host-key override and the backend migration performed even during state listing.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: correct local validation evidence
65f0cd7 
Align workload-zone checks, troubleshooting artifacts, and control-plane removal paths with local script behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: correct control-plane prerequisites
3d35f9b 
Quote the commit placeholder, use absolute control-plane parameter paths, and document required non-MSI service-principal inputs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: add local deployment input requirements
982cea7 
Document host architecture, workload subscription scope, and component BOM values required by the local wrappers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: use wrapper-compatible BOM values
b7d93e7 
Show unquoted BOM component scalars so download_menu.sh does not retain quote characters in the generated name.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: clarify control-plane removal recovery
a73aae8 
Warn that a persisted removal step can make reruns exit successfully while deployer resources remain, and require reviewed component recovery.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: add host and key cleanup prerequisites
869244e 
Require Git before cloning and remove the retrieved SSH private key after each configuration-menu run.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: clarify local execution environments
641fa75 
List the documented Linux setup versions and distinguish the portable Bash entry points from the Linux-specific setup helper.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: avoid unsupported host version claims
10a8e8d 
Describe the setup helper's recognized distributions without treating its code guards as an authoritative support matrix.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: clarify local execution safety boundaries
b21ad6b 
Document service-principal argument exposure, identity selection after profile loading, and provider-lock requirements for deterministic retries.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
docs: clarify local subscription and removal recovery
9ea6e73 
Set workload subscription context for SAP-system deployment and removal, and exclude interrupted control-plane removal from generic retries.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
@devanshjainms
clarify local deployment terminology and safeguards
de3d9dc 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 6d10f85a-7a25-43b0-bcb2-abf87810f1b2
Copilot AI review requested due to automatic review settings July 28, 2026 17:38
@devanshjainms
devanshjainms force-pushed the docs/local-execution-journey branch from c1bf2fd to de3d9dc Compare July 28, 2026 17:38
@devanshjainms
devanshjainms merged commit 7b43bfc into Azure:release/july-2026 Jul 28, 2026
3 checks passed
Copilot AI reviewed Jul 28, 2026
View reviewed changes

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

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

docs/local/06-00-software-and-installation.md:63

  • The download creates the aggregated BOM under save_bom_as, but the later configuration_menu.sh invocation does not read that field; it passes the existing bom_base_name from sap-parameters.yaml to BOM processing (configuration_menu.sh:188, 3.3-bom-processing/tasks/main.yaml:66). Unless these values are explicitly kept equal, installation looks for the pre-download/generated BOM name rather than the aggregated BOM. Set bom_base_name to the same combined name in this preparation step.
application_bom_name: <APPLICATION_BOM>
database_bom_name: <DATABASE_BOM>
sap_kernel_bom_name: <KERNEL_BOM>
save_bom_as: <COMBINED_BOM_NAME>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@hdamecharla hdamecharla hdamecharla approved these changes
@nnoaman nnoaman Awaiting requested review from nnoaman nnoaman is a code owner automatically assigned from Azure/azure-sap-deployment-automation

Assignees

@hdamecharla hdamecharla

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@devanshjainms @hdamecharla