github.com/argoproj/argo-cd/v3@v3.2.1/docs/proposals/multiple-sources-for-applications-ui.md (about)

     1  ---
     2  title: Proposal for support multi-source apps in the UI
     3  authors:
     4    - "@keithchong"
     5  sponsors:
     6    - TBD
     7  reviewers:
     8    - "@alexmt"
     9    - "@crenshaw-dev"
    10    - "@ishitasequeira" 
    11    - "@jannfis"
    12    - "@rbreeze"
    13  approvers:
    14    - "@jannfis"
    15    - "@alexmt"
    16    - "@crenshaw-dev"
    17  
    18  creation-date: 2024-02-06
    19  last-updated: 2024-02-06
    20  ---
    21  
    22  # UI Support for Multiple Sources in Applications
    23  
    24  This is the proposal for the UI changes to support multiple sources for an Application.
    25  
    26  Related Issues:
    27  * [Proposal: Support multiple sources for an application](https://github.com/argoproj/argo-cd/blob/master/docs/proposals/multiple-sources-for-applications.md)
    28  * [Issue for the Proposal: Support multiple sources for an application](https://github.com/argoproj/argo-cd/issues/677)
    29  
    30  ## Summary
    31  
    32  This is a follow-on proposal to supporting Multiple Sources for Applications, but for the UI.
    33  
    34  The above [original](https://github.com/argoproj/argo-cd/blob/master/docs/proposals/multiple-sources-for-applications.md#changes-to-ui) ‘core’ proposal deferred
    35  any design changes for the UI to a separate feature or secondary proposal. The proposal implementation that was made in [PR 10432](https://github.com/argoproj/argo-cd/pull/10432) 
    36  enabled the UI to tolerate multi-source applications with the new Sources field, while still supporting the original Source field. 
    37  
    38  Here are the current restrictions and limitations of the UI when applications with multiple sources are used:
    39  
    40  1. The application’s details page (for [example](https://cd.apps.argoproj.io/applications/argocd/guestbook?view=tree&node=argoproj.io%2FApplication%2Fargocd%2Fguestbook%2F0&resource=)) 
    41  currently shows one ApplicationSource, regardless of whether the application has one source or multiple sources. With the PR 10432 implementation, if the application has multiple sources,
    42  the UI displays only the first of the sources. Also, in particular, in the Summary tab, the source parameters are non-editable. 
    43  
    44  2. History and Rollback is disabled for multi-source applications. The button is disabled. Jorge has submitted a PR for 
    45  rollback which includes [controller and UI changes](https://github.com/argoproj/argo-cd/pull/14124).
    46  
    47     <img height="40%" width="40%" src="images/history-and-rollback-button.png"/>
    48  
    49  3. The New Application dialog currently only allows users to provide one source.
    50  
    51  Thus, multiple source applications are not considered first class citizens in the UI.
    52  
    53  Note, see the [Open Questions](https://github.com/argoproj/argo-cd/docs/proposals/multiple-sources-for-applications-ui.md#open-questions) 
    54  section for concerns regarding the priority or value of some of the above changes.
    55  
    56  ## Motivation
    57  
    58  The motivation behind this change is to add a more complete story for the multiple source feature. The UI should support 
    59  the creation of multiple source applications, and also support the viewing and editing of parameters from all sources. The three
    60  points in the summary above are the base or core changes that need to be addressed.
    61  
    62  ### Goals
    63  
    64  The goals of the proposal are:
    65  
    66  - Provide first-class support of multiple sources for applications in the UI (e.g. address the aforementioned restrictions)
    67  - Outline stages of implementation that will help ease PR review, and reduce the risk of introducing regressions/issues.
    68  
    69  
    70  ### Non-goals
    71  * The design changes for the Argo CD CLI is beyond the scope of this proposal (The server APIs can probably be reused)
    72  
    73  ## Proposal
    74  
    75  As mentioned in the previous summary section, the application source parameters are surfaced in the UI in three locations.
    76  The Resource details pages, specifically, the Summary and Parameters tabs, the deployment history, and the Application
    77  Create panel page. These pages should be updated.
    78  
    79  ### Resource Details
    80  
    81  The following describes the current behavior and proposed changes for the Summary tab and the Parameters Tab.
    82  
    83  #### i) Summary Tab
    84  
    85  _Current Behavior:_ 
    86  
    87  The current Summary tab includes source-related information, including the repository. For example, in Figure 1 below,
    88  the REPO URL and PATH.
    89  
    90  <img height="50%" width="50%" src="images/current-summary-tab.png"/>
    91  
    92  Figure 1: The current Summary tab
    93  
    94  _Proposed Change:_
    95  
    96  To support multiple sources, the source-related information, from a single-source-based design, will be ‘pulled out’ 
    97  and put into a new tab called **Sources**, and it will be combined with the **Parameters** tab (more details following). 
    98  The new **Sources** tab will allow users to view all the information related to each source, including the repo URL 
    99  and path, chart and revision for Helm, etc. 
   100  
   101  The view should show one source at a time (similar to what the UI is doing now, which only shows one source), but with 
   102  widgets to allow users to cycle (via pagination or combo selector?) through each source. There are API calls to retrieve 
   103  the data for each source.
   104  
   105  <img height="50%" width="50%" src="images/new-sources-tab.png"/>
   106  
   107  Figure 2. The new SOURCES tab will allow access to view all sources and application parameters.
   108  
   109  #### ii) Parameters Tab
   110  _Current Behavior:_ 
   111  
   112  The Parameters tab shows the application parameters for the application’s repository details type or source. These can 
   113  be Helm, Kustomize, Directory or Plugin (CMP).
   114  
   115  _Proposed Change:_
   116  
   117  The Parameter tab will be removed but the contents of the current parameters tab will be ‘reused’ and will be shown in 
   118  the new **SOURCES** tab as described above. The parameters and parameter values will be shown for whatever source is 
   119  selected by the user.
   120  
   121  #### iii) Update/Edit Capability in the New Sources Tab
   122  
   123  The above points describe how all the sources will be rendered.  However, the Sources tab should be the page to allow 
   124  users to delete and add sources. (You can currently change the repo URL and path from the Summary tab, or manually edit 
   125  the application by hand, in the Manifest tab, but this is not considered as ‘guided’ editing.)
   126  
   127  _Current Behavior:_ 
   128  
   129  The current form-based UI doesn’t support deleting a chosen/desired source of a multi-source application. It,
   130  obviously, does not support deleting the only source in a single-source application.
   131  
   132  _Proposed Change:_
   133  
   134  In addition to adding the new SOURCES tab from section i) and ii), two new buttons (_Add Source_ and _Delete Source_) will 
   135  be added to the page. For the _Add Source_ button, a separate dialog/panel will need to appear to allow the user to
   136  input the parameters or other information.
   137  
   138  Validation of any newly added source should prevent users from adding the same resource, and prevent users from
   139  deleting all sources, etc.
   140  
   141  ### History and Rollback
   142  
   143  Current Behavior: The History and Rollback button for multi-source apps is disabled. It's only enabled
   144  for single-source apps, and shows source information as shown in Figure 3.
   145  
   146  <img height="50%" width="50%" src="images/history-rollback-contents.png"/>
   147  
   148  Figure 3: Source information in History
   149  
   150  Jorge has submitted a [PR](https://github.com/argoproj/argo-cd/pull/14124) for rollback which includes controller and UI changes. 
   151  This can be treated as a separate, independent proposal.
   152  
   153  Other related changes pertain to the Last Synced Details. The Sync Details panel needs to be updated to show sync info
   154  from multiple sources.  See [Issue 13215](https://github.com/argoproj/argo-cd/issues/13215).
   155  
   156  ### New App Dialog
   157  
   158  _Current Behavior:_ 
   159  
   160  The dialog currently allows users to ‘quickly’ create a single source application..
   161  
   162  _Proposed Changes:_
   163  
   164  Make the form view of the dialog support adding, updating and viewing of multiple sources. The issue with the current 
   165  single source New App wizard is that it can lead to loss of “input” provided by the user. The content in the form-based 
   166  editor and the YAML editor (accessed via the Edit as YAML button) must match. If the user provides multiple sources in 
   167  the YAML editor, and then switches back to the form view, the form will only show the first source. The other sources 
   168  are effectively ‘lost’. Furthermore, if the user switches back to the YAML editor, only one source will be shown as well.
   169  
   170  The design and changes (React components) from the new Sources tab can likely be reused in this dialog.
   171  
   172  Other Changes. This includes the underlying plumbing to create an app using the Sources field of the Application CR, so that the 
   173  deprecated Source field can be removed in the future.
   174  
   175  
   176  
   177  ### Use cases
   178  
   179  The use cases involves those areas in the UI where the current source is displayed. These have been described
   180  in the Summary and Proposal sections.
   181  
   182  
   183  ### Implementation Details
   184  
   185  The implementation plan can be divided into different stages. Read-only capability can be provided first and it will 
   186  be the safest change. The UI currently is not showing all the sources for the multi-source application so this should 
   187  be the highest priority. (Before you can edit, you have to first display it.)
   188  
   189  Here are the general enhancements to be implemented (Upstream issues to be opened if not already):
   190  
   191  1. Create new Sources tab to replace Parameters tab so that all sources can be displayed (Read-only)
   192  2. Update History and Rollback to show a summary of all sources of an application
   193     As mentioned above, this is already covered by Jorge’s [PR](https://github.com/argoproj/argo-cd/pull/14124)
   194  3. Add _Add Source_ and _Delete Source_ buttons to Sources tab. This will depend on #1 above. (Update and Delete)
   195  4. Update New App dialog. (Creation)
   196     - Support adding multiple sources in New App dialog. (This will likely depend on the Components from #1 and #3)
   197     - Use Sources field instead of Source field. Clean up code.
   198  
   199  ### Security Considerations
   200  None
   201  
   202  ### Risks and Mitigations
   203  None
   204  
   205  ### Upgrade / Downgrade Strategy
   206  If downgraded, the UI will revert to showing just the first source.
   207  
   208  ## Drawbacks
   209  None
   210  
   211  ## Open Questions
   212  
   213  Supporting multiple sources in the New App dialog may not be ‘worth’ the effort? The drawback is that switching from the 
   214  YAML editor and form editor can lead to loss of information.
   215  
   216  Users can simply edit the application manifest to add their sources by hand.
   217  
   218  
   219  ## Appendix
   220  Multiple sources can be shown as a list of collapsible cards or sections, one below the other, under one page of the
   221  SOURCES tab. However, this can be cumbersome especially when a source, like Helm, has many source parameters.
   222  so it'll be difficult to find the desired source. Perhaps showing one source per page  will be better.
   223  
   224  Appendix Figure 1: Zoomed out view of the Helm source parameter list
   225  
   226  <img height="50%" width="50%" src="images/helm-parameter-list.png"/>