Skip to content

docs: Rewrite Azure Batch tutorial for native Batch Forge support - #1674

Open
adamrtalbot wants to merge 10 commits into
masterfrom
docs/azure-batch-native-tutorial
Open

docs: Rewrite Azure Batch tutorial for native Batch Forge support#1674
adamrtalbot wants to merge 10 commits into
masterfrom
docs/azure-batch-native-tutorial

Conversation

@adamrtalbot

Copy link
Copy Markdown
Contributor

Context

The manual-azure-batch-setup.md tutorials were written when advanced Azure Batch topologies required manual Nextflow config and manual Azure Portal pool creation. Seqera Platform now provisions most of these natively via Batch Forge and the compute-environment form.

Verified against seqera/platform:

Old tutorial option Now native?
Batch Forge single pool Forge now creates separate head/worker pools by default
Separate pools via process.queue Native (Forge default)
Hot head node Native (disable autoscale + Head VM type/CPUs/memory)
Nextflow autopool Deprecated/disabled (allowPoolCreation=false)
Entra service principal + managed identity Native (Entra credential + MI form fields)
VNet pool Native (Subnet ID field, Entra-gated)
VNet + autopool workers Native (subnet applied to worker pool by Forge)

Batch Forge provisions dedicated nodes only, so low-priority (spot) nodes remain a genuinely manual step and are preserved.

Changes

  • Restructure both tutorials as a native-first Batch Forge walkthrough (Cloud + Enterprise latest).
  • Keep genuinely manual content: low-priority (spot) worker nodes and pre-existing/custom pools.
  • Remove the deprecated Nextflow autopool options; replace with a short deprecation note.
  • Add reference cross-links from compute-envs/azure-batch.md to the tutorial (previously only linked one way).

Versioned snapshots (24.2–26.1) left untouched.

🤖 Generated with Claude Code

Batch Forge now provisions most advanced Azure Batch topologies natively
(separate head/worker pools, dedicated head job resources, autoscaling,
Entra authentication, and private networking). The manual-setup tutorials
taught Nextflow-config workarounds that are now redundant, and the Nextflow
autopool option was misleading since Platform disables allowPoolCreation.

- Restructure both tutorials as a native-first Batch Forge walkthrough
- Keep genuinely manual content: low-priority (spot) worker nodes
  (Forge is dedicated-only) and pre-existing/custom pools
- Remove deprecated autopool options; replace with a deprecation note
- Add reference cross-links from compute-envs/azure-batch.md to the tutorial

Scope: cloud + enterprise latest only; versioned snapshots untouched.

Generated by Claude Code
@netlify

netlify Bot commented Jul 21, 2026

Copy link
Copy Markdown

Deploy Preview for seqera-docs ready!

Name Link
🔨 Latest commit adda104
🔍 Latest deploy log https://app.netlify.com/projects/seqera-docs/deploys/6a7f27f30943360008a41c48
😎 Deploy Preview https://deploy-preview-1674--seqera-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@justinegeffen

Copy link
Copy Markdown
Contributor

@claude please port this to the current versioned docs (26.1) as well

@claude

claude Bot commented Jul 21, 2026

Copy link
Copy Markdown

Claude finished @justinegeffen's task in 2m 50s —— View job


Porting Azure Batch tutorial to versioned docs (26.1)

  • Read the 26.1 versioned files and compare with the new master versions
  • Port manual-azure-batch-setup.md to version-26.1
  • Port azure-batch.md cross-link to version-26.1
  • Verify relative links resolve in the versioned tree
  • Commit and pushcommitted locally, but push denied (403)

I ported both changes to platform-enterprise_versioned_docs/version-26.1/, mirroring the master rewrite:

  • enterprise/advanced-topics/manual-azure-batch-setup.md — full native-first Batch Forge rewrite (Parts 1–4 + Advanced), matching the enterprise-latest version. Verified the versioned cross-link anchors resolve (#entra-service-principal-and-managed-identity at line 150, #create-a-nextflow-compatible-azure-batch-pool at line 394). I kept the versioned file's existing install-seqera-cli reference (https://docs.seqera.io/platform-cli/installation) rather than the root-relative form used in the unversioned file, consistent with the snapshot's conventions.
  • compute-envs/azure-batch.md — added the same :::tip cross-link to the walkthrough under Add compute environment.

Net: +60 / −328 across the two files. The changes are committed locally as 3c40718.

Warning

I could not push the commit. Every push attempt (both HEAD and the branch name, via the required git-push.sh wrapper) fails with:

remote: Permission to seqeralabs/docs.git denied to github-actions[bot].
fatal: ... error: 403

The github-actions[bot] token in this run doesn't have write access to the branch. This is a permissions/config issue outside what I can fix from here — the workflow needs permissions: contents: write (and, for PRs from the same repo, an appropriately scoped token). Once that's granted, re-trigger @claude and I'll push, or a maintainer can cherry-pick commit 3c40718.
docs/azure-batch-native-tutorial

justinegeffen and others added 2 commits July 22, 2026 10:49
Applies the same native-Batch-Forge rewrite to the versioned 26.1
snapshot so the current release surface matches master. Preserves
the versioned-tree convention of using an absolute URL for the
Seqera CLI installation link.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@justinegeffen
justinegeffen requested review from jonmarti and justinegeffen and removed request for jonmarti July 22, 2026 20:34
@justinegeffen justinegeffen added 1. Editor review Needs a language review 1. Dev/PM/SME Needs a review by a Dev/PM/SME deslop-to-do labels Jul 22, 2026
Comment thread platform-enterprise_docs/enterprise/advanced-topics/manual-azure-batch-setup.md Outdated
Comment thread platform-enterprise_docs/enterprise/advanced-topics/manual-azure-batch-setup.md Outdated
Comment thread platform-enterprise_docs/enterprise/advanced-topics/manual-azure-batch-setup.md Outdated
@jonmarti

Copy link
Copy Markdown
Contributor

Small self-correction on my review — I retracted my earlier comment about the head-pool Autoscale tip (it's now deleted). Turns out the compute-env form does expose a per-pool autoScale control in dual-pool mode (see compute-env-azure-platform.component.ts:271 on master), so the tutorial's tip about disabling Autoscale on the head pool via the UI is accurate as-is. Apologies for the noise — I'd validated against my memory from earlier in the year rather than current master. The other five comments still stand after re-checking the current codebase.

justinegeffen and others added 7 commits July 28, 2026 22:45
Signed-off-by: Justine Geffen <justinegeffen@users.noreply.github.com>
Clarify spot pool support, managed identity resource IDs,
head pool autoscaling, and VNet permissions.
Clarify required service principal roles and manual pool networking.
Move allocation-mode guidance to the manual pool section and align
Azure Batch links across tutorial variants.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1. Dev/PM/SME Needs a review by a Dev/PM/SME 1. Editor review Needs a language review deslop-to-do

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants