elastic / elastic/docs-builder
[Feature Request]: Generate the air-gapped artifact list from the Elastic artifacts API
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
### Prerequisites
- [x] I have searched existing issues to ensure this feature hasn't already been requested
### What problem are you trying to solve?
The [Host your own artifact registry for binary downloads](https://www.elastic.co/docs/reference/fleet/air-gapped#host-artifact-registry) guide tells air-gapped users to mirror Elastic binaries onto their own file server. To do that, they need to know every artifact that exists for a given release.
The docs don't tell them. The existing docs list ~14 `curl` commands, but all are for `linux-x86_64` `.tar.gz` only. It then says "you may replace x86_64 with arm64" and "the exact list depends on which integrations you're using." There's no way to know which components ship for Windows, macOS, `.deb`, or `.rpm`. Not every component ships for every platform, and there's no published list of which combinations exist.
Our users are having problems with this, so a support engineer (s/o @jeanfabrice) wrote a shell script to work around this problem (see: https://github.com/elastic/docs-content/issues/1821).
As the list of artifacts changes by release and depending on integrations used, we can't accurately document a list in the docs.
### Proposed Solution
Generate the list. `https://artifacts-api.elastic.co/v1/versions/{version}/builds/latest/projects/{project}` returns every package for a project, with the filename, package type, architecture, OS, and the sha512 and `.asc` URLs.
1. A script queries the artifacts API for each supported release.
2. It filters down to the components an air-gapped Elastic Agent deployment needs.
3. It writes a CSV or YAML file into `docs-content`, and opens a PR so a human reviews the diff.
4. The air-gapped page renders it with `{csv-include}`, or with a small purpose-built directive if the CSV table isn't good enough on its own.
### Additional Context
Some things to look into when this gets prioritized:
- Same problem likely applies to the [Elastic Endpoint Artifact Repository](https://www.elastic.co/docs/deploy-manage/deploy/self-managed/air-gapped-install#air-gapped-elastic-endpoint-artifact-repository) section, which points users at the same mirroring pattern with different artifacts.
- There's a second, partially overlapping artifact script in [`air-gapped-install.md`](https://www.elastic.co/docs/deploy-manage/deploy/self-managed/air-gapped-install#air-gapped-elastic-artifact-registry) with a different component list than the one on the Fleet page.
### How important is this feature to you?
Important
Contributor guide
Research direction
Start with the air-gapped Fleet page and air-gapped-install.md, then inspect the artifacts API response for the release and project combinations involved. Define the supported component filter and generated CSV or YAML shape, and verify that the rendered documentation covers the required platform packages and URLs through a reviewed PR.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- shell
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100