Elgato_dark/argo-cd
1
0
Fork 0
mirror of https://github.com/argoproj/argo-cd synced 2026-04-21 08:57:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 14

docs: use GitHub alerts instead of mkdocs admonitions (#24631)

Browse source 
Signed-off-by: Michael Crenshaw <350466+crenshaw-dev@users.noreply.github.com>
This commit is contained in:
Michael Crenshaw 2025-09-21 19:46:10 -04:00 committed by GitHub
parent f960274139
commit a864d7052f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
92 changed files with 886 additions and 723 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/developer-guide/ci.md
View file

@ -68,9 +68,9 @@ make builder-image IMAGE_NAMESPACE=argoproj IMAGE_TAG=v1.0.0
Every commit to master is built and published to `ghcr.io/argoproj/argo-cd/argocd:<version>-<short-sha>`. The list of images is available at
[https://github.com/argoproj/argo-cd/packages](https://github.com/argoproj/argo-cd/packages).
!!! note
GitHub docker registry [requires](https://github.community/t5/GitHub-Actions/docker-pull-from-public-GitHub-Package-Registry-fail-with-quot/m-p/32888#M1294) authentication to read
even publicly available packages. Follow the steps from Kubernetes [documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry)
to configure image pull secret if you want to use `ghcr.io/argoproj/argo-cd/argocd` image.
> [!NOTE]
> GitHub docker registry [requires](https://github.community/t5/GitHub-Actions/docker-pull-from-public-GitHub-Package-Registry-fail-with-quot/m-p/32888#M1294) authentication to read
> even publicly available packages. Follow the steps from Kubernetes [documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry)
> to configure image pull secret if you want to use `ghcr.io/argoproj/argo-cd/argocd` image.
The image is automatically deployed to the dev Argo CD instance: [https://cd.apps.argoproj.io/](https://cd.apps.argoproj.io/)

10
docs/developer-guide/debugging-locally.md
View file

@ -26,8 +26,8 @@ api-server: [ "$BIN_MODE" = 'true' ] && COMMAND=./dist/argocd || COMMAND='go run
```
This configuration example will be used as the basis for the next steps.
!!! note
The Procfile for a component may change with time. Please go through the Procfile and make sure you use the latest configuration for debugging.
> [!NOTE]
> The Procfile for a component may change with time. Please go through the Procfile and make sure you use the latest configuration for debugging.
### Configure component env variables
The component that you will run in your IDE for debugging (`api-server` in our case) will need env variables. Copy the env variables from `Procfile`, located in the `argo-cd` root folder of your development branch. The env variables are located before the `$COMMAND` section in the `sh -c` section of the component run command.
@ -112,8 +112,8 @@ Example for an `api-server` launch configuration snippet, based on our above exa
</component>
```
!!! note
As an alternative to importing the above file to Goland, you can create a Run/Debug Configuration using the official [Goland docs](https://www.jetbrains.com/help/go/go-build.html) and just copy the `parameters`, `directory` and `PATH` sections from the example above (specifying `Run kind` as `Directory` in the Run/Debug Configurations wizard)
> [!NOTE]
> As an alternative to importing the above file to Goland, you can create a Run/Debug Configuration using the official [Goland docs](https://www.jetbrains.com/help/go/go-build.html) and just copy the `parameters`, `directory` and `PATH` sections from the example above (specifying `Run kind` as `Directory` in the Run/Debug Configurations wizard)
## Run Argo CD without the debugged component
Next, we need to run all Argo CD components, except for the debugged component (cause we will run this component separately in the IDE).
@ -143,4 +143,4 @@ To debug the `api-server`, run:
Finally, run the component you wish to debug from your IDE and make sure it does not have any errors.
## Important
When running Argo CD components separately, ensure components aren't creating conflicts - each component needs to be up exactly once, be it running locally with the local toolchain or running from your IDE. Otherwise you may get errors about ports not available or even debugging a process that does not contain your code changes.
When running Argo CD components separately, ensure components aren't creating conflicts - each component needs to be up exactly once, be it running locally with the local toolchain or running from your IDE. Otherwise you may get errors about ports not available or even debugging a process that does not contain your code changes.

4
docs/developer-guide/development-cycle.md
View file

@ -42,8 +42,8 @@ Argo CD relies on Google's [Protocol Buffers](https://developers.google.com/prot
* Check if something has changed by running `git status` or `git diff`
* Commit any possible changes to your local Git branch, an appropriate commit message would be `Changes from codegen`, for example.
!!!note
There are a few non-obvious assets that are auto-generated. You should not change the autogenerated assets, as they will be overwritten by a subsequent run of `make codegen`. Instead, change their source files. Prominent examples of non-obvious auto-generated code are `swagger.json` or the installation manifest YAMLs.
> [!NOTE]
> There are a few non-obvious assets that are auto-generated. You should not change the autogenerated assets, as they will be overwritten by a subsequent run of `make codegen`. Instead, change their source files. Prominent examples of non-obvious auto-generated code are `swagger.json` or the installation manifest YAMLs.
### Build your code and run unit tests

4
docs/developer-guide/docs-site.md
View file

@ -38,7 +38,7 @@ If you want to build and test the site directly on your local machine without th
## Analytics
!!! tip
Don't forget to disable your ad-blocker when testing.
> [!TIP]
> Don't forget to disable your ad-blocker when testing.
We collect [Google Analytics](https://analytics.google.com/analytics/web/#/report-home/a105170809w198079555p192782995).

9
docs/developer-guide/extensions/proxy-extensions.md
View file

@ -1,9 +1,10 @@
# Proxy Extensions
!!! warning "Beta Feature (Since 2.7.0)"
This feature is in the [Beta](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#beta) stage.
It is generally considered stable, but there may be unhandled edge cases.
> [!WARNING]
> **Beta Feature (Since 2.7.0)**
>
> This feature is in the [Beta](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#beta) stage.
> It is generally considered stable, but there may be unhandled edge cases.
## Overview

4
docs/developer-guide/faq.md
View file

@ -6,8 +6,8 @@
Sure thing! You can either open an Enhancement Proposal in our GitHub issue tracker or you can [join us on Slack](https://argoproj.github.io/community/join-slack) in channel #argo-contributors to discuss your ideas and get guidance for submitting a PR.
!!! note
Regular [contributor meetings](https://argo-cd.readthedocs.io/en/latest/developer-guide/code-contributions/#regular-contributor-meeting) are held weekly. Please follow the link for more details.
> [!NOTE]
> Regular [contributor meetings](https://argo-cd.readthedocs.io/en/latest/developer-guide/code-contributions/#regular-contributor-meeting) are held weekly. Please follow the link for more details.
### No one has looked at my PR yet. Why?

14
docs/developer-guide/index.md
View file

@ -1,10 +1,12 @@
# Overview
!!! warning "As an Argo CD user, you probably don't want to be reading this section of the docs."
This part of the manual is aimed at helping people contribute to Argo CD, documentation, or to develop third-party applications that interact with Argo CD, e.g.
* A chat bot
* A Slack integration
> [!WARNING]
> **As an Argo CD user, you probably don't want to be reading this section of the docs.**
>
> This part of the manual is aimed at helping people contribute to Argo CD, documentation, or to develop third-party applications that interact with Argo CD, e.g.
>
> * A chat bot
> * A Slack integration
## Preface
#### Understand the [Code Contribution Guide](code-contributions.md)
@ -100,4 +102,4 @@ Need help? Start with the [Contributors FAQ](faq/)
* [Config Management Plugins](../operator-manual/config-management-plugins/)
## Contributing to Argo Website
The Argo website is maintained in the [argo-site](https://github.com/argoproj/argo-site) repository.
The Argo website is maintained in the [argo-site](https://github.com/argoproj/argo-site) repository.

14
docs/developer-guide/releasing.md
View file

@ -71,17 +71,17 @@ Example:
./hack/trigger-release.sh v2.7.2 upstream
```
!!! tip
The tag must be in one of the following formats to trigger the GH workflow:<br>
* GA: `v<MAJOR>.<MINOR>.<PATCH>`<br>
* Pre-release: `v<MAJOR>.<MINOR>.<PATCH>-rc<RC#>`
> [!TIP]
> The tag must be in one of the following formats to trigger the GH workflow:<br>
> * GA: `v<MAJOR>.<MINOR>.<PATCH>`<br>
> * Pre-release: `v<MAJOR>.<MINOR>.<PATCH>-rc<RC#>`
Once the script is executed successfully, a GitHub workflow will start
execution. You can follow its progress under the [Actions](https://github.com/argoproj/argo-cd/actions/workflows/release.yaml) tab, the name of the action is `Publish ArgoCD Release`.
!!! warning
You cannot perform more than one release on the same release branch at the
same time.
> [!WARNING]
> You cannot perform more than one release on the same release branch at the
> same time.
### Verifying automated release

4
docs/developer-guide/running-locally.md
View file

@ -230,8 +230,8 @@ make manifests-local
(depending on your toolchain) to build a new set of installation manifests which include your specific image reference.
!!!note
Do not commit these manifests to your repository. If you want to revert the changes, the easiest way is to unset `IMAGE_NAMESPACE` and `IMAGE_TAG` from your environment and run `make manifests` again. This will re-create the default manifests.
> [!NOTE]
> Do not commit these manifests to your repository. If you want to revert the changes, the easiest way is to unset `IMAGE_NAMESPACE` and `IMAGE_TAG` from your environment and run `make manifests` again. This will re-create the default manifests.
#### Configure your cluster with custom manifests

16
docs/developer-guide/submit-your-pr.md
View file

@ -7,11 +7,13 @@
## Preface
!!!note "Before you start"
The Argo CD project continuously grows, both in terms of features and community size. It gets adopted by more and more organizations which entrust Argo CD to handle their critical production workloads. Thus, we need to take great care with any changes that affect compatibility, performance, scalability, stability and security of Argo CD. For this reason, every new feature or larger enhancement must be properly designed and discussed before it gets accepted into the code base.
We do welcome and encourage everyone to participate in the Argo CD project, but please understand that we can't accept each and every contribution from the community, for various reasons. If you want to submit code for a great new feature or enhancement, we kindly ask you to take a look at the
[code contribution guide](code-contributions.md#) before you start to write code or submit a PR.
> [!NOTE]
> **Before you start**
>
> The Argo CD project continuously grows, both in terms of features and community size. It gets adopted by more and more organizations which entrust Argo CD to handle their critical production workloads. Thus, we need to take great care with any changes that affect compatibility, performance, scalability, stability and security of Argo CD. For this reason, every new feature or larger enhancement must be properly designed and discussed before it gets accepted into the code base.
>
> We do welcome and encourage everyone to participate in the Argo CD project, but please understand that we can't accept each and every contribution from the community, for various reasons. If you want to submit code for a great new feature or enhancement, we kindly ask you to take a look at the
> [code contribution guide](code-contributions.md#) before you start to write code or submit a PR.
If you want to submit a PR, please read this document carefully, as it contains important information guiding you through our PR quality gates.
@ -34,8 +36,8 @@ make pre-commit-local
When you submit a PR against Argo CD's GitHub repository, a couple of CI checks will be run automatically to ensure your changes will build fine and meet certain quality standards. Your contribution needs to pass those checks in order to be merged into the repository.
!!!note
Please make sure that you always create PRs from a branch that is up-to-date with the latest changes from Argo CD's master branch. Depending on how long it takes for the maintainers to review and merge your PR, it might be necessary to pull in latest changes into your branch again.
> [!NOTE]
> Please make sure that you always create PRs from a branch that is up-to-date with the latest changes from Argo CD's master branch. Depending on how long it takes for the maintainers to review and merge your PR, it might be necessary to pull in latest changes into your branch again.
Please understand that we, as an Open Source project, have limited capacities for reviewing and merging PRs to Argo CD. We will do our best to review your PR and give you feedback as soon as possible, but please bear with us if it takes a little longer as expected.

22
docs/developer-guide/test-e2e.md
View file

@ -6,16 +6,18 @@ namespace `argocd-e2e***` is created prior to the execution of the tests. The th
The [/test/e2e/testdata](https://github.com/argoproj/argo-cd/tree/master/test/e2e/testdata) directory contains various Argo CD applications. Before test execution, the directory is copied into `/tmp/argo-e2e***` temp directory and used in tests as a
Git repository via file url: `file:///tmp/argo-e2e***`.
!!! note "Rancher Desktop Volume Sharing"
The e2e git server runs in a container. If you are using Rancher Desktop, you will need to enable volume sharing for
the e2e container to access the testdata directory. To do this, add the following to
`~/Library/Application\ Support/rancher-desktop/lima/_config/override.yaml` and restart Rancher Desktop:
```yaml
mounts:
- location: /private/tmp
writable: true
```
> [!NOTE]
> **Rancher Desktop Volume Sharing**
>
> The e2e git server runs in a container. If you are using Rancher Desktop, you will need to enable volume sharing for
> the e2e container to access the testdata directory. To do this, add the following to
> `~/Library/Application\ Support/rancher-desktop/lima/_config/override.yaml` and restart Rancher Desktop:
>
> ```yaml
> mounts:
> - location: /private/tmp
> writable: true
> ```
## Running Tests Locally

4
docs/developer-guide/toolchain-guide.md
View file

@ -120,8 +120,8 @@ Goreman is used to start all needed processes to get a working Argo CD developme
#### Install required dependencies and build-tools
!!!note
The installations instructions are valid for Linux hosts only. Mac instructions will follow shortly.
> [!NOTE]
> The installations instructions are valid for Linux hosts only. Mac instructions will follow shortly.
For installing the tools required to build and test Argo CD on your local system, we provide convenient installer scripts. By default, they will install binaries to `/usr/local/bin` on your system, which might require `root` privileges.

25
docs/faq.md
View file

@ -53,10 +53,14 @@ a secret named `argocd-initial-admin-secret`.
To change the password, edit the `argocd-secret` secret and update the `admin.password` field with a new bcrypt hash.
!!! note "Generating a bcrypt hash"
Use the following command to generate a bcrypt hash for `admin.password`
argocd account bcrypt --password <YOUR-PASSWORD-HERE>
> [!NOTE]
> **Generating a bcrypt hash**
>
> Use the following command to generate a bcrypt hash for `admin.password`
>
> ```shell
> argocd account bcrypt --password <YOUR-PASSWORD-HERE>
> ```
To apply the new password hash, use the following command (replacing the hash with your own):
@ -140,8 +144,8 @@ Argo CD automatically sets the `app.kubernetes.io/instance` label and uses it to
If the tool does this too, this causes confusion. You can change this label by setting
the `application.instanceLabelKey` value in the `argocd-cm`. We recommend that you use `argocd.argoproj.io/instance`.
!!! note
When you make this change your applications will become out of sync and will need re-syncing.
> [!NOTE]
> When you make this change your applications will become out of sync and will need re-syncing.
See [#1482](https://github.com/argoproj/argo-cd/issues/1482).
@ -199,7 +203,8 @@ If you're not running in a production system (e.g. you're testing Argo CD out),
argocd ... --insecure
```
!!! warning "Do not use `--insecure` in production"
> [!WARNING]
> Do not use `--insecure` in production.
## I have configured Dex via `dex.config` in `argocd-cm`, it still says Dex is unconfigured. Why?
@ -266,8 +271,10 @@ In this case, the duplicated keys have been **emphasized** to help you identify
The most common instance of this error is with `env:` fields for `containers`.
!!! note "Dynamic applications"
It's possible that your application is being generated by a tool in which case the duplication might not be evident within the scope of a single file. If you have trouble debugging this problem, consider filing a ticket to the owner of the generator tool asking them to improve its validation and error reporting.
> [!NOTE]
> **Dynamic applications**
>
> It's possible that your application is being generated by a tool in which case the duplication might not be evident within the scope of a single file. If you have trouble debugging this problem, consider filing a ticket to the owner of the generator tool asking them to improve its validation and error reporting.
## How to rotate Redis secret?
* Delete `argocd-redis` secret in the namespace where Argo CD is installed.

56
docs/getting_started.md
View file

@ -1,7 +1,7 @@
# Getting Started
!!! tip
This guide assumes you have a grounding in the tools that Argo CD is based on. Please read [understanding the basics](understand_the_basics.md) to learn about these tools.
> [!TIP]
> This guide assumes you have a grounding in the tools that Argo CD is based on. Please read [understanding the basics](understand_the_basics.md) to learn about these tools.
## Requirements
@ -18,12 +18,12 @@ kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/st
This will create a new namespace, `argocd`, where Argo CD services and application resources will live.
!!! 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.
> [!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.
!!! tip
If you are not interested in UI, SSO, and multi-cluster features, then you can install only the [core](operator-manual/core.md#installing) Argo CD components.
> [!TIP]
> If you are not interested in UI, SSO, and multi-cluster features, then you can install only the [core](operator-manual/core.md#installing) Argo CD components.
This default installation will have a self-signed certificate and cannot be accessed without a bit of extra work.
Do one of:
@ -32,16 +32,18 @@ Do one of:
* Configure the client OS to trust the self signed certificate.
* Use the --insecure flag on all Argo CD CLI operations in this guide.
!!! note
Default namespace for `kubectl` config must be set to `argocd`.
This is only needed for the following commands since the previous commands have -n argocd already:
`kubectl config set-context --current --namespace=argocd`
> [!NOTE]
> Default namespace for `kubectl` config must be set to `argocd`.
> This is only needed for the following commands since the previous commands have -n argocd already:
>
> ```shell
> kubectl config set-context --current --namespace=argocd
> ```
Use `argocd login --core` to [configure](./user-guide/commands/argocd_login.md) CLI access and skip steps 3-5.
!!! note
This default installation for Redis is using password authentication. The Redis password is stored in Kubernetes secret `argocd-redis` with key `auth` in the namespace where Argo CD is installed.
> [!NOTE]
> This default installation for Redis is using password authentication. The Redis password is stored in Kubernetes secret `argocd-redis` with key `auth` in the namespace where Argo CD is installed.
## 2. Download Argo CD CLI
@ -94,12 +96,12 @@ using the `argocd` CLI:
argocd admin initial-password -n argocd
```
!!! warning
You should delete the `argocd-initial-admin-secret` from the Argo CD
namespace once you changed the password. The secret serves no other
purpose than to store the initially generated password in clear and can
safely be deleted at any time. It will be re-created on demand by Argo CD
if a new admin password must be re-generated.
> [!WARNING]
> You should delete the `argocd-initial-admin-secret` from the Argo CD
> namespace once you changed the password. The secret serves no other
> purpose than to store the initially generated password in clear and can
> safely be deleted at any time. It will be re-created on demand by Argo CD
> if a new admin password must be re-generated.
Using the username `admin` and the password from above, login to Argo CD's IP or hostname:
@ -107,8 +109,8 @@ Using the username `admin` and the password from above, login to Argo CD's IP or
argocd login <ARGOCD_SERVER>
```
!!! note
The CLI environment must be able to communicate with the Argo CD API server. If it isn't directly accessible as described above in step 3, you can tell the CLI to access it using port forwarding through one of these mechanisms: 1) add `--port-forward-namespace argocd` flag to every CLI command; or 2) set `ARGOCD_OPTS` environment variable: `export ARGOCD_OPTS='--port-forward-namespace argocd'`.
> [!NOTE]
> The CLI environment must be able to communicate with the Argo CD API server. If it isn't directly accessible as described above in step 3, you can tell the CLI to access it using port forwarding through one of these mechanisms: 1) add `--port-forward-namespace argocd` flag to every CLI command; or 2) set `ARGOCD_OPTS` environment variable: `export ARGOCD_OPTS='--port-forward-namespace argocd'`.
Change the password using the command:
@ -137,17 +139,17 @@ The above command installs a ServiceAccount (`argocd-manager`), into the kube-sy
that kubectl context, and binds the service account to an admin-level ClusterRole. Argo CD uses this
service account token to perform its management tasks (i.e. deploy/monitoring).
!!! note
The rules of the `argocd-manager-role` role can be modified such that it only has `create`, `update`, `patch`, `delete` privileges to a limited set of namespaces, groups, kinds.
However `get`, `list`, `watch` privileges are required at the cluster-scope for Argo CD to function.
> [!NOTE]
> The rules of the `argocd-manager-role` role can be modified such that it only has `create`, `update`, `patch`, `delete` privileges to a limited set of namespaces, groups, kinds.
> However `get`, `list`, `watch` privileges are required at the cluster-scope for Argo CD to function.
## 6. Create An Application From A Git Repository
An example repository containing a guestbook application is available at
[https://github.com/argoproj/argocd-example-apps.git](https://github.com/argoproj/argocd-example-apps.git) to demonstrate how Argo CD works.
!!! note
Note: The following example application may only be compatible with AMD64 architecture. If you are running on a different architecture (such as ARM64 or ARMv7), you may encounter issues with dependencies or container images that are not built for your platform. Consider verifying the compatibility of the application or building architecture-specific images if necessary.
> [!NOTE]
> Note: The following example application may only be compatible with AMD64 architecture. If you are running on a different architecture (such as ARM64 or ARMv7), you may encounter issues with dependencies or container images that are not built for your platform. Consider verifying the compatibility of the application or building architecture-specific images if necessary.
### Creating Apps Via CLI

24
docs/operator-manual/app-any-namespace.md
View file

@ -1,7 +1,7 @@
# Applications in any namespace
!!! warning
Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
> [!WARNING]
> Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
## Introduction
@ -73,8 +73,8 @@ kubectl apply -k examples/k8s-rbac/argocd-server-applications/
`argocd-notifications-controller-rbac-clusterrole.yaml` and `argocd-notifications-controller-rbac-clusterrolebinding.yaml` are used to support notifications controller to notify apps in all namespaces.
!!! note
At some later point in time, we may make this cluster role part of the default installation manifests.
> [!NOTE]
> At some later point in time, we may make this cluster role part of the default installation manifests.
### Allowing additional namespaces in an AppProject
@ -118,15 +118,15 @@ Also, the Argo CD API will enforce these constraints, regardless of the Argo CD
The `.spec.sourceNamespaces` field of the `AppProject` is a list that can contain an arbitrary amount of namespaces, and each entry supports shell-style wildcard, so that you can allow namespaces with patterns like `team-one-*`.
!!! warning
Do not add user controlled namespaces in the `.spec.sourceNamespaces` field of any privileged AppProject like the `default` project. Always make sure that the AppProject follows the principle of granting least required privileges. Never grant access to the `argocd` namespace within the AppProject.
> [!WARNING]
> Do not add user controlled namespaces in the `.spec.sourceNamespaces` field of any privileged AppProject like the `default` project. Always make sure that the AppProject follows the principle of granting least required privileges. Never grant access to the `argocd` namespace within the AppProject.
!!! note
For backwards compatibility, Applications in the Argo CD control plane's namespace (`argocd`) are allowed to set their `.spec.project` field to reference any AppProject, regardless of the restrictions placed by the AppProject's `.spec.sourceNamespaces` field.
!!! note
Currently it's not possible to have a applicationset in one namespace and have the application
be generated in another. See [#11104](https://github.com/argoproj/argo-cd/issues/11104) for more info.
> [!NOTE]
> For backwards compatibility, Applications in the Argo CD control plane's namespace (`argocd`) are allowed to set their `.spec.project` field to reference any AppProject, regardless of the restrictions placed by the AppProject's `.spec.sourceNamespaces` field.
> [!NOTE]
> Currently it's not possible to have a applicationset in one namespace and have the application
> be generated in another. See [#11104](https://github.com/argoproj/argo-cd/issues/11104) for more info.
### Application names

28
docs/operator-manual/app-sync-using-impersonation.md
View file

@ -1,13 +1,15 @@
# Application Sync using impersonation
!!! warning "Alpha Feature (Since 2.13.0)"
This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha)
feature that allows you to control the service account used for the sync operation. The configured service account
could have lesser privileges required for creating resources compared to the highly privileged access required for
the control plane operations.
> [!WARNING]
> **Alpha Feature (Since 2.13.0)**
>
> This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha)
> feature that allows you to control the service account used for the sync operation. The configured service account
> could have lesser privileges required for creating resources compared to the highly privileged access required for
> the control plane operations.
!!! warning
Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
> [!WARNING]
> Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
## Introduction
@ -17,8 +19,8 @@ By default, application syncs in Argo CD have the same privileges as the Argo CD
Some manual steps will need to be performed by the Argo CD administrator in order to enable this feature, as it is disabled by default.
!!! note
This feature is considered alpha as of now. Some of the implementation details may change over the course of time until it is promoted to a stable status. We will be happy if early adopters use this feature and provide us with bug reports and feedback.
> [!NOTE]
> This feature is considered alpha as of now. Some of the implementation details may change over the course of time until it is promoted to a stable status. We will be happy if early adopters use this feature and provide us with bug reports and feedback.
### What is Impersonation
@ -65,11 +67,11 @@ data:
application.sync.impersonation.enabled: "false"
```
!!! note
This feature is disabled by default.
> [!NOTE]
> This feature is disabled by default.
!!! note
This feature can be enabled/disabled only at the system level and once enabled/disabled it is applicable to all Applications managed by ArgoCD.
> [!NOTE]
> This feature can be enabled/disabled only at the system level and once enabled/disabled it is applicable to all Applications managed by ArgoCD.
## Configuring destination service accounts

12
docs/operator-manual/applicationset/Application-Deletion.md
View file

@ -15,15 +15,15 @@ The end result is that when an ApplicationSet is deleted, the following occurs (
Thus the lifecycle of the `ApplicationSet`, the `Application`, and the `Application`'s resources, are equivalent.
!!! note
See also the [controlling resource modification](Controlling-Resource-Modification.md) page for more information about how to prevent deletion or modification of Application resources by the ApplicationSet controller.
> [!NOTE]
> See also the [controlling resource modification](Controlling-Resource-Modification.md) page for more information about how to prevent deletion or modification of Application resources by the ApplicationSet controller.
It *is* still possible to delete an `ApplicationSet` resource, while preventing `Application`s (and their deployed resources) from also being deleted, using a non-cascading delete:
```
kubectl delete ApplicationSet (NAME) --cascade=orphan
```
!!! warning
Even if using a non-cascaded delete, the `resources-finalizer.argocd.argoproj.io` is still specified on the `Application`. Thus, when the `Application` is deleted, all of its deployed resources will also be deleted. (The lifecycle of the Application, and its *child* objects, are still equivalent.)
To prevent the deletion of the resources of the Application, such as Services, Deployments, etc, set `.syncPolicy.preserveResourcesOnDeletion` to true in the ApplicationSet. This syncPolicy parameter prevents the finalizer from being added to the Application.
> [!WARNING]
> Even if using a non-cascaded delete, the `resources-finalizer.argocd.argoproj.io` is still specified on the `Application`. Thus, when the `Application` is deleted, all of its deployed resources will also be deleted. (The lifecycle of the Application, and its *child* objects, are still equivalent.)
>
> To prevent the deletion of the resources of the Application, such as Services, Deployments, etc, set `.syncPolicy.preserveResourcesOnDeletion` to true in the ApplicationSet. This syncPolicy parameter prevents the finalizer from being added to the Application.

22
docs/operator-manual/applicationset/Appset-Any-Namespace.md
View file

@ -1,11 +1,13 @@
# ApplicationSet in any namespace
!!! warning "Beta Feature (Since v2.8.0)"
This feature is in the [Beta](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#beta) stage.
It is generally considered stable, but there may be unhandled edge cases.
> [!WARNING]
> **Beta Feature (Since v2.8.0)**
>
> This feature is in the [Beta](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#beta) stage.
> It is generally considered stable, but there may be unhandled edge cases.
!!! warning
Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
> [!WARNING]
> Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
## Introduction
@ -70,12 +72,12 @@ data:
applicationsetcontroller.allowed.scm.providers: https://git.mydomain.com/,https://gitlab.mydomain.com/
```
!!! note
Please note url used in the `api` field of the `ApplicationSet` must match the url declared by the Administrator including the protocol
> [!NOTE]
> Please note url used in the `api` field of the `ApplicationSet` must match the url declared by the Administrator including the protocol
!!! warning
The allow-list only applies to SCM providers for which the user may configure a custom `api`. Where an SCM or PR
generator does not accept a custom API URL, the provider is implicitly allowed.
> [!WARNING]
> The allow-list only applies to SCM providers for which the user may configure a custom `api`. Where an SCM or PR
> generator does not accept a custom API URL, the provider is implicitly allowed.
If you do not intend to allow users to use the SCM or PR generators, you can disable them entirely by setting the environment variable `ARGOCD_APPLICATIONSET_CONTROLLER_ENABLE_SCM_PROVIDERS` to argocd-cmd-params-cm `applicationsetcontroller.enable.scm.providers` to `false`.

8
docs/operator-manual/applicationset/Argo-CD-Integration.md
View file

@ -10,9 +10,11 @@ Thus the ApplicationSet controller:
- Does not connect to clusters other than the one Argo CD is deployed to
- Does not interact with namespaces other than the one Argo CD is deployed within
!!!important "Use the Argo CD namespace"
All ApplicationSet resources and the ApplicationSet controller must be installed in the same namespace as Argo CD.
ApplicationSet resources in a different namespace will be ignored.
> [!IMPORTANT]
> **Use the Argo CD namespace**
>
> All ApplicationSet resources and the ApplicationSet controller must be installed in the same namespace as Argo CD.
> ApplicationSet resources in a different namespace will be ignored.
It is Argo CD itself that is responsible for the actual deployment of the generated child `Application` resources, such as Deployments, Services, and ConfigMaps.

26
docs/operator-manual/applicationset/Controlling-Resource-Modification.md
View file

@ -198,12 +198,12 @@ spec:
targetRevision: main
```
!!! note
[Future improvements](https://github.com/argoproj/argo-cd/issues/15975) to the ApplicationSet controller may
eliminate this problem. For example, the `ref` field might be made a merge key, allowing the ApplicationSet
controller to generate and use a StrategicMergePatch instead of a MergePatch. You could then target a specific
source by `ref`, ignore changes to a field in that source, and changes to other sources would not cause the ignored
field to be overwritten.
> [!NOTE]
> [Future improvements](https://github.com/argoproj/argo-cd/issues/15975) to the ApplicationSet controller may
> eliminate this problem. For example, the `ref` field might be made a merge key, allowing the ApplicationSet
> controller to generate and use a StrategicMergePatch instead of a MergePatch. You could then target a specific
> source by `ref`, ignore changes to a field in that source, and changes to other sources would not cause the ignored
> field to be overwritten.
## Prevent an `Application`'s child resources from being deleted, when the parent Application is deleted
@ -288,10 +288,10 @@ kubectl apply -n argocd -f install.yaml
## Preserving changes made to an Applications annotations and labels
!!! note
The same behavior can be achieved on a per-app basis using the [`ignoreApplicationDifferences`](#ignore-certain-changes-to-applications)
feature described above. However, preserved fields may be configured globally, a feature that is not yet available
for `ignoreApplicationDifferences`.
> [!NOTE]
> The same behavior can be achieved on a per-app basis using the [`ignoreApplicationDifferences`](#ignore-certain-changes-to-applications)
> feature described above. However, preserved fields may be configured globally, a feature that is not yet available
> for `ignoreApplicationDifferences`.
It is common practice in Kubernetes to store state in annotations, operators will often make use of this. To allow for this, it is possible to configure a list of annotations that the ApplicationSet should preserve when reconciling.
@ -325,9 +325,9 @@ The ApplicationSet controller will leave this annotation and label as-is when re
By default, the Argo CD notifications and the Argo CD refresh type annotations are also preserved.
!!!note
One can also set global preserved fields for the controller by passing a comma separated list of annotations and labels to
`ARGOCD_APPLICATIONSET_CONTROLLER_GLOBAL_PRESERVED_ANNOTATIONS` and `ARGOCD_APPLICATIONSET_CONTROLLER_GLOBAL_PRESERVED_LABELS` respectively.
> [!NOTE]
> One can also set global preserved fields for the controller by passing a comma separated list of annotations and labels to
> `ARGOCD_APPLICATIONSET_CONTROLLER_GLOBAL_PRESERVED_ANNOTATIONS` and `ARGOCD_APPLICATIONSET_CONTROLLER_GLOBAL_PRESERVED_LABELS` respectively.
## Debugging unexpected changes to Applications

10
docs/operator-manual/applicationset/Generators-Cluster-Decision-Resource.md
View file

@ -79,7 +79,9 @@ The ApplicationSet needs to be created in the Argo CD namespace, placing the `Co
The ClusterDecisionResource generator passes the 'name', 'server' and any other key/value in the duck-type resource's status list as parameters into the ApplicationSet template. In this example, the decision array contained an additional key `clusterName`, which is now available to the ApplicationSet template.
!!! note "Clusters listed as `Status.Decisions` must be predefined in Argo CD"
The cluster names listed in the `Status.Decisions` *must* be defined within Argo CD, in order to generate applications for these values. The ApplicationSet controller does not create clusters within Argo CD.
The Default Cluster list key is `clusters`.
> [!NOTE]
> **Clusters listed as `Status.Decisions` must be predefined in Argo CD**
>
> The cluster names listed in the `Status.Decisions` *must* be defined within Argo CD, in order to generate applications for these values. The ApplicationSet controller does not create clusters within Argo CD.
>
> The Default Cluster list key is `clusters`.

10
docs/operator-manual/applicationset/Generators-Cluster.md
View file

@ -13,8 +13,8 @@ It automatically provides the following parameter values to the Application temp
- `metadata.labels.<key>` *(for each label in the Secret)*
- `metadata.annotations.<key>` *(for each annotation in the Secret)*
!!! note
Use the `nameNormalized` parameter if your cluster name contains characters (such as underscores) that are not valid for Kubernetes resource names. This prevents rendering invalid Kubernetes resources with names like `my_cluster-app1`, and instead would convert them to `my-cluster-app1`.
> [!NOTE]
> Use the `nameNormalized` parameter if your cluster name contains characters (such as underscores) that are not valid for Kubernetes resource names. This prevents rendering invalid Kubernetes resources with names like `my_cluster-app1`, and instead would convert them to `my-cluster-app1`.
Within [Argo CD cluster Secrets](../../declarative-setup/#clusters) are data fields describing the cluster:
@ -203,8 +203,8 @@ spec:
In this example the `revision` value from the `generators.clusters` fields is passed into the template as `values.revision`, containing either `HEAD` or `stable` (based on which generator generated the set of parameters).
!!! note
The `values.` prefix is always prepended to values provided via `generators.clusters.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
> [!NOTE]
> The `values.` prefix is always prepended to values provided via `generators.clusters.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
In `values` we can also interpolate the following parameter values (i.e. the same values as presented in the beginning of this page)
@ -312,4 +312,4 @@ spec:
- name: cluster2
```
In case you are using several cluster generators, each with the flatList option, one Application would be generated by cluster generator, as we can't simply merge values and templates that would potentially differ in each generator.
In case you are using several cluster generators, each with the flatList option, one Application would be generated by cluster generator, as we can't simply merge values and templates that would potentially differ in each generator.

62
docs/operator-manual/applicationset/Generators-Git.md
View file

@ -2,14 +2,13 @@
The Git generator contains two subtypes: the Git directory generator, and Git file generator.
!!! warning
Git generators are often used to make it easier for (non-admin) developers to create Applications.
If the `project` field in your ApplicationSet is templated, developers may be able to create Applications under Projects with excessive permissions.
For ApplicationSets with a templated `project` field, [the source of truth _must_ be controlled by admins](./Security.md#templated-project-field)
- in the case of git generators, PRs must require admin approval.
- Git generator does not support Signature Verification For ApplicationSets with a templated `project` field.
- You must only use "non-scoped" repositories for ApplicationSets with a templated `project` field (see ["Repository Credentials for Applicationsets" below](#repository-credentials-for-applicationsets)).
> [!WARNING]
> Git generators are often used to make it easier for (non-admin) developers to create Applications.
> If the `project` field in your ApplicationSet is templated, developers may be able to create Applications under Projects with excessive permissions.
> For ApplicationSets with a templated `project` field, [the source of truth _must_ be controlled by admins](./Security.md#templated-project-field)
> - in the case of git generators, PRs must require admin approval.
> - Git generator does not support Signature Verification For ApplicationSets with a templated `project` field.
> - You must only use "non-scoped" repositories for ApplicationSets with a templated `project` field (see ["Repository Credentials for Applicationsets" below](#repository-credentials-for-applicationsets)).
## Git Generator: Directories
@ -121,11 +120,12 @@ spec:
This example excludes the `exclude-helm-guestbook` directory from the list of directories scanned for this `ApplicationSet` resource.
!!! note "Exclude rules have higher priority than include rules"
If a directory matches at least one `exclude` pattern, it will be excluded. Or, said another way, *exclude rules take precedence over include rules.*
As a corollary, which directories are included/excluded is not affected by the order of `path`s in the `directories` field list (because, as above, exclude rules always take precedence over include rules).
> [!NOTE]
> **Exclude rules have higher priority than include rules**
>
> If a directory matches at least one `exclude` pattern, it will be excluded. Or, said another way, *exclude rules take precedence over include rules.*
>
> As a corollary, which directories are included/excluded is not affected by the order of `path`s in the `directories` field list (because, as above, exclude rules always take precedence over include rules).
For example, with these directories:
@ -237,8 +237,8 @@ spec:
namespace: '{{.values.cluster}}'
```
!!! note
The `values.` prefix is always prepended to values provided via `generators.git.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
> [!NOTE]
> The `values.` prefix is always prepended to values provided via `generators.git.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
In `values` we can also interpolate all fields set by the git directory generator as mentioned above.
@ -417,8 +417,8 @@ spec:
namespace: guestbook
```
!!! note
The `values.` prefix is always prepended to values provided via `generators.git.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
> [!NOTE]
> The `values.` prefix is always prepended to values provided via `generators.git.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
In `values` we can also interpolate all fields set by the git files generator as mentioned above.
@ -431,16 +431,16 @@ different default value is set by the
You can customize this interval per ApplicationSet using
`requeueAfterSeconds`.
!!!note
The Git generator uses the ArgoCD Repo Server to retrieve file
and directory lists from Git. Therefore, the Git generator is
affected by the Repo Server's Revision Cache Expiration setting
(see the description of the `timeout.reconciliation` parameter in
[argocd-cm.yaml](../argocd-cm-yaml.md/#:~:text=timeout.reconciliation%3A)).
If this value exceeds the configured Git Polling Interval, the
Git generator might not see files or directories from new commits
until the previous cache entry expires.
> [!NOTE]
> The Git generator uses the ArgoCD Repo Server to retrieve file
> and directory lists from Git. Therefore, the Git generator is
> affected by the Repo Server's Revision Cache Expiration setting
> (see the description of the `timeout.reconciliation` parameter in
> [argocd-cm.yaml](../argocd-cm-yaml.md/#:~:text=timeout.reconciliation%3A)).
> If this value exceeds the configured Git Polling Interval, the
> Git generator might not see files or directories from new commits
> until the previous cache entry expires.
>
## The `argocd.argoproj.io/application-set-refresh` Annotation
Setting the `argocd.argoproj.io/application-set-refresh` annotation
@ -475,8 +475,8 @@ spec:
# ...
```
!!! note
The ApplicationSet controller webhook does not use the same webhook as the API server as defined [here](../webhook.md). ApplicationSet exposes a webhook server as a service of type ClusterIP. An ApplicationSet specific Ingress resource needs to be created to expose this service to the webhook source.
> [!NOTE]
> The ApplicationSet controller webhook does not use the same webhook as the API server as defined [here](../webhook.md). ApplicationSet exposes a webhook server as a service of type ClusterIP. An ApplicationSet specific Ingress resource needs to be created to expose this service to the webhook source.
### 1. Create the webhook in the Git provider
@ -487,8 +487,8 @@ arbitrary value in the secret. This value will be used when configuring the webh
![Add Webhook](../../assets/applicationset/webhook-config.png "Add Webhook")
!!! note
When creating the webhook in GitHub, the "Content type" needs to be set to "application/json". The default value "application/x-www-form-urlencoded" is not supported by the library used to handle the hooks
> [!NOTE]
> When creating the webhook in GitHub, the "Content type" needs to be set to "application/json". The default value "application/x-www-form-urlencoded" is not supported by the library used to handle the hooks
### 2. Configure ApplicationSet with the webhook secret (Optional)

6
docs/operator-manual/applicationset/Generators-List.md
View file

@ -52,8 +52,10 @@ spec:
# (...)
```
!!! note "Clusters must be predefined in Argo CD"
These clusters *must* already be defined within Argo CD, in order to generate applications for these values. The ApplicationSet controller does not create clusters within Argo CD (for instance, it does not have the credentials to do so).
> [!NOTE]
> **Clusters must be predefined in Argo CD**
>
> These clusters *must* already be defined within Argo CD, in order to generate applications for these values. The ApplicationSet controller does not create clusters within Argo CD (for instance, it does not have the credentials to do so).
## Dynamically generated elements
The List generator can also dynamically generate its elements based on a yaml/json it gets from a previous generator like git by combining the two with a matrix generator. In this example we are using the matrix generator with a git followed by a list generator and pass the content of a file in git as input to the `elementsYaml` field of the list generator:

6
docs/operator-manual/applicationset/Generators-Plugin.md
View file

@ -62,9 +62,9 @@ spec:
- `configMapRef.name`: A `ConfigMap` name containing the plugin configuration to use for RPC call.
- `input.parameters`: Input parameters included in the RPC call to the plugin. (Optional)
!!! note
The concept of the plugin should not undermine the spirit of GitOps by externalizing data outside of Git. The goal is to be complementary in specific contexts.
For example, when using one of the PullRequest generators, it's impossible to retrieve parameters related to the CI (only the commit hash is available), which limits the possibilities. By using a plugin, it's possible to retrieve the necessary parameters from a separate data source and use them to extend the functionality of the generator.
> [!NOTE]
> The concept of the plugin should not undermine the spirit of GitOps by externalizing data outside of Git. The goal is to be complementary in specific contexts.
> For example, when using one of the PullRequest generators, it's impossible to retrieve parameters related to the CI (only the commit hash is available), which limits the possibilities. By using a plugin, it's possible to retrieve the necessary parameters from a separate data source and use them to extend the functionality of the generator.
### Add a ConfigMap to configure the access of the plugin

18
docs/operator-manual/applicationset/Generators-Pull-Request.md
View file

@ -19,11 +19,11 @@ spec:
# ...
```
!!! note
Know the security implications of PR generators in ApplicationSets.
[Only admins may create ApplicationSets](./Security.md#only-admins-may-createupdatedelete-applicationsets) to avoid
leaking Secrets, and [only admins may create PRs](./Security.md#templated-project-field) if the `project` field of
an ApplicationSet with a PR generator is templated, to avoid granting management of out-of-bounds resources.
> [!NOTE]
> Know the security implications of PR generators in ApplicationSets.
> [Only admins may create ApplicationSets](./Security.md#only-admins-may-createupdatedelete-applicationsets) to avoid
> leaking Secrets, and [only admins may create PRs](./Security.md#templated-project-field) if the `project` field of
> an ApplicationSet with a PR generator is templated, to avoid granting management of out-of-bounds resources.
## GitHub
@ -452,8 +452,8 @@ When using a Pull Request generator, the ApplicationSet controller polls every `
The configuration is almost the same as the one described [in the Git generator](Generators-Git.md), but there is one difference: if you want to use the Pull Request Generator as well, additionally configure the following settings.
!!! note
The ApplicationSet controller webhook does not use the same webhook as the API server as defined [here](../webhook.md). ApplicationSet exposes a webhook server as a service of type ClusterIP. An ApplicationSet specific Ingress resource needs to be created to expose this service to the webhook source.
> [!NOTE]
> The ApplicationSet controller webhook does not use the same webhook as the API server as defined [here](../webhook.md). ApplicationSet exposes a webhook server as a service of type ClusterIP. An ApplicationSet specific Ingress resource needs to be created to expose this service to the webhook source.
### Github webhook configuration
@ -528,7 +528,7 @@ spec:
namespace: default
```
!!! note
The `values.` prefix is always prepended to values provided via `generators.pullRequest.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
> [!NOTE]
> The `values.` prefix is always prepended to values provided via `generators.pullRequest.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
In `values` we can also interpolate all fields set by the Pull Request generator as mentioned above.

14
docs/operator-manual/applicationset/Generators-SCM-Provider.md
View file

@ -19,11 +19,11 @@ spec:
* `cloneProtocol`: Which protocol to use for the SCM URL. Default is provider-specific but ssh if possible. Not all providers necessarily support all protocols, see provider documentation below for available options.
!!! note
Know the security implications of using SCM generators. [Only admins may create ApplicationSets](./Security.md#only-admins-may-createupdatedelete-applicationsets)
to avoid leaking Secrets, and [only admins may create repos/branches](./Security.md#templated-project-field) if the
`project` field of an ApplicationSet with an SCM generator is templated, to avoid granting management of
out-of-bounds resources.
> [!NOTE]
> Know the security implications of using SCM generators. [Only admins may create ApplicationSets](./Security.md#only-admins-may-createupdatedelete-applicationsets)
> to avoid leaking Secrets, and [only admins may create repos/branches](./Security.md#templated-project-field) if the
> `project` field of an ApplicationSet with an SCM generator is templated, to avoid granting management of
> out-of-bounds resources.
## GitHub
@ -492,7 +492,7 @@ spec:
namespace: default
```
!!! note
The `values.` prefix is always prepended to values provided via `generators.scmProvider.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
> [!NOTE]
> The `values.` prefix is always prepended to values provided via `generators.scmProvider.values` field. Ensure you include this prefix in the parameter name within the `template` when using it.
In `values` we can also interpolate all fields set by the SCM generator as mentioned above.

4
docs/operator-manual/applicationset/Getting-Started.md
View file

@ -57,8 +57,8 @@ How it works:
- After each successful commit to *argoproj/applicationset* `master` branch, a GitHub action will run that performs a container build/push to [`argoproj/argocd-applicationset:latest`](https://quay.io/repository/argoproj/argocd-applicationset?tab=tags )
- [Documentation for the `master`-branch-based developer builds](https://argocd-applicationset.readthedocs.io/en/master/) is available from Read the Docs.
!!! warning
Development builds contain newer features and bug fixes, but are more likely to be unstable, as compared to release builds.
> [!WARNING]
> Development builds contain newer features and bug fixes, but are more likely to be unstable, as compared to release builds.
See the `master` branch [Read the Docs](https://argocd-applicationset.readthedocs.io/en/master/) page for documentation on post-release features. -->

4
docs/operator-manual/applicationset/Progressive-Syncs.md
View file

@ -1,6 +1,8 @@
# Progressive Syncs
!!! warning "Alpha Feature (Since v2.6.0)"
> [!WARNING]
> **Alpha Feature (Since v2.6.0)**
>
This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha)
feature that allows you to control the order in which the ApplicationSet controller will create or update the Applications

26
docs/operator-manual/applicationset/Template.md
View file

@ -184,18 +184,18 @@ spec:
{{- end }}
```
!!! important
`templatePatch` only works when [go templating](../applicationset/GoTemplate.md) is enabled.
This means that the `goTemplate` field under `spec` needs to be set to `true` for template patching to work.
> [!IMPORTANT]
> `templatePatch` only works when [go templating](../applicationset/GoTemplate.md) is enabled.
> This means that the `goTemplate` field under `spec` needs to be set to `true` for template patching to work.
!!! important
The `templatePatch` can apply arbitrary changes to the template. If parameters include untrustworthy user input, it
may be possible to inject malicious changes into the template. It is recommended to use `templatePatch` only with
trusted input or to carefully escape the input before using it in the template. Piping input to `toJson` should help
prevent, for example, a user from successfully injecting a string with newlines.
> [!IMPORTANT]
> The `templatePatch` can apply arbitrary changes to the template. If parameters include untrustworthy user input, it
> may be possible to inject malicious changes into the template. It is recommended to use `templatePatch` only with
> trusted input or to carefully escape the input before using it in the template. Piping input to `toJson` should help
> prevent, for example, a user from successfully injecting a string with newlines.
>
> The `spec.project` field is not supported in `templatePatch`. If you need to change the project, you can use the
> `spec.project` field in the `template` field.
The `spec.project` field is not supported in `templatePatch`. If you need to change the project, you can use the
`spec.project` field in the `template` field.
!!! important
When writing a `templatePatch`, you're crafting a patch. So, if the patch includes an empty `spec: # nothing in here`, it will effectively clear out existing fields. See [#17040](https://github.com/argoproj/argo-cd/issues/17040) for an example of this behavior.
> [!IMPORTANT]
> When writing a `templatePatch`, you're crafting a patch. So, if the patch includes an empty `spec: # nothing in here`, it will effectively clear out existing fields. See [#17040](https://github.com/argoproj/argo-cd/issues/17040) for an example of this behavior.

4
docs/operator-manual/applicationset/index.md
View file

@ -15,8 +15,8 @@ The ApplicationSet controller, supplements Argo CD by adding additional features
- Improved support for monorepos: in the context of Argo CD, a monorepo is multiple Argo CD Application resources defined within a single Git repository
- Within multitenant clusters, improves the ability of individual cluster tenants to deploy applications using Argo CD (without needing to involve privileged cluster administrators in enabling the destination clusters/namespaces)
!!! note
Be aware of the [security implications](./Security.md) of ApplicationSets before using them.
> [!NOTE]
> Be aware of the [security implications](./Security.md) of ApplicationSets before using them.
## The ApplicationSet resource

14
docs/operator-manual/cluster-bootstrapping.md
View file

@ -4,12 +4,14 @@ This guide is for operators who have already installed Argo CD, and have a new c
There's no one particular pattern to solve this problem, e.g. you could write a script to create your apps, or you could even manually create them. However, users of Argo CD tend to use the **app of apps pattern**.
!!!warning "App of Apps is an admin-only tool"
The ability to create Applications in arbitrary [Projects](./declarative-setup.md#projects)
is an admin-level capability. Only admins should have push access to the parent Application's source repository.
Admins should review pull requests to that repository, paying particular attention to the `project` field in each
Application. Projects with access to the namespace in which Argo CD is installed effectively have admin-level
privileges.
> [!WARNING]
> **App of Apps is an admin-only tool**
>
> The ability to create Applications in arbitrary [Projects](./declarative-setup.md#projects)
> is an admin-level capability. Only admins should have push access to the parent Application's source repository.
> Admins should review pull requests to that repository, paying particular attention to the `project` field in each
> Application. Projects with access to the namespace in which Argo CD is installed effectively have admin-level
> privileges.
## App Of Apps Pattern

6
docs/operator-manual/cluster-management.md
View file

@ -19,5 +19,7 @@ Run `argocd cluster rm context-name`.
This removes the cluster with the specified name.
!!!note "in-cluster cannot be removed"
The `in-cluster` cluster cannot be removed with this. If you want to disable the `in-cluster` configuration, you need to update your `argocd-cm` ConfigMap. Set [`cluster.inClusterEnabled`](./argocd-cm-yaml.md) to `"false"`
> [!NOTE]
> **in-cluster cannot be removed**
>
> The `in-cluster` cluster cannot be removed with this. If you want to disable the `in-cluster` configuration, you need to update your `argocd-cm` ConfigMap. Set [`cluster.inClusterEnabled`](./argocd-cm-yaml.md) to `"false"`

86
docs/operator-manual/config-management-plugins.md
View file

@ -12,10 +12,10 @@ task of building manifests to the plugin.
The following sections will describe how to create, install, and use plugins. Check out the
[example plugins](https://github.com/argoproj/argo-cd/tree/master/examples/plugins) for additional guidance.
!!! warning
Plugins are granted a level of trust in the Argo CD system, so it is important to implement plugins securely. Argo
CD administrators should only install plugins from trusted sources, and they should audit plugins to weigh their
particular risks and benefits.
> [!WARNING]
> Plugins are granted a level of trust in the Argo CD system, so it is important to implement plugins securely. Argo
> CD administrators should only install plugins from trusted sources, and they should audit plugins to weigh their
> particular risks and benefits.
## Installing a config management plugin
@ -119,9 +119,9 @@ spec:
provideGitCreds: false
```
!!! note
While the ConfigManagementPlugin _looks like_ a Kubernetes object, it is not actually a custom resource.
It only follows kubernetes-style spec conventions.
> [!NOTE]
> While the ConfigManagementPlugin _looks like_ a Kubernetes object, it is not actually a custom resource.
> It only follows kubernetes-style spec conventions.
The `generate` command must print a valid Kubernetes YAML or JSON object stream to stdout. Both `init` and `generate` commands are executed inside the application source directory.
@ -207,10 +207,12 @@ volumes:
name: cmp-tmp
```
!!! important "Double-check these items"
1. Make sure to use `/var/run/argocd/argocd-cmp-server` as an entrypoint. The `argocd-cmp-server` is a lightweight GRPC service that allows Argo CD to interact with the plugin.
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.
> [!IMPORTANT]
> **Double-check these items**
>
> 1. Make sure to use `/var/run/argocd/argocd-cmp-server` as an entrypoint. The `argocd-cmp-server` is a lightweight GRPC service that allows Argo CD to interact with the plugin.
> 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
@ -276,9 +278,11 @@ Plugin commands have access to
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.
> [!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
@ -311,24 +315,26 @@ If you don't need to set any environment variables, you can set an empty plugin
plugin: {}
```
!!! important
If your CMP command runs too long, the command will be killed, and the UI will show an error. The CMP server
respects the timeouts set by the `server.repo.server.timeout.seconds` and `controller.repo.server.timeout.seconds`
items in `argocd-cm`. Increase their values from the default of 60s.
Each CMP command will also independently timeout on the `ARGOCD_EXEC_TIMEOUT` set for the CMP sidecar. The default
is 90s. So if you increase the repo server timeout greater than 90s, be sure to set `ARGOCD_EXEC_TIMEOUT` on the
sidecar.
> [!IMPORTANT]
> If your CMP command runs too long, the command will be killed, and the UI will show an error. The CMP server
> respects the timeouts set by the `server.repo.server.timeout.seconds` and `controller.repo.server.timeout.seconds`
> items in `argocd-cm`. Increase their values from the default of 60s.
>
> Each CMP command will also independently timeout on the `ARGOCD_EXEC_TIMEOUT` set for the CMP sidecar. The default
> is 90s. So if you increase the repo server timeout greater than 90s, be sure to set `ARGOCD_EXEC_TIMEOUT` on the
> sidecar.
!!! note
Each Application can only have one config management plugin configured at a time. If you're converting an existing
plugin configured through the `argocd-cm` ConfigMap to a sidecar, make sure to update the plugin name to either `<metadata.name>-<spec.version>`
if version was mentioned in the `ConfigManagementPlugin` spec or else just use `<metadata.name>`. You can also remove the name altogether
and let the automatic discovery to identify the plugin.
!!! note
If a CMP renders blank manfiests, and `prune` is set to `true`, Argo CD will automatically remove resources. CMP plugin authors should ensure errors are part of the exit code. Commonly something like `kustomize build . | cat` won't pass errors because of the pipe. Consider setting `set -o pipefail` so anything piped will pass errors on failure.
!!! note
If a CMP command fails to gracefully exit on `ARGOCD_EXEC_TIMEOUT`, it will be forcefully killed after an additional timeout of `ARGOCD_EXEC_FATAL_TIMEOUT`.
> [!NOTE]
> Each Application can only have one config management plugin configured at a time. If you're converting an existing
> plugin configured through the `argocd-cm` ConfigMap to a sidecar, make sure to update the plugin name to either `<metadata.name>-<spec.version>`
> if version was mentioned in the `ConfigManagementPlugin` spec or else just use `<metadata.name>`. You can also remove the name altogether
> and let the automatic discovery to identify the plugin.
> [!NOTE]
> If a CMP renders blank manfiests, and `prune` is set to `true`, Argo CD will automatically remove resources. CMP plugin authors should ensure errors are part of the exit code. Commonly something like `kustomize build . | cat` won't pass errors because of the pipe. Consider setting `set -o pipefail` so anything piped will pass errors on failure.
> [!NOTE]
> If a CMP command fails to gracefully exit on `ARGOCD_EXEC_TIMEOUT`, it will be forcefully killed after an additional timeout of `ARGOCD_EXEC_FATAL_TIMEOUT`.
## Debugging a CMP
@ -414,9 +420,9 @@ spec:
args: ["sample args"]
```
!!! note
The `lockRepo` key is not relevant for sidecar plugins, because sidecar plugins do not share a single source repo
directory when generating manifests.
> [!NOTE]
> The `lockRepo` key is not relevant for sidecar plugins, because sidecar plugins do not share a single source repo
> directory when generating manifests.
Next, we need to decide how this yaml is going to be added to the sidecar. We can either bake the yaml directly into the image, or we can mount it from a ConfigMap.
@ -491,9 +497,9 @@ Once tests have checked out, remove the plugin entry from your argocd-cm ConfigM
By default, config management plugin receives source repository files with reset file mode. This is done for security
reasons. If you want to preserve original file mode, you can set `preserveFileMode` to `true` in the plugin spec:
!!! warning
Make sure you trust the plugin you are using. If you set `preserveFileMode` to `true` then the plugin might receive
files with executable permissions which can be a security risk.
> [!WARNING]
> Make sure you trust the plugin you are using. If you set `preserveFileMode` to `true` then the plugin might receive
> files with executable permissions which can be a security risk.
```yaml
apiVersion: argoproj.io/v1alpha1
@ -527,9 +533,9 @@ To change the socket path, you must set the `ARGOCD_ASK_PASS_SOCK` environment v
To allow the plugin to access the reposerver git credentials, you can set `provideGitCreds` to `true` in the plugin spec:
!!! warning
Make sure you trust the plugin you are using. If you set `provideGitCreds` to `true` then the plugin will receive
credentials used to clone the source Git repository.
> [!WARNING]
> Make sure you trust the plugin you are using. If you set `provideGitCreds` to `true` then the plugin will receive
> credentials used to clone the source Git repository.
```yaml
apiVersion: argoproj.io/v1alpha1

80
docs/operator-manual/declarative-setup.md
View file

@ -21,8 +21,10 @@ All resources, including `Application` and `AppProject` specs, have to be instal
For each specific kind of ConfigMap and Secret resource, there is only a single supported resource name (as listed in the above table) - if you need to merge things you need to do it before creating them.
!!!warning "A note about ConfigMap resources"
Be sure to annotate your ConfigMap resources using the label `app.kubernetes.io/part-of: argocd`, otherwise Argo CD will not be able to use them.
> [!WARNING]
> **A note about ConfigMap resources**
>
> Be sure to annotate your ConfigMap resources using the label `app.kubernetes.io/part-of: argocd`, otherwise Argo CD will not be able to use them.
### Multiple configuration objects
@ -63,11 +65,11 @@ spec:
See [application.yaml](application.yaml) for additional fields. As long as you have completed the first step of [Getting Started](../getting_started.md#1-install-argo-cd), you can apply this with `kubectl apply -n argocd -f application.yaml` and Argo CD will start deploying the guestbook application.
!!! note
The namespace must match the namespace of your Argo CD instance - typically this is `argocd`.
> [!NOTE]
> The namespace must match the namespace of your Argo CD instance - typically this is `argocd`.
!!! note
When creating an application from a Helm repository, the `chart` attribute must be specified instead of the `path` attribute within `spec.source`.
> [!NOTE]
> When creating an application from a Helm repository, the `chart` attribute must be specified instead of the `path` attribute within `spec.source`.
```yaml
spec:
@ -77,8 +79,8 @@ spec:
chart: argo
```
!!! warning
Without the `resources-finalizer.argocd.argoproj.io` finalizer, deleting an application will not delete the resources it manages. To perform a cascading delete, you must add the finalizer. See [App Deletion](../user-guide/app_deletion.md#about-the-deletion-finalizer).
> [!WARNING]
> Without the `resources-finalizer.argocd.argoproj.io` finalizer, deleting an application will not delete the resources it manages. To perform a cascading delete, you must add the finalizer. See [App Deletion](../user-guide/app_deletion.md#about-the-deletion-finalizer).
```yaml
metadata:
@ -102,11 +104,13 @@ It is defined by the following key pieces of information:
* `destinations` reference to clusters and namespaces that applications within the project can deploy into.
* `roles` list of entities with definitions of their access to resources within the project.
!!!warning "Projects which can deploy to the Argo CD namespace grant admin access"
If a Project's `destinations` configuration allows deploying to the namespace in which Argo CD is installed, then
Applications under that project have admin-level access. [RBAC access](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/)
to admin-level Projects should be carefully restricted, and push access to allowed `sourceRepos` should be limited
to only admins.
> [!WARNING]
> **Projects which can deploy to the Argo CD namespace grant admin access**
>
> If a Project's `destinations` configuration allows deploying to the namespace in which Argo CD is installed, then
> Applications under that project have admin-level access. [RBAC access](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/)
> to admin-level Projects should be carefully restricted, and push access to allowed `sourceRepos` should be limited
> to only admins.
An example spec is as follows:
@ -168,19 +172,19 @@ spec:
## Repositories
!!!note
Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to
specify the `.git` suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the
repository URL suffixed with `.git`. Argo CD will **not** follow these redirects, so you have to
adjust your repository URL to be suffixed with `.git`.
> [!NOTE]
> Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to
> specify the `.git` suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the
> repository URL suffixed with `.git`. Argo CD will **not** follow these redirects, so you have to
> adjust your repository URL to be suffixed with `.git`.
Repository details are stored in secrets. To configure a repo, create a secret which contains repository details.
Consider using [bitnami-labs/sealed-secrets](https://github.com/bitnami-labs/sealed-secrets) to store an encrypted secret definition as a Kubernetes manifest.
Each repository must have a `url` field and, depending on whether you connect using HTTPS, SSH, or GitHub App, `username` and `password` (for HTTPS), `sshPrivateKey` (for SSH), or `githubAppPrivateKey` (for GitHub App).
Credentials can be scoped to a project using the optional `project` field. When omitted, the credential will be used as the default for all projects without a scoped credential.
!!!warning
When using [bitnami-labs/sealed-secrets](https://github.com/bitnami-labs/sealed-secrets) the labels will be removed and have to be readded as described here: https://github.com/bitnami-labs/sealed-secrets#sealedsecrets-as-templates-for-secrets
> [!WARNING]
> When using [bitnami-labs/sealed-secrets](https://github.com/bitnami-labs/sealed-secrets) the labels will be removed and have to be readded as described here: https://github.com/bitnami-labs/sealed-secrets#sealedsecrets-as-templates-for-secrets
Example for HTTPS:
@ -285,8 +289,8 @@ stringData:
}
```
!!! tip
The Kubernetes documentation has [instructions for creating a secret containing a private key](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-pod-with-ssh-keys).
> [!TIP]
> The Kubernetes documentation has [instructions for creating a secret containing a private key](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-pod-with-ssh-keys).
Example for Azure Container Registry/ Azure Devops repositories using Azure workload identity:
@ -340,8 +344,8 @@ In order for Argo CD to use a credential template for any given repository, the
* The repository must either not be configured at all, or if configured, must not contain any credential information (i.e. contain none of `sshPrivateKey`, `username`, `password` )
* The URL configured for a credential template (e.g. `https://github.com/argoproj`) must match as prefix for the repository URL (e.g. `https://github.com/argoproj/argocd-example-apps`).
!!! note
Matching credential template URL prefixes is done on a _best match_ effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration.
> [!NOTE]
> Matching credential template URL prefixes is done on a _best match_ effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration.
The following keys are valid to refer to credential secrets:
@ -422,8 +426,8 @@ data:
```
!!! note
The `argocd-tls-certs-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/tls` in the pods of `argocd-server` and `argocd-repo-server`. It will create files for each data key in the mount path directory, so above example would leave the file `/app/config/tls/server.example.com`, which contains the certificate data. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.
> [!NOTE]
> The `argocd-tls-certs-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/tls` in the pods of `argocd-server` and `argocd-repo-server`. It will create files for each data key in the mount path directory, so above example would leave the file `/app/config/tls/server.example.com`, which contains the certificate data. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.
### SSH known host public keys
@ -474,8 +478,8 @@ data:
vs-ssh.visualstudio.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
```
!!! note
The `argocd-ssh-known-hosts-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/ssh` in the pods of `argocd-server` and `argocd-repo-server`. It will create a file `ssh_known_hosts` in that directory, which contains the SSH known hosts data used by Argo CD for connecting to Git repositories via SSH. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.
> [!NOTE]
> The `argocd-ssh-known-hosts-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/ssh` in the pods of `argocd-server` and `argocd-repo-server`. It will create a file `ssh_known_hosts` in that directory, which contains the SSH known hosts data used by Argo CD for connecting to Git repositories via SSH. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.
### Configure repositories with proxy
@ -559,14 +563,14 @@ tlsClientConfig:
disableCompression: boolean
```
!!! important
When `namespaces` is set, Argo CD will perform a separate list/watch operation for each namespace. This can cause
the Application controller to exceed the maximum number of idle connections allowed for the Kubernetes API server.
To resolve this issue, you can increase the `ARGOCD_K8S_CLIENT_MAX_IDLE_CONNECTIONS` environment variable in the
Application controller.
> [!IMPORTANT]
> When `namespaces` is set, Argo CD will perform a separate list/watch operation for each namespace. This can cause
> the Application controller to exceed the maximum number of idle connections allowed for the Kubernetes API server.
> To resolve this issue, you can increase the `ARGOCD_K8S_CLIENT_MAX_IDLE_CONNECTIONS` environment variable in the
> Application controller.
!!! important
Note that if you specify a command to run under `execProviderConfig`, that command must be available in the Argo CD image. See [BYOI (Build Your Own Image)](custom_tools.md#byoi-build-your-own-image).
> [!IMPORTANT]
> Note that if you specify a command to run under `execProviderConfig`, that command must be available in the Argo CD image. See [BYOI (Build Your Own Image)](custom_tools.md#byoi-build-your-own-image).
Cluster secret example:
@ -687,7 +691,7 @@ The 3 service accounts need to be modified to include an annotation with the Arg
Here's an example service account configurations for `argocd-application-controller`, `argocd-applicationset-controller`, and `argocd-server`.
!!! warning
> [!WARNING]
Once the annotations has been set on the service accounts, the application controller and server pods need to be restarted.
```yaml
@ -1331,5 +1335,5 @@ patches:
The live example of self managed Argo CD config is available at [https://cd.apps.argoproj.io](https://cd.apps.argoproj.io) and with configuration
stored at [argoproj/argoproj-deployments](https://github.com/argoproj/argoproj-deployments/tree/master/argocd).
!!! 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)
> [!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)

8
docs/operator-manual/deep_links.md
View file

@ -28,11 +28,11 @@ Each link in the list has five subfields:
data as the `url` field. If the condition resolves to `true` the deep link will be displayed - else it will be hidden. If
the field is omitted, by default the deep links will be displayed. This uses [expr-lang/expr](https://github.com/expr-lang/expr/tree/master/docs) for evaluating conditions
!!!note
For resources of kind Secret the data fields are redacted but other fields are accessible for templating the deep links.
> [!NOTE]
> For resources of kind Secret the data fields are redacted but other fields are accessible for templating the deep links.
!!!warning
Make sure to validate the url templates and inputs to prevent data leaks or possible generation of any malicious links.
> [!WARNING]
> Make sure to validate the url templates and inputs to prevent data leaks or possible generation of any malicious links.
As mentioned earlier the links and conditions can be templated to use data from the resource, each category of links can access different types of data linked to that resource.
Overall we have these 4 resources available for templating in the system:

4
docs/operator-manual/disaster_recovery.md
View file

@ -24,5 +24,5 @@ Import from a backup:
docker run -i -v ~/.kube:/home/argocd/.kube --rm quay.io/argoproj/argocd:$VERSION argocd admin import - < backup.yaml
```
!!! note
If you are running Argo CD on a namespace different than default remember to pass the namespace parameter (-n <namespace>). 'argocd admin export' will not fail if you run it in the wrong namespace.
> [!NOTE]
> If you are running Argo CD on a namespace different than default remember to pass the namespace parameter (-n <namespace>). 'argocd admin export' will not fail if you run it in the wrong namespace.

12
docs/operator-manual/dynamic-cluster-distribution.md
View file

@ -1,8 +1,10 @@
# Dynamic Cluster Distribution
!!! warning "Alpha Feature (Since v2.9.0)"
This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha) feature.
It may be removed in future releases or modified in backwards-incompatible ways.
> [!WARNING]
> **Alpha Feature (Since v2.9.0)**
>
> This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha) feature.
> It may be removed in future releases or modified in backwards-incompatible ways.
*Current Status: [Alpha][1] (Since v2.9.0)*
@ -23,8 +25,8 @@ which does not require a restart of the application controller pods.
This feature is disabled by default while it is in alpha. In order to utilize the feature, the manifests `manifests/ha/base/controller-deployment/` can be applied as a Kustomize overlay. This overlay sets the StatefulSet replicas to `0` and deploys the application controller as a Deployment. Also, you must set the environment `ARGOCD_ENABLE_DYNAMIC_CLUSTER_DISTRIBUTION` to true when running the Application Controller as a deployment.
!!! important
The use of a Deployment instead of a StatefulSet is an implementation detail which may change in future versions of this feature. Therefore, the directory name of the Kustomize overlay may change as well. Monitor the release notes to avoid issues.
> [!IMPORTANT]
> The use of a Deployment instead of a StatefulSet is an implementation detail which may change in future versions of this feature. Therefore, the directory name of the Kustomize overlay may change as well. Monitor the release notes to avoid issues.
Note the introduction of new environment variable `ARGOCD_CONTROLLER_HEARTBEAT_TIME`. The environment variable is explained in [working of Dynamic Distribution Heartbeat Process](#working-of-dynamic-distribution)

17
docs/operator-manual/feature-maturity.md
View file

@ -3,14 +3,15 @@
Argo CD features may be marked with a certain [status](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md)
to indicate their stability and maturity. These are the statuses of non-stable features in Argo CD:
!!! danger "Using Alpha/Beta features risks"
Aplha and Beta features do not guarantee backward compatibility and are subject to breaking changes in the future releases.
It is highly suggested for Argo users not to rely on these features in production environments, especially if you do not have
control over the Argo CD upgrades.
Furthermore, removal of Alpha features may modify your resources to an unpredictable state after Argo CD is upgraded.
You should make sure to document which features are in use and review the [release notes](./upgrading/overview.md) before upgrading.
> [!CAUTION]
> **Using Alpha/Beta features risks**
>
> Alpha and Beta features do not guarantee backward compatibility and are subject to breaking changes in the future releases.
> It is highly suggested for Argo users not to rely on these features in production environments, especially if you do not have
> control over the Argo CD upgrades.
>
> Furthermore, removal of Alpha features may modify your resources to an unpredictable state after Argo CD is upgraded.
> You should make sure to document which features are in use and review the [release notes](./upgrading/overview.md) before upgrading.
## Overview

15
docs/operator-manual/health.md
View file

@ -116,9 +116,9 @@ specify a wildcard in the resource kind, and anywhere in the resource group, lik
...
```
!!!important
Please, note that wildcards are only supported when using the `resource.customizations` key, the `resource.customizations.health.<group>_<kind>`
style keys do not work since wildcards (`*`) are not supported in Kubernetes configmap keys.
> [!IMPORTANT]
> Please, note that wildcards are only supported when using the `resource.customizations` key, the `resource.customizations.health.<group>_<kind>`
> style keys do not work since wildcards (`*`) are not supported in Kubernetes configmap keys.
The `obj` is a global variable which contains the resource. The script must return an object with status and optional message field.
The custom health check might return one of the following health statuses:
@ -191,10 +191,11 @@ If multiple wildcard checks match, the first one in the directory structure is u
We use the [doublestar](https://github.com/bmatcuk/doublestar) glob library to match the wildcard checks. We currently
only treat a path as a wildcard if it contains a `_` character, but this may change in the future.
!!!important "Avoid Massive Scripts"
Avoid writing massive scripts to handle multiple resources. They'll get hard to read and maintain. Instead, just
duplicate the relevant parts in resource-specific scripts.
> [!IMPORTANT]
> **Avoid Massive Scripts**
>
> Avoid writing massive scripts to handle multiple resources. They'll get hard to read and maintain. Instead, just
> duplicate the relevant parts in resource-specific scripts.
## Overriding Go-Based Health Checks

23
docs/operator-manual/high_availability.md
View file

@ -4,10 +4,9 @@ Argo CD is largely stateless. All data is persisted as Kubernetes objects, which
A set of [HA manifests](https://github.com/argoproj/argo-cd/tree/stable/manifests/ha) are provided for users who wish to run Argo CD in a highly available manner. This runs more containers, and runs Redis in HA mode.
!!! note
The HA installation will require at least three different nodes due to pod anti-affinity roles in the
specs. Additionally, IPv6 only clusters are not supported.
> [!NOTE]
> The HA installation will require at least three different nodes due to pod anti-affinity roles in the
> specs. Additionally, IPv6 only clusters are not supported.
## Scaling Up
@ -95,9 +94,11 @@ spec:
The `--sharding-method` parameter can also be overridden by setting the key `controller.sharding.algorithm` in the `argocd-cmd-params-cm` `configMap` (preferably) or by setting the `ARGOCD_CONTROLLER_SHARDING_ALGORITHM` environment variable and by specifying the same possible values.
!!! warning "Alpha Features"
The `round-robin` shard distribution algorithm is an experimental feature. Reshuffling is known to occur in certain scenarios with cluster removal. If the cluster at rank-0 is removed, reshuffling all clusters across shards will occur and may temporarily have negative performance impacts.
The `consistent-hashing` shard distribution algorithm is an experimental feature. Extensive benchmark have been documented on the [CNOE blog](https://cnoe.io/blog/argo-cd-application-scalability) with encouraging results. Community feedback is highly appreciated before moving this feature to a production ready state.
> [!WARNING]
> **Alpha Features**
>
> The `round-robin` shard distribution algorithm is an experimental feature. Reshuffling is known to occur in certain scenarios with cluster removal. If the cluster at rank-0 is removed, reshuffling all clusters across shards will occur and may temporarily have negative performance impacts.
> The `consistent-hashing` shard distribution algorithm is an experimental feature. Extensive benchmark have been documented on the [CNOE blog](https://cnoe.io/blog/argo-cd-application-scalability) with encouraging results. Community feedback is highly appreciated before moving this feature to a production ready state.
* A cluster can be manually assigned and forced to a `shard` by patching the `shard` field in the cluster secret to contain the shard number, e.g.
```yaml
@ -217,8 +218,8 @@ Similarly, applications referencing an external Helm values file will not get th
For webhooks, the comparison is done using the files specified in the webhook event payload instead.
!!! note
Application manifest paths annotation support for webhooks depends on the git provider used for the Application. It is currently only supported for GitHub, GitLab, and Gogs based repos.
> [!NOTE]
> Application manifest paths annotation support for webhooks depends on the git provider used for the Application. It is currently only supported for GitHub, GitLab, and Gogs based repos.
* **Relative path** The annotation might contain a relative path. In this case the path is considered relative to the path specified in the application source:
@ -293,8 +294,8 @@ spec:
# ...
```
!!! note
If application manifest generation using the `argocd.argoproj.io/manifest-generate-paths` annotation feature is enabled, only the resources specified by this annotation will be sent to the CMP server for manifest generation, rather than the entire repository. To determine the appropriate resources, a common root path is calculated based on the paths provided in the annotation. The application path serves as the deepest path that can be selected as the root.
> [!NOTE]
> If application manifest generation using the `argocd.argoproj.io/manifest-generate-paths` annotation feature is enabled, only the resources specified by this annotation will be sent to the CMP server for manifest generation, rather than the entire repository. To determine the appropriate resources, a common root path is calculated based on the paths provided in the annotation. The application path serves as the deepest path that can be selected as the root.
### Application Sync Timeout & Jitter

4
docs/operator-manual/index.md
View file

@ -2,5 +2,5 @@
This guide is for administrators and operators wanting to install and configure Argo CD for other developers.
!!! note
Please make sure you've completed the [getting started guide](../getting_started.md).
> [!NOTE]
> Please make sure you've completed the [getting started guide](../getting_started.md).

10
docs/operator-manual/ingress.md
View file

@ -685,9 +685,8 @@ spec:
```
---
!!! note
The next two steps (the certificate secret and the Ingress) are described supposing that you manage the certificate yourself, and you have the certificate and key files for it. In the case that your certificate is Google-managed, fix the next two steps using the [guide to use a Google-managed SSL certificate](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs#creating_an_ingress_with_a_google-managed_certificate).
> [!NOTE]
> The next two steps (the certificate secret and the Ingress) are described supposing that you manage the certificate yourself, and you have the certificate and key files for it. In the case that your certificate is Google-managed, fix the next two steps using the [guide to use a Google-managed SSL certificate](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs#creating_an_ingress_with_a_google-managed_certificate).
---
@ -705,9 +704,8 @@ kubectl -n argocd create secret tls secret-yourdomain-com \
And finally, to top it all, our Ingress. Note the reference to our frontend config, the service, and to the certificate secret.
---
!!! note
GKE clusters running versions earlier than `1.21.3-gke.1600`, [the only supported value for the pathType field](https://cloud.google.com/kubernetes-engine/docs/how-to/load-balance-ingress#creating_an_ingress) is `ImplementationSpecific`. So you must check your GKE cluster's version. You need to use different YAML depending on the version.
> [!NOTE]
> GKE clusters running versions earlier than `1.21.3-gke.1600`, [the only supported value for the pathType field](https://cloud.google.com/kubernetes-engine/docs/how-to/load-balance-ingress#creating_an_ingress) is `ImplementationSpecific`. So you must check your GKE cluster's version. You need to use different YAML depending on the version.
---

6
docs/operator-manual/notifications/index.md
View file

@ -108,8 +108,8 @@ metadata:
notifications.argoproj.io/subscribe.on-sync-failed.pagerdutyv2: "<serviceID for Pagerduty>"
```
!!! note
When the same notification service and trigger are defined in controller level configuration and application level configuration,
both notifications will be sent according to its own configuration.
> [!NOTE]
> When the same notification service and trigger are defined in controller level configuration and application level configuration,
> both notifications will be sent according to its own configuration.
[Defining and using secrets within notification templates](templates/#defining-and-using-secrets-within-notification-templates) function is not available when flag `--self-service-notification-enable` is on.

4
docs/operator-manual/notifications/monitoring.md
View file

@ -2,8 +2,8 @@
The Argo CD Notification controller serves Prometheus metrics on port 9001.
!!! note
The metrics port can be changed using the `--metrics-port` flag in `argocd-notifications-controller` deployment.
> [!NOTE]
> The metrics port can be changed using the `--metrics-port` flag in `argocd-notifications-controller` deployment.
## Metrics
The following metrics are available:

116
docs/operator-manual/rbac.md
View file

@ -23,11 +23,12 @@ These default built-in role definitions can be seen in [builtin-policy.csv](http
When a user is authenticated in Argo CD, it will be granted the role specified in `policy.default`.
!!! warning "Restricting Default Permissions"
**All authenticated users get _at least_ the permissions granted by the default policies. This access cannot be blocked
by a `deny` rule.** It is recommended to create a new `role:authenticated` with the minimum set of permissions possible,
then grant permissions to individual roles as needed.
> [!WARNING]
> **Restricting Default Permissions**
>
> **All authenticated users get _at least_ the permissions granted by the default policies. This access cannot be blocked
> by a `deny` rule.** It is recommended to create a new `role:authenticated` with the minimum set of permissions possible,
> then grant permissions to individual roles as needed.
## Anonymous Access
@ -35,10 +36,9 @@ Enabling anonymous access to the Argo CD instance allows users to assume the def
The anonymous access to Argo CD can be enabled using the `users.anonymous.enabled` field in `argocd-cm` (see [argocd-cm.yaml](argocd-cm-yaml.md)).
!!! warning
When enabling anonymous access, consider creating a new default role and assigning it to the default policies
with `policy.default: role:unauthenticated`.
> [!WARNING]
> When enabling anonymous access, consider creating a new default role and assigning it to the default policies
> with `policy.default: role:unauthenticated`.
## RBAC Model Structure
@ -125,15 +125,16 @@ For instance, to grant access to `example-user` to only delete Pods in the `prod
p, example-user, applications, delete/*/Pod/*/*, default/prod-app, allow
```
!!!warning "Understand glob pattern behavior"
Argo CD RBAC does not use `/` as a separator when evaluating glob patterns. So the pattern `delete/*/kind/*`
will match `delete/<group>/kind/<namespace>/<name>` but also `delete/<group>/<kind>/kind/<name>`.
The fact that both of these match will generally not be a problem, because resource kinds generally contain capital
letters, and namespaces cannot contain capital letters. However, it is possible for a resource kind to be lowercase.
So it is better to just always include all the parts of the resource in the pattern (in other words, always use four
slashes).
> [!WARNING]
> **Understand glob pattern behavior**
>
> Argo CD RBAC does not use `/` as a separator when evaluating glob patterns. So the pattern `delete/*/kind/*`
> will match `delete/<group>/kind/<namespace>/<name>` but also `delete/<group>/<kind>/kind/<name>`.
>
> The fact that both of these match will generally not be a problem, because resource kinds generally contain capital
> letters, and namespaces cannot contain capital letters. However, it is possible for a resource kind to be lowercase.
> So it is better to just always include all the parts of the resource in the pattern (in other words, always use four
> slashes).
If we want to grant access to the user to update all resources of an application, but not the application itself:
@ -155,24 +156,25 @@ p, example-user, applications, update, default/prod-app, allow
p, example-user, applications, update/*, default/prod-app, deny
```
!!! note "Preserve Application permission Inheritance (Since v3.0.0)"
Prior to v3, `update` and `delete` actions (without a `/*`) were also evaluated
on sub-resources.
To preserve this behavior, you can set the config value
`server.rbac.disableApplicationFineGrainedRBACInheritance` to `false` in
the Argo CD ConfigMap `argocd-cm`.
When disabled, it is not possible to deny fine-grained permissions for a sub-resource
if the action was **explicitly allowed on the application**.
For instance, the following policies will **allow** a user to delete the Pod and any
other resources in the application:
```csv
p, example-user, applications, delete, default/prod-app, allow
p, example-user, applications, delete/*/Pod/*, default/prod-app, deny
```
> [!NOTE]
> **Preserve Application permission Inheritance (Since v3.0.0)**
>
> Prior to v3, `update` and `delete` actions (without a `/*`) were also evaluated
> on sub-resources.
>
> To preserve this behavior, you can set the config value
> `server.rbac.disableApplicationFineGrainedRBACInheritance` to `false` in
> the Argo CD ConfigMap `argocd-cm`.
>
> When disabled, it is not possible to deny fine-grained permissions for a sub-resource
> if the action was **explicitly allowed on the application**.
> For instance, the following policies will **allow** a user to delete the Pod and any
> other resources in the application:
>
> ```csv
> p, example-user, applications, delete, default/prod-app, allow
> p, example-user, applications, delete/*/Pod/*, default/prod-app, deny
> ```
#### The `action` action
@ -215,10 +217,9 @@ The `applicationsets` resource is an [Application-Specific policy](#application-
Allowing the `create` action on the resource effectively grants the ability to create Applications. While it doesn't allow the
user to create Applications directly, they can create Applications via an ApplicationSet.
!!! note
In v2.5, it is not possible to create an ApplicationSet with a templated Project field (e.g. `project: {{path.basename}}`)
via the API (or, by extension, the CLI). Disallowing templated projects makes project restrictions via RBAC safe:
> [!NOTE]
> In v2.5, it is not possible to create an ApplicationSet with a templated Project field (e.g. `project: {{path.basename}}`)
> via the API (or, by extension, the CLI). Disallowing templated projects makes project restrictions via RBAC safe:
With the resource being application-specific, the `<object>` of the applicationsets policy will have the format `<app-project>/<app-name>`.
However, since an ApplicationSet does belong to any project, the `<app-project>` value represents the projects in which the ApplicationSet will be able to create Applications.
@ -370,23 +371,24 @@ This example shows how to assign a role to a local user.
g, my-local-user, role:admin
```
!!! warning "Ambiguous Group Assignments"
If you have [enabled SSO](user-management/index.md#sso), any SSO user with a scope that matches a local user will be
added to the same roles as the local user. For example, if local user `sally` is assigned to `role:admin`, and if an
SSO user has a scope which happens to be named `sally`, that SSO user will also be assigned to `role:admin`.
An example of where this may be a problem is if your SSO provider is an SCM, and org members are automatically
granted scopes named after the orgs. If a user can create or add themselves to an org in the SCM, they can gain the
permissions of the local user with the same name.
To avoid ambiguity, if you are using local users and SSO, it is recommended to assign policies directly to local
users, and not to assign roles to local users. In other words, instead of using `g, my-local-user, role:admin`, you
should explicitly assign policies to `my-local-user`:
```yaml
p, my-local-user, *, *, *, allow
```
> [!WARNING]
> **Ambiguous Group Assignments**
>
> If you have [enabled SSO](user-management/index.md#sso), any SSO user with a scope that matches a local user will be
> added to the same roles as the local user. For example, if local user `sally` is assigned to `role:admin`, and if an
> SSO user has a scope which happens to be named `sally`, that SSO user will also be assigned to `role:admin`.
>
> An example of where this may be a problem is if your SSO provider is an SCM, and org members are automatically
> granted scopes named after the orgs. If a user can create or add themselves to an org in the SCM, they can gain the
> permissions of the local user with the same name.
>
> To avoid ambiguity, if you are using local users and SSO, it is recommended to assign policies directly to local
> users, and not to assign roles to local users. In other words, instead of using `g, my-local-user, role:admin`, you
> should explicitly assign policies to `my-local-user`:
>
> ```yaml
> p, my-local-user, *, *, *, allow
> ```
## Policy CSV Composition

8
docs/operator-manual/reconcile.md
View file

@ -77,8 +77,8 @@ To find these logs, search for `"Requesting app refresh caused by object update"
fields for `api-version` and `kind`. Counting the number of refreshes triggered, by api-version/kind should
reveal the high-churn resource kinds.
!!! note
These logs are at the `debug` level. Configure the application-controller's log level to `debug`.
> [!NOTE]
> These logs are at the `debug` level. Configure the application-controller's log level to `debug`.
Once you have identified some resources which change often, you can try to determine which fields are changing. Here is
one approach:
@ -99,8 +99,8 @@ Whenever Argo CD skips a refresh due to an ignored resource update, the controll
Search the application-controller logs for this line to confirm that your resource ignore rules are being applied.
!!! note
These logs are at the `debug` level. Configure the application-controller's log level to `debug`.
> [!NOTE]
> These logs are at the `debug` level. Configure the application-controller's log level to `debug`.
## Examples

8
docs/operator-manual/resource_actions.md
View file

@ -96,10 +96,10 @@ resource.customizations.actions.argoproj.io_Rollout: |
#### Creating new resources with a custom action
!!! important
Creating resources via the Argo CD UI is an intentional, strategic departure from GitOps principles. We recommend
that you use this feature sparingly and only for resources that are not part of the desired state of the
application.
> [!IMPORTANT]
> Creating resources via the Argo CD UI is an intentional, strategic departure from GitOps principles. We recommend
> that you use this feature sparingly and only for resources that are not part of the desired state of the
> application.
The resource the action is invoked on would be referred to as the `source resource`.
The new resource and all the resources implicitly created as a result, must be permitted on the AppProject level, otherwise the creation will fail.

20
docs/operator-manual/security.md
View file

@ -119,12 +119,12 @@ kubectl delete secret argocd-manager-token-XXXXXX -n kube-system
argocd cluster add CONTEXTNAME
```
!!! note
Kubernetes 1.24 [stopped automatically creating tokens for Service Accounts](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade).
[Starting in Argo CD 2.4](https://github.com/argoproj/argo-cd/pull/9546), `argocd cluster add` creates a
ServiceAccount _and_ a non-expiring Service Account token Secret when adding 1.24 clusters. In the future, Argo CD
will [add support for the Kubernetes TokenRequest API](https://github.com/argoproj/argo-cd/issues/9610) to avoid
using long-lived tokens.
> [!NOTE]
> Kubernetes 1.24 [stopped automatically creating tokens for Service Accounts](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade).
> [Starting in Argo CD 2.4](https://github.com/argoproj/argo-cd/pull/9546), `argocd cluster add` creates a
> ServiceAccount _and_ a non-expiring Service Account token Secret when adding 1.24 clusters. In the future, Argo CD
> will [add support for the Kubernetes TokenRequest API](https://github.com/argoproj/argo-cd/issues/9610) to avoid
> using long-lived tokens.
To revoke Argo CD's access to a managed cluster, delete the RBAC artifacts against the *_managed_*
cluster, and remove the cluster entry from Argo CD:
@ -172,8 +172,8 @@ kubectl edit clusterrole argocd-server
kubectl edit clusterrole argocd-application-controller
```
!!! tip
If you want to deny Argo CD access to a kind of resource then add it as an [excluded resource](declarative-setup.md#resource-exclusion).
> [!TIP]
> If you want to deny Argo CD access to a kind of resource then add it as an [excluded resource](declarative-setup.md#resource-exclusion).
## Auditing
@ -226,8 +226,8 @@ Security-related logs are tagged with a `security` field to make them easier to
Where applicable, a `CWE` field is also added specifying the [Common Weakness Enumeration](https://cwe.mitre.org/index.html) number.
!!! warning
Please be aware that not all security logs are comprehensively tagged yet and these examples are not necessarily implemented.
> [!WARNING]
> Please be aware that not all security logs are comprehensively tagged yet and these examples are not necessarily implemented.
### API Logs

10
docs/operator-manual/signed-release-assets.md
View file

@ -100,9 +100,9 @@ slsa-verifier verify-image "$IMAGE" \
If you prefer using cosign, follow these [instructions](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/container/README.md#cosign).
!!! tip
`cosign` or `slsa-verifier` can both be used to verify image attestations.
Check the documentation of each binary for detailed instructions.
> [!TIP]
> `cosign` or `slsa-verifier` can both be used to verify image attestations.
> Check the documentation of each binary for detailed instructions.
***
@ -151,7 +151,7 @@ slsa-verifier verify-artifact sbom.tar.gz \
## Verification on Kubernetes
### Policy controllers
!!! note
We encourage all users to verify signatures and provenances with your admission/policy controller of choice. Doing so will verify that an image was built by us before it's deployed on your Kubernetes cluster.
> [!NOTE]
> We encourage all users to verify signatures and provenances with your admission/policy controller of choice. Doing so will verify that an image was built by us before it's deployed on your Kubernetes cluster.
Cosign signatures and SLSA provenances are compatible with several types of admission controllers. Please see the [cosign documentation](https://docs.sigstore.dev/cosign/overview/#kubernetes-integrations) and [slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/container/README.md#verification) for supported controllers.

20
docs/operator-manual/tls.md
View file

@ -204,10 +204,12 @@ The `argocd-server` and `argocd-application-controller` workloads will now
validate the TLS certificate of the `argocd-repo-server` by using the
certificate stored in the `argocd-repo-server-tls` secret.
!!!note "Certificate expiry"
Please make sure that the certificate has a proper lifetime. Remember,
when replacing certificates, all workloads must be restarted to pick up
the certificate and work properly.
> [!NOTE]
> **Certificate expiry**
>
> Please make sure that the certificate has a proper lifetime. Remember,
> when replacing certificates, all workloads must be restarted to pick up
> the certificate and work properly.
### Configuring TLS to argocd-dex-server
@ -232,10 +234,12 @@ The `argocd-server` workload will now validate the TLS certificate of the
`argocd-dex-server` by using the certificate stored in the `argocd-dex-server-tls`
secret.
!!!note "Certificate expiry"
Please make sure that the certificate has a proper lifetime. Remember,
when replacing certificates, all workloads must be restarted to pick up
the certificate and work properly.
> [!NOTE]
> **Certificate expiry**
>
> Please make sure that the certificate has a proper lifetime. Remember,
> when replacing certificates, all workloads must be restarted to pick up
> the certificate and work properly.
### Disabling TLS to argocd-repo-server

6
docs/operator-manual/upgrading/1.4-1.5.md
View file

@ -9,8 +9,8 @@ using `ARGOCD_LEGACY_CONTROLLER_METRICS=true` environment variable. The legacy e
## Redis HA Proxy
!!! warning
Manual intervention might be required to complete the upgrade.
> [!WARNING]
> Manual intervention might be required to complete the upgrade.
High-availability (HA) Argo CD manifests now bundles Redis in HA Proxy in front of it. Following issue have been
observed during the upgrade:
@ -24,4 +24,4 @@ As workaround "restart" `argocd-redis-ha-haproxy` Deployment and `argocd-redis-h
Note that bundled Kustomize has been upgraded to v3.6.1.
From here on you can follow the [regular upgrade process](./overview.md).
From here on you can follow the [regular upgrade process](./overview.md).

36
docs/operator-manual/upgrading/2.14-3.0.md
View file

@ -9,10 +9,10 @@ most recent minor versions (so 2.14 until 3.2 is released and 2.13 until 3.1 is
## Images missing release notes on GitHub
!!! important
Images 3.0.7 - 3.0.10 are missing release notes on GitHub. There was an issue with GoReleaser and building the darwin
CLI that prevented the release notes from being published. More information can be found
on [PR #23507](https://github.com/argoproj/argo-cd/pull/23507)
> [!IMPORTANT]
> Images 3.0.7 - 3.0.10 are missing release notes on GitHub. There was an issue with GoReleaser and building the darwin
> CLI that prevented the release notes from being published. More information can be found
> on [PR #23507](https://github.com/argoproj/argo-cd/pull/23507)
## Breaking Changes
@ -280,13 +280,14 @@ For most users, it is safe to upgrade to Argo CD 3.0 and use annotation-based tr
annotations on the next sync. Applications will not be marked as out-of-sync if labels are not present on the
resources.
!!! warning "Potential for orphaned resources"
There is a known edge case when switching from label-based tracking to annotation-based tracking that may cause
resources to be orphaned. If the first sync operation after switching to annotation-based tracking includes a
resource being deleted, Argo CD will fail to recognize that the resource is managed by the Application and will not
delete it. To avoid this edge case, it is recommended to perform a sync operation on your Applications, even if
they are not out of sync, so that orphan resource detection will work as expected on the next sync.
> [!WARNING]
> **Potential for orphaned resources**
>
> There is a known edge case when switching from label-based tracking to annotation-based tracking that may cause
> resources to be orphaned. If the first sync operation after switching to annotation-based tracking includes a
> resource being deleted, Argo CD will fail to recognize that the resource is managed by the Application and will not
> delete it. To avoid this edge case, it is recommended to perform a sync operation on your Applications, even if
> they are not out of sync, so that orphan resource detection will work as expected on the next sync.
##### Users who rely on label-based for resources that are not managed by Argo CD
Some users rely on label-based tracking to track resources that are not managed by Argo CD. They may set annotations
@ -300,10 +301,9 @@ argocd.argoproj.io/tracking-id: <app name>:<resource group>/<resource kind>:<res
For cluster-scoped resources, the namespace is set to the value in the Application's `spec.destination.namespace` field.
!!! warning
Manually constructing and applying tracking labels and annotations is not an officially supported feature, and Argo
CD's behavior may change in the future. It is recommended to manage resources with Argo CD via GitOps.
> [!WARNING]
> Manually constructing and applying tracking labels and annotations is not an officially supported feature, and Argo
> CD's behavior may change in the future. It is recommended to manage resources with Argo CD via GitOps.
#### Opting Out
@ -401,8 +401,8 @@ kubectl get applications.argoproj.io <my app> -n argocd -o jsonpath='{.status.re
Any tools or CLI commands parsing the `.status.resources[].health` need to be updated to use the argocd cli/API to get the health status.
!!! note
The application list API (argocd app list) no longer returns the individual health status of resources.
> [!NOTE]
> The application list API (argocd app list) no longer returns the individual health status of resources.
```sh
argocd app get <my app> -o json
@ -497,4 +497,4 @@ More details for ignored resource updates in the [Diffing customization](../../u
Due to security reasons ([GHSA-786q-9hcg-v9ff](https://github.com/argoproj/argo-cd/security/advisories/GHSA-786q-9hcg-v9ff)),
the project API response was sanitized to remove sensitive information. This includes
credentials of project-scoped repositories and clusters.
credentials of project-scoped repositories and clusters.

10
docs/operator-manual/upgrading/2.3-2.4.md
View file

@ -143,11 +143,11 @@ p, role:org-admin, gpgkeys, create, my-proj/*, allow
access. <del>In 2.5, you will have to explicitly grant `logs, get` access. Logs RBAC enforcement can be enabled with a flag
in 2.4. We recommend enabling the flag now for an easier upgrade experience in 2.5.</del>
!!! important
Logs RBAC enforcement **will not** be enabled by default in 2.5. This decision
[was made](https://github.com/argoproj/argo-cd/issues/10551#issuecomment-1242303457) to avoid breaking logs access
under [Project Roles](../../user-guide/projects.md#project-roles), which do not provide a mechanism to grant `logs`
resource access.
> [!IMPORTANT]
> Logs RBAC enforcement **will not** be enabled by default in 2.5. This decision
> [was made](https://github.com/argoproj/argo-cd/issues/10551#issuecomment-1242303457) to avoid breaking logs access
> under [Project Roles](../../user-guide/projects.md#project-roles), which do not provide a mechanism to grant `logs`
> resource access.
To enabled logs RBAC enforcement, add this to your argocd-cm ConfigMap:

12
docs/operator-manual/upgrading/2.4-2.5.md
View file

@ -153,12 +153,12 @@ In order to support CMPs and reduce local requirements, we have implemented *ser
In v2.7, the `--server-side-generate` argument will become the default, 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.7. Existing scripts utilizing `diff --local` may break in v2.7 if `spec.source.path` was not `/`.
> [!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.7. Existing scripts utilizing `diff --local` may break in v2.7 if `spec.source.path` was not `/`.
## Upgraded Kustomize Version

28
docs/operator-manual/upgrading/3.1-3.2.md
View file

@ -63,20 +63,22 @@ The `ManifestRequest` and `RepoServerAppDetailsQuery` messages are used by the f
After the upgrade, Application's status may transition to `Degraded` depending on the CronJob health.
!!! note "CronJob with running jobs"
> [!NOTE]
> **CronJob with running jobs**
>
> If the CronJob is `Degraded` and a new job is scheduled, the health will change to `Healthy` until the active job completes.
> This may cause your application to go from `Degraded` to `Healthy` to `Degraded` again. The CronJob status does not contain enough
> information to infer the health of the last completed job if there are active jobs.
>
> If the CronJob constantly has active jobs, the health will be constantly `Healthy` even if the last job failed.
If the CronJob is `Degraded` and a new job is scheduled, the health will change to `Healthy` until the active job completes.
This may cause your application to go from `Degraded` to `Healthy` to `Degraded` again. The CronJob status does not contain enough
information to infer the health of the last completed job if there are active jobs.
If the CronJob constantly has active jobs, the health will be constantly `Healthy` even if the last job failed.
!!! note "CronJob with suspended state"
If the CronJob is in a suspended state, the CronJob status will remain Healthy. You can override this behaviour by configuring the
health check using the `resource.customizations.health.batch_CronJob` key in the argocd-cm ConfigMap.
If you decide to do so and the CronJob is `Suspended`, then the aggregated health of the Application will now be `Suspended` instead of `Healthy`.
> [!NOTE]
> **CronJob with suspended state**
>
> If the CronJob is in a suspended state, the CronJob status will remain Healthy. You can override this behaviour by configuring the
> health check using the `resource.customizations.health.batch_CronJob` key in the argocd-cm ConfigMap.
>
> If you decide to do so and the CronJob is `Suspended`, then the aggregated health of the Application will now be `Suspended` instead of `Healthy`.
If you do not want your CronJob to affect the Application's aggregated Health, you can configure the annotation
`argocd.argoproj.io/ignore-healthcheck: "true"` on the CronJob resource.

16
docs/operator-manual/upgrading/overview.md
View file

@ -1,9 +1,8 @@
# Overview
!!!note
This section contains information on upgrading Argo CD. Before upgrading please make sure to read details about
the breaking changes between Argo CD versions.
> [!NOTE]
> This section contains information on upgrading Argo CD. Before upgrading please make sure to read details about
> the breaking changes between Argo CD versions.
Argo CD uses semver-like versioning that ensures the following rules:
@ -30,11 +29,10 @@ kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/<v
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/<version>/manifests/ha/install.yaml
```
!!! 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
introducing misconfiguration.
> [!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
> introducing misconfiguration.
<hr/>

6
docs/operator-manual/user-management/auth0.md
View file

@ -70,5 +70,7 @@ data:
<br>
!!! note "Storing Client Secrets"
Details on storing your clientSecret securely and correctly can be found on the [User Management Overview page](index.md#sensitive-data-and-sso-client-secrets).
> [!NOTE]
> **Storing Client Secrets**
>
> Details on storing your clientSecret securely and correctly can be found on the [User Management Overview page](index.md#sensitive-data-and-sso-client-secrets).

7
docs/operator-manual/user-management/google.md
View file

@ -76,9 +76,10 @@ data:
---
!!! warning "Deprecation Warning"
Note that, according to [Dex documentation](https://dexidp.io/docs/connectors/saml/#warning), SAML is considered unsafe and they are planning to deprecate that module.
> [!WARNING]
> **Deprecation Warning**
>
> Note that, according to [Dex documentation](https://dexidp.io/docs/connectors/saml/#warning), SAML is considered unsafe and they are planning to deprecate that module.
---

6
docs/operator-manual/user-management/identity-center.md
View file

@ -1,7 +1,9 @@
# Identity Center (AWS SSO)
!!! note "Are you using this? Please contribute!"
If you're using this IdP please consider [contributing](../../developer-guide/docs-site.md) to this document.
> [!NOTE]
> **Are you using this? Please contribute!**
>
> If you're using this IdP please consider [contributing](../../developer-guide/docs-site.md) to this document.
A working Single Sign-On configuration using Identity Center (AWS SSO) has been achieved using the following method:

18
docs/operator-manual/user-management/index.md
View file

@ -12,8 +12,8 @@ Such token can be used to automatically create applications, projects etc.
* Additional users for a very small team where use of SSO integration might be considered an overkill. The local users don't provide advanced features such as groups,
login history etc. So if you need such features it is strongly recommended to use SSO.
!!! note
When you create local users, each of those users will need additional [RBAC rules](../rbac.md) set up, otherwise they will fall back to the default policy specified by `policy.default` field of the `argocd-rbac-cm` ConfigMap.
> [!NOTE]
> When you create local users, each of those users will need additional [RBAC rules](../rbac.md) set up, otherwise they will fall back to the default policy specified by `policy.default` field of the `argocd-rbac-cm` ConfigMap.
The maximum length of a local account's username is 32.
@ -276,8 +276,8 @@ data:
- groups
```
!!! warning
Because group information is only refreshed at authentication time just adding or removing an account from a group will not change a user's membership until they reauthenticate. Depending on your organization's needs this could be a security risk and could be mitigated by changing the authentication token's lifetime.
> [!WARNING]
> Because group information is only refreshed at authentication time just adding or removing an account from a group will not change a user's membership until they reauthenticate. Depending on your organization's needs this could be a security risk and could be mitigated by changing the authentication token's lifetime.
### Retrieving claims that are not in the token
@ -353,9 +353,9 @@ data:
enablePKCEAuthentication: true
```
!!! note
The callback address should be the /auth/callback endpoint of your Argo CD URL
(e.g. https://argocd.example.com/auth/callback).
> [!NOTE]
> The callback address should be the /auth/callback endpoint of your Argo CD URL
> (e.g. https://argocd.example.com/auth/callback).
### Requesting additional ID token claims
@ -426,8 +426,8 @@ By default, this would take the user to their OIDC provider's login page after l
You are not required to specify a logoutRedirectURL as this is automatically generated by ArgoCD as your base ArgoCD url + Rootpath
!!! note
The post logout redirect URI may need to be whitelisted against your OIDC provider's client settings for ArgoCD.
> [!NOTE]
> The post logout redirect URI may need to be whitelisted against your OIDC provider's client settings for ArgoCD.
### Configuring a custom root CA certificate for communicating with the OIDC provider

4
docs/operator-manual/user-management/microsoft.md
View file

@ -1,7 +1,7 @@
# Microsoft
!!! note ""
Entra ID was formerly known as Azure AD.
> [!NOTE]
> Entra ID was formerly known as Azure AD.
* [Entra ID App Registration Auth using OIDC](#entra-id-app-registration-auth-using-oidc)
* [Entra ID SAML Enterprise App Auth using Dex](#entra-id-saml-enterprise-app-auth-using-dex)

30
docs/operator-manual/user-management/okta.md
View file

@ -1,7 +1,9 @@
# Okta
!!! note "Are you using this? Please contribute!"
If you're using this IdP please consider [contributing](../../developer-guide/docs-site.md) to this document.
> [!NOTE]
> **Are you using this? Please contribute!**
>
> If you're using this IdP please consider [contributing](../../developer-guide/docs-site.md) to this document.
A working Single Sign-On configuration using Okta via at least two methods was achieved using:
@ -10,8 +12,10 @@ A working Single Sign-On configuration using Okta via at least two methods was a
## SAML (with Dex)
!!! note "Okta app group assignment"
The Okta app's **Group Attribute Statements** regex will be used later to map Okta groups to Argo CD RBAC roles.
> [!NOTE]
> **Okta app group assignment**
>
> The Okta app's **Group Attribute Statements** regex will be used later to map Okta groups to Argo CD RBAC roles.
1. Create a new SAML application in Okta UI.
* ![Okta SAML App 1](../../assets/saml-1.png)
@ -118,15 +122,17 @@ data:
## OIDC (without Dex)
!!! warning "Okta groups for RBAC"
If you want `groups` scope returned from Okta, you will need to enable [API Access Management with Okta](https://developer.okta.com/docs/concepts/api-access-management/). This addon is free, and automatically enabled, on Okta developer edition. However, it's an optional add-on for production environments, with an additional associated cost.
> [!WARNING]
> **Okta groups for RBAC**
>
> If you want `groups` scope returned from Okta, you will need to enable [API Access Management with Okta](https://developer.okta.com/docs/concepts/api-access-management/). This addon is free, and automatically enabled, on Okta developer edition. However, it's an optional add-on for production environments, with an additional associated cost.
>
> You may alternately add a "groups" scope and claim to the default authorization server, and then filter the claim in the Okta application configuration. It's not clear if this requires the Authorization Server add-on.
>
> If this is not an option for you, use the [SAML (with Dex)](#saml-with-dex) option above instead.
You may alternately add a "groups" scope and claim to the default authorization server, and then filter the claim in the Okta application configuration. It's not clear if this requires the Authorization Server add-on.
If this is not an option for you, use the [SAML (with Dex)](#saml-with-dex) option above instead.
!!! note
These instructions and screenshots are of Okta version 2023.05.2 E. You can find the current version in the Okta website footer.
> [!NOTE]
> These instructions and screenshots are of Okta version 2023.05.2 E. You can find the current version in the Okta website footer.
First, create the OIDC integration:

12
docs/operator-manual/user-management/onelogin.md
View file

@ -1,7 +1,9 @@
# OneLogin
!!! note "Are you using this? Please contribute!"
If you're using this IdP please consider [contributing](../../developer-guide/docs-site.md) to this document.
> [!NOTE]
> **Are you using this? Please contribute!**
>
> If you're using this IdP please consider [contributing](../../developer-guide/docs-site.md) to this document.
<!-- markdownlint-disable MD033 -->
<div style="text-align:center"><img src="../../../assets/argo.png" /></div>
@ -39,7 +41,8 @@ Update the "Configuration" settings as follows:
3. Set the "Redirect Url" field to https://argocd.myproject.com/auth/callback, replacing the hostname with your own.
4. Click "Save".
!!! note "OneLogin may not let you save any other fields until the above fields are set."
> [!NOTE]
> OneLogin may not let you save any other fields until the above fields are set.
#### Info Tab
@ -134,7 +137,8 @@ The “issuer” is taken from the SSO tab of the OneLogin application. It is on
The "clientSecret" value is a client secret located in the SSO tab of the OneLogin application.
!!! note "If you get an `invalid_client` error when trying the authenticate with OneLogin, there is a possibility that your client secret is not proper. Keep in mind that in previous versions `clientSecret` value had to be base64 encrypted, but it is not required anymore."
> [!NOTE]
> **If you get an `invalid_client` error when trying the authenticate with OneLogin, there is a possibility that your client secret is not proper. Keep in mind that in previous versions `clientSecret` value had to be base64 encrypted, but it is not required anymore.**
### Configure Permissions for OneLogin Auth'd Users

12
docs/operator-manual/webhook.md
View file

@ -7,10 +7,10 @@ this delay from polling, the API server can be configured to receive webhook eve
Git webhook notifications from GitHub, GitLab, Bitbucket, Bitbucket Server, Azure DevOps and Gogs. The following explains how to configure
a Git webhook for GitHub, but the same process should be applicable to other providers.
!!! note
The webhook handler does not differentiate between branch events and tag events where the branch and tag names are
the same. A hook event for a push to branch `x` will trigger a refresh for an app pointing at the same repo with
`targetRevision: refs/tags/x`.
> [!NOTE]
> The webhook handler does not differentiate between branch events and tag events where the branch and tag names are
> the same. A hook event for a push to branch `x` will trigger a refresh for an app pointing at the same repo with
> `targetRevision: refs/tags/x`.
## 1. Create The WebHook In The Git Provider
@ -25,8 +25,8 @@ To prevent DDoS attacks with unauthenticated webhook events (the `/api/webhook`
![Add Webhook](../assets/webhook-config.png "Add Webhook")
!!! note
When creating the webhook in GitHub, the "Content type" needs to be set to "application/json". The default value "application/x-www-form-urlencoded" is not supported by the library used to handle the hooks
> [!NOTE]
> When creating the webhook in GitHub, the "Content type" needs to be set to "application/json". The default value "application/x-www-form-urlencoded" is not supported by the library used to handle the hooks
### Azure DevOps

4
docs/proposals/feature-bounties/hide-annotations.md
View file

@ -6,8 +6,8 @@ Award amount: $100
## Solution
!!! note
This is the proposed solution. The accepted PR may differ from this proposal.
> [!NOTE]
> This is the proposed solution. The accepted PR may differ from this proposal.
Add a new config item in argocd-cm:

1
docs/requirements.txt
View file

@ -1,4 +1,5 @@
mkdocs==1.6.1
mkdocs-github-admonitions-plugin==0.1.1
# Strict mode has been disabled in latest versions of mkdocs-material.
# Thus pointing to the older version of mkdocs-material.
mkdocs-material==7.1.8

12
docs/security_considerations.md
View file

@ -1,10 +1,12 @@
# Security Considerations
!!!warning "Deprecation notice"
This page is now deprecated and serves as an archive only. For up-to-date
information, please have a look at our
[security policy](https://github.com/argoproj/argo-cd/security/policy) and
[published security advisories](https://github.com/argoproj/argo-cd/security/advisories).
> [!WARNING]
> **Deprecation notice**
>
> This page is now deprecated and serves as an archive only. For up-to-date
> information, please have a look at our
> [security policy](https://github.com/argoproj/argo-cd/security/policy) and
> [published security advisories](https://github.com/argoproj/argo-cd/security/advisories).
As a deployment tool, Argo CD needs to have production access which makes security a very important topic.
The Argoproj team takes security very seriously and continuously working on improving it. Learn more about security

6
docs/snyk/index.md
View file

@ -3,9 +3,9 @@
Every Sunday, Snyk scans are generated for Argo CD's `master` branch and the most recent patches of the three most
recent minor releases.
!!! note
For the most recent scans, view the [`latest` version of the docs](https://argo-cd.readthedocs.io/en/latest/snyk/).
You can return to your preferred version of the docs site using the dropdown selector at the top of the page.
> [!NOTE]
> For the most recent scans, view the [`latest` version of the docs](https://argo-cd.readthedocs.io/en/latest/snyk/).
> You can return to your preferred version of the docs site using the dropdown selector at the top of the page.
## Scans

4
docs/try_argo_cd_locally.md
View file

@ -1,7 +1,7 @@
# Try Argo CD Locally
!!! tip
This guide assumes you have a grounding in the tools that Argo CD is based on. Please read [understanding the basics](understand_the_basics.md) to learn about these tools.
> [!TIP]
> This guide assumes you have a grounding in the tools that Argo CD is based on. Please read [understanding the basics](understand_the_basics.md) to learn about these tools.
Follow these steps to install `Kind` for local development and set it up with Argo CD.

6
docs/user-guide/application-set.md
View file

@ -4,9 +4,9 @@ The [ApplicationSet controller](../operator-manual/applicationset/index.md) adds
The set of tools provided by the ApplicationSet controller may also be used to allow developers (without access to the Argo CD namespace) to independently create Applications without cluster-administrator intervention.
!!! warning
Be aware of the [security implications](../operator-manual/applicationset/Security.md) before allowing developers to
create Applications via ApplicationSets.
> [!WARNING]
> Be aware of the [security implications](../operator-manual/applicationset/Security.md) before allowing developers to
> create Applications via ApplicationSets.
The ApplicationSet controller automatically generates Argo CD Applications based on the contents of an `ApplicationSet` Custom Resource (CR).

8
docs/user-guide/auto_sync.md
View file

@ -26,8 +26,8 @@ spec:
enabled: true
```
!!!note
Setting the `spec.syncPolicy.automated.enabled` flag to null will be treated as if automated sync is enabled. When the `enabled` field is set to false, fields like `prune`, `selfHeal` and `allowEmpty` can be set without enabling them.
> [!NOTE]
> Setting the `spec.syncPolicy.automated.enabled` flag to null will be treated as if automated sync is enabled. When the `enabled` field is set to false, fields like `prune`, `selfHeal` and `allowEmpty` can be set without enabling them.
## Temporarily toggling auto-sync for applications managed by ApplicationSets
@ -91,8 +91,8 @@ spec:
selfHeal: true
```
!!!note
Disabling self-heal does not guarantee that live cluster changes in multi-source applications will persist. Although one of the resource's sources remains unchanged, changes in another can trigger `autosync`. To handle such cases, consider disabling `autosync`.
> [!NOTE]
> Disabling self-heal does not guarantee that live cluster changes in multi-source applications will persist. Although one of the resource's sources remains unchanged, changes in another can trigger `autosync`. To handle such cases, consider disabling `autosync`.
## Automatic Retry Refresh on new revisions

8
docs/user-guide/ci_automation.md
View file

@ -17,10 +17,10 @@ docker push mycompany/guestbook:v2.0
## Update The Local Manifests Using Your Preferred Templating Tool, And Push The Changes To Git
!!! tip
The use of a different Git repository to hold your Kubernetes manifests (separate from
your application source code), is highly recommended. See [best practices](best_practices.md)
for further rationale.
> [!TIP]
> The use of a different Git repository to hold your Kubernetes manifests (separate from
> your application source code), is highly recommended. See [best practices](best_practices.md)
> for further rationale.
```bash
git clone https://github.com/mycompany/guestbook-config.git

10
docs/user-guide/compare-options.md
View file

@ -12,8 +12,8 @@ metadata:
![compare option needs pruning](../assets/compare-option-ignore-needs-pruning.png)
!!! note
This only affects the sync status. If the resource's health is degraded, then the app will also be degraded.
> [!NOTE]
> This only affects the sync status. If the resource's health is degraded, then the app will also be degraded.
Kustomize has a feature that allows you to generate config maps ([read more ⧉](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/configGeneration.md)). You can set `generatorOptions` to add this annotation so that your app remains in sync:
@ -28,7 +28,7 @@ generatorOptions:
kind: Kustomization
```
!!! note
`generatorOptions` adds annotations to both config maps and secrets ([read more ⧉](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/generatorOptions.md)).
> [!NOTE]
> `generatorOptions` adds annotations to both config maps and secrets ([read more ⧉](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/generatorOptions.md)).
>
You may wish to combine this with the [`Prune=false` sync option](sync-options.md).

6
docs/user-guide/diff-strategies.md
View file

@ -17,8 +17,10 @@ Argo CD currently has 3 different strategies to calculate diffs:
## 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.
> [!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][2] library

4
docs/user-guide/diffing.md
View file

@ -129,8 +129,8 @@ data:
If you rely on the status field being part of your desired state, although this is not recommended, the `ignoreResourceStatusField` setting can be used to configure this behavior.
!!! note
Since it is common for `CustomResourceDefinitions` to have their `status` committed to Git, consider using `crd` over `none`.
> [!NOTE]
> Since it is common for `CustomResourceDefinitions` to have their `status` committed to Git, consider using `crd` over `none`.
### Ignoring RBAC changes made by AggregateRoles

8
docs/user-guide/directory.md
View file

@ -43,8 +43,8 @@ spec:
recurse: true
```
!!! warning
Directory-type applications only work for plain manifest files. If Argo CD encounters Kustomize, Helm, or Jsonnet files when directory: is set, it will fail to render the manifests.
> [!WARNING]
> Directory-type applications only work for plain manifest files. If Argo CD encounters Kustomize, Helm, or Jsonnet files when directory: is set, it will fail to render the manifests.
## Including/Excluding Files
@ -59,8 +59,8 @@ For example, if you want to include only `.yaml` files, you can use this pattern
argocd app set guestbook --directory-include "*.yaml"
```
!!! note
It is important to quote `*.yaml` so that the shell does not expand the pattern before sending it to Argo CD.
> [!NOTE]
> It is important to quote `*.yaml` so that the shell does not expand the pattern before sending it to Argo CD.
It is also possible to include multiple patterns. Wrap the patterns with `{}` and separate them with commas. To include
`.yml` and `.yaml` files, use this pattern:

48
docs/user-guide/gpg-verification.md
View file

@ -23,16 +23,18 @@ the `argocd-server`, `argocd-repo-server`, `argocd-application-controller` and
Verification of GnuPG signatures is only supported with Git repositories. It is
not possible using Helm repositories.
!!!note "A few words about trust"
ArgoCD uses a very simple trust model for the keys you import: Once the key
is imported, ArgoCD will trust it. ArgoCD does not support more complex
trust models, and it is not necessary (nor possible) to sign the public keys
you are going to import into ArgoCD.
> [!NOTE]
> **A few words about trust**
>
> ArgoCD uses a very simple trust model for the keys you import: Once the key
> is imported, ArgoCD will trust it. ArgoCD does not support more complex
> trust models, and it is not necessary (nor possible) to sign the public keys
> you are going to import into ArgoCD.
!!!note Limitations
Signature verification is not supported for the templated `project` field when
using the Git generator.
> [!NOTE]
> Signature verification is not supported for the templated `project` field when
> using the Git generator.
## Signature verification targets
@ -61,9 +63,9 @@ Once you have configured one or more keys to be required for verification for
a given project, enforcement is active for all applications associated with
this project.
!!!warning
If signature verification is enforced, you will not be able to sync from
local sources (i.e. `argocd app sync --local`) anymore.
> [!WARNING]
> If signature verification is enforced, you will not be able to sync from
> local sources (i.e. `argocd app sync --local`) anymore.
## RBAC rules for managing GnuPG keys
@ -94,11 +96,11 @@ You can configure the GnuPG public keys that ArgoCD will use for verification
of commit signatures using either the CLI, the web UI or configuring it using
declarative setup.
!!!note
After you have imported a GnuPG key, it may take a while until the key is
propagated within the cluster, even if listed as configured. If you still
cannot sync to commits signed by the already imported key, please see the
troubleshooting section below.
> [!NOTE]
> After you have imported a GnuPG key, it may take a while until the key is
> propagated within the cluster, even if listed as configured. If you still
> cannot sync to commits signed by the already imported key, please see the
> troubleshooting section below.
Users wanting to manage the GnuPG public key configuration require the RBAC
permissions for `gpgkeys` resources.
@ -299,13 +301,13 @@ pods of `argocd-repo-server`. The keys in the keyring are synchronized to the
configuration stored in the `argocd-gpg-keys-cm` ConfigMap resource, which is
volume-mounted to the `argocd-repo-server` pods.
!!!note
The GnuPG key ring in the pods is transient and gets recreated from the
configuration on each restart of the pods. You should never add or remove
keys manually to the key ring, because your changes will be lost. Also,
any of the private keys found in the key ring are transient and will be
regenerated upon each restart. The private key is only used to build the
trust DB for the running pod.
> [!NOTE]
> The GnuPG key ring in the pods is transient and gets recreated from the
> configuration on each restart of the pods. You should never add or remove
> keys manually to the key ring, because your changes will be lost. Also,
> any of the private keys found in the key ring are transient and will be
> regenerated upon each restart. The private key is only used to build the
> trust DB for the running pod.
To check whether the keys are actually in sync, you can `kubectl exec` into the
repository server's pods and inspect the key ring, which is located at path

46
docs/user-guide/helm.md
View file

@ -42,8 +42,10 @@ spec:
namespace: nginx
```
!!! note "When using Helm there are multiple ways to provide values"
Order of precedence is `parameters > valuesObject > values > valueFiles > helm repository values.yaml` (see [Here](./helm.md#helm-value-precedence) for a more detailed example)
> [!NOTE]
> **When using Helm there are multiple ways to provide values**
>
> Order of precedence is `parameters > valuesObject > values > valueFiles > helm repository values.yaml` (see [Here](./helm.md#helm-value-precedence) for a more detailed example)
See [here](../operator-manual/declarative-setup.md#helm) for more info about how to configure private Helm repositories and private OCI registries.
@ -56,12 +58,12 @@ flag. The flag can be repeated to support multiple values files:
```bash
argocd app set helm-guestbook --values values-production.yaml
```
!!! note
Before `v2.6` of Argo CD, Values files must be in the same git repository as the Helm
chart. The files can be in a different location in which case it can be accessed using
a relative path relative to the root directory of the Helm chart.
As of `v2.6`, values files can be sourced from a separate repository than the Helm chart
by taking advantage of [multiple sources for Applications](./multiple_sources.md#helm-value-files-from-external-git-repository).
> [!NOTE]
> Before `v2.6` of Argo CD, Values files must be in the same git repository as the Helm
> chart. The files can be in a different location in which case it can be accessed using
> a relative path relative to the root directory of the Helm chart.
> As of `v2.6`, values files can be sourced from a separate repository than the Helm chart
> by taking advantage of [multiple sources for Applications](./multiple_sources.md#helm-value-files-from-external-git-repository).
In the declarative syntax:
@ -213,10 +215,12 @@ values: |
the result will be param1=value5
```
!!! note "When valueFiles or values is used"
The chart is rendered correctly using the set of values from the different possible sources plus any parameters, merged in the expected order as documented here.
There is a bug (see [this issue](https://github.com/argoproj/argo-cd/issues/9213)) in the UI that only shows the parameters, i.e. it does not represent the complete set of values.
As a workaround, using parameters instead of values/valuesObject will provide a better overview of what will be used for resources.
> [!NOTE]
> **When valueFiles or values is used**
>
> The chart is rendered correctly using the set of values from the different possible sources plus any parameters, merged in the expected order as documented here.
> There is a bug (see [this issue](https://github.com/argoproj/argo-cd/issues/9213)) in the UI that only shows the parameters, i.e. it does not represent the complete set of values.
> As a workaround, using parameters instead of values/valuesObject will provide a better overview of what will be used for resources.
## Helm --set-file support
@ -254,8 +258,10 @@ source:
releaseName: myRelease
```
!!! warning "Important notice on overriding the release name"
Please note that overriding the Helm release name might cause problems when the chart you are deploying is using the `app.kubernetes.io/instance` label. Argo CD injects this label with the value of the Application name for tracking purposes. So when overriding the release name, the Application name will stop being equal to the release name. Because Argo CD will overwrite the label with the Application name it might cause some selectors on the resources to stop working. In order to avoid this we can configure Argo CD to use another label for tracking in the [ArgoCD configmap argocd-cm.yaml](../operator-manual/argocd-cm.yaml) - check the lines describing `application.instanceLabelKey`.
> [!WARNING]
> **Important notice on overriding the release name**
>
> Please note that overriding the Helm release name might cause problems when the chart you are deploying is using the `app.kubernetes.io/instance` label. Argo CD injects this label with the value of the Application name for tracking purposes. So when overriding the release name, the Application name will stop being equal to the release name. Because Argo CD will overwrite the label with the Application name it might cause some selectors on the resources to stop working. In order to avoid this we can configure Argo CD to use another label for tracking in the [ArgoCD configmap argocd-cm.yaml](../operator-manual/argocd-cm.yaml) - check the lines describing `application.instanceLabelKey`.
## Helm Hooks
@ -284,11 +290,15 @@ Argo CD supports many (most?) Helm hooks by mapping the Helm annotations onto Ar
Unsupported hooks are ignored. In Argo CD, hooks are created by using `kubectl apply`, rather than `kubectl create`. This means that if the hook is named and already exists, it will not change unless you have annotated it with `before-hook-creation`.
!!! warning "Helm hooks + ArgoCD hooks"
If you define any Argo CD hooks, _all_ Helm hooks will be ignored.
> [!WARNING]
> **Helm hooks + ArgoCD hooks**
>
> If you define any Argo CD hooks, _all_ Helm hooks will be ignored.
!!! warning "'install' vs 'upgrade' vs 'sync'"
Argo CD cannot know if it is running a first-time "install" or an "upgrade" - every operation is a "sync'. This means that, by default, apps that have `pre-install` and `pre-upgrade` will have those hooks run at the same time.
> [!WARNING]
> **'install' vs 'upgrade' vs 'sync'**
>
> Argo CD cannot know if it is running a first-time "install" or an "upgrade" - every operation is a "sync'. This means that, by default, apps that have `pre-install` and `pre-upgrade` will have those hooks run at the same time.
### Hook Tips

4
docs/user-guide/index.md
View file

@ -2,5 +2,5 @@
This guide is for developers who have Argo CD installed for them and are managing applications.
!!! note
Please make sure you've completed the [getting started guide](../getting_started.md).
> [!NOTE]
> Please make sure you've completed the [getting started guide](../getting_started.md).

4
docs/user-guide/kustomize.md
View file

@ -42,8 +42,8 @@ The following configuration options are available for Kustomize:
To use Kustomize with an overlay, point your path to the overlay.
!!! tip
If you're generating resources, you should read up how to ignore those generated resources using the [`IgnoreExtraneous` compare option](compare-options.md).
> [!TIP]
> If you're generating resources, you should read up how to ignore those generated resources using the [`IgnoreExtraneous` compare option](compare-options.md).
## Patches
Patches are a way to kustomize resources using inline configurations in Argo CD applications. `patches` follow the same logic as the corresponding Kustomization. Any patches that target existing Kustomization file will be merged.

14
docs/user-guide/multiple_sources.md
View file

@ -34,8 +34,10 @@ spec:
The above example has two sources specified that need to be combined in order to create the "billing" application. Argo CD will generate the manifests for each source separately and combine
the resulting manifests.
!!! warning "Do not abuse multiple sources"
Note this feature is **NOT** destined as a generic way to group different/unrelated applications. Take a look at [applicationsets](../user-guide/application-set.md) and the [app-of-apps](../../operator-manual/cluster-bootstrapping/) pattern if you want to have a single entity for multiple applications. If you find yourself using more than 2-3 items in the `sources` array then you are almost certainly abusing this feature and you need to rethink your application grouping strategy.
> [!WARNING]
> **Do not abuse multiple sources**
>
> Note this feature is **NOT** destined as a generic way to group different/unrelated applications. Take a look at [applicationsets](../user-guide/application-set.md) and the [app-of-apps](../../operator-manual/cluster-bootstrapping/) pattern if you want to have a single entity for multiple applications. If you find yourself using more than 2-3 items in the `sources` array then you are almost certainly abusing this feature and you need to rethink your application grouping strategy.
If multiple sources produce the same resource (same `group`, `kind`, `name`, and `namespace`), the last source to
produce the resource will take precedence. Argo CD will produce a `RepeatedResourceWarning` in this case, but it will
@ -79,8 +81,8 @@ Note that the `$values` variable can only be used at the beginning of the value
If the `path` field is set in the `$values` source, Argo CD will attempt to generate resources from the git repository
at that URL. If the `path` field is not set, Argo CD will use the repository solely as a source of value files.
!!! note
Sources with the `ref` field set cannot include the `chart` field. Currently, Argo CD does not support using another Helm chart as a source for value files.
> [!NOTE]
> Sources with the `ref` field set cannot include the `chart` field. Currently, Argo CD does not support using another Helm chart as a source for value files.
!!! note
Even when the `ref` field is configured with the `path` field, `$value` still represents the root of sources with the `ref` field. Consequently, `valueFiles` must be specified as relative paths from the root of sources.
> [!NOTE]
> Even when the `ref` field is configured with the `path` field, `$value` still represents the root of sources with the `ref` field. Consequently, `valueFiles` must be specified as relative paths from the root of sources.

10
docs/user-guide/parameters.md
View file

@ -6,11 +6,11 @@ for *some* parts of the k8s manifests determined dynamically, or outside of Git
redeploying an application by changing application parameters via Argo CD, instead of making the
changes to the manifests in Git.
!!! tip
Many consider this mode of operation as an anti-pattern to GitOps, since the source of
truth becomes a union of the Git repository, and the application overrides. The Argo CD parameter
overrides feature is provided mainly as a convenience to developers and is intended to be used in
dev/test environments, vs. production environments.
> [!TIP]
> Many consider this mode of operation as an anti-pattern to GitOps, since the source of
> truth becomes a union of the Git repository, and the application overrides. The Argo CD parameter
> overrides feature is provided mainly as a convenience to developers and is intended to be used in
> dev/test environments, vs. production environments.
To use parameter overrides, run the `argocd app set -p (COMPONENT=)PARAM=VALUE` command:

100
docs/user-guide/private-repositories.md
View file

@ -1,10 +1,10 @@
# Private Repositories
!!!note
Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to
specify the `.git` suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the
repository URL suffixed with `.git`. Argo CD will **not** follow these redirects, so you have to
adapt your repository URL to be suffixed with `.git`.
> [!NOTE]
> Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to
> specify the `.git` suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the
> repository URL suffixed with `.git`. Argo CD will **not** follow these redirects, so you have to
> adapt your repository URL to be suffixed with `.git`.
## Credentials
@ -47,8 +47,8 @@ Instead of using username and password you might use access token. Following ins
Then, connect the repository using any non-empty string as username and the access token value as a password.
!!!note
For some services, you might have to specify your account name as the username instead of any string.
> [!NOTE]
> For some services, you might have to specify your account name as the username instead of any string.
### TLS Client Certificates for HTTPS repositories
@ -62,11 +62,11 @@ Of course, you can also use this in combination with the `--username` and `--pas
Your TLS client certificate and corresponding key can also be configured using the UI, see instructions for adding Git repos using HTTPS.
!!! note
Your client certificate and key data must be in PEM format, other formats (such as PKCS12) are not supported. Also make sure that your certificate's key is not password protected, otherwise it cannot be used by Argo CD.
> [!NOTE]
> Your client certificate and key data must be in PEM format, other formats (such as PKCS12) are not supported. Also make sure that your certificate's key is not password protected, otherwise it cannot be used by Argo CD.
!!! note
When pasting TLS client certificate and key in the text areas in the web UI, make sure they contain no unintended line breaks or additional characters.
> [!NOTE]
> When pasting TLS client certificate and key in the text areas in the web UI, make sure they contain no unintended line breaks or additional characters.
### SSH Private Key Credential
@ -74,11 +74,11 @@ Private repositories that require an SSH private key have a URL that typically s
You can configure your Git repository using SSH either using the CLI or the UI.
!!! note
Argo CD 2.4 upgraded to OpenSSH 8.9. OpenSSH 8.8
[dropped support for the `ssh-rsa` SHA-1 key signature algorithm](https://www.openssh.com/txt/release-8.8).
See the [2.3 to 2.4 upgrade guide](../operator-manual/upgrading/2.3-2.4.md) for details about testing SSH servers
for compatibility with Argo CD and for working around servers that do not support newer algorithms.
> [!NOTE]
> Argo CD 2.4 upgraded to OpenSSH 8.9. OpenSSH 8.8
> [dropped support for the `ssh-rsa` SHA-1 key signature algorithm](https://www.openssh.com/txt/release-8.8).
> See the [2.3 to 2.4 upgrade guide](../operator-manual/upgrading/2.3-2.4.md) for details about testing SSH servers
> for compatibility with Argo CD and for working around servers that do not support newer algorithms.
Using the CLI:
@ -98,18 +98,18 @@ Using the UI:
3. Click `Connect` to test the connection and have the repository added
!!!note
When pasting SSH private key in the UI, make sure there are no unintended line breaks or additional characters in the text area
> [!NOTE]
> When pasting SSH private key in the UI, make sure there are no unintended line breaks or additional characters in the text area
!!!note
When your SSH repository is served from a non-standard port, you have to use `ssh://`-style URLs to specify your repository. The scp-style `git@yourgit.com:yourrepo` URLs do **not** support port specification, and will treat any port number as part of the repository's path.
> [!NOTE]
> When your SSH repository is served from a non-standard port, you have to use `ssh://`-style URLs to specify your repository. The scp-style `git@yourgit.com:yourrepo` URLs do **not** support port specification, and will treat any port number as part of the repository's path.
### GitHub App Credential
Private repositories that are hosted on GitHub.com or GitHub Enterprise can be accessed using credentials from a GitHub Application. Consult the [GitHub documentation](https://docs.github.com/en/developers/apps/about-apps#about-github-apps) on how to create an application.
!!!note
Ensure your application has at least `Read-only` permissions to the `Contents` of the repository. This is the minimum requirement.
> [!NOTE]
> Ensure your application has at least `Read-only` permissions to the `Contents` of the repository. This is the minimum requirement.
You can configure access to your Git repository hosted by GitHub.com or GitHub Enterprise using the GitHub App method by either using the CLI or the UI.
@ -119,8 +119,8 @@ Using the CLI:
argocd repo add https://github.com/argoproj/argocd-example-apps.git --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem
```
!!!note
To add a private Git repository on GitHub Enterprise using the CLI add `--github-app-enterprise-base-url https://ghe.example.com/api/v3` flag.
> [!NOTE]
> To add a private Git repository on GitHub Enterprise using the CLI add `--github-app-enterprise-base-url https://ghe.example.com/api/v3` flag.
Using the UI:
@ -130,21 +130,21 @@ Using the UI:
2. Click `Connect Repo using GitHub App` button, choose type: `GitHub` or `GitHub Enterprise`, enter the URL, App Id, Installation Id, and the app's private key.
!!!note
Enter the GitHub Enterprise Base URL for type `GitHub Enterprise`.
![connect repo](../assets/repo-add-github-app.png)
> [!NOTE]
> Enter the GitHub Enterprise Base URL for type `GitHub Enterprise`.
> ![connect repo](../assets/repo-add-github-app.png)
3. Click `Connect` to test the connection and have the repository added
!!!note
When pasting GitHub App private key in the UI, make sure there are no unintended line breaks or additional characters in the text area
> [!NOTE]
> When pasting GitHub App private key in the UI, make sure there are no unintended line breaks or additional characters in the text area
### Google Cloud Source
Private repositories hosted on Google Cloud Source can be accessed using Google Cloud service account key in JSON format. Consult [Google Cloud documentation](https://cloud.google.com/iam/docs/creating-managing-service-accounts) on how to create a service account.
!!!note
Ensure your application has at least `Source Repository Reader` permissions for the Google Cloud project. This is the minimum requirement.
> [!NOTE]
> Ensure your application has at least `Source Repository Reader` permissions for the Google Cloud project. This is the minimum requirement.
You can configure access to your Git repository hosted on Google Cloud Source using the CLI or the UI.
@ -248,11 +248,11 @@ In order for Argo CD to use a credential template for any given repository, the
* The repository must either not be configured at all, or if configured, must not contain any credential information
* The URL configured for a credential template (e.g. `https://github.com/argoproj`) must match as prefix for the repository URL (e.g. `https://github.com/argoproj/argocd-example-apps`).
!!! note
Repositories that require authentication can be added using CLI or Web UI without specifying credentials only after a matching repository credential has been set up
> [!NOTE]
> Repositories that require authentication can be added using CLI or Web UI without specifying credentials only after a matching repository credential has been set up
!!! note
Matching credential template URL prefixes is done on a _best match_ effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration.
> [!NOTE]
> Matching credential template URL prefixes is done on a _best match_ effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration.
The following is an example CLI session, depicting repository credential set-up:
@ -284,14 +284,14 @@ If you are connecting a repository on a HTTPS server using a self-signed certifi
2. You can configure ArgoCD to use a custom certificate for the verification of the server's certificate using the `cert add-tls` command of the `argocd` CLI utility. This is the recommended method and suitable for production use. In order to do so, you will need the server's certificate, or the certificate of the CA used to sign the server's certificate, in PEM format.
!!! note
For invalid server certificates, such as those without matching server name, or those that are expired, adding a CA certificate will not help. In this case, your only option will be to use the `--insecure-skip-server-verification` flag to connect the repository. You are strongly urged to use a valid certificate on the repository server, or to urge the server's administrator to replace the faulty certificate with a valid one.
> [!NOTE]
> For invalid server certificates, such as those without matching server name, or those that are expired, adding a CA certificate will not help. In this case, your only option will be to use the `--insecure-skip-server-verification` flag to connect the repository. You are strongly urged to use a valid certificate on the repository server, or to urge the server's administrator to replace the faulty certificate with a valid one.
!!! note
TLS certificates are configured on a per-server, not on a per-repository basis. If you connect multiple repositories from the same server, you only have to configure the certificates once for this server.
> [!NOTE]
> TLS certificates are configured on a per-server, not on a per-repository basis. If you connect multiple repositories from the same server, you only have to configure the certificates once for this server.
!!! note
It can take up to a couple of minutes until the changes performed by the `argocd cert` command are propagated across your cluster, depending on your Kubernetes setup.
> [!NOTE]
> It can take up to a couple of minutes until the changes performed by the `argocd cert` command are propagated across your cluster, depending on your Kubernetes setup.
### Managing TLS certificates using the CLI
@ -324,8 +324,8 @@ You can also add more than one PEM for a server by concatenating them into the i
cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert
```
!!! note
To replace an existing certificate for a server, use the `--upsert` flag to the `cert add-tls` CLI command.
> [!NOTE]
> To replace an existing certificate for a server, use the `--upsert` flag to the `cert add-tls` CLI command.
Finally, TLS certificates can be removed using the `argocd cert rm` command with the `--cert-type https` modifier:
@ -364,11 +364,11 @@ If you are using a privately hosted Git service over SSH, then you have the foll
2. You can make the server's SSH public key known to ArgoCD by using the `cert add-ssh` command of the `argocd` CLI utility. This is the recommended method and suitable for production use. In order to do so, you will need the server's SSH public host key, in the `known_hosts` format understood by `ssh`. You can get the server's public SSH host key e.g. by using the `ssh-keyscan` utility.
!!! note
It can take up to a couple of minutes until the changes performed by the `argocd cert` command are propagated across your cluster, depending on your Kubernetes setup.
!!! note
When importing SSH known hosts key from a `known_hosts` file, the hostnames or IP addresses in the input data must **not** be hashed. If your `known_hosts` file contains hashed entries, it cannot be used as input source for adding SSH known hosts - neither in the CLI nor in the UI. If you absolutely wish to use hashed known hosts data, the only option will be using declarative setup (see below). Be aware that this will break CLI and UI certificate management, so it is generally not recommended.
> [!NOTE]
> It can take up to a couple of minutes until the changes performed by the `argocd cert` command are propagated across your cluster, depending on your Kubernetes setup.
>
> [!NOTE]
> When importing SSH known hosts key from a `known_hosts` file, the hostnames or IP addresses in the input data must **not** be hashed. If your `known_hosts` file contains hashed entries, it cannot be used as input source for adding SSH known hosts - neither in the CLI nor in the UI. If you absolutely wish to use hashed known hosts data, the only option will be using declarative setup (see below). Be aware that this will break CLI and UI certificate management, so it is generally not recommended.
### Managing SSH Known Hosts using the CLI
@ -473,8 +473,8 @@ Specify the `--enable-oci` flag of the `argocd repo add` command:
argocd repo add registry-1.docker.io/bitnamicharts --type=helm --enable-oci=true <additional-flags>
```
!!! note
The protocol, such as `oci://` should be omitted when referencing an OCI registry
> [!NOTE]
> The protocol, such as `oci://` should be omitted when referencing an OCI registry
Using the UI:

10
docs/user-guide/projects.md
View file

@ -334,11 +334,11 @@ stringData:
password: ****
```
!!! warning
Please keep in mind when using a project-scoped repository, only applications or applicationsets with a matching project
name can make use of it. When using an applicationset with a Git generator that also makes use of a templated `project`
(i.e. it contains ``{{ ... }}``) only non-scoped repositories can be used with the applicationset (i.e. repositories
that do _not_ have a `project` set).
> [!WARNING]
> Please keep in mind when using a project-scoped repository, only applications or applicationsets with a matching project
> name can make use of it. When using an applicationset with a Git generator that also makes use of a templated `project`
> (i.e. it contains ``{{ ... }}``) only non-scoped repositories can be used with the applicationset (i.e. repositories
> that do _not_ have a `project` set).
All the examples above concern Git repositories, but the same principles apply to clusters as well.

10
docs/user-guide/scale_application_resources.md
View file

@ -12,9 +12,9 @@ This enables users to scale resources directly from the Argo CD UI. Users will b
5. User presses OK, and the resource is scaled accordingly.
![result for scaling](../assets/scale_resources_3.png)
!!! note
This feature will only apply to `Deployments`, and `StatefulSets`.
> [!NOTE]
> This feature will only apply to `Deployments`, and `StatefulSets`.
!!! note
If you use HPA (Horizontal Pod Autoscaling) or enabled Argo CD auto-sync, changing the replica count in scale actions would be overwritten.
Ensure that invalid values (e.g., `non-numeric` characters, `negative` numbers, or values beyond the `max integer limit`) cannot be entered.
> [!NOTE]
> If you use HPA (Horizontal Pod Autoscaling) or enabled Argo CD auto-sync, changing the replica count in scale actions would be overwritten.
> Ensure that invalid values (e.g., `non-numeric` characters, `negative` numbers, or values beyond the `max integer limit`) cannot be entered.

10
docs/user-guide/skip_reconcile.md
View file

@ -1,9 +1,11 @@
# Skip Application Reconcile
!!! warning "Alpha Feature (Since v2.7.0)"
This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha) feature.
The primary use case is to provide integration with third party projects.
This feature may be removed in future releases or modified in backwards-incompatible ways.
> [!WARNING]
> **Alpha Feature (Since v2.7.0)**
>
> This is an experimental, [alpha-quality](https://github.com/argoproj/argoproj/blob/main/community/feature-status.md#alpha) feature.
> The primary use case is to provide integration with third party projects.
> This feature may be removed in future releases or modified in backwards-incompatible ways.
Argo CD allows users to stop an Application from reconciling.
The skip reconcile option is configured with the `argocd.argoproj.io/skip-reconcile: "true"` annotation.

30
docs/user-guide/source-hydrator.md
View file

@ -26,8 +26,8 @@ data:
hydrator.enabled: "true"
```
!!! important
After updating the ConfigMap, you must restart the Argo CD controller and API server for the changes to take effect.
> [!IMPORTANT]
> After updating the ConfigMap, you must restart the Argo CD controller and API server for the changes to take effect.
If you are using one of the `*-install.yaml` manifests to install Argo CD, you can use the
`*-install-with-hydrator.yaml` version of that file instead.
@ -39,10 +39,10 @@ Without hydrator: https://raw.githubusercontent.com/argoproj/argo-cd/stable/mani
With hydrator: https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install-with-hydrator.yaml
```
!!! important
The `*-with-hydrator-install.yaml` manifests will eventually be removed when the source hydrator is either enabled
by default or removed. The upgrade guide will note if the `install-with-hydrator.yaml` manifests are no longer
available.
> [!IMPORTANT]
> The `*-with-hydrator-install.yaml` manifests will eventually be removed when the source hydrator is either enabled
> by default or removed. The upgrade guide will note if the `install-with-hydrator.yaml` manifests are no longer
> available.
## Using the Source Hydrator
@ -116,7 +116,9 @@ During each hydration run, Argo CD cleans the application's configured path befo
It is important to note that hydration only cleans the currently configured application path. If an application’s path changes, the old directory is not removed automatically. Likewise, if an application is deleted, its output path remains in the repository and must be cleaned up manually by the repository owner if desired. This design is intentional: it prevents accidental deletion of files when applications are restructured or removed, and it protects critical files like CI pipelines that may coexist in the repository.
!!! important "Project-Scoped Repositories"
> [!IMPORTANT]
> **Project-Scoped Repositories**
>
Repository Secrets may contain a `project` field, making the secret only usable by Applications in that project.
The source hydrator only supports project-scoped repositories if all Applications writing to the same repository and
@ -194,8 +196,8 @@ git commit -m "Bump image to v1.2.3" \
--trailer "Argocd-reference-commit-date: 2025-06-09T13:50:18-04:00"
```
!!!note Newlines are not allowed
The commit trailers must not contain newlines.
> [!NOTE]
> The commit trailers must not contain newlines.
So the full CI script might look something like this:
@ -375,8 +377,8 @@ from pushing to the hydrated branches, enable branch protection in your SCM.
It is best practice to prefix the hydrated branches with a common prefix, such as `environments/`. This makes it easier
to configure branch protection rules on the destination repository.
!!! note
To maintain reproducibility and determinism in the Hydrator’s output,
Argo CD-specific metadata (such as `argocd.argoproj.io/tracking-id`) is
not written to Git during hydration. These annotations are added dynamically
during application sync and comparison.
> [!NOTE]
> To maintain reproducibility and determinism in the Hydrator’s output,
> Argo CD-specific metadata (such as `argocd.argoproj.io/tracking-id`) is
> not written to Git during hydration. These annotations are added dynamically
> during application sync and comparison.

12
docs/user-guide/sync-options.md
View file

@ -185,9 +185,9 @@ spec:
If the `Replace=true` sync option is set, Argo CD will use `kubectl replace` or `kubectl create` command to apply changes.
!!! warning
During the sync process, the resources will be synchronized using the 'kubectl replace/create' command.
This sync option has the potential to be destructive and might lead to resources having to be recreated, which could cause an outage for your application.
> [!WARNING]
> During the sync process, the resources will be synchronized using the 'kubectl replace/create' command.
> This sync option has the potential to be destructive and might lead to resources having to be recreated, which could cause an outage for your application.
This can also be configured at individual resource level.
```yaml
@ -200,9 +200,9 @@ metadata:
For certain resources you might want to delete and recreate, e.g. job resources that should run every time when syncing.
!!! warning
During the sync process, the resources will be synchronized using the 'kubectl delete/create' command.
This sync option has a destructive action, which could cause an outage for your application.
> [!WARNING]
> During the sync process, the resources will be synchronized using the 'kubectl delete/create' command.
> This sync option has a destructive action, which could cause an outage for your application.
In such cases you might use `Force=true` sync option in target resources annotation:
```yaml

8
docs/user-guide/tracking_strategies.md
View file

@ -6,8 +6,8 @@ In all tracking strategies, the app has the option to sync automatically. If [au
is configured, the new resources manifests will be applied automatically -- as soon as a difference
is detected.
!!! note
In all tracking strategies, any [parameter overrides](parameters.md) take precedence over the Git state.
> [!NOTE]
> In all tracking strategies, any [parameter overrides](parameters.md) take precedence over the Git state.
## Helm
@ -23,8 +23,8 @@ Helm chart versions are [Semantic Versions](https://semver.org/). As a result, y
[Read about version ranges](https://www.telerik.com/blogs/the-mystical-magical-semver-ranges-used-by-npm-bower)
!!! note
If you want Argo CD to include all existing prerelease version tags of a repository in the comparison logic, you explicitly have to add a prerelease `-0` suffix to the version constraint. As mentioned `*-0` will compare against prerelease versions in a repository, `*` will not. The same applies for other constraints e.g. `>=1.2.2` will **not** compare prerelease versions vs. `>=1.2.2-0` which will include prerelease versions in the comparison.
> [!NOTE]
> If you want Argo CD to include all existing prerelease version tags of a repository in the comparison logic, you explicitly have to add a prerelease `-0` suffix to the version constraint. As mentioned `*-0` will compare against prerelease versions in a repository, `*` will not. The same applies for other constraints e.g. `>=1.2.2` will **not** compare prerelease versions vs. `>=1.2.2-0` which will include prerelease versions in the comparison.
[Read about prerelease version comparison](https://github.com/Masterminds/semver?tab=readme-ov-file#working-with-prerelease-versions)

72
hack/admonitions-to-alerts.sh Executable file
View file

@ -0,0 +1,72 @@
#!/usr/bin/env bash
# Historically we've used mkdocs admonitions for callouts in our documentation. Those admonitions look great in mkdocs,
# but they don't render well in GitHub. GitHub supports a different style of callouts, called alerts.
# This script converts mkdocs admonitions to GitHub-flavored markdown alerts.
# GitHub alerts don't support titles, so we convert titles to bold text at the start of the alert body.
# This script is run manually. It's left here in case we need to run it again in the future.
declare -A TYPE_MAP=(
["note"]="NOTE"
["tip"]="TIP"
["important"]="IMPORTANT"
["warning"]="WARNING"
["danger"]="CAUTION"
)
# Process all .md files in the docs directory.
find docs -type f -name "*.md" | while read -r FILE; do
# Skip the file if it doesn't contain any admonitions.
if ! grep -q '^!!!' "$FILE"; then
continue
fi
# Create a temporary file to store the converted content.
TEMP_FILE=$(mktemp)
# Read the file line by line.
ALERT_STARTED=0
while IFS= read -r LINE || [[ -n "$LINE" ]]; do
# Check if the line starts with an admonition (!!!).
if [[ "$LINE" =~ ^!!![[:space:]]*([a-zA-Z]+)([[:space:]]*\"(.*)\")? ]]; then
TYPE=${BASH_REMATCH[1]}
TITLE=${BASH_REMATCH[3]}
# Map the MkDocs type to GitHub alert type.
ALERT_TYPE=${TYPE_MAP[$TYPE]}
if [[ -z "$ALERT_TYPE" ]]; then
# If the type is not in the map, copy the line as is.
echo "$LINE" >> "$TEMP_FILE"
continue
fi
# Start the GitHub alert.
echo -e "> [!$ALERT_TYPE]" >> "$TEMP_FILE"
ALERT_STARTED=1
# Add the title as bold text if it exists.
if [[ -n "$TITLE" ]]; then
echo -e "> **$TITLE**" >> "$TEMP_FILE"
# Add a blank line after the title for better formatting.
echo -e ">" >> "$TEMP_FILE"
fi
else
# For non-admonition lines, check indentation and adjust for alert body.
if [[ ALERT_STARTED -eq 1 ]] && [[ "$LINE" =~ ^[[:space:]]+ ]]; then
# Strip leading whitespace and prepend "> "
STRIPPED_LINE=${LINE##+([[:space:]])}
echo -e "> $STRIPPED_LINE" >> "$TEMP_FILE"
else
echo "$LINE" >> "$TEMP_FILE"
ALERT_STARTED=0
fi
fi
done < "$FILE"
# Replace the original file with the converted content.
mv "$TEMP_FILE" "$FILE"
done
echo "Conversion complete."

2
mkdocs.yml
View file

@ -235,6 +235,8 @@ nav:
- roadmap.md
- Releases ⧉: https://github.com/argoproj/argo-cd/releases
- Blog ⧉: https://blog.argoproj.io/
plugins:
- gh-admonitions
repo_url: https://github.com/argoproj/argo-cd
site_name: Argo CD - Declarative GitOps CD for Kubernetes
site_url: !ENV READTHEDOCS_CANONICAL_URL