github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/app-sync-using-impersonation.md (about)

     1  # Application Sync using impersonation
     2  
     3  !!! warning "Alpha Feature (Since 2.13.0)"
     4      This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha) 
     5      feature that allows you to control the service account used for the sync operation. The configured service account 
     6      could have lesser privileges required for creating resources compared to the highly privileged access required for 
     7      the control plane operations.
     8  
     9  !!! warning
    10      Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
    11  
    12  ## Introduction
    13  
    14  Argo CD supports syncing `Application` resources using the same service account used for its control plane operations. This feature enables users to decouple service account used for application sync from the service account used for control plane operations.
    15  
    16  By default, application syncs in Argo CD have the same privileges as the Argo CD control plane. As a consequence, in a multi-tenant setup, the Argo CD control plane privileges needs to match the tenant that needs the highest privileges. As an example, if an Argo CD instance has 10 Applications and only one of them requires admin privileges, then the Argo CD control plane must have admin privileges in order to be able to sync that one Application. This provides an opportunity for malicious tenants to gain admin level access. Argo CD provides a multi-tenancy model to restrict what each `Application` is authorized to do using `AppProjects`, however it is not secure enough and if Argo CD is compromised, attackers will easily gain `cluster-admin` access to the cluster.
    17  
    18  Some manual steps will need to be performed by the Argo CD administrator in order to enable this feature, as it is disabled by default.
    19  
    20  !!! note
    21      This feature is considered alpha as of now. Some of the implementation details may change over the course of time until it is promoted to a stable status. We will be happy if early adopters use this feature and provide us with bug reports and feedback.
    22  
    23  ### What is Impersonation
    24  
    25  Impersonation is a feature in Kubernetes and enabled in the `kubectl` CLI client, using which, a user can act as another user through impersonation headers. For example, an admin could use this feature to debug an authorization policy by temporarily impersonating another user and seeing if a request was denied.
    26  
    27  Impersonation requests first authenticate as the requesting user, then switch to the impersonated user info.
    28  
    29  ## Prerequisites
    30  
    31  In a multi-team/multi-tenant environment, a team/tenant is typically granted access to a target namespace to self-manage their kubernetes resources in a declarative way.
    32  A typical tenant onboarding process looks like below:
    33  1. The platform admin creates a tenant namespace and the service account to be used for creating the resources is also created in the same tenant namespace.
    34  2. The platform admin creates one or more Role(s) to manage kubernetes resources in the tenant namespace
    35  3. The platform admin creates one or more RoleBinding(s) to map the service account to the role(s) created in the previous steps.
    36  4. The platform admin can choose to use either the [apps-in-any-namespace](./app-any-namespace.md) feature or provide access to tenants to create applications in the ArgoCD control plane namespace.
    37  5. If the platform admin chooses apps-in-any-namespace feature, tenants can self-service their Argo applications in their respective tenant namespaces and no additional access needs to be provided for the control plane namespace.
    38  
    39  ## Implementation details
    40  
    41  ### Overview
    42  
    43  In order for an application to use a different service account for the application sync operation, the following steps needs to be performed:
    44  
    45  1. The impersonation feature flag should be enabled. Please refer the steps provided in [Enable application sync with impersonation feature](#enable-application-sync-with-impersonation-feature)
    46  
    47  2. The `AppProject` referenced by the `.spec.project` field of the `Application` must have the `DestinationServiceAccounts` mapping the destination server and namespace to a service account to be used for the sync operation. Please refer the steps provided in [Configuring destination service accounts](#configuring-destination-service-accounts)
    48  
    49  
    50  ### Enable application sync with impersonation feature
    51  
    52  In order to enable this feature, the Argo CD administrator must reconfigure the `application.sync.impersonation.enabled` settings in the `argocd-cm` ConfigMap as below:
    53  
    54  ```yaml
    55  data:
    56    application.sync.impersonation.enabled: "true"
    57  ```
    58  
    59  ### Disable application sync with impersonation feature
    60  
    61  In order to disable this feature, the Argo CD administrator must reconfigure the `application.sync.impersonation.enabled` settings in the `argocd-cm` ConfigMap as below:
    62  
    63  ```yaml
    64  data:
    65    application.sync.impersonation.enabled: "false"
    66  ```
    67  
    68  !!! note
    69      This feature is disabled by default.
    70  
    71  !!! note
    72      This feature can be enabled/disabled only at the system level and once enabled/disabled it is applicable to all Applications managed by ArgoCD.
    73  
    74  ## Configuring destination service accounts
    75  
    76  Destination service accounts can be added to the `AppProject` under `.spec.destinationServiceAccounts`. Specify the target destination `server` and `namespace` and provide the service account to be used for the sync operation using `defaultServiceAccount` field. Applications that refer this `AppProject` will use the corresponding service account configured for its destination.
    77  
    78  During the application sync operation, the controller loops through the available `destinationServiceAccounts` in the mapped `AppProject` and tries to find a matching candidate. If there are multiple matches for a destination server and namespace combination, then the first valid match will be considered. If there are no matches, then an error is reported during the sync operation. In order to avoid such sync errors, it is highly recommended that a valid service account may be configured as a catch-all configuration, for all target destinations and kept in lowest order of priority.
    79  
    80  It is possible to specify service accounts along with its namespace. eg: `tenant1-ns:guestbook-deployer`. If no namespace is provided for the service account, then the Application's `spec.destination.namespace` will be used. If no namespace is provided for the service account and the optional `spec.destination.namespace` field is also not provided in the `Application`, then the Application's namespace will be used.
    81  
    82  `DestinationServiceAccounts` associated to a `AppProject` can be created and managed, either declaratively or through the Argo CD API (e.g. using the CLI, the web UI, the REST API, etc).
    83  
    84  ### Using declarative yaml
    85  
    86  For declaratively configuring destination service accounts, create an yaml file for the `AppProject` as below and apply the changes using `kubectl apply` command.
    87  
    88  ```yaml
    89  apiVersion: argoproj.io/v1alpha1
    90  kind: AppProject
    91  metadata:
    92    name: my-project
    93    namespace: argocd
    94  spec:
    95    description: Example Project
    96    # Allow manifests to deploy from any Git repos
    97    sourceRepos:
    98      - '*'
    99    destinations:
   100      - '*'
   101    destinationServiceAccounts:
   102      - server: https://kubernetes.default.svc
   103        namespace: guestbook
   104        defaultServiceAccount: guestbook-deployer
   105      - server: https://kubernetes.default.svc
   106        namespace: guestbook-dev
   107        defaultServiceAccount: guestbook-dev-deployer
   108      - server: https://kubernetes.default.svc
   109        namespace: guestbook-stage
   110        defaultServiceAccount: guestbook-stage-deployer
   111      - server: https://kubernetes.default.svc # catch-all configuration
   112        namespace: '*'
   113        defaultServiceAccount: default
   114  ```
   115  
   116  ### Using the CLI
   117  
   118  Destination service accounts can be added to an `AppProject` using the ArgoCD CLI.
   119  
   120  For example, to add a destination service account for `in-cluster` and `guestbook` namespace, you can use the following CLI command:
   121  
   122  ```shell
   123  argocd proj add-destination-service-account my-project https://kubernetes.default.svc guestbook guestbook-sa
   124  ```
   125  
   126  Likewise, to remove the destination service account from an `AppProject`, you can use the following CLI command:
   127  
   128  ```shell
   129  argocd proj remove-destination-service-account my-project https://kubernetes.default.svc guestbook
   130  ```
   131  
   132  ### Using the UI
   133  
   134  Similar to the CLI, you can add destination service account when creating or updating an `AppProject` from the UI