chore: add --force-conflicts and notes (#25639)

Signed-off-by: Peter Jiang <peterjiang823@gmail.com>
Co-authored-by: Regina Voloshin <regina.voloshin@codefresh.io>

.goreleaser.yaml

@@ -66,14 +66,14 @@ release:
 
     ```shell
     kubectl create namespace argocd
-    kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/{{ .Env.GORELEASER_CURRENT_REPOSITORY }}/{{.Tag}}/manifests/install.yaml
+    kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/{{ .Env.GORELEASER_CURRENT_REPOSITORY }}/{{.Tag}}/manifests/install.yaml
     ```
 
     ### HA:
 
     ```shell
     kubectl create namespace argocd
-    kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/{{ .Env.GORELEASER_CURRENT_REPOSITORY }}/{{.Tag}}/manifests/ha/install.yaml
+    kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/{{ .Env.GORELEASER_CURRENT_REPOSITORY }}/{{.Tag}}/manifests/ha/install.yaml
     ```
 
     ## Release Signatures and Provenance

docs/developer-guide/development-environment.md

@@ -109,7 +109,7 @@ make install-codegen-tools-local
 
 ```shell
 kubectl create namespace argocd &&
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
 ```
 
 Set kubectl config to avoid specifying the namespace in every kubectl command.  

docs/developer-guide/running-locally.md

@@ -21,7 +21,7 @@ First push the installation manifest into argocd namespace:
 
 ```shell
 kubectl create namespace argocd
-kubectl apply -n argocd --server-side -f manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f manifests/install.yaml
 ```
 
 The services you will start later assume you are running in the namespace where Argo CD is installed. You can set the current context default namespace as follows:
@@ -246,5 +246,5 @@ make manifests-local
 The final step is to push the manifests to your cluster, so it will pull and run your image:
 
 ```bash
-kubectl apply -n argocd --server-side -f manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f manifests/install.yaml
 ```

docs/getting_started.md

@@ -13,11 +13,18 @@
 
 ```bash
 kubectl create namespace argocd
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
 ```
 
 This will create a new `argocd` namespace where all Argo CD services and application resources will reside. It will also install Argo CD by applying the official manifests from the stable branch. Using a pinned version (like `v3.2.0`) is recommended for production.
 
+> [!NOTE]
+> **Why `--server-side --force-conflicts`?**
+>
+> The `--server-side` flag is required because some Argo CD CRDs (like ApplicationSet) exceed the 262KB annotation size limit imposed by client-side `kubectl apply`. Server-side apply avoids this limitation by not storing the `last-applied-configuration` annotation.
+>
+> The `--force-conflicts` flag allows the apply operation to take ownership of fields that may have been previously managed by other tools (such as Helm or a previous `kubectl apply`). This is safe for fresh installs and necessary for upgrades. Note that any custom modifications you've made to fields that are defined in the Argo CD manifests (like `affinity`, `env`, or `probes`) will be overwritten. However, fields not specified in the manifests (like `resources` limits/requests or `tolerations`) will be preserved.
+
 > [!WARNING]
 > The installation manifests include `ClusterRoleBinding` resources that reference `argocd` namespace. If you are installing Argo CD into a different
 > namespace then make sure to update the namespace reference.

docs/index.md

@@ -21,9 +21,11 @@ Application deployment and lifecycle management should be automated, auditable,
 
 ```bash
 kubectl create namespace argocd
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
 ```
 
+The `--server-side --force-conflicts` flags are required due to CRD size limitations. See the [getting started guide](getting_started.md) for details.
+
 Follow our [getting started guide](getting_started.md). Further user oriented [documentation](user-guide/)
 is provided for additional features. If you are looking to upgrade Argo CD, see the [upgrade guide](./operator-manual/upgrading/overview.md).
 Developer oriented [documentation](developer-guide/) is available for people interested in building third-party integrations.

docs/operator-manual/applicationset/Controlling-Resource-Modification.md

@@ -283,7 +283,7 @@ cd applicationset/manifests
 # as described in the previous section.
 
 # Apply the change to the cluster
-kubectl apply -n argocd --server-side -f install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f install.yaml
 ```
 
 ## Preserving changes made to an Applications annotations and labels

docs/operator-manual/applicationset/Getting-Started.md

@@ -29,7 +29,7 @@ The ApplicationSet controller *must* be installed into the same namespace as the
 Presuming that Argo CD is installed into the `argocd` namespace, run the following command:
 
 ```bash
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/applicationset/v0.4.0/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/applicationset/v0.4.0/manifests/install.yaml
 ```
 
 Once installed, the ApplicationSet controller requires no additional setup.
@@ -47,7 +47,7 @@ The `manifests/install.yaml` file contains the Kubernetes manifests required to
 
 Development builds of the ApplicationSet controller can be installed by running the following command:
 ```bash
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/applicationset/master/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/applicationset/master/manifests/install.yaml
 ```
 
 With this option you will need to ensure that Argo CD is already installed into the `argocd` namespace.

docs/operator-manual/core.md

@@ -58,7 +58,7 @@ Example:
 ```
 export ARGOCD_VERSION=<desired argo cd release version (e.g. v2.7.0)>
 kubectl create namespace argocd
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/$ARGOCD_VERSION/manifests/core-install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/$ARGOCD_VERSION/manifests/core-install.yaml
 ```
 
 ## Using

docs/operator-manual/declarative-setup.md

@@ -1415,3 +1415,35 @@ stored at [argoproj/argoproj-deployments](https://github.com/argoproj/argoproj-d
 
 > [!NOTE]
 > You will need to sign-in using your GitHub account to get access to [https://cd.apps.argoproj.io](https://cd.apps.argoproj.io)
+
+### Server-Side Apply Requirement
+
+When managing Argo CD with Argo CD, you **must** enable the `ServerSideApply=true` sync option. See the [getting started guide](../getting_started.md#1-install-argo-cd) for details on why server-side apply is required.
+
+Example Application for self-managed Argo CD:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: argocd
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/argoproj/argo-cd
+    path: manifests/cluster-install
+    targetRevision: stable
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: argocd
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - ServerSideApply=true
+```
+
+> [!NOTE]
+> To customize Argo CD deployments, use Kustomize patches in your configuration repository rather than manually modifying the live resources. See the [sync options documentation](../user-guide/sync-options.md#server-side-apply) for details on field ownership behavior.

docs/operator-manual/managed-by-url.md

@@ -121,11 +121,11 @@ To test the annotation with two local Argo CD instances:
 ```bash
 # Install primary instance
 kubectl create namespace argocd
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
 
 # Install secondary instance
 kubectl create namespace namespace-b
-kubectl apply -n namespace-b --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+kubectl apply -n namespace-b --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
 
 # Port forward both instances
 kubectl port-forward -n argocd svc/argocd-server 8080:443 &

docs/operator-manual/notifications/index.md

@@ -11,7 +11,7 @@ So you can just use them instead of reinventing new ones.
 * Install Triggers and Templates from the catalog
 
     ```bash
-    kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/notifications_catalog/install.yaml
+    kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/notifications_catalog/install.yaml
     ```
 
 * Add email username and password token to the `argocd-notifications-secret` secret

docs/operator-manual/upgrading/overview.md

@@ -20,15 +20,18 @@ command to upgrade Argo CD. Make sure to replace `<version>` with the required v
 **Non-HA**:
 
 ```bash
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/<version>/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/<version>/manifests/install.yaml
 ```
 
 **HA**:
 
 ```bash
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/<version>/manifests/ha/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/<version>/manifests/ha/install.yaml
 ```
 
+> [!NOTE]
+> The `--server-side --force-conflicts` flags are required because some Argo CD CRDs exceed the size limit for client-side apply. See the [getting started guide](../../getting_started.md#1-install-argo-cd) for more details.
+
 > [!WARNING]
 > Even though some releases require only image change it is still recommended to apply whole manifests set.
 > Manifest changes might include important parameter modifications and applying the whole set will protect you from

docs/try_argo_cd_locally.md

@@ -30,9 +30,12 @@ This command verifies that `kubectl` is pointed to the right cluster.
 You can now install Argo CD on your `kind` cluster. First, apply the Argo CD manifest to create the necessary resources:
 ```bash
 kubectl create namespace argocd
-kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
 ```
 
+> [!NOTE]
+> The `--server-side --force-conflicts` flags are required because some Argo CD CRDs exceed the size limit for client-side apply. See the [getting started guide](getting_started.md) for more details.
+
 ## Expose ArgoCD API Server
 By default, Argo CD's API server is not exposed outside the cluster. You need to expose it to access the UI locally. For development purposes, you can use Kubectl 'port-forward'.
 ```bash

docs/user-guide/sync-options.md

@@ -233,7 +233,7 @@ However, there are some cases where you want to use `kubectl apply --server-side
 - Use a more declarative approach, which tracks a user's field management, rather than a user's last
   applied state.
 
-If the `ServerSideApply=true` sync option is set, Argo CD will use the `kubectl apply --server-side`
+If the `ServerSideApply=true` sync option is set, Argo CD will use the `kubectl apply --server-side --force-conflicts`
 command to apply changes.
 
 It can be enabled at the application level like in the example below:
@@ -293,7 +293,7 @@ spec:
     - Validate=false
 ```
 
-In this case, Argo CD will use the `kubectl apply --server-side --validate=false` command
+In this case, Argo CD will use the `kubectl apply --server-side --force-conflicts --validate=false` command
 to apply changes.
 
 Note: [`Replace=true`](#replace-resource-instead-of-applying-changes) takes precedence over `ServerSideApply=true`.