docs: update Testing on cloud section to use mage targets

[ycombinator]

What is the problem this PR solves?

The "Testing on cloud" section of the developer guide references make -C dev-tools/cloud targets (cloud-deploy, cloud-clean, build-and-push-cloud-image) that no longer exist — dev-tools/cloud contains only a terraform/ directory with no Makefile.

How does this PR solve the problem?

Replaces the stale make commands with the current mage-based workflow that CI actually uses (via .buildkite/scripts/cloud_e2e_test.sh):

• Documents the manual deploy workflow (docker:cover, docker:customAgentImage, docker:push, test:cloudE2EUp, test:cloudE2EDown) as the primary path for developers who want a live ECH deployment for manual testing.
• Documents mage test:cloudE2E as the all-in-one CI target — equivalent to the manual steps with test:cloudE2ERun inserted between test:cloudE2EUp and test:cloudE2EDown.

How to test this PR locally

No code changes — docs only.

Design Checklist

N/A — docs change only.

Checklist

• I have made corresponding changes to the documentation

Related issues

[github-actions]

🔍 Preview links for changed docs

• docs/developers-guide.md

[github-actions]

Elastic Docs Style Checker (Vale)

Summary: 1 suggestion found

💡 Suggestions (1): Optional style improvements. Apply when helpful.

File	Line	Rule	Message
docs/developers-guide.md	432	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.

---

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

[Copilot]

Pull request overview

Updates the “Testing on cloud” developer documentation to reflect the current CI-supported mage workflow (instead of removed make -C dev-tools/cloud targets), aligning local instructions with how cloud E2E is run in Buildkite.

Changes:

• Replace obsolete make -C dev-tools/cloud commands with mage test:cloudE2E and its underlying steps.
• Document the end-to-end mage shortcut and the individual “up/run/down” targets for manual operation.
• Add notes about Docker image overrides for cloud deployments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[blakerouse]

Looks good.

[Copilot]

Pull request overview

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

Suppressed comments (3)

docs/developers-guide.md:421

• This sentence frames DOCKER_IMAGE/DOCKER_IMAGE_TAG as optional overrides, but in the manual workflow they need to be set (or at least DOCKER_IMAGE_TAG) so docker:customAgentImage, docker:push, and test:cloudE2EUp all refer to the same image; their defaults don’t align. It may also help to mention the CI-recommended SNAPSHOT/PLATFORMS values here since they affect the produced image/arch.

The `DOCKER_IMAGE` and `DOCKER_IMAGE_TAG` environment variables can be used to override the image name and tag. Run `mage -h test:cloudE2EUp` for all available options.

docs/developers-guide.md:411

• The manual workflow example omits DOCKER_IMAGE, DOCKER_IMAGE_TAG, and PLATFORMS. Without setting these, docker:customAgentImage will default to a local image name/tag (e.g. fleet-server-e2e-agent:git-...), while docker:push/test:cloudE2EUp default to docker.elastic.co/beats-ci/elastic-agent-cloud-fleet:<version>, so the pushed/deployed image won’t match what was built. On Apple Silicon, leaving PLATFORMS unset may also build an arm64 image that won’t run in ECH.

This issue also appears on line 421 of the same file.

```bash
EC_API_KEY=yourapikey mage docker:cover docker:customAgentImage docker:push test:cloudE2EUp
# ... manual testing ...
EC_API_KEY=yourapikey mage test:cloudE2EDown

**docs/developers-guide.md:403**
* ECH is an acronym for “Elastic Cloud Hosted”, so “Elastic Cloud (ECH)” is a mismatched expansion. Updating the wording avoids confusion for readers unfamiliar with the acronym.

Elastic employees can create an Elastic Cloud (ECH) deployment with a locally built Fleet Server.

</details>

[ycombinator]

Addressed in the latest commit — clarified that DOCKER_IMAGE/DOCKER_IMAGE_TAG overrides apply only when running the individual targets, and that mage test:cloudE2E sets these variables internally so external overrides have no effect on the all-in-one target.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Suppressed comments (2)

docs/developers-guide.md:414

• This sentence implies PLATFORMS=linux/amd64 prevents producing an arm64 image on Apple Silicon, but mage docker:customAgentImage hard-codes --platform linux/<host-arch> (see magefile.go), so PLATFORMS only affects the binary build (docker:cover), not the image architecture. The docs should clarify that the cloud workflow must run in an amd64 environment for ECH.

`SNAPSHOT=true` and `PLATFORMS=linux/amd64` are required — ECH runs on `linux/amd64`, so omitting `PLATFORMS` on Apple Silicon will produce an `arm64` image that won't run in the deployment. Setting a consistent `DOCKER_IMAGE_TAG` ensures that `docker:customAgentImage`, `docker:push`, and `test:cloudE2EUp`/`test:cloudE2EDown` all refer to the same image.

docs/developers-guide.md:411

• The example command is missing DOCKER_IMAGE=.... Without it, mage docker:customAgentImage defaults to tagging the image as fleet-server-e2e-agent:*, while mage docker:push and mage test:cloudE2EUp default to docker.elastic.co/beats-ci/elastic-agent-cloud-fleet:*, so the push/deploy steps won't reference the image that was built.

This issue also appears on line 414 of the same file.

SNAPSHOT=true PLATFORMS=linux/amd64 DOCKER_IMAGE_TAG=my-custom-tag \
  EC_API_KEY=yourapikey mage docker:cover docker:customAgentImage docker:push test:cloudE2EUp
# ... manual testing ...
DOCKER_IMAGE_TAG=my-custom-tag EC_API_KEY=yourapikey mage test:cloudE2EDown