docs: update config management plugin docs

docs/operator-manual/config-management-plugins.md

@@ -20,51 +20,21 @@ The following sections will describe how to create, install, and use plugins. Ch
 
 There are two ways to install a Config Management Plugin:
 
-1. Add the plugin config to the Argo CD ConfigMap (**this method is deprecated and will be removed in a future 
-   version**). The repo-server container will run your plugin's commands. This is a good option for a simple plugin that
-   requires only a few lines of code that fit nicely in the Argo CD ConfigMap.
-2. Add the plugin as a sidecar to the repo-server Pod.
-   This is a good option for a more complex plugin that would clutter the Argo CD ConfigMap. A copy of the repository is 
-   sent to the sidecar container as a tarball and processed individually per application, which makes it a good option 
-   for [concurrent processing of monorepos](high_availability.md#enable-concurrent-processing).
-
-### Option 1: Configure plugins via Argo CD configmap (deprecated)
-
-The following changes are required to configure a new plugin:
-
-1. Make sure required binaries are available in `argocd-repo-server` pod. The binaries can be added via volume mounts or 
-   using a custom image (see [custom_tools](custom_tools.md) for examples of both).
-2. Register a new plugin in `argocd-cm` ConfigMap:
-
-        :::yaml
-        data:
-          configManagementPlugins: |
-            - name: pluginName
-              init:                          # Optional command to initialize application source directory
-                command: ["sample command"]
-                args: ["sample args"]
-              generate:                      # Command to generate manifests YAML
-                command: ["sample command"]
-                args: ["sample args"]
-              lockRepo: true                 # Defaults to false. See below.
-
-    The `generate` command must print a valid YAML or JSON stream to stdout. Both `init` and `generate` commands are executed inside the application source directory or in `path` when specified for the app.
-
-3. [Create an Application which uses your new CMP](#using-a-cmp).
-
-More CMP examples are available in [argocd-example-apps](https://github.com/argoproj/argocd-example-apps/tree/master/plugins).
+ * **Sidecar plugin**
+
+    This is a good option for a more complex plugin that would clutter the Argo CD ConfigMap. A copy of the repository is
+    sent to the sidecar container as a tarball and processed individually per application.
 
-!!!note "Repository locking"
-    If your plugin makes use of `git` (e.g. `git crypt`), it is advised to set
-    `lockRepo` to `true` so that your plugin will have exclusive access to the
-    repository at the time it is executed. Otherwise, two applications synced
-    at the same time may result in a race condition and sync failure.
+ * **ConfigMap plugin** (**this method is deprecated and will be removed in a future 
+   version**)
+
+    The repo-server container will run your plugin's commands.
 
-### Option 2: Configure plugin via sidecar
+### Sidecar plugin
 
 An operator can configure a plugin tool via a sidecar to repo-server. The following changes are required to configure a new plugin:
 
-#### 1. Write the plugin configuration file
+#### Write the plugin configuration file
 
 Plugins will be configured via a ConfigManagementPlugin manifest located inside the plugin container.
 
@@ -168,7 +138,7 @@ If `discover.fileName` is not provided, the `discover.find.command` is executed
 application repository is supported by the plugin or not. The `find` command should return a non-error exit code
 and produce output to stdout when the application source type is supported.
 
-#### 2. Place the plugin configuration file in the sidecar
+#### Place the plugin configuration file in the sidecar
 
 Argo CD expects the plugin configuration file to be located at `/home/argocd/cmp-server/config/plugin.yaml` in the sidecar.
 
@@ -203,7 +173,7 @@ data:
         fileName: "./subdir/s*.yaml"
 ```
 
-#### 3. Register the plugin sidecar
+#### Register the plugin sidecar
 
 To install a plugin, patch argocd-repo-server to run the plugin container as a sidecar, with argocd-cmp-server as its 
 entrypoint. You can use either off-the-shelf or custom-built plugin image as sidecar image. For example:
@@ -242,90 +212,115 @@ volumes:
     2. Make sure that sidecar container is running as user 999.
     3. Make sure that plugin configuration file is present at `/home/argocd/cmp-server/config/plugin.yaml`. It can either be volume mapped via configmap or baked into image.
 
-### Using environment variables in your plugin
-
-Plugin commands have access to
+### ConfigMap plugin
 
-1. The system environment variables (of the repo-server container for argocd-cm plugins or of the sidecar for sidecar plugins)
-2. [Standard build environment variables](../user-guide/build-environment.md)
-3. Variables in the Application spec (References to system and build variables will get interpolated in the variables' values):
-
-```yaml
-apiVersion: argoproj.io/v1alpha1
-kind: Application
-spec:
-  source:
-    plugin:
-      env:
-        - name: FOO
-          value: bar
-        - name: REV
-          value: test-$ARGOCD_APP_REVISION
-```
+!!! warning "Deprecated"
+    ConfigMap plugins are deprecated and will no longer be supported in 2.7.
 
-!!! note
-    The `discover.command` command only has access to the above environment starting with v2.4.
+The following changes are required to configure a new plugin:
 
-Before reaching the `init.command`, `generate.command`, and `discover.command` commands, Argo CD prefixes all 
-user-supplied environment variables (#3 above) with `ARGOCD_ENV_`. This prevents users from directly setting 
-potentially-sensitive environment variables.
+1. Make sure required binaries are available in `argocd-repo-server` pod. The binaries can be added via volume mounts or
+   using a custom image (see [custom_tools](../operator-manual/custom_tools.md) for examples of both).
+2. Register a new plugin in `argocd-cm` ConfigMap:
 
-If your plugin was written before 2.4 and depends on user-supplied environment variables, then you will need to update
-your plugin's behavior to work with 2.4. If you use a third-party plugin, make sure they explicitly advertise support
-for 2.4.
+        data:
+          configManagementPlugins: |
+            - name: pluginName
+              init:                          # Optional command to initialize application source directory
+                command: ["sample command"]
+                args: ["sample args"]
+              generate:                      # Command to generate manifests YAML
+                command: ["sample command"]
+                args: ["sample args"]
+              lockRepo: true                 # Defaults to false. See below.
+
+    The `generate` command must print a valid YAML or JSON stream to stdout. Both `init` and `generate` commands are executed inside the application source directory or in `path` when specified for the app.
 
-4. (Starting in v2.4) Parameters in the Application spec:
+3. [Create an Application which uses your new CMP](#using-a-cmp).
 
-```yaml
-apiVersion: argoproj.io/v1alpha1
-kind: Application
-spec:
- source:
-   plugin:
-     parameters:
-       - name: values-files
-         array: [values-dev.yaml]
-       - name: helm-parameters
-         map:
-           image.tag: v1.2.3
-```
+More CMP examples are available in [argocd-example-apps](https://github.com/argoproj/argocd-example-apps/tree/master/plugins).
 
-The parameters are available as JSON in the `ARGOCD_APP_PARAMETERS` environment variable. The example above would
-produce this JSON:
+!!!note "Repository locking"
+    If your plugin makes use of `git` (e.g. `git crypt`), it is advised to set
+    `lockRepo` to `true` so that your plugin will have exclusive access to the
+    repository at the time it is executed. Otherwise, two applications synced
+    at the same time may result in a race condition and sync failure.
 
-```json
-[{"name": "values-files", "array": ["values-dev.yaml"]}, {"name": "helm-parameters", "map": {"image.tag": "v1.2.3"}}]
-```
+### Using environment variables in your plugin
 
-!!! note
-    Parameter announcements, even if they specify defaults, are _not_ sent to the plugin in `ARGOCD_APP_PARAMETERS`.
-    Only parameters explicitly set in the Application spec are sent to the plugin. It is up to the plugin to apply
-    the same defaults as the ones announced to the UI.
+Plugin commands have access to
 
-The same parameters are also available as individual environment variables. The names of the environment variables
-follows this convention:
+1. The system environment variables (of the repo-server container for argocd-cm plugins or of the sidecar for sidecar plugins)
+2. [Standard build environment variables](../user-guide/build-environment.md)
+3. Variables in the Application spec (References to system and build variables will get interpolated in the variables' values):
 
-```yaml
-   - name: some-string-param
-     string: some-string-value
-   # PARAM_SOME_STRING_PARAM=some-string-value
+        apiVersion: argoproj.io/v1alpha1
+        kind: Application
+        spec:
+          source:
+            plugin:
+              env:
+                - name: FOO
+                  value: bar
+                - name: REV
+                  value: test-$ARGOCD_APP_REVISION
 
-   - name: some-array-param
-     value: [item1, item2]
-   # PARAM_SOME_ARRAY_PARAM_0=item1
-   # PARAM_SOME_ARRAY_PARAM_1=item2
+    !!! note
+        The `discover.find.command` command only has access to the above environment starting with v2.4.
+
+    Before reaching the `init.command`, `generate.command`, and `discover.find.command` commands, Argo CD prefixes all 
+    user-supplied environment variables (#3 above) with `ARGOCD_ENV_`. This prevents users from directly setting 
+    potentially-sensitive environment variables.
+
+    If your plugin was written before 2.4 and depends on user-supplied environment variables, then you will need to update
+    your plugin's behavior to work with 2.4. If you use a third-party plugin, make sure they explicitly advertise support
+    for 2.4.
+
+4. (Starting in v2.6) Parameters in the Application spec:
+
+        apiVersion: argoproj.io/v1alpha1
+        kind: Application
+        spec:
+         source:
+           plugin:
+             parameters:
+               - name: values-files
+                 array: [values-dev.yaml]
+               - name: helm-parameters
+                 map:
+                   image.tag: v1.2.3
 
-   - name: some-map-param
-     map:
-       image.tag: v1.2.3
-   # PARAM_SOME_MAP_PARAM_IMAGE_TAG=v1.2.3
-```
-
-!!! warning 
-    Sanitize/escape user input. As part of Argo CD's manifest generation system, config management plugins are treated with a level of trust. Be
+    The parameters are available as JSON in the `ARGOCD_APP_PARAMETERS` environment variable. The example above would
+    produce this JSON:
+
+        [{"name": "values-files", "array": ["values-dev.yaml"]}, {"name": "helm-parameters", "map": {"image.tag": "v1.2.3"}}]
+
+    !!! note
+        Parameter announcements, even if they specify defaults, are _not_ sent to the plugin in `ARGOCD_APP_PARAMETERS`.
+        Only parameters explicitly set in the Application spec are sent to the plugin. It is up to the plugin to apply
+        the same defaults as the ones announced to the UI.
+
+    The same parameters are also available as individual environment variables. The names of the environment variables
+    follows this convention:
+
+           - name: some-string-param
+             string: some-string-value
+           # PARAM_SOME_STRING_PARAM=some-string-value
+
+           - name: some-array-param
+             value: [item1, item2]
+           # PARAM_SOME_ARRAY_PARAM_0=item1
+           # PARAM_SOME_ARRAY_PARAM_1=item2
+
+           - name: some-map-param
+             map:
+               image.tag: v1.2.3
+           # PARAM_SOME_MAP_PARAM_IMAGE_TAG=v1.2.3
+
+!!! warning "Sanitize/escape user input" 
+    As part of Argo CD's manifest generation system, config management plugins are treated with a level of trust. Be
     sure to escape user input in your plugin to prevent malicious input from causing unwanted behavior.
 
-
 ## Using a config management plugin with an Application
 
 If your CMP is defined in the `argocd-cm` ConfigMap, you can create a new Application using the CLI. Replace 
@@ -414,7 +409,7 @@ a future release.
 
 The following will show how to convert an argocd-cm plugin to a sidecar plugin.
 
-### 1. Convert the ConfigMap entry into a config file
+### Convert the ConfigMap entry into a config file
 
 First, copy the plugin's configuration into its own YAML file. Take for example the following ConfigMap entry:
 
@@ -451,18 +446,17 @@ spec:
     The `lockRepo` key is not relevant for sidecar plugins, because sidecar plugins do not share a single source repo
     directory when generating manifests.
 
-### 2. Write discovery rules for your plugin
+### Write discovery rules for your plugin
 
 Sidecar plugins can use either discovery rules or a plugin name to match Applications to plugins. If the discovery rule is omitted 
 then you have to explicitly specify the plugin by name in the app spec or else that particular plugin will not match any app.
 
-Write rules applicable to your plugin [using the instructions above](#1-write-the-plugin-configuration-file) and add
-them to your configuration file.
+If you want to use discovery instead of the plugin name to match applications to your plugin, write rules applicable to 
+your plugin [using the instructions above](#1-write-the-plugin-configuration-file) and add them to your configuration 
+file.
 
-!!! note
-    After installing your sidecar plugin, you may remove the `name` field from the plugin config in your
-    Application specs for auto-discovery or update the name to `<metadata.name>-<spec.version>`
-    if version was mentioned in the `ConfigManagementPlugin` spec or else just use `<metadata.name>`. For example:
+To use the name instead of discovery, update the name in your application manifest to `<metadata.name>-<spec.version>` 
+if version was mentioned in the `ConfigManagementPlugin` spec or else just use `<metadata.name>`. For example:
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1
@@ -475,7 +469,7 @@ spec:
       name: pluginName  # Delete this for auto-discovery (and set `plugin: {}` if `name` was the only value) or use proper sidecar plugin name
 ```
 
-### 3. Make sure the plugin has access to the tools it needs
+### Make sure the plugin has access to the tools it needs
 
 Plugins configured with argocd-cm ran on the Argo CD image. This gave it access to all the tools installed on that
 image by default (see the [Dockerfile](https://github.com/argoproj/argo-cd/blob/master/Dockerfile) for base image and
@@ -484,7 +478,7 @@ installed tools).
 You can either use a stock image (like busybox) or design your own base image with the tools your plugin needs. For
 security, avoid using image with more binaries installed than what your plugin actually needs.
 
-### 4. Test the plugin
+### Test the plugin
 
 After installing the plugin as a sidecar [according to the directions above](#installing-a-config-management-plugin),
 test it out on a few Applications before migrating all of them to the sidecar plugin.

docs/operator-manual/upgrading/2.4-2.5.md

@@ -34,7 +34,7 @@ p, role:org-admin, exec,         create, *, allow
 ## argocd-cm plugins (CMPs) are deprecated
 
 Starting with Argo CD v2.5, installing config management plugins (CMPs) via the `argocd-cm` ConfigMap is deprecated.
-Support will be removed in v2.6.
+~~Support will be removed in v2.6.~~ Support will be removed in v2.7.
 
 You can continue to use the plugins by [installing them as sidecars](https://argo-cd.readthedocs.io/en/stable/user-guide/config-management-plugins/)
 on the repo-server Deployment.
@@ -47,6 +47,8 @@ following message:
 
 > argocd-cm plugins are deprecated, and support will be removed in v2.6. Upgrade your plugin to be installed via sidecar. https://argo-cd.readthedocs.io/en/stable/user-guide/config-management-plugins/
 
+**NOTE:** removal of argocd-cm plugin support was delayed to v2.7. Update your logs scan to use `v2.7` instead of `v2.6`.
+
 If you run `argocd app list` as admin, the list of Applications using deprecated plugins will be logged as a warning.
 
 ## Dex server TLS configuration
@@ -97,14 +99,14 @@ When using `argocd app diff --local`, code from the repo server is run on the us
 
 In order to support CMPs and reduce local requirements, we have implemented *server-side generation* of local manifests via the `--server-side-generate` argument. For example, `argocd app diff --local repoDir --server-side-generate` will upload the contents of `repoDir` to the repo server and run your manifest generation pipeline against it, the same as it would for a Git repo.
 
-In v2.7, the `--server-side-generate` argument will become the default and client-side generation will be removed.
+In ~~v2.6~~ v2.7, the `--server-side-generate` argument will become the default, ~~and client-side generation will be removed~~ and client-side generation will be supported as an alternative.
 
 !!! warning
     The semantics of *where* Argo will start generating manifests within a repo has changed between client-side and server-side generation. With client-side generation, the application's path (`spec.source.path`) was ignored and the value of `--local-repo-root` was effectively used (by default `/` relative to `--local`).
 
     For example, given an application that has an application path of `/manifests`, you would have had to run `argocd app diff --local yourRepo/manifests`. This behavior did not match the repo server's process of downloading the full repo/chart and then beginning generation in the path specified in the application manifest.
 
-    When switching to server-side generation, `--local` should point to the root of your repo *without* including your `spec.source.path`. This is especially important to keep in mind when `--server-side-generate` becomes the default in v2.6. Existing scripts utilizing `diff --local` may break in v2.6 if `spec.source.path` was not `/`.
+    When switching to server-side generation, `--local` should point to the root of your repo *without* including your `spec.source.path`. This is especially important to keep in mind when `--server-side-generate` becomes the default in v2.7. Existing scripts utilizing `diff --local` may break in v2.7 if `spec.source.path` was not `/`.
 
 ## Upgraded Kustomize Version
 

docs/operator-manual/upgrading/2.5-2.6.md

@@ -21,3 +21,11 @@ If you rely on an OIDC provider which does not provide a `aud` claim, you can di
 `skipAudienceCheckWhenTokenHasNoAudience` flag to `true` in your Argo CD OIDC configuration. (See the 
 [OIDC configuration documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/#existing-oidc-provider)
 for an example.)
+
+## Removal of argocd-cm plugin support delayed until 2.7
+
+Support for argocd-cm plugins was previously scheduled for 2.6. At the time, sidecar plugins could not be specified by
+name. Argo CD v2.6 introduces support for specifying sidecar plugins by name. 
+
+Removal of argocd-cm plugin support has been delayed until 2.7 to provide a transition time for users who need to 
+specify plugins by name.