docs: update Testing on cloud section to use mage targets - #7592
Merged
ycombinator merged 9 commits intoAug 12, 2026
Merged
Conversation
The make -C dev-tools/cloud targets (cloud-deploy, cloud-clean, build-and-push-cloud-image) no longer exist — dev-tools/cloud contains only a terraform/ directory. Replace with the current mage-based workflow (test:cloudE2E and the individual docker:/test: targets) that CI actually uses.
Contributor
🔍 Preview links for changed docs |
Contributor
Elastic Docs Style Checker (Vale)Summary: 2 suggestions found 💡 Suggestions (2): Optional style improvements. Apply when helpful.
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. |
There was a problem hiding this comment.
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/cloudcommands withmage test:cloudE2Eand 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.
ycombinator
added
documentation
There was a problem hiding this comment.
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_TAGas optional overrides, but in the manual workflow they need to be set (or at leastDOCKER_IMAGE_TAG) sodocker:customAgentImage,docker:push, andtest:cloudE2EUpall refer to the same image; their defaults don’t align. It may also help to mention the CI-recommendedSNAPSHOT/PLATFORMSvalues 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, andPLATFORMS. Without setting these,docker:customAgentImagewill default to a local image name/tag (e.g.fleet-server-e2e-agent:git-...), whiledocker:push/test:cloudE2EUpdefault todocker.elastic.co/beats-ci/elastic-agent-cloud-fleet:<version>, so the pushed/deployed image won’t match what was built. On Apple Silicon, leavingPLATFORMSunset may also build anarm64image 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
enabled auto-merge (squash)
August 7, 2026 20:10
ycombinator
commented
Aug 7, 2026
ycombinator
left a comment
ycombinator
left a comment
Contributor
Author
There was a problem hiding this comment.
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.
- Fix ECH expansion: Elastic Cloud Hosted (ECH) - Add required SNAPSHOT, PLATFORMS, and DOCKER_IMAGE_TAG env vars to manual deploy example; explain why each is needed - Note that mage test:cloudE2E may leave a deployment running on failure and how to clean up
There was a problem hiding this comment.
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/amd64prevents producing anarm64image on Apple Silicon, butmage docker:customAgentImagehard-codes--platform linux/<host-arch>(seemagefile.go), soPLATFORMSonly affects the binary build (docker:cover), not the image architecture. The docs should clarify that the cloud workflow must run in anamd64environment 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:customAgentImagedefaults to tagging the image asfleet-server-e2e-agent:*, whilemage docker:pushandmage test:cloudE2EUpdefault todocker.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
macdewee
reviewed
Aug 10, 2026
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
docs/developers-guide.md:422
- Step 3 implies the push destination is always
docker.elastic.co/beats-ci/elastic-agent-cloud-fleet, butdocker:pushusesDOCKER_IMAGE/DOCKER_IMAGE_TAG(anddocker:customAgentImagedefaults to a local image name unlessDOCKER_IMAGEis set). Tweaking the wording here avoids misleading readers who changeDOCKER_IMAGE.
3. **`mage docker:push`** — pushes the custom image to the registry (`docker.elastic.co/beats-ci/elastic-agent-cloud-fleet`)
blakerouse
approved these changes
Aug 11, 2026
macdewee
approved these changes
Aug 12, 2026
Contributor
|
@Mergifyio backport 9.5 9.4 8.19 |
Contributor
✅ Backports have been createdDetails
|
This was referenced Aug 12, 2026
ycombinator
added a commit
that referenced
this pull request
Aug 12, 2026
) * docs: update Testing on cloud section to use mage targets The make -C dev-tools/cloud targets (cloud-deploy, cloud-clean, build-and-push-cloud-image) no longer exist — dev-tools/cloud contains only a terraform/ directory. Replace with the current mage-based workflow (test:cloudE2E and the individual docker:/test: targets) that CI actually uses. * docs: put manual deploy workflow first, cloudE2E is the CI target * docs: clarify that test:cloudE2E adds test:cloudE2ERun to the manual flow * docs: clarify when test:cloudE2ERun runs relative to up/down * docs: note CFT region is used for cloud E2E deployment (cherry picked from commit 5c894cd) Co-authored-by: Shaunak Kashyap <ycombinator@gmail.com>
ycombinator
added a commit
that referenced
this pull request
Aug 12, 2026
) * docs: update Testing on cloud section to use mage targets The make -C dev-tools/cloud targets (cloud-deploy, cloud-clean, build-and-push-cloud-image) no longer exist — dev-tools/cloud contains only a terraform/ directory. Replace with the current mage-based workflow (test:cloudE2E and the individual docker:/test: targets) that CI actually uses. * docs: put manual deploy workflow first, cloudE2E is the CI target * docs: clarify that test:cloudE2E adds test:cloudE2ERun to the manual flow * docs: clarify when test:cloudE2ERun runs relative to up/down * docs: note CFT region is used for cloud E2E deployment (cherry picked from commit 5c894cd) Co-authored-by: Shaunak Kashyap <ycombinator@gmail.com>
ycombinator
added a commit
that referenced
this pull request
Aug 12, 2026
) * docs: update Testing on cloud section to use mage targets The make -C dev-tools/cloud targets (cloud-deploy, cloud-clean, build-and-push-cloud-image) no longer exist — dev-tools/cloud contains only a terraform/ directory. Replace with the current mage-based workflow (test:cloudE2E and the individual docker:/test: targets) that CI actually uses. * docs: put manual deploy workflow first, cloudE2E is the CI target * docs: clarify that test:cloudE2E adds test:cloudE2ERun to the manual flow * docs: clarify when test:cloudE2ERun runs relative to up/down * docs: note CFT region is used for cloud E2E deployment (cherry picked from commit 5c894cd) Co-authored-by: Shaunak Kashyap <ycombinator@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the problem this PR solves?
The "Testing on cloud" section of the developer guide references
make -C dev-tools/cloudtargets (cloud-deploy,cloud-clean,build-and-push-cloud-image) that no longer exist —dev-tools/cloudcontains only aterraform/directory with no Makefile.How does this PR solve the problem?
Replaces the stale
makecommands with the current mage-based workflow that CI actually uses (via.buildkite/scripts/cloud_e2e_test.sh):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.mage test:cloudE2Eas the all-in-one CI target — equivalent to the manual steps withtest:cloudE2ERuninserted betweentest:cloudE2EUpandtest:cloudE2EDown.How to test this PR locally
No code changes — docs only.
Design Checklist
N/A — docs change only.
Checklist
Related issues