github.com/argoproj/argo-cd/v3@v3.2.1/docs/proposals/project-scoped-repository-enhancements.md (about)

     1  ---
     2  title: Project scoped repository credential enhancements
     3  authors:
     4    - "@blakepettersson" 
     5  sponsors:
     6    - TBD
     7  reviewers:
     8    - "@alexmt"
     9    - "@jsoref"
    10    - "@christianh814"
    11    - "@wanghong230"
    12    - "@yyzxw"
    13  approvers:
    14    - "@alexmt"
    15  
    16  creation-date: 2024-05-17
    17  last-updated: 2024-06-04
    18  ---
    19  
    20  # Project scoped repository credential enhancements
    21  
    22  ## Summary
    23  
    24  This is to allow the possibility to have multiple repository credentials which share the same URL. Currently, multiple repository
    25  credentials sharing the same URL is disallowed by the Argo CD API.
    26  
    27  ## Motivation
    28  
    29  This is to allow the possibility to have multiple repository credentials which share the same URL. Currently, multiple repository
    30  credentials sharing the same URL is disallowed by the Argo CD API. If the credentials are added directly to the `argocd`
    31  namespace, we "get around" `argocd-server` returning an error, but this still does not work since the first secret that 
    32  matches a repository URL is the one that gets returned, and the order is also undefined. 
    33  
    34  The reason why we want this is due to the fact that in a multi-tenant environment, multiple teams may want to 
    35  independently use the same repositories without needing to ask an Argo CD admin to add the repository for them, and then
    36  add the necessary RBAC in the relevant `AppProject`s to prevent other teams from having access to the repository 
    37  credentials. In other words, this will enable more self-service capabilities for dev teams. 
    38  
    39  ### Goals
    40  
    41  The goal of this proposal is to allow multiple app projects to have the ability to have separate repository credentials 
    42  which happen to share the same URL.
    43  
    44  ### Non-Goals
    45  
    46  - Having multiple repository secrets sharing the same URL _within the same_ `AppProject`.
    47  - Allowing a single repository credential to be used in multiple `AppProject`s. 
    48  - Preventing non project-scoped repository credentials from being used by an Application.
    49  - Extending this to repository credential templates.
    50  
    51  ## Proposal
    52  
    53  There are a few parts to this proposal.
    54  
    55  We need to distinguish between a user accessing a repository via the API/CLI/UI and an application retrieving repository
    56  credentials. In the first case, we need to maintain backwards compatibility for API consumers. The current behaviour 
    57  is that the API will return the first repository found matching the URL given. Since we now want to allow the same URL 
    58  to potentially be in multiple projects, we need to do some minor changes.
    59  
    60  * If there is only one matching repository with the same URL, and assuming the user is allowed to access it _and_ there is
    61  no app project given as a parameter, use that repository ignoring any project-scope. This is in line with the 
    62  current behavior.
    63  * If there is only one matching repository with the same URL, and assuming the user is allowed to access it _and_ there is
    64  an app project given as a parameter, use that repository only if it also matches the app project given. 
    65  * If there are multiple repositories with the same URL and assuming the user is allowed to access them, then setting a
    66  project parameter would be required, since there would otherwise be no way to determine which of the credentials a user
    67  wants to access. This is not a breaking change since this adds functionality which has previously not existed.
    68  
    69  This change would apply when we retrieve a _single_ repository credential, or when we delete a repository credential.
    70  For listing repository credentials, nothing changes - the logic would be the same as today.
    71  
    72  In the case of selecting a suitable repository for an application, the logic would differ slightly. What instead happens 
    73  is that the lookup would first attempt to find the first `repository` secret which matches the `project` 
    74  and repository URL of the requesting application. If there are no credentials which match the requested `project`, it 
    75  will fall back to returning the first unscoped credential, i.e, the first credential with an empty `project` parameter.
    76  
    77  When it comes to mutating a repository credential we need to strictly match the project to which the repository belongs, since 
    78  there would otherwise be a risk of changing (inadvertently or otherwise) a credential not belonging to the correct project.
    79  This can be done without any breaking changes.
    80  
    81  The second part is specifically for when we imperatively create repository secrets. Currently, when we create a repository
    82  secret in the UI/CLI, a suffix gets generated which is a hash of the repository URL. This mechanism will be extended to 
    83  also hash the repository _project_.
    84  
    85  On the API server side no major changes are anticipated to the public API. The only change we need to do from the API 
    86  perspective is to add an `appProject` parameter when retrieving or deleting a repository credential. To preserve backwards 
    87  compatibility this option is optional and would only be a required parameter if multiple repository credentials are 
    88  found for the same URL.
    89  
    90  Finally, we need to change the way the cache keys for the repository paths are generated in the repo-server 
    91  (see `Security Considerations`). 
    92  
    93  ### Security Considerations
    94  
    95  * Special care needs to be taken in order not to inadvertently expose repository credentials belonging to other `AppProject`s.
    96  Access to repositories are covered by RBAC checks on the project, so we should be good.
    97  * We need to change how the cache keys for the checked out repository paths are generated on the repo-server side, the 
    98  reason being that we do not want separate `AppProject`s sharing the same paths of sources which have been downloaded. 
    99  With this change there is a potential for multiple `AppProject`s to have rendered/downloaded different manifests due to 
   100  having different sets of credentials, so to mitigate that we need to check out a separate copy of the repository per 
   101  `AppProject`.
   102  
   103  ### Risks and Mitigations
   104  
   105  ### Upgrade / Downgrade Strategy
   106  
   107  When upgrading no changes need to happen - the repository credentials will work as before. On the other hand, when 
   108  downgrading to an older version we need to consider that the existing order in which multiple credentials with the same
   109  URL gets returned is undefined. This means that deleting the credentials before downgrading to an older version would be
   110  advisable.
   111  
   112  ## Drawbacks
   113  
   114  * It will be more difficult to reason about how a specific repository credential gets selected. There could be scenarios 
   115  where a repository has both a global repository credential and a scoped credential for the project to which the 
   116  application belongs.
   117  * There will be more secrets proliferating in the `argocd` namespace. This has the potential to increase maintenance burden
   118  to keeping said secrets safe, and it also makes it harder to have a bird's eye view from an Argo CD admin's perspective.
   119  * Depending on the number of projects making use of distinct credentials for the same repository URL, loading the correct 
   120  credentials from the repository secrets has the potential to scale linearly with the number of app projects (in the worst case 
   121  scenario we would need to loop through all the credentials before finding the correct credential to load). This is likely 
   122  a non-issue in practice.
   123  * Also depending on the number of projects making use of distinct credentials for the same repository URL, this will 
   124  imply that for each `AppProject` sharing the same repository URL, a separate copy of the repository will be checked out.
   125  This has potential implications in terms of memory consumption, sync times, CPU load times etc. This is something 
   126  of which an Argo CD admin will need to be mindful.
   127  
   128  ## Alternatives
   129  
   130  To keep the existing behavior of having a single repository credential shared by multiple `AppProject`s. It would be up 
   131  to the Argo CD admins to ensure that a specific repository credential cannot be used by unauthorized parties.