elastic / elastic/docs-builder

[Feature Request]: Generate the air-gapped artifact list from the Elastic artifacts API

Open
#3,896 0 comments 0 reactions 0 assignees View on GitHub
needs triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.