Refresh docs

[pasha-codefresh]

User description

Checklist:

• Either (a) I've created an enhancement proposal and discussed it with the community, (b) this is a bug fix, or (c) this does not need to be in the release notes.
• The title of the PR states what changed and the related issues number (used for the release note).
• The title of the PR conforms to the Toolchain Guide
• I've included "Closes [ISSUE #]" or "Fixes [ISSUE #]" in the description to automatically close the associated issue.
• I've updated both the CLI and UI to expose my feature, or I plan to submit a second PR with them.
• Does this PR require documentation updates?
• I've updated documentation as required by this PR.
• I have signed off all my commits as required by DCO
• I have written unit and/or e2e tests for my change. PRs without these are unlikely to be merged.
• My build is green (troubleshooting builds).
• My new feature complies with the feature status guidelines.
• I have added a brief description of why this PR is necessary and/or what this PR solves.
• Optional. My organization is added to USERS.md.
• Optional. For bug fixes, I've indicated what older releases this fix should be cherry-picked into (this may or may not happen depending on risk/complexity).

---

Type

enhancement, documentation

---

Description

• Introduced and detailed repository concepts, authentication methods, and credential templates in Argo CD.
• Provided comprehensive guides on managing Applications, including their state, health, and sync windows.
• Explained project-level settings, including destinations, sources, cluster resources, and GnuPG keys.
• Included installation instructions for Argo CD server components and CLI tools on various platforms.

---

Changes walkthrough

Relevant files

Documentation

10 files index.md Introduce Repository Concepts and Configuration in Argo CD docs/basics/repos/index.md Introduced the concept of unconfigured vs. configured repositories in Argo CD Explained the difference between Git and Helm repositories Described how to specify repository URLs +126/-0  auth.md Detail Repository Authentication Methods in Argo CD            docs/basics/repos/auth.md Detailed the available authentication methods for repositories Explained Personal Access Tokens (PAT) usage for Git providers Introduced credential templates for repository access +77/-0    index.md Overview of Argo CD Applications and Their Configuration  docs/basics/apps/index.md Overview of Argo CD Applications Explained the relationship between Application, Source, and Destination Mentioned optional Sync Policy for Applications +92/-0    manage.md Guide on Managing Argo CD Applications                                      docs/basics/apps/manage.md Instructions on managing Applications via argocd CLI and web UI Provided examples for listing and getting details about Applications Described how to create new Applications using the CLI +72/-0    state.md Understanding Application State and Health in Argo CD        docs/basics/apps/state.md Described the Sync Status and Application Health concepts Explained how Argo CD determines these statuses Mentioned the impact of diffing behavior on Sync Status +66/-0    sync_windows.md Detailed Guide on Sync Windows in Argo CD                                docs/advanced/sync_windows.md Introduced Sync Windows concept for controlling sync operations Provided CLI commands and examples for managing Sync Windows Explained how Sync Windows affect manual and automated syncs +112/-1  manage.md Guide on Managing Clusters in Argo CD                                        docs/basics/clusters/manage.md Instructions on managing clusters via argocd CLI, web UI, and Kubernetes API Provided examples for listing, adding, and removing clusters Explained how clusters are stored as Kubernetes secrets +117/-0  settings.md Configuring Project-Level Settings in Argo CD                        docs/basics/projects/settings.md Described project-level settings in Argo CD Explained how to configure destinations, sources, and resource permissions Introduced GnuPG keys and Sync Windows settings for projects +135/-0  install.md Installation Instructions for Argo CD Server Components    docs/getting_started/install.md Provided installation instructions for Argo CD server components Explained different installation types and variants Included steps for pre-requisites, installation, and post-installation tasks +226/-0  install_cli.md Installing Argo CD CLI on Linux and MacOS                                docs/getting_started/install_cli.md Instructions on installing Argo CD CLI on Linux and MacOS Provided manual download and install steps Mentioned Homebrew installation option for MacOS +121/-0

---

✨ PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[qodo-code-review]

PR-Agent was enabled for this repository. To use it, please link your git user with your CodiumAI identity here.

CI Failure Feedback

Action: Validate PR Title

Failed stage: Run thehanimo/pr-title-checker@0cf5902181e78341bb97bb06646396e5bd354b3f [❌]

Failure summary: The action failed because it encountered an HttpError when attempting to add the label 'title needs formatting' to the PR. This error indicates that the integration (in this case, the action thehanimo/pr-title-checker) does not have the necessary permissions to modify PR labels. This is likely due to insufficient permissions configured for the GITHUB_TOKEN used by the action.

Relevant error logs: 1: ##[group]Operating System 2: Ubuntu ... 22: Prepare all required actions 23: Getting action download info 24: Download action repository 'thehanimo/pr-title-checker@0cf5902181e78341bb97bb06646396e5bd354b3f' (SHA:0cf5902181e78341bb97bb06646396e5bd354b3f) 25: Complete job name: Validate PR Title 26: ##[group]Run thehanimo/pr-title-checker@0cf5902181e78341bb97bb06646396e5bd354b3f 27: with: 28: GITHUB_TOKEN: *** 29: configuration_path: .github/pr-title-checker-config.json 30: pass_on_octokit_error: false 31: ##[endgroup] 32: Using config file .github/pr-title-checker-config.json from repo pasha-codefresh/argo-cd [ref: 8bb41eda04d9a41a4fe7375888d77f91a68fd429] 33: Creating label (title needs formatting)... 34: Label (title needs formatting) already created. 35: ##[notice]PR Title needs to pass regex '^(feat|fix|docs|test|ci|chore)!?(\(.*\))?!?:.* 36: Adding label (title needs formatting) to PR... 37: HttpError: Resource not accessible by integration 38: ##[error]Failed to add label (title needs formatting) to PR

---

✨ CI feedback usage guide:

---

The CI feedback tool (/checks) automatically triggers when a PR has a failed check.
The tool analyzes the failed checks and provides several feedbacks:

• Failed stage
• Failed test name
• Failure summary
• Relevant error logs

In addition to being automatically triggered, the tool can also be invoked manually by commenting on a PR:

/checks "https://github.com/{repo_name}/actions/runs/{run_number}/job/{job_number}"

where {repo_name} is the name of the repository, {run_number} is the run number of the failed check, and {job_number} is the job number of the failed check.

Configuration options

• enable_auto_checks_feedback - if set to true, the tool will automatically provide feedback when a check is failed. Default is true.
• excluded_checks_list - a list of checks to exclude from the feedback, for example: ["check1", "check2"]. Default is an empty list.
• enable_help_text - if set to true, the tool will provide a help message with the feedback. Default is true.
• persistent_comment - if set to true, the tool will overwrite a previous checks comment with the new feedback. Default is true.
• final_update_message - if persistent_comment is true and updating a previous checks message, the tool will also create a new message: "Persistent checks updated to latest commit". Default is true.

See more information about the checks tool in the docs.

[qodo-code-review]

PR-Agent was enabled for this repository. To use it, please link your git user with your CodiumAI identity here.

PR Description updated to latest commit (8409da4)

• Copy walkthrough table to "Files Changed" Tab

[qodo-code-review]

PR-Agent was enabled for this repository. To use it, please link your git user with your CodiumAI identity here.

PR Review

⏱️ Estimated effort to review [1-5]	5, because the PR introduces significant changes across multiple files, including new features, documentation updates, and structural changes. The complexity and breadth of the changes require a thorough review to ensure consistency, accuracy, and adherence to project standards.
🧪 Relevant tests	No
🔍 Possible issues	Possible Bug: Without seeing the implementation details, it's hard to assess potential issues like performance impacts, security vulnerabilities, or bugs in the new features and documentation updates.
	Documentation Consistency: With the addition of new documentation and updates to existing ones, there's a risk of inconsistencies or inaccuracies that could confuse users.
	Feature Completeness: It's unclear if all new features introduced in the PR are fully implemented and tested, which could lead to incomplete functionality.
🔒 Security concerns	No specific security concerns identified without more context on the implementation details of the new features and changes. However, general security best practices should be reviewed, especially concerning any new authentication mechanisms or changes to permission handling.

---

✨ Review tool usage guide:

---

Overview:
The review tool scans the PR code changes, and generates a PR review which includes several types of feedbacks, such as possible PR issues, security threats and relevant test in the PR. More feedbacks can be added by configuring the tool.

The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR.

• When commenting, to edit configurations related to the review tool (pr_reviewer section), use the following template:

/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...

• With a configuration file, use the following template:

[pr_reviewer]
some_config1=...
some_config2=...

See the review usage page for a comprehensive guide on using this tool.

[qodo-code-review]

PR Code Suggestions

Category	Suggestions
Enhancement	Correct a typo in the document. Consider revising the spelling of "privately hostes ones" to "privately hosted ones" to correct the typo. docs/basics/repositories.md [11] -* Git repositories, such as GitHub, GitLab or privately hostes ones +* Git repositories, such as GitHub, GitLab or privately hosted ones
	Correct a spelling mistake in the document. Replace "accesible" with "accessible" to correct the spelling mistake. docs/basics/repositories.md [43] -repository when creating an application, as long as the repository is allowed as a source in the [project's configuration](projects/#sources) and is publicly accesible or matches one of the configured credential templates. +repository when creating an application, as long as the repository is allowed as a source in the [project's configuration](projects/#sources) and is publicly accessible or matches one of the configured credential templates.
	Correct a spelling error in the document. Consider revising "convinient" to "convenient" to correct the spelling error. docs/basics/repositories.md [387] -Credential templates are a convinient method for accessing multiple repositories with the same set of credentials, so you don't have to configure (and possibly change regulary) credentials for every repository that you might want to access from ArgoCD. +Credential templates are a convenient method for accessing multiple repositories with the same set of credentials, so you don't have to configure (and possibly change regularly) credentials for every repository that you might want to access from ArgoCD.
	Correct another spelling mistake in the document. Replace "regulary" with "regularly" to correct the spelling mistake. docs/basics/repositories.md [387] -Credential templates are a convinient method for accessing multiple repositories with the same set of credentials, so you don't have to configure (and possibly change regulary) credentials for every repository that you might want to access from ArgoCD. +Credential templates are a convenient method for accessing multiple repositories with the same set of credentials, so you don't have to configure (and possibly change regularly) credentials for every repository that you might want to access from ArgoCD.
	Improve grammatical accuracy in the document. Consider revising "you do not want use this switch for production environments." to "you do not want to use this switch in production environments." for grammatical accuracy. docs/basics/repositories.md [230] -|`--insecure-skip-server-verification`|None|Disables verification of the server's TLS certificate or SSH known host signature, depending on the connection method. You do not want use this switch for production environments.| +|`--insecure-skip-server-verification`|None|Disables verification of the server's TLS certificate or SSH known host signature, depending on the connection method. You do not want to use this switch in production environments.|
	Add information or a link on how to find cluster IDs for controller sharding. Consider adding a brief explanation or link to documentation on how to determine the ID of a cluster, as this information is crucial for understanding how to manage controller sharding effectively. docs/operations/scaling.md [137] -Each controller shard will manage a set group of clusters. A shard determines if it should reconcile changes for a cluster if the ID of the cluster mod `ARGOCD_CONTROLLER_REPLICAS` is equal to the index number of the controller shard. +Each controller shard will manage a set group of clusters. A shard determines if it should reconcile changes for a cluster if the ID of the cluster mod `ARGOCD_CONTROLLER_REPLICAS` is equal to the index number of the controller shard. For details on how to find a cluster's ID, refer to [Finding Cluster IDs](#finding-cluster-ids).
	Provide an example for adding the shard key to a cluster's secret. For the section on "Pinning" Clusters, it would be beneficial to include an example command or code snippet showing how to base64 encode and add the shard key to a cluster's secret, making it easier for users to follow along. docs/operations/scaling.md [146] -Once you know the name of the cluster you want to pin, you need to add the `shard` key to the `Secret` resource using `kubectl edit secrets <secret name>`. The value **must be base64 encoded and have no whitespace**. +Once you know the name of the cluster you want to pin, you can add the `shard` key to the `Secret` resource like so: +```bash +SHARD_NUM=$(echo -n "9" | base64) +kubectl patch secret <secret name> -p '{"data":{"shard":"'"$SHARD_NUM"'"}}' +``` +
	Add a table of contents for better document navigation. To ensure the documentation remains accessible and easy to navigate, consider adding a table of contents at the beginning of the document. This table should link to the major sections such as "Common Scaling Problems", "High Availability Mode", "Controller Sharding", and "Settings Reference For Individual Components". docs/operations/scaling.md [1] +## Table of Contents +- [Common Scaling Problems](#common-scaling-problems) +- [High Availability Mode](#high-availability-mode) +- [Controller Sharding](#controller-sharding) +- [Settings Reference For Individual Components](#settings-reference-for-individual-components) + ## Common Scaling Problems
	Include an introduction or link to Kustomize documentation for beginners. For the section on using Kustomize to manage pinned clusters, it would be helpful to include a brief explanation or link to documentation on how to use Kustomize for those who may not be familiar with it. This would make the documentation more inclusive for users with varying levels of experience. docs/operations/scaling.md [150] -It's also possible to use kustomize to generate pinned cluster secrets using [kustomize secret generators](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/), which means if you already manage your Argo CD installation via kustomize it's easy to update it to track pinned clusters in git. +It's also possible to use kustomize to generate pinned cluster secrets using [kustomize secret generators](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/). If you're not familiar with Kustomize, it's a tool for customizing Kubernetes configurations. This means if you already manage your Argo CD installation via kustomize, it's easy to update it to track pinned clusters in git. For a beginner's guide to Kustomize, see [Getting Started with Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/).
	Add examples for configuring Git and Helm repositories using the CLI. To improve clarity and user understanding, consider adding examples for each type of repository configuration (Git and Helm) when using the CLI. This will help users quickly grasp how to configure different types of repositories with specific options. docs/basics/repos/manage.md [47-49] To add a configuration for a Git repository to be connected using HTTPS, you can use the `argocd repo add` command, specifying a repository URL starting -with `https://`. +with `https://`. For example, to add a Helm repository: +```bash +argocd repo add --type helm --name my-helm-repo https://example.com/helm/charts +``` + +This command adds a Helm repository named `my-helm-repo` located at `https://example.com/helm/charts`. +
	Add a troubleshooting section for common repository configuration issues. To enhance the documentation's usability and accessibility, consider adding a troubleshooting section that addresses common issues users might encounter when adding, editing, or removing repository configurations. This section could include solutions to typical error messages or problems. docs/basics/repos/manage.md [17] ## Using the CLI +## Troubleshooting + +This section provides solutions to common issues you might encounter when managing repository configurations with ArgoCD. + +- **Issue:** Error message "Failed to connect to repository" + **Solution:** Ensure the repository URL is correct and accessible from your ArgoCD instance. Check network connectivity and firewall settings. + +- **Issue:** Error message "Authentication failed" + **Solution:** Verify the correctness of your credentials. For SSH connections, ensure your SSH key is added to the SSH agent. +
	Add descriptions for major sections in the documentation navigation. To improve the accessibility and usability of your documentation, consider adding a description for each major section in your navigation. This can be done by providing a brief summary or objective of the section as a comment above its declaration. This not only aids in understanding the purpose of each section but also assists in future documentation planning and updates. mkdocs.yml [29-30] +# Getting started guides help new users set up and familiarize themselves with the system - Getting started: - Server installation: getting_started/install.md
	Automate the update of navigation structure in the documentation. To ensure the documentation remains up-to-date and maintainable, consider using a script to automatically update the navigation structure based on the directory and file structure within the documentation source. This can help in automatically reflecting new additions, renames, or removals without manual updates to the mkdocs.yml. mkdocs.yml [29-30] -- Getting started: - - Server installation: getting_started/install.md +# Suggested improvement involves external scripting and automation, not a direct change in mkdocs.yml
	Add the pymdownx.superfences extension for advanced code block features. For the markdown_extensions section, consider adding the pymdownx.superfences extension. This extension allows for more advanced code block features, such as nested code blocks and custom formatting. It can enhance the readability and functionality of code examples in your documentation. mkdocs.yml [21-23] markdown_extensions: - codehilite - admonition +- pymdownx.superfences
Maintainability	Use a table to summarize settings for better readability. To improve the readability and maintainability of the documentation, consider using a table to summarize the settings for argocd-application-controller, argocd-repo-server, and other components instead of listing them in bullet points. docs/operations/scaling.md [172-178] -**settings:** +| Setting | Description | Default Value | +|---------|-------------|---------------| +| Controller Sharding | For large instances of Argo CD where it's difficult to scale a single controller instance. | See [controller sharding](#controller-sharding) | +| Queue Processors | Number of processors for application reconciliation and app syncing queues. | `--status-processors`: 20, `--operation-processors`: 10 | -* For large instances of Argo CD where it's difficult to scale a single controller instance to meet resource demands, see [controller sharding](#controller-sharding) - -* each controller replica uses two separate queues to process application reconciliation (milliseconds) and app syncing (seconds). Number of queue processors for each queue is controlled by -`--status-processors` (20 by default) and `--operation-processors` (10 by default) flags. -
	Group related items under a single parent in the documentation navigation. For better organization and readability, consider grouping related items under a single parent in the navigation. For example, all Upgrading guides can be nested under a single Upgrading parent. This reduces the navigation depth and makes it easier for users to find related content. mkdocs.yml [90-93] - Upgrading: - - Upgrading Argo CD: operations/upgrading/index.md - - Upgrade guides: + - Overview: operations/upgrading/index.md + - Guides: - 1.7 to 1.8: operations/upgrading/1_7-1_8.md
Security	Add security cautions for --insecure-skip-server-verification and --password flags. Consider adding a note about the potential security implications of using --insecure-skip-server-verification and --password flags. It's important to caution users about the risks of disabling server verification and transmitting passwords in plain text, especially in production environments. docs/basics/repos/manage.md [67-69] -|`--insecure-skip-server-verification`|None|Disables verification of the server's TLS certificate or SSH known host signature, depending on the connection method. You do not want use this switch for production environments.| -|`--password`|`password`|Use `password` for authenticating at the server (only valid for HTTPS repositories and in combination with `--username`)| +|`--insecure-skip-server-verification`|None|Disables verification of the server's TLS certificate or SSH known host signature, depending on the connection method. **Caution:** This can expose you to man-in-the-middle attacks. Avoid using this option in production environments.| +|`--password`|`password`|Use `password` for authenticating at the server (only valid for HTTPS repositories and in combination with `--username`). **Note:** Transmitting passwords in plain text can be insecure. Consider using more secure authentication methods where possible.|
Best practice	Highlight the importance of using secure communication protocols for repository configurations. It's recommended to highlight the importance of using secure communication protocols (HTTPS over HTTP, SSH over plain Git) when adding repository configurations. This can be done by adding a note or warning that emphasizes the security benefits of HTTPS and SSH and discourages the use of insecure protocols. docs/basics/repos/manage.md [32-34] Connecting a repository via HTTPS (TLS) is supported for both repository types, `git` and `helm`. The URL for a Git repository connected using HTTPS must be fully-qualified and prefixed with the protocol, i.e. `https://`. +**Important:** Always prefer using HTTPS or SSH for repository connections to ensure secure communication. Avoid using insecure protocols like HTTP or plain Git, which can expose sensitive data to interception. +
	Suggest using environment variables or secure storage for handling sensitive information. For improved security and maintainability, suggest using environment variables or secure storage for sensitive information like passwords and SSH keys, instead of passing them directly in CLI commands. This can be mentioned as a best practice note in the relevant sections. docs/basics/repos/manage.md [69] -|`--password`|`password`|Use `password` for authenticating at the server (only valid for HTTPS repositories and in combination with `--username`)| +|`--password`|`password`|Use `password` for authenticating at the server (only valid for HTTPS repositories and in combination with `--username`). **Best Practice:** Instead of passing passwords directly, consider using environment variables or secure storage solutions to handle sensitive information securely.|
	Use consistent naming conventions for markdown file paths. Consider using a consistent naming convention for markdown file paths. For example, if you're using getting_started/install.md for getting started guides, consider using basics/apps/overview.md instead of basics/apps/index.md for consistency. This helps in maintaining a uniform structure across your documentation, making it easier for both contributors and users to navigate. mkdocs.yml [30-35] - Server installation: getting_started/install.md -- Overview: basics/apps/index.md +- Overview: basics/apps/overview.md

---

✨ Improve tool usage guide:

---

Overview:
The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR.

• When commenting, to edit configurations related to the improve tool (pr_code_suggestions section), use the following template:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

• With a configuration file, use the following template:

[pr_code_suggestions]
some_config1=...
some_config2=...

See the improve usage page for a comprehensive guide on using this tool.