github.com/argoproj/argo-cd/v2@v2.10.5/docs/proposals/002-ui-extensions.md (about)

     1  ---
     2  title: Argo CD Extensions
     3  authors:
     4    - "@rbreeze"
     5    - "@jsuen"
     6    - "@alexmt"
     7  sponsors:
     8    - TBD
     9  reviewers:
    10    - "@alexmt"
    11    - "@jsuen"
    12    - TBD
    13  approvers:
    14    - TBD
    15  
    16  creation-date: 2021-05-13
    17  last-updated: 2021-05-27
    18  ---
    19  
    20  # Argo CD Extensions
    21  
    22  
    23  ## Summary
    24  
    25  This proposal is to provide a mechanism to extend Argo CD such that it can provide resource-specific visualizations, capabilities and interactions in the following ways:
    26  
    27  1. Richer and context-sensitive UI components can be displayed in the user interface about custom resources.
    28  2. Custom health checks can be configured to assess the health of the resource.
    29  3. Custom actions could be performed to manipulate resources in predefined ways.
    30  
    31  
    32  ## Motivation
    33  
    34  Argo CD is commonly used as a dashboard to Kubernetes applications. The current UI is limited in that it only displays very general information about Kubernetes objects. Any special visualizations can currently only be done for native Kubernetes kinds.
    35  
    36  For custom resources, Argo CD does not by default have any special handling or understanding of CRs, such as how to assess the health of the object or visualizations. When examining a resource, a user can only see a YAML view of the object, which is not helpful unless they are familiar with the object's spec and status information.
    37  
    38  Note that Argo CD does currently have a resource customizations feature, which allows operators to define health checks and actions via lua scripts in the argocd-cm ConfigMap. However, the current mechanism of configuring resource customizations is difficult and highly error prone.
    39  
    40  This proposal would allow operators to more easily configure Argo CD to understand custom resources, as well as provide more powerful visualization of objects.
    41  
    42  
    43  ## Use cases
    44  
    45  ### Use case 1: 
    46  As a user, I would like to see visual information about my Rollout without having to use the CLI or otherwise leave Argo CD.
    47  
    48  ### Use case 2:
    49  As an operator, I would like to configure Argo CD to be able to assess the health of a custom resource based on its status.
    50  
    51  ### Use case 3:
    52  As an operator, I would like to configure Argo CD to perform pre-defined actions (object mutations) on a custom resource, for example restarting a Rollout.
    53  
    54  
    55  ### Goals
    56  
    57  - Enable new visualizations in the UI for resources that do not have baked-in support
    58  - Extensions can be configured by operators at runtime, without a feature being built directly into Argo CD, and with no need to recompile UI code.
    59  - Extensions should be easy to develop and install.
    60  - Loose coupling between Argo CD and extensions.
    61  - Replace current resource customizations in `argocd-cm` ConfigMap with extensions
    62  
    63  
    64  ## Proposal
    65   
    66  A new `ArgoCDExtension` CRD would be introduced which will allow operators configure Argo CD to understand how to handle and visualize custom resources. Visualizing a object requires javascript to render the object, and health/actions require lua scripts. As such, the extension CR would need to point to some location where the javascript/lua code would be hosted.
    67  
    68  It is proposed that a git repository be used to contain the javascript code, as well as the lua scripts necessary to assess health or perform actions of a resource.
    69  
    70  
    71  ### ArgoCDExtension CRD
    72  
    73  In the most simplest form, an Argo CD extension could simply be a pointer to a git repository at a revision:
    74  
    75  ```yaml
    76  kind: ArgoCDExtension
    77  metadata:
    78    name: argo-rollouts
    79  spec:
    80    repository: https://github.com/argoproj-labs/rollout-extension
    81    revision: HEAD
    82  ```
    83  
    84  ### Git Repository Structure
    85  
    86  The git repository would have an expected structure, such that the scripts and UI component could be discovered easily by Argo CD based on resource kind.
    87  
    88  ```
    89  ├── README.md
    90  ├── argoproj.io
    91  │   ├── AnalysisRun
    92  │   │   ├── actions
    93  │   │   │   ├── discovery.lua
    94  │   │   │   └── terminate
    95  │   │   │       └── action.lua
    96  │   │   └── health.lua
    97  │   ├── Experiment
    98  │   │   └── health.lua
    99  │   └── Rollout
   100  │       ├── ui
   101  │       │   └── extension.js   # dynamically loaded by argocd-server
   102  │       ├── actions
   103  │       │   ├── abort
   104  │       │   │   └── action.lua
   105  │       │   ├── discovery.lua
   106  │       │   ├── promote-full
   107  │       │   │   └── action.lua
   108  │       │   ├── restart
   109  │       │   │   └── action.lua
   110  │       │   ├── resume
   111  │       │   │   └── action.lua
   112  │       │   ├── retry
   113  │       │   │   └── action.lua
   114  ```
   115  
   116  Note that it may be necessary to support multiple versions of a resource (e.g. v1alpha1 vs. a v1 version of a custom esource), and so the path structure may need to also support incorporating the version in the path. For example:
   117  
   118  ```
   119  ├── argoproj.io
   120  │   ├── v1alpha1
   121  │   │   ├── AnalysisRun
   122  ```
   123  
   124  ### User Interface
   125  
   126  In the UI, a new tab in the Resource View will be made available. The contents of that tab would dynamically loaded by the Argo CD API server at the git URL specified in the extension, which would be cloned locally by the API server.
   127  
   128  
   129  ## Implementation Details
   130  
   131  At a high level an Argo CD extension is simply a React component, which is dynamically loaded at runtime by the Argo CD API server.
   132  
   133  In order for the component to render some visualization about a resource, it needs to be supplied at least two key peices of information:
   134  1. The full resource object itself
   135  2. The entire Application Resource Tree
   136  
   137  We provide the entire application tree to accomplish two things: 
   138  
   139  1. Extensions get basic (shallow) live updates for free because the Resource Tree is already live updated
   140  2. Extensions may wish to display richer hierarchical structure for other related objects (e.g. the Rollout extension would want to display ReplicaSets and Pods)
   141  
   142  Further, if an Extension needs richer information than that provided by the Resource Tree, it can request additional information about a resource from the Argo CD API server.
   143  
   144  ```typescript
   145  interface Extention {
   146      ResourceTab: React.Component<{resource: any}>;
   147  }
   148  ```
   149  
   150  
   151  The UI will dynamically import an Extension React component from the Argo CD API Server. This is accomplished by specifying the generic Extension component as a Webpack external, and including a `<script>` tag in the `index.html` template that refers to the Argo CD API Server's generic extension endpoint (i.e. `/api/v1/extensions`). The API Server serves a different instantiation of the generic Extension component depending on the Resource being displayed; the generic extensions endpoint will have intelligence that reverse proxies the relevant third-party Extension API. The third-party Extension itself must conform to certain standards for this dynamic import (i.e. it must not bundle React). 
   152  
   153  ### Installation
   154  
   155  Installing Argo CD Extensions support will be enabled with a single `kubectl apply`. This will:
   156  
   157  1. Install the `ArgoCDExtension` CRD
   158  2. Patch the Argo CD API Server with a sidecar
   159  
   160  The sidecar will be responsible for cloning repos specified in `ArgoCDExtension` CRs and mounting them in a well known location understood by the API server. 
   161  
   162  Some changes are required in the Argo CD API server:
   163  
   164  1. It will serve Javascript assets mounted by the sidecar in the well known location to the UI at an endpoint (i.e. `/api/v1/extensions/<resource-kind>`)
   165  2. It will retrieve Actions Lua scripts from the same well known location mounted by the sidecar instead of from `argocd-cm`
   166  
   167  
   168  ### UI Extention Interface
   169  
   170  TODO
   171  
   172  
   173  ### Detailed examples
   174  
   175  TODO
   176  
   177  #### Argo Rollout Extension PoC: 
   178  
   179  ![Rollout Extension](./rollout-extension.png)
   180  
   181  ### Security Considerations
   182  
   183  - Any write operations must be configured as Lua scripts defined in the ArgoCDExtension Custom Resource so that Argo CD RBAC can be enforced when a user invokes an action
   184  
   185  
   186  ### Risks and Mitigations
   187  
   188  We will be allowing the Argo CD UI to serve dynamically imported UI assets; while these dynamic imports will only occur from same-origin, malicious Extensions may inject hazardous code. We may also consider publishing a list of "sanctioned" or "approved" Extensions that we believe to be trustworthy (e.g. Argo Rollouts' or Workflows' Extensions).
   189  
   190  
   191  ### Upgrade / Downgrade Strategy
   192  
   193  Existing Argo CD instances should be unaffected by this change. Extensions are opt-in only, and ideally none should be installed by default. 
   194  
   195  To opt in, operators will need to install services that comply with the Argo CD Extensions API and expose that service such that it is reachable by the Argo CD API Server. To uninstall an extension should be as simple as deleting the ArgoCDExtension CR.
   196  
   197  ## Drawbacks
   198  
   199  Argo CD was designed to be a GitOps tool, not a cluster visualization dashboard. Extensions open the door to increase Argo CD's scope in a way that may not be desirable.
   200  
   201  ## Alternatives
   202  
   203  We originally considered building native support for resources like a Rollout directly into Argo CD. However, this tightly couples the Argo CD Server to an Argo Rollouts version, which is problematic when Argo CD manages several clusters all running different Rollouts versions.
   204  
   205  We additionally considered requiring recompilation of the Argo CD UI (and by extension, the API server) to install Extensions in a similar fashion to Config Management Plugins. However, this is a headache for operators, and given that we are in the process of improving the Config Management Plugin paradigm, we should not go down this path if possible.
   206  
   207  ## Open Questions
   208  
   209  It will be important to allow Extensions to specify their own documentation URLs to be displayed as a button or banner to users, as to make clear that UI with support requests for third party extensions.