Skip to content

Commit 722cccb

Browse files
pjiang-devpjiang-dev
committed
docs: add docs on appset ui
Signed-off-by: Peter Jiang <peterjiang823@gmail.com>
1 parent 0dc4f57 commit 722cccb

3 files changed

Lines changed: 215 additions & 0 deletions

File tree

‎docs/operator-manual/applicationset/Web-UI.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# ApplicationSet Web UI
2+
3+
> [!CAUTION]
4+
> The ApplicationSet Web UI is **Alpha** as of Argo CD v3.5.0. The look,
5+
> behavior, and APIs it consumes may change in future releases. See
6+
> [Feature Maturity](../feature-maturity.md) for details.
7+
8+
Argo CD v3.5.0 introduces a first-class Web UI for ApplicationSets. Until
9+
now, ApplicationSets were managed primarily through `kubectl`, the
10+
`argocd appset` CLI, or by browsing the generated child Applications. The
11+
new UI surfaces ApplicationSets directly, with a list view, a resource
12+
tree, a slide-out details panel, and a preview tab that lets you see what
13+
Applications an ApplicationSet will generate.
14+
15+
## ApplicationSets list page
16+
17+
The new `/applicationsets` page is the entry point. It lives next to the
18+
existing Applications list and shares the same filtering, search, and
19+
view-preferences, so it should feel familiar.
20+
21+
You can reach it from the top-level navigation, or directly at
22+
`https://<your-argocd>/applicationsets`.
23+
24+
![ApplicationSets list page](../../assets/applicationset/Web-UI/01-applicationsets-list.png)
25+
26+
What's on the page:
27+
28+
- **Search bar** — fuzzy-matches against name and namespace. Use the
29+
keyboard shortcut `/` to focus it.
30+
- **Filters sidebar** — filter by project, namespace, labels, and
31+
ApplicationSet health status (`Healthy`, `Progressing`, `Degraded`,
32+
`Unknown`). Filters are reflected in the URL so they can be shared or
33+
bookmarked.
34+
- **Health summary** — a pie chart at the top summarizes the health of
35+
ApplicationSets matching the current filter.
36+
- **Tile / table views** — toggle between a tile grid and a table view.
37+
The table view shows name, namespace, project, health, conditions, and
38+
the number of generated Applications.
39+
40+
> [!TIP]
41+
> The page shows ApplicationSets across every namespace your user has
42+
> access to. RBAC is enforced exactly as on the CLI — if you can `get` an
43+
> ApplicationSet from `argocd appset get`, you can see it here.
44+
45+
## ApplicationSet resource tree
46+
47+
Selecting an ApplicationSet from the list opens its details page. The
48+
center of the page is a **resource tree** that visualizes the
49+
ApplicationSet and the child Applications it generates.
50+
51+
![ApplicationSet resource tree](../../assets/applicationset/Web-UI/02-appset-resource-tree.png)
52+
53+
Things to know:
54+
55+
- The root node is the ApplicationSet itself. Each downstream node is a
56+
child Application generated by the ApplicationSet.
57+
- Health and sync status icons render on each node the same way they do
58+
on the Application resource tree.
59+
- Clicking a child Application navigates to that Application's own
60+
details page.
61+
62+
## Slide-out panel: Summary, Manifest, Events, Preview
63+
64+
Clicking the ApplicationSet node (or any node on the tree) opens a
65+
slide-out panel from the right edge of the screen — the same pattern used
66+
elsewhere in Argo CD for resource details.
67+
68+
The panel has four tabs.
69+
70+
### Summary
71+
72+
Shows metadata at a glance: name, namespace, creation timestamp,
73+
health, conditions, labels, annotations, and sync policy.
74+
75+
![Summary tab](../../assets/applicationset/Web-UI/03-summary-tab.png)
76+
77+
If the ApplicationSet has conditions, the **CONDITIONS** row links to a
78+
detailed conditions view so you can see warnings or errors raised by the
79+
controller (for example, a generator that failed to evaluate).
80+
81+
### Manifest
82+
83+
A read-only YAML view of the ApplicationSet's `spec`.
84+
85+
![Manifest tab](../../assets/applicationset/Web-UI/04-manifest-tab.png)
86+
87+
### Events
88+
89+
Kubernetes events for the ApplicationSet — useful when investigating why
90+
a particular generator parameter set produced (or failed to produce) an
91+
Application.
92+
93+
![Events tab](../../assets/applicationset/Web-UI/05-events-tab.png)
94+
95+
### Preview
96+
97+
The Preview tab is the most significant new capability. It is covered in
98+
detail in the next section.
99+
100+
## Preview: see what your ApplicationSet will generate
101+
102+
The **PREVIEW** tab mirrors the `argocd appset generate` CLI command in
103+
the browser. It shows you the Applications an ApplicationSet would
104+
generate right now. When you edit the spec a diff between the
105+
proposed output and what is currently live.
106+
107+
![Preview tab — initial view](../../assets/applicationset/Web-UI/06-preview-initial.png)
108+
109+
### How it works
110+
111+
The Preview tab calls the existing
112+
`POST /api/v1/applicationsets/generate` endpoint, which the controller
113+
uses to render template output without persisting anything to the
114+
cluster.
115+
116+
The result is rendered in three sub-tabs:
117+
118+
| Tab | Shows |
119+
|----------------|--------------------------------------------------------------------------------|
120+
| `DIFF` | The default tab. A unified diff of each Application that would change. |
121+
| `LIVE APPS` | The Applications currently generated by the ApplicationSet on the cluster. |
122+
| `DESIRED APPS` | The Applications that *would* be generated if the proposed spec were applied. |
123+
124+
![Preview tab — diff view](../../assets/applicationset/Web-UI/07-preview-diff.png)
125+
126+
Each entry in `DIFF` represents one child Application and is categorized
127+
as added (only in `DESIRED APPS`), removed (only in `LIVE APPS`), or
128+
modified (present in both with field-level differences).
129+
130+
### Editing the spec
131+
132+
Click **Edit** on the ApplicationSet manifest card to make the YAML
133+
editable. Hit **Preview** again and the diff regenerates against your
134+
edits. Click **Cancel** to discard local edits.
135+
136+
![Preview tab — editing the spec](../../assets/applicationset/Web-UI/08-preview-edit.png)
137+
138+
> [!IMPORTANT]
139+
> Edits in the Preview tab are **never saved**. The tab is a sandbox; to
140+
> persist a change you must update the ApplicationSet through your normal
141+
> GitOps flow (or via `kubectl apply` / `argocd appset create`).
142+
143+
### Permissions
144+
145+
Generating a preview requires `applicationsets, create` permission on
146+
the project of the ApplicationSet's template. If you don't have it, the
147+
Preview tab returns a clear permission-denied message instead of a diff.
148+
149+
## Changes to Applications generated by an ApplicationSet
150+
151+
For Applications that are generated by an ApplicationSet (i.e. that have
152+
an `ApplicationSet` `ownerReference`), the Application UI now shows two
153+
new things on the resource tree.
154+
155+
### Owner badge
156+
157+
A small badge labeled with the parent ApplicationSet's name
158+
appears on the Application node. Clicking it jumps directly to the
159+
ApplicationSet details page.
160+
161+
![ApplicationSet owner badge on an Application](../../assets/applicationset/Web-UI/09-appset-owner-badge.png)
162+
163+
### Show / hide parent ApplicationSet
164+
165+
In the Application's view preferences, a new toggle —
166+
**Show parent ApplicationSet** — adds the parent ApplicationSet as a
167+
synthetic root node on the resource tree, with an edge to the
168+
Application. This is useful when you want a single view that includes
169+
both the ApplicationSet and the Application it produced.
170+
171+
![Toggling Show parent ApplicationSet](../../assets/applicationset/Web-UI/10-show-parent-toggle.png)
172+
173+
When the toggle is on, the badge is hidden (since the parent is already
174+
rendered explicitly).
175+
176+
### Per-Application preview from the app-of-appset pattern
177+
178+
When you use the
179+
[app-of-ApplicationSets pattern](Use-Cases.md) — an Application whose
180+
resources include an ApplicationSet — the ApplicationSet node on the
181+
parent Application's tree now includes a preview feature in its slide-out
182+
panel. Selecting it opens a panel with a **Preview** experience similar
183+
to the one described above, scoped to the changes that would land when
184+
you sync the parent Application.
185+
186+
![App-of-AppSet preview](../../assets/applicationset/Web-UI/11-app-of-appset-preview.png)
187+
188+
There are two important differences from the standalone Preview tab:
189+
190+
- **Desired state comes from Git, not an editor.** The proposed
191+
ApplicationSet is the target manifest tracked by the parent
192+
Application (i.e. what's in Git). There is no YAML editor in this panel.
193+
- **Only available when the ApplicationSet is OutOfSync.** If the parent
194+
Application's ApplicationSet resource is already in sync, there is no
195+
diff to show — the panel renders a short status message instead.
196+
197+
This is the bridge between "I have a pending sync on my parent
198+
Application" and "show me which child Applications would change as a
199+
result."
200+
201+
## Known limitations
202+
203+
- The Preview tab compares whole Application manifests. It does **not**
204+
recurse into the Kubernetes resources inside each child Application —
205+
for that, sync the child Application and use the existing Application
206+
diff view.
207+
- Generators that depend on external systems (Git, SCM Provider, Pull
208+
Request, Cluster) are re-evaluated each time you click **Preview**. If
209+
the upstream system is slow or flaky, the preview will reflect that.
210+
- The UI honors ApplicationSet RBAC. Users who cannot `create`
211+
ApplicationSets in the target project will not be able to render a
212+
preview, even if they can `get` the ApplicationSet.

‎docs/operator-manual/feature-maturity.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ to indicate their stability and maturity. These are the statuses of non-stable f
2525
| [Cluster Sharding: consistent-hashing][9] | v2.12.0 | Alpha |
2626
| [Service Account Impersonation][10] | v2.13.0 | Beta |
2727
| [Source Hydrator][11] | v2.14.0 | Alpha |
28+
| [ApplicationSet Web UI][12] | v3.5.0 | Alpha |
2829

2930
## Unstable Configurations
3031

@@ -73,3 +74,4 @@ to indicate their stability and maturity. These are the statuses of non-stable f
7374
[9]: ./high_availability.md#argocd-application-controller
7475
[10]: app-sync-using-impersonation.md
7576
[11]: ../user-guide/source-hydrator.md
77+
[12]: applicationset/Web-UI.md

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ nav:
129129
- Git File Generator Globbing: operator-manual/applicationset/Generators-Git-File-Globbing.md
130130
- ApplicationSet Specification Reference: operator-manual/applicationset/applicationset-specification.md
131131
- ApplicationSet in any namespace: operator-manual/applicationset/Appset-Any-Namespace.md
132+
- ApplicationSet Web UI: operator-manual/applicationset/Web-UI.md
132133
- Server Configuration Parameters:
133134
- operator-manual/server-commands/argocd-server.md
134135
- operator-manual/server-commands/argocd-application-controller.md

0 commit comments

Comments
 (0)