Skip to content

docs(orchestrator): consolidate duplicate guides and write How it works - #2588

Merged
marcus-souza-azion merged 2 commits into
mainfrom
docs/mm-16242-orchestrator-consolidate-how-it-works
Nov 12, 2026
Merged

marcus-souza-azion merged 2 commits into
mainfrom
docs/mm-16242-orchestrator-consolidate-how-it-works

Conversation

@bruno-andrade-azion

@bruno-andrade-azion bruno-andrade-azion commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

What & why

Related issue: MM-16242
Pages affected:

  • /en/documentation/platform/orchestrator/explore-usage/ · /pt-br/documentacao/plataforma/orchestrator/explore-uso/ (How it works, rewritten)
  • /en/documentation/platform/orchestrator/edge-node/ · /pt-br/documentacao/plataforma/orchestrator/edge-node/ (new Requirements section)
  • /en/documentation/platform/orchestrator/ · /pt-br/documentacao/plataforma/orchestrator/, and the Services reference pair (Implementation tables)
  • /en/documentation/guides/application-development/automation/authorize-an-edge-node/ · /pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/automacao/autorizar-edge-node/
  • /en/documentation/guides/application-development/automation/install-orchestrator-agent/ · /pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/automacao/instalar-orchestrator-agent/
  • Removed: the two Orchestrator "first steps" guides, in en and pt-br (redirected, see the checklist)

Duplicate guides retired. The Orchestrator "first steps" guides for nodes and services covered the same tasks as the deploy-journey guides, with steps that disagreed: key icon vs three dots, edge-orchestrator start vs sudo ./edge-orchestrator start, and root vs administrator. The Guides tree listed both sets, so the hub showed each task twice. Each retired URL now redirects to the guide that covers its task. The facts that existed only in the old guides moved to the pages that stay:

  • bulk authorization in Azion Console;
  • the HashId column, as the install guide's outcome;
  • the delay of up to 10 seconds, stated once for every authorization.

How it works rewritten as a concept page. The old page was a list of agent commands, and its meta tags had the typo "Azion Edge Orchireply". The new page covers:

  • the agent and the node;
  • authorization;
  • services, resources, variables, and facts;
  • the bind between a service and a node;
  • how the agent applies a manifest, with a Mermaid diagram;
  • the Watcher;
  • the two logs.

The facts come from the Services and Node references, the authorize, bind, and watch-logs guides, and the Orchestrator overviews. Where a source left a point open, the sentence was narrowed to what the source says. The permalink did not change.

Node requirements. The node reference gets a Requirements section: OS and architecture, privileges, service manager, personal token, and network. The agent command examples now use one form, sudo ./edge-orchestrator, as the install guide does. In the install guide, the download uses https://, and the contradictory log note is fixed.

How it was checked.

  • Rebased on main. The only conflicts were the four retired guides, where main had only applied the docs(style-guide): standardize Azion Console click paths #2596 click-path convention, so the deletion stands.
  • pnpm lint:navcheck passes.
  • The build-free link check of the changed pages reports 0 broken links, 0 cross-language links, and every namespace paired. The anchors #requirements, #requisitos, #variables, and #facts exist.
  • No page still links to a retired URL.
  • Not run: pnpm build:local, and the agent commands on a real machine.

Open questions for the Orchestrator SME. The pages state nothing about these three points until they are answered:

  1. Which outbound ports and hosts does the agent need? Requirements names only the network types the overview supports.
  2. Where does install copy the binary, and is edge-orchestrator on PATH afterward? Until that is answered, the examples run ./edge-orchestrator from the download directory.
  3. Is Add-On Services under Orchestration Modules a prerequisite for binding a service? The bind-service guide turns it on, and the retired guide skipped it. The concept page leaves it out until this is confirmed.

Out of scope, because each has its own task:

  • the "Edge Node" and "Edge Services" names (MM-16249);
  • the pt-br aside labels (MM-16255);
  • the trigger names in watch-logs;
  • the other untranslated aside label in the pt-br install guide (MM-16255).

Overlap with #2584 (MM-16233, the API version). #2584 removes the Console and API tabs from authorize-node and moves the API steps to a v3 page. This PR adds a sentence right after those tabs and a section after it, so whichever PR merges second needs a small rebase. For the same reason, this PR states no API behavior.

Type of change

  • 🆕 New content (feat)
  • 🩹 Fix (fix) — typo, broken link, wrong information
  • ♻️ Content update (docs) — rewrite, expansion, upkeep
  • 🌐 Translation sync (i18n)
  • 🏗️ Platform / structure (refactor / chore) — reviewed by UXE, no content mixed in

Author checklist

  • PR title follows type(scope): summary (see GOVERNANCE.md §4)
  • Frontmatter complete: title, description, meta_tags, namespace, permalink, last_reviewed — every changed page has the first five; last_reviewed is on no page of the corpus
  • No legacy "edge-" product names in the copy — the Console labels Edge Nodes and Edge Services and the term "edge node" remain; the rename is MM-16249
  • How-to/tutorial content includes at least one runnable, copy-paste-tested code block — the install and authorize guides carry their commands, but this PR did not run them
  • Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
  • Internal links are relative and resolve locally
  • If any permalink changed or page moved: redirect added in this PR — in apps/docs/redirects/en/01.json and apps/docs/redirects/pt-br/01.json, and the older rows that pointed at the retired URLs now point at the final targets, so no chain remains:
    • /en/documentation/guides/application-development/automation/edge-node-first-steps/ → /en/documentation/guides/application-development/automation/install-orchestrator-agent/
    • /en/documentation/guides/application-development/automation/edge-services-first-steps/ → /en/documentation/guides/application-development/automation/create-edge-service/
    • /pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/automacao/edge-node-primeiros-passos/ → /pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/automacao/instalar-orchestrator-agent/
    • /pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/automacao/criando-edge-service/ → /pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/automacao/criar-edge-service/
  • i18n: pt-br updated in this PR or follow-up i18n issue created — pt-br updated in this PR
  • I ran pnpm build:local (build + frontmatter check) without errors — not run in this review

egermano and others added 2 commits November 12, 2026 15:28
- Retire the two first-steps guides (en and pt-br) that duplicated the
  deploy-journey guides with diverging steps, and redirect them to the
  install and create-service guides. Rechain older redirects that pointed
  at the retired URLs.
- Carry the only content they had that the current guides lacked: bulk
  authorization, the HashId column and the 10-second delay.
- Rewrite the How it works page as a concept page: agent and node,
  authorization, services and resources, binds, manifests, the Watcher,
  and logs.
- Add a Requirements section to the node reference, and use one form for
  the agent commands.
- Use HTTPS for the agent download and fix the contradictory log note.

Refs: MM-16242
…solidated pages

- How it works: drop the unsourced authorization rationale, scope the
  Watcher sentence to the service and its binds, rebuild the manifest
  diagram with a legend and numbered steps, link variables and facts
  separately, rename the gerund heading, and trim the descriptions.
- Authorize node: state the 10-second delay for every authorization,
  and use the canonical click path and select verbs in the bulk section.
- Install guide: add the outcome (Edge Nodes list, Waiting
  Authorization, HashId) that the retired first-steps guide carried.
- Overview: replace "Learn more" phrasing; translate the pt-br scope cells.
@marcus-souza-azion
marcus-souza-azion force-pushed the docs/mm-16242-orchestrator-consolidate-how-it-works branch from 99dd89a to 1016041 Compare November 12, 2026 18:28
@marcus-souza-azion
marcus-souza-azion merged commit bf03fc7 into main Nov 12, 2026
9 checks passed
@marcus-souza-azion
marcus-souza-azion deleted the docs/mm-16242-orchestrator-consolidate-how-it-works branch November 12, 2026 18:33
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (48 commits)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  docs(observe): fix dataset name, Data Stream filter, and Grafana Data path (#2573)
  fix(fundamentals): rewrite the Load Balancer steps in minimize-downtime from the reference (#2578)
  i18n(pt-br): label unlabelled asides and fix label casing (#2622)
  fix(links): point pt-br links to their existing pt-br pages (#2620)
  i18n(pt-br): resync the drifted release notes, punctuation, and Edge Services pairs (#2624)
  i18n(pt-br): pair three pages with their English versions by namespace (#2625)
  docs(style-guide): adopt the jsonl tag for JSON Lines samples (#2642)
  chore(lint): check the changelog entries a PR adds (#2634)
  [NO-ISSUE] ci: replace technote-space/assign-author (SO-5131) (#2591)
  fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags (#2629)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/billing.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/teams-permissions.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/faturamento.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/teams-permissions.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
Resolve the 16 conflicts in the current Orchestrator how-tos: keep the
PR's Console-only layout with main's Console steps (#2596) and the
authorize additions from #2588.

Rebuild the 16 -v3 pages from main's version of each page, so they carry
the Console click paths (#2596), the #2574 review fixes, the pt-br link
and aside fixes (#2620, #2622), and the authorize additions (#2588).

Also apply the PR review:
- en create-service: move the active-service note out of the step list
  and drop its contractions
- en descriptions: start with the verb instead of "Learn how to"
- pt-br run-scripts: replace the "borda" DocButton labels

Refs MM-16233
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
* origin/main: (58 commits)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  ...
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
…nce-soc-pci

* origin/main: (59 commits)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/compliance/pci-dss.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/compliance/soc-2.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/compliance/pci-dss.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/compliance/soc.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
* origin/main: (59 commits)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  ...

# Conflicts:
#	apps/docs/redirects/en/01.json
#	apps/docs/redirects/pt-br/01.json
#	apps/docs/src/content/docs/en/homes/architctures/by-use-case/application-and-network-security.mdx
#	apps/docs/src/content/docs/pt-br/homes/arquiteturas/por-solucao/seguranca-de-aplicacoes-e-redes.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
…ts-formatting

* origin/main: (55 commits)
  docs(architectures): keep security-modernization and bot-management as API v3 versions (#2589)
  fix(runtime): clean up unused imports and JSDoc in the Node.js API samples (#2649)
  docs(platform): retire the v3 build and deploy journey pages (#2587)
  fix(compliance): correct the SOC report cadence and PCI DSS version (#2585)
  docs(runtime): fix the azion dev port and the function size limit (#2583)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/agreements/faqs/faqs-index.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
…uide-coherence

* origin/main: (56 commits)
  docs(architectures): keep security-modernization and bot-management as API v3 versions (#2589)
  fix(runtime): clean up unused imports and JSDoc in the Node.js API samples (#2649)
  docs(platform): retire the v3 build and deploy journey pages (#2587)
  fix(compliance): correct the SOC report cadence and PCI DSS version (#2585)
  docs(runtime): fix the azion dev port and the function size limit (#2583)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/style-guide/content/information-architecture.mdx
#	apps/docs/src/content/docs/en/pages/style-guide/content/navigation-hubs.mdx
#	apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/arquitetura-de-informacao.mdx
#	apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/conteudo/hubs-de-navegacao.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
…inks-use-case-closing

* origin/main: (55 commits)
  docs(architectures): keep security-modernization and bot-management as API v3 versions (#2589)
  fix(runtime): clean up unused imports and JSDoc in the Node.js API samples (#2649)
  docs(platform): retire the v3 build and deploy journey pages (#2587)
  fix(compliance): correct the SOC report cadence and PCI DSS version (#2585)
  docs(runtime): fix the azion dev port and the function size limit (#2583)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants