From df2a759c657f8b95532d83a5c1dc4800c343b8ff Mon Sep 17 00:00:00 2001 From: Peter Jiang <35584807+pjiang-dev@users.noreply.github.com> Date: Sun, 14 Dec 2025 09:54:43 -0800 Subject: [PATCH] chore: add --force-conflicts and notes (#25639) Signed-off-by: Peter Jiang Co-authored-by: Regina Voloshin --- .goreleaser.yaml | 4 +-- .../development-environment.md | 2 +- docs/developer-guide/running-locally.md | 4 +-- docs/getting_started.md | 9 +++++- docs/index.md | 4 ++- .../Controlling-Resource-Modification.md | 2 +- .../applicationset/Getting-Started.md | 4 +-- docs/operator-manual/core.md | 2 +- docs/operator-manual/declarative-setup.md | 32 +++++++++++++++++++ docs/operator-manual/managed-by-url.md | 4 +-- docs/operator-manual/notifications/index.md | 2 +- docs/operator-manual/upgrading/overview.md | 7 ++-- docs/try_argo_cd_locally.md | 5 ++- docs/user-guide/sync-options.md | 4 +-- 14 files changed, 66 insertions(+), 19 deletions(-) diff --git a/.goreleaser.yaml b/.goreleaser.yaml index 663b763fb3..5a2ca4df2b 100644 --- a/.goreleaser.yaml +++ b/.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 diff --git a/docs/developer-guide/development-environment.md b/docs/developer-guide/development-environment.md index 4d94c3ecc1..eb0a5145ae 100644 --- a/docs/developer-guide/development-environment.md +++ b/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. diff --git a/docs/developer-guide/running-locally.md b/docs/developer-guide/running-locally.md index 3958b867fa..faf66ed0fc 100644 --- a/docs/developer-guide/running-locally.md +++ b/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 ``` diff --git a/docs/getting_started.md b/docs/getting_started.md index 658f4566ef..ea40cae3f2 100644 --- a/docs/getting_started.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 0f7ac6e00a..484381c195 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/operator-manual/applicationset/Controlling-Resource-Modification.md b/docs/operator-manual/applicationset/Controlling-Resource-Modification.md index 38d02f911a..28f5b8a93f 100644 --- a/docs/operator-manual/applicationset/Controlling-Resource-Modification.md +++ b/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 diff --git a/docs/operator-manual/applicationset/Getting-Started.md b/docs/operator-manual/applicationset/Getting-Started.md index 154edf0db2..fb5a467ff2 100644 --- a/docs/operator-manual/applicationset/Getting-Started.md +++ b/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. diff --git a/docs/operator-manual/core.md b/docs/operator-manual/core.md index 9bcd2a8ef0..b79e738f4e 100644 --- a/docs/operator-manual/core.md +++ b/docs/operator-manual/core.md @@ -58,7 +58,7 @@ Example: ``` export ARGOCD_VERSION= 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 diff --git a/docs/operator-manual/declarative-setup.md b/docs/operator-manual/declarative-setup.md index e6dfaf037e..be43668fee 100644 --- a/docs/operator-manual/declarative-setup.md +++ b/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. diff --git a/docs/operator-manual/managed-by-url.md b/docs/operator-manual/managed-by-url.md index 1e81d9b94b..e65b300a99 100644 --- a/docs/operator-manual/managed-by-url.md +++ b/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 & diff --git a/docs/operator-manual/notifications/index.md b/docs/operator-manual/notifications/index.md index 4a132762b8..0e77679f38 100644 --- a/docs/operator-manual/notifications/index.md +++ b/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 diff --git a/docs/operator-manual/upgrading/overview.md b/docs/operator-manual/upgrading/overview.md index b016d46163..b192c2ed80 100644 --- a/docs/operator-manual/upgrading/overview.md +++ b/docs/operator-manual/upgrading/overview.md @@ -20,15 +20,18 @@ command to upgrade Argo CD. Make sure to replace `` with the required v **Non-HA**: ```bash -kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd//manifests/install.yaml +kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd//manifests/install.yaml ``` **HA**: ```bash -kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd//manifests/ha/install.yaml +kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd//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 diff --git a/docs/try_argo_cd_locally.md b/docs/try_argo_cd_locally.md index 268da3dba3..ee88dbcfba 100644 --- a/docs/try_argo_cd_locally.md +++ b/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 diff --git a/docs/user-guide/sync-options.md b/docs/user-guide/sync-options.md index 96fbedc21d..701924267b 100644 --- a/docs/user-guide/sync-options.md +++ b/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`.