github.com/argoproj/argo-cd/v2@v2.10.5/docs/proposals/multiple-sources-for-applications.md (about)

     1  ---
     2  title: Neat-enhancement-idea
     3  authors:
     4    - "@ishitasequeira" # Authors' github accounts here.
     5  sponsors:
     6    - TBD        # List all intereste parties here.
     7  reviewers:
     8    - "@jannfis"
     9    - "@crenshaw-dev"
    10    - "@alexmt"
    11  approvers:
    12    - "@jannfis"
    13    - "@alexmt"
    14    - "@crenshaw-dev"
    15  
    16  creation-date: 2022-01-28
    17  last-updated: 2022-04-01
    18  ---
    19  
    20  # Multiple Sources for application
    21  
    22  Support more than one source for creating an Application.
    23  
    24  Related Issues:
    25  * [Proposal: Support multiple sources for an application](https://github.com/argoproj/argo-cd/issues/677)
    26  * [Helm chart + values from Git](https://github.com/argoproj/argo-cd/issues/2789)
    27  
    28  ## Open Questions
    29  * Adding external sources to the Application resource would add additional latencies for creation/reconciliation process. Should we add it to the doc in Risks?
    30  
    31  ## Summary
    32  
    33  Currently, Argo CD supports Applications with only a single ApplicationSource. In certain scenarios, it would be useful to support more than one source for the application. For example, consider a need to create multiple deployments of the same application and manifests but manifests can come from different sources. Today we would have to copy manifest files from one application to another.
    34  
    35  For example, from [one of the comments on this proposal PR](https://github.com/argoproj/argo-cd/pull/8322/files#r799624767)
    36  ```
    37  An independent support of the Helm charts and their values files. This opens a door to such highly requested scenarios like multiple deployments of the same (possibly external) Helm chart with different values files or an independent migration to a newer Helm chart version for the same applications installed in Test and Production environments.
    38  ```
    39  
    40  Creating applications from multiple sources would allow users to configure multiple services stored at various sources within the same application.
    41  
    42  ## Motivation
    43  
    44  The main motivation behind this enhancement proposal is to allow users to create an application using services that are stored in various sources.
    45  
    46  ### Goals
    47  
    48  The goals of the enhancement are:
    49  
    50  #### **Supporting multiple sources for creating an application**
    51  
    52  Users should be able to specify multiple sources to add services to the application. Argo CD should compile all the sources and reconcile each source individually for creating the application.
    53  
    54  #### **Allow specifying external value files for Helm repositories**
    55  
    56  Users should be able to specify different sources for Helm charts and values files. The Helm charts specified by the user could be available in Git or Helm repository and the value files are stored in Git. Argo CD should track changes in both the Helm charts and the value files repository and reconcile the application.
    57  
    58  #### Changes to UI
    59  
    60  The UI should allow users to add multiple sources while creating the application. For each source, UI should allow users to add multiple external values files Helm projects. We would need a separate proposal for changes to UI.
    61  
    62  #### Changes to cli
    63  
    64  The cli would need to support adding a list of resources instead of just one while creating the application. `values` field should allow referencing value files from other sources. We would need a separate proposal for changes to cli.
    65  
    66  ### Non-goals
    67  *
    68  
    69  ## Proposal
    70  
    71  ### Add new `sources` field in Application Spec
    72  
    73  The proposal is to add a new field `sources` which would allow users to input list of `ApplicationSource`s. We would mark field `source` as deprecated and would ignore the details under `source` with details under `sources` field.
    74  
    75  Below example shows how the yaml would look like for `source` and `sources` field. We would ignore the `source` field and apply the resources mentioned under `sources` field.
    76  
    77  ```yaml
    78  spec:
    79    source:
    80      repoURL: https://github.com/elastic/helm-charts/tree/main/elasticsearch
    81      targetRevision: 6.8
    82      helm:
    83        valueFiles:
    84          - values.yaml
    85    sources:                                          # new field
    86      - repoURL: https://github.com/helm/charts
    87        targetRevision: master
    88        path: incubator/elasticsearch
    89        helm:
    90          valueFiles:
    91            - values.yaml
    92  ```
    93  
    94  ### Make `path/chart` field optional
    95  
    96  While adding sources to the application, users can decide not to add `path/chart` field in the application yaml. The controller will not generate manifests for the sources that do not have `path/chart` field specified. For example, in the below application spec, controller will generate the manifest for `elasticsearch` source but not for source `my-repo`.
    97  
    98  ```
    99  spec:
   100    sources:
   101      - repoURL: https://github.com/my-org/my-repo # path is missing so no manifests are generated
   102        targetRevision: master
   103        ref: myRepo                                 # repo is available via symlink "my-repo"
   104      - repoURL: https://github.com/helm/charts
   105        targetRevision: master
   106        path: incubator/elasticsearch               # path "incubator/elasticsearch" is used to generate manifests
   107        helm:
   108          valueFiles:
   109            - $myRepo/values.yaml                   # values.yaml is located in source with reference name $myRepo
   110  ```
   111  
   112  ### Add optional `ref` field to Application Source
   113  
   114  For making files accessible to other sources, add a new `ref` field to the source. For example, in below ApplicationSpec, we have added `ref: myRepo` to the `my-repo` repository and have used reference `$myRepo` to the `elasticSearch` repository.
   115  
   116  ```yaml
   117  spec:
   118    sources:
   119      - repoURL: https://github.com/my-org/my-repo  # path is missing so no manifests are generated
   120        targetRevision: master
   121        ref: myRepo                                 # repo is available via symlink "myRepo"
   122      - repoURL: https://github.com/helm/charts
   123        targetRevision: master
   124        path: incubator/elasticsearch               # path "incubator/elasticsearch" is used to generate manifests
   125        helm:
   126          valueFiles:
   127            - $myRepo/values.yaml                   # values.yaml is located in source with reference name $myRepo
   128  ```
   129  
   130  ### Combined Example Application yaml
   131  
   132  ```yaml
   133  apiVersion: argoproj.io/v1alpha1
   134  kind: Application
   135  metadata:
   136    name: grafana
   137    namespace: argocd
   138  spec:
   139    destination:
   140      namespace: monitoring
   141      server: https://some.k8s.url.com:6443
   142    project: default
   143    source:
   144      repoURL: https://github.com/helm/charts
   145      targetRevision: master
   146      helm:
   147      valueFiles:
   148          - values.yaml
   149      chart: incubator/elasticsearch
   150    sources:                                          # new field
   151    # application that consists of MongoDB and ElasticSearch resources
   152      - repoURL: https://github.com/helm/charts
   153        targetRevision: master
   154        path: incubator/mongodb
   155      - repoURL: https://github.com/helm/charts
   156        targetRevision: master
   157        path: incubator/elasticsearch
   158      - repoURL: https://github.com/my-org/my-repo  # path is missing so no manifests are generated
   159        targetRevision: master
   160        ref: myRepo                                 # repo is available via symlink "my-repo"
   161      - repoURL: https://github.com/helm/charts
   162        targetRevision: master
   163        path: incubator/elasticsearch               # path "incubator/elasticsearch" is used to generate manifests
   164        helm:
   165          valueFiles:
   166            - $myRepo/values.yaml                   # values.yaml is located in source with reference name $myRepo
   167    syncPolicy:
   168      automated: {}
   169  ```
   170  
   171  In scenarios, where you have same resource mentioned multiple times in the application yaml, the last resource in the source list will override the previous resources.
   172  
   173  ### Use cases
   174  
   175  Add a list of detailed use cases this enhancement intends to take care of.
   176  
   177  #### Use case 1:
   178  As a user, I have an Application that uses the [elasticsearch](https://github.com/helm/charts/tree/master/incubator/elasticsearch) helm chart as source. Today, user needs to create a separate Application to configure the [elasticsearch-exporter](https://github.com/helm/charts/tree/master/stable/elasticsearch-exporter
   179  ) to expose Prometheus metrics.
   180  https://github.com/argoproj/argo-cd/issues/677
   181  
   182  #### Use case 2:
   183  As per one of the [comment]((https://github.com/argoproj/argo-cd/issues/2789#issuecomment-562495307)) on the issue [Helm chart + values files from Git](https://github.com/argoproj/argo-cd/issues/2789):
   184  ```
   185  We have a Helm Chart which is used in 30+ Services and each of them is customized for 3 possible environments.
   186  Replicating this Chart 30 times without a centralized Repo looks dirty. Can be a show stopper for the whole migration.
   187  Modifying the Application definition is not an option since the whole goal is to reduce the rights that the CI-solution has. Giving it the right to update all Application-definitions from various teams in the argocd namespace is a hard thing to convince people with.
   188  ```
   189  
   190  ### Implementation Details
   191  
   192  #### Attach multiple sources to the Application
   193  
   194  To allow multiple sources to the Application, we would add a new field `sources` which would allow users to input list of `ApplicationSource`s. As part of this update and to support backward compatibility, we would mark field `source` as deprecated and remove it in later revisions.
   195  
   196  To avoid complexity on the deciding the list of sources, if both `source` and `sources` fields are specified, we would override the source under `source` field with all the sources under `sources` field.
   197  
   198  **Depracating `source` field:** - Once the `sources` field is implemented in UI and cli as well, we will mark the `source` field as deprecated. At the same time, we will log `WARNING` messages and add UI blurbs about the deprecation. When maintainers feel confident about the adoption of the `sources` field, we will remove the `source` field from later releases.
   199  
   200  #### Invalidating existing cache
   201  
   202  Argo CD benefits from the assumption of a single repo per application to detect changes and to cache the results. But this enhancement now requires us to look at all the source repo "HEAD"s and invalidate the cache if any one of them changes.
   203  
   204  #### Reconcilation of the Application
   205  
   206  As we would have multiple sources as part of the same Application, we would need to track updates to each source and reconcile the Application for each source. When one of the sources change, we would need to ensure that target revisions of other sources are up-to-date, e.g. force a simple refresh to see if target revision of the source (e.g. HEAD), still points to revisionX for example.
   207  
   208  #### Updates to UI
   209  Today, we allow users to add only one source in the UI. We would need to update the UI to add multiple sources and configure specific
   210  
   211  #### Updates to cli
   212  
   213  We would need to create new options to the `argocd app create` command for adding multiple sources to the Application. We would also need to introduce allowing `ref` field for sources and to reference the files from symlinked source.
   214  
   215  As per the community call on February 3, changes to UI and cli are huge and are not planned to be part of first iteration.
   216  
   217  ### Security Considerations
   218  
   219  Good unit- and end-to-end tests need to be in place for this functionality to ensure we don't accidentally introduce a change that would break the feature.
   220  
   221  ### Risks and Mitigations
   222  
   223  #### Uncontrolled number of sources added to Application
   224  
   225  The users might add a huge number of external sources to the Application, with a potential performance impact on the Argo CD creation/reconciliation processes. This would apply even for the external value files for Helm projects.
   226  
   227  A possible mitigation to this would be to enforce the number of external sources allowed per Application.
   228  
   229  #### Unauthorised access to external resources
   230  
   231  The users might reference the source that has not been whitelisted in the project. This might lead to access issues and failure to sync the Application.
   232  
   233  A possible solution would be to check for the source repository to be whitelisted in the project before syncing and report appropriate error messages in respective scenarios.
   234  
   235  
   236  ### Upgrade / Downgrade Strategy
   237  
   238  Upgrading to a version implementing this proposal should be frictionless and wouldn't require administrators to perform any changes in the configuration to keep the current behaviour. Application created without the new field `.spec.sources` being set will keep their behaviour, since they will allow Application resources to be created the same way they are today.
   239  
   240  Downgrading would not be easily possible once users start to make use of the feature and create Applications with the new field `.spec.sources` being set. The Application would no longer be able to recognize the resources and will fail the reconciliation/creation step.
   241  
   242  
   243  ## Drawbacks
   244  
   245  * Downgrade/rollback would not be easily possible