github.com/argoproj/argo-cd/v2@v2.10.5/docs/proposals/deep-links.md (about)

     1  ---
     2  title: Deep Links
     3  
     4  authors:
     5  - "@gdsoumya"
     6  - "@alexmt"
     7  
     8  sponsors:
     9  - TBD
    10  
    11  reviewers:
    12  - TBD
    13  
    14  approvers:
    15  - TBD
    16  
    17  creation-date: 2022-08-01
    18  
    19  ---
    20  
    21  # Deep Links
    22  
    23  Deep links allow end users to quickly redirect to third-party systems such as Splunk, DataDog etc. from the Argo CD
    24  user interface.
    25  
    26  
    27  ## Summary
    28  
    29  Argo CD administrator will be able to configure links that redirect users to third-party systems such as Splunk,
    30  DataDog etc. The template should be able to reference different types of resources relating to where the links show up,
    31  this includes projects, applications, or individual resources(pods, services etc.) that are part of the application.
    32  
    33  Deep Link is a generic integration solution for third-party systems which enables users to integrate any system -  not
    34  only popular solutions but also custom/private systems that can leverage the data available in Argo CD.
    35  
    36  ## Motivation
    37  
    38  Argo CD UI with deep links to third-party integrations will provide a unified solution for users making it easier for
    39  them to switch between relevant systems without having to separately navigate and correlate the information.
    40  
    41  
    42  ## Proposal
    43  
    44  The configuration for Deep Links will be present in the `argocd-cm`, we will add new `<location>.links` fields in the
    45  cm to list all the deep links that will be displayed in the provided location. The possible values for `<location>`
    46  currently are :
    47  - `project` : all links under this field will show up in the project tab in the Argo CD UI.
    48  - `application` : all links under this field will show up in the application summary tab.
    49  - `resource` : all links under this field will show up in the individual resource(deployments, pods, services etc.)
    50    summary tab.
    51  
    52  Each link in the list has five subfields :
    53  1. `title` : title/tag that will be displayed in the UI corresponding to that link
    54  2. `url` : the actual URL where the deep link will redirect to, this field can be templated to use data from the
    55     application, project or resource objects (depending on where it is located)
    56  3. `description` (optional) : a description for what the deep link is about
    57  4. `icon.class` (optional) : a font-awesome icon class to be used when displaying the links in dropdown menus.
    58  5. `if` (optional) : a conditional statement that results in either `true` or `false`, it also has access to the same
    59     data as the `url` field. If the condition resolves to `true` the deep link will be displayed else it will be hidden. If
    60     the field is omitted by default the deep links will be displayed.
    61  
    62  
    63  An example `argocd-cm.yaml` file with deep links and its variations :
    64  
    65  ```yaml
    66  data:
    67    # project level links
    68    project.links: |
    69      - url: https://myaudit-system.com?project={{proj.metadata.name}}
    70        title: Audit
    71    # application level links
    72    application.links: |
    73      - url: https://mycompany.splunk.com?search={{app.spec.destination.namespace}}
    74        title: Splunk
    75      # conditionally show link e.g. for specific project
    76      - url: https://mycompany.splunk.com?search={{app.spec.destination.namespace}}
    77        title: Splunk
    78        if: app.spec.proj == "abc"
    79      - url: https://{{project.metadata.annotations.splunkhost}}?search={{app.spec.destination.namespace}}
    80        title: Splunk
    81        if: project.metadata.annotations.splunkhost
    82      
    83    # resource level links
    84    resource.links: |
    85      - url: https://mycompany.splunk.com?search={{res.metadata.namespace}}
    86        title: Splunk
    87        if: res.kind == "Pod" || res.kind == "Deployment"
    88  
    89  ```
    90  
    91  The argocd server will expose new APIs for rendering deep links in the UI, the server will handle the templating and
    92  conditional rendering logic and will provide the UI with the final list of links that need to be displayed for a
    93  particular location/resource.
    94  
    95  The following API methods are proposed:
    96  
    97  ```protobuf
    98  message LinkInfo {
    99    required string name = 1;
   100    required string url = 2;
   101    optional string description = 3;
   102    optional string iconClass = 4;
   103  }
   104  
   105  message LinksResponse {
   106    repeated LinkInfo items = 1;
   107  }
   108  
   109  service ApplicationService {
   110    rpc ListLinks(google.protobuf.Empty) returns (LinksResponse) {
   111      option (google.api.http).get = "/api/v1/applications/{name}/links";
   112    }
   113  
   114    rpc ListResourceLinks(ApplicationResourceRequest) returns (LinksResponse) {
   115      option (google.api.http).get = "/api/v1/applications/{name}/resource/links";
   116    }
   117  }
   118  
   119  service ProjectService {
   120    
   121    rpc ListLinks(google.protobuf.Empty) returns (LinksResponse) {
   122      option (google.api.http).get = "/api/v1/projects/{name}/links";
   123    }
   124  }
   125  ```
   126  
   127  ### Use cases
   128  
   129  Some example use cases this enhancement intends to take care of -
   130  
   131  #### Use case 1:
   132  As a user, I would like to quickly open a splunk/datadog UI with a query that retrieves all logs of application
   133  namespace or metrics for specific applications etc.