github.com/argoproj/argo-cd@v1.8.7/docs/user-guide/projects.md (about)

     1  ## Projects
     2  
     3  Projects provide a logical grouping of applications, which is useful when Argo CD is used by multiple
     4  teams. Projects provide the following features:
     5  
     6  * restrict *what* may be deployed (trusted Git source repositories)
     7  * restrict *where* apps may be deployed to (destination clusters and namespaces)
     8  * restrict what kinds of objects may or may not be deployed (e.g. RBAC, CRDs, DaemonSets, NetworkPolicy etc...)
     9  * defining project roles to provide application RBAC (bound to OIDC groups and/or JWT tokens)
    10  
    11  ### The Default Project
    12  
    13  Every application belongs to a single project. If unspecified, an application belongs to the
    14  `default` project, which is created automatically and by default, permits deployments from any
    15  source repo, to any cluster, and all resource Kinds. The default project can be modified, but not
    16  deleted. When initially created, it's specification is configured to be the most permissive:
    17  
    18  ```yaml
    19  spec:
    20    sourceRepos:
    21    - '*'
    22    destinations:
    23    - namespace: '*'
    24      server: '*'
    25    clusterResourceWhitelist:
    26    - group: '*'
    27      kind: '*'
    28  ```
    29  
    30  ### Creating Projects
    31  
    32  Additional projects can be created to give separate teams different levels of access to namespaces.
    33  The following command creates a new project `myproject` which can deploy applications to namespace
    34  `mynamespace` of cluster `https://kubernetes.default.svc`. The permitted Git source repository is
    35  set to `https://github.com/argoproj/argocd-example-apps.git` repository.
    36  
    37  ```bash
    38  argocd proj create myproject -d https://kubernetes.default.svc,mynamespace -s https://github.com/argoproj/argocd-example-apps.git
    39  ```
    40  
    41  ### Managing Projects
    42  
    43  Permitted source Git repositories are managed using commands:
    44  
    45  ```bash
    46  argocd proj add-source <PROJECT> <REPO>
    47  argocd proj remove-source <PROJECT> <REPO>
    48  ```
    49  
    50  Permitted destination clusters and namespaces are managed with the commands (for clusters always provide server, the name is not used for matching):
    51  
    52  ```bash
    53  argocd proj add-destination <PROJECT> <CLUSTER>,<NAMESPACE>
    54  argocd proj remove-destination <PROJECT> <CLUSTER>,<NAMESPACE>
    55  ```
    56  
    57  Permitted destination K8s resource kinds are managed with the commands. Note that namespaced-scoped
    58  resources are restricted via a deny list, whereas cluster-scoped resources are restricted via
    59  allow list.
    60  
    61  ```bash
    62  argocd proj allow-cluster-resource <PROJECT> <GROUP> <KIND>
    63  argocd proj allow-namespace-resource <PROJECT> <GROUP> <KIND>
    64  argocd proj deny-cluster-resource <PROJECT> <GROUP> <KIND>
    65  argocd proj deny-namespace-resource <PROJECT> <GROUP> <KIND>
    66  ```
    67  
    68  ### Assign Application To A Project
    69  
    70  The application project can be changed using `app set` command. In order to change the project of
    71  an app, the user must have permissions to access the new project.
    72  
    73  ```
    74  argocd app set guestbook-default --project myproject
    75  ```
    76  
    77  ## Project Roles
    78  
    79  Projects include a feature called roles that enable automated access to a project's applications.
    80  These can be used to give a CI pipeline a restricted set of permissions. For example, a CI system
    81  may only be able to sync a single app (but not change its source or destination).
    82  
    83  Projects can have multiple roles, and those roles can have different access granted to them. These
    84  permissions are called policies, and they are stored within the role as a list of policy strings.
    85  A role's policy can only grant access to that role and are limited to applications within the role's
    86  project.  However, the policies have an option for granting wildcard access to any application
    87  within a project.
    88  
    89  In order to create roles in a project and add policies to a role, a user will need permission to
    90  update a project.  The following commands can be used to manage a role.
    91  
    92  ```bash
    93  argocd proj role list
    94  argocd proj role get
    95  argocd proj role create
    96  argocd proj role delete
    97  argocd proj role add-policy
    98  argocd proj role remove-policy
    99  ```
   100  
   101  Project roles in itself are not useful without generating a token to associate to that role. Argo CD
   102  supports JWT tokens as the means to authenticate to a role. Since the JWT token is
   103  associated with a role's policies, any changes to the role's policies will immediately take effect
   104  for that JWT token.
   105  
   106  The following commands are used to manage the JWT tokens.
   107  
   108  ```bash
   109  argocd proj role create-token PROJECT ROLE-NAME
   110  argocd proj role delete-token PROJECT ROLE-NAME ISSUED-AT
   111  ```
   112  
   113  Since the JWT tokens aren't stored in Argo CD, they can only be retrieved when they are created. A
   114  user can leverage them in the cli by either passing them in using the `--auth-token` flag or setting
   115  the ARGOCD_AUTH_TOKEN environment variable. The JWT tokens can be used until they expire or are
   116  revoked.  The JWT tokens can created with or without an expiration, but the default on the cli is
   117  creates them without an expirations date.  Even if a token has not expired, it cannot be used if
   118  the token has been revoked.
   119  
   120  Below is an example of leveraging a JWT token to access a guestbook application.  It makes the
   121  assumption that the user already has a project named myproject and an application called
   122  guestbook-default.
   123  
   124  ```bash
   125  PROJ=myproject
   126  APP=guestbook-default
   127  ROLE=get-role
   128  argocd proj role create $PROJ $ROLE
   129  argocd proj role create-token $PROJ $ROLE -e 10m
   130  JWT=<value from command above>
   131  argocd proj role list $PROJ
   132  argocd proj role get $PROJ $ROLE
   133  
   134  # This command will fail because the JWT Token associated with the project role does not have a policy to allow access to the application
   135  argocd app get $APP --auth-token $JWT
   136  # Adding a policy to grant access to the application for the new role
   137  argocd proj role add-policy $PROJ $ROLE --action get --permission allow --object $APP
   138  argocd app get $PROJ-$ROLE --auth-token $JWT
   139  
   140  # Removing the policy we added and adding one with a wildcard.
   141  argocd proj role remove-policy $PROJ $TOKEN -a get -o $PROJ-$TOKEN
   142  argocd proj role add-policy $PROJ $ROLE -a get --permission allow -o '*'
   143  # The wildcard allows us to access the application due to the wildcard.
   144  argocd app get $PROJ-$TOKEN --auth-token $JWT
   145  argocd proj role get $PROJ
   146  
   147  
   148  argocd proj role get $PROJ $ROLE
   149  # Revoking the JWT token
   150  argocd proj role delete-token $PROJ $ROLE <id field from the last command>
   151  # This will fail since the JWT Token was deleted for the project role.
   152  argocd app get $APP --auth-token $JWT
   153  ```
   154  
   155  ## Configuring RBAC With Projects
   156  
   157  The project Roles allows configuring RBAC rules scoped to the project. The following sample
   158  project provides read-only permissions on project applications to any member of `my-oidc-group` group.
   159  
   160  *AppProject example:*
   161  
   162  ```yaml
   163  apiVersion: argoproj.io/v1alpha1
   164  kind: AppProject
   165  metadata:
   166    name: my-project
   167    namespace: argocd
   168  spec:
   169    roles:
   170    # A role which provides read-only access to all applications in the project
   171    - name: read-only
   172      description: Read-only privileges to my-project
   173      policies:
   174      - p, proj:my-project:read-only, applications, get, my-project/*, allow
   175      groups:
   176      - my-oidc-group
   177  ```
   178  
   179  You can use `argocd proj role` CLI commands or project details page in the user interface to configure the policy.
   180  Note that each project role policy rule must be scoped to that project only. Use the `argocd-rbac-cm` ConfigMap described in
   181  [RBAC](../operator-manual/rbac.md) documentation if you want to configure cross project RBAC rules.
   182  
   183  ## Configuring Global Projects (v1.8)
   184  
   185  Global projects can be configured to provide configurations that other projects can inherit from. 
   186  
   187  Projects, which match `matchExpressions` specified in `argocd-cm` ConfigMap, inherit the following fields from the global project:
   188  
   189  * namespaceResourceBlacklist
   190  * namespaceResourceWhitelist
   191  * clusterResourceBlacklist
   192  * clusterResourceWhitelist
   193  * SyncWindows
   194  
   195  Configure global projects in `argocd-cm` ConfigMap:
   196  ```yaml
   197  data:
   198    globalProjects: |-
   199      - labelSelector:
   200          matchExpressions:
   201            - key: opt
   202              operator: In
   203              values:
   204                - prod
   205        projectName: proj-global-test
   206  kind: ConfigMap
   207  ``` 
   208  
   209  Valid operators you can use are: In, NotIn, Exists, DoesNotExist. Gt, and Lt.
   210  
   211  projectName: `proj-global-test` should be replaced with your own global project name.