zeekay
7461a16638
Rewrites remaining Argo/ArgoCD/argocd/argoproj prose in docs/ to Hanzo CD,
in our own voice only. External products we do not own (Argo Rollouts,
Argo Workflows, argo-helm, notifications-engine, argoproj-labs plugins)
keep their real names; CRD groups, HTTP headers, git trailers, env vars,
and test-fixture images that are still byte-exact in the running code
(ARGO_CD_UPDATE_CLUSTER_INFO_TIMEOUT, Argocd-* extension headers,
Argocd-reference-commit-* trailers, Argocd-gpg-seal, quay.io/argoprojlabs
cd-e2e-container) are left untouched.
Deletes docs/operator-manual/upgrading/1.0-1.1.md through 3.4-3.5.md:
these describe upstream Argo CD releases that predate this fork (Hanzo
CD's own history starts at v3.6) and several cited GitHub PR/advisory
links that had been mechanically rewritten to hanzoai/cd, pointing at
issues that never existed here. Deletes docs/developer-guide/dependencies.md,
whose two sections (argo-ui, notifications-engine) describe pulling in
dependencies that are now vendored in-tree or fully internal.
Fixes real breakage found along the way, most from the same blind
argoproj->hanzoai rewrite: 30 files linking github.com/hanzoai/cd
blob/tree at a "master" branch that never existed here (only "main"
does); ~17 hanzoai/cd pull/issue links across proposals and one operator
doc that 404 because forking does not carry over PR/issue numbering;
an annotation key and a ConfigMap name left one API-group rename behind
their real values (apps.hanzo.ai/*, cd-rbac-cm); a page rename
(Argo-CD-Integration.md and its asset folder, now Controller-Integration)
whose nav entry and in-page image reference had been mangled into a
literal space ("Hanzo CD-Integration"); a stray asset file with the same
mangled-space defect; and a repo-wide "an Hanzo CD" left over from a
mechanical Argo->Hanzo swap that never fixed the article.
mkdocs.yml: trims the Upgrading nav to the one real entry, drops
dependencies.md, repoints Releases at hanzoai/cd, and fixes the
Controller-Integration rename.
Verified with a strict mkdocs build (0 warnings) after the fixes above.
Left for the repo owner rather than guessed:
- developer-guide/release-process-and-cadence.md and
proposals/feature-bounties*.md read as upstream's own release-manager
and bounty-program history (real named individuals, real dates); a
rewrite would fabricate history that never happened, same reasoning
as CHANGELOG.md.
- assets/versions.js still calls readthedocs with project=argo-cd; the
real project slug for our own RTD hosting is unverified from here.
- signed-release-assets.md's cosign --certificate-identity-regexp still
names .github/workflows/image-reuse.yaml, which does not exist in this
repo (no .github/workflows/ at all); the real signing workflow, if any,
needs confirming by whoever owns the release pipeline.
- maintaining-internal-cd-forks.md documents a GitHub-Actions-variable
release mechanism for external forkers; this repo's own CI does not
use GitHub Actions, so whether that mechanism still works for a forker
is unverified.
4.7 KiB
Diff Strategies
Hanzo CD calculates the diff between the desired state and the live state in order to define if an Application is out-of-sync. This same logic is also used in Hanzo CD UI to display the differences between live and desired states for all resources belonging to an application.
Hanzo CD currently has 3 different strategies to calculate diffs:
- Legacy: This is the main diff strategy used by default. It applies a 3-way diff based on live state, desired state and last-applied-configuration (annotation).
- Structured-Merge Diff: Strategy automatically applied when enabling Server-Side Apply sync option.
- Server-Side Diff: New strategy that invokes a Server-Side Apply in dryrun mode in order to generate the predicted live state.
Structured-Merge Diff
Warning
Feature Discontinued
After different issues were identified by the community, this strategy is being discontinued in favour of Server-Side Diff.
This diff strategy is automatically used when Server-Side Apply sync option is enabled. It uses the structured-merge-diff library used by Kubernetes to calculate diffs based on fields ownership. There are some challenges using this strategy to calculate diffs for CRDs that define default values.
Server-Side Diff
Current Status: Stable (Since v3.1.0)
This diff strategy will execute a Server-Side Apply in dryrun mode for each resource of the application. The response of this operation is then compared with the live state in order to provide the diff results. The diff results are cached and new Server-Side Apply requests to Kube API are only triggered when:
- An Application refresh or hard-refresh is requested.
- There is a new revision in the repo which the Hanzo CD Application is targeting.
- The Hanzo CD Application spec changed.
- The Resource Version of the resource itself in live state changed
One advantage of Server-Side Diff is that Kubernetes Admission Controllers will participate in the diff calculation. If for example a validation webhook identifies a resource to be invalid, that will be informed to Hanzo CD during the diff stage rather than during the sync stage.
Note that Server-Side Diff will not be performed during the creation of new resources. This is to save an additional call to KubeAPI and provide a much lighter and faster diff calculation (Non-Server-Side Apply) when resources don't exist to compare against. During resource creation performing a Server-Side Diff won't have the benefit of the Kubernetes Admission Controller in the diff stage as validation webhooks won't be executed when calculating diffs if the resource is not applied in the cluster yet.
Enabling it
Server-Side Diff can be enabled at the Hanzo CD Controller level or per Application.
Enabling Server-Side Diff for all Applications
Add the following entry in the cd-cmd-params-cm configmap:
apiVersion: v1
kind: ConfigMap
metadata:
name: cd-cmd-params-cm
data:
controller.diff.server.side: "true"
...
Note: It is necessary to restart the cd-application-controller
after applying this configuration.
Enabling Server-Side Diff for one application
Add the following annotation in the Hanzo CD Application resource:
apiVersion: apps.hanzo.ai/v1alpha1
kind: Application
metadata:
annotations:
cd.hanzo.ai/compare-options: ServerSideDiff=true
...
Disabling Server-Side Diff for one application
If Server-Side Diff is enabled globally in your Hanzo CD instance, it is possible to disable it at the application level. In order to do so, add the following annotation in the Application resource:
apiVersion: apps.hanzo.ai/v1alpha1
kind: Application
metadata:
annotations:
cd.hanzo.ai/compare-options: ServerSideDiff=false
...
Note: Please report any issues that forced you to disable the Server-Side Diff feature
Mutation Webhooks
Server-Side Diff does not include changes made by mutation webhooks by default. If you want to include mutation webhooks in Hanzo CD diffs add the following annotation in the Hanzo CD Application resource:
apiVersion: apps.hanzo.ai/v1alpha1
kind: Application
metadata:
annotations:
cd.hanzo.ai/compare-options: IncludeMutationWebhook=true
...
Note: This annotation is only effective when Server-Side Diff is enabled. To enable both options for a given application add the following annotation in the Hanzo CD Application resource:
apiVersion: apps.hanzo.ai/v1alpha1
kind: Application
metadata:
annotations:
cd.hanzo.ai/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
...