From a666dbc192404570c3f226725c58aa5c49b29431 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 11 Feb 2025 17:59:02 +0200 Subject: [PATCH 1/3] Split app creation and app settings Created new reference article for application configuration settings; updated argohub and nav yamls --- .../application-configuration-settings.md | 1 + _data/argohub-nav.yml | 4 +- _data/nav.yml | 2 + .../application-configuration-settings.md | 160 ++++++++++++++ .../deployments/gitops/create-application.md | 199 ++++-------------- assets/js/src/argohub-redirect-mapping.json | 3 +- 6 files changed, 212 insertions(+), 157 deletions(-) create mode 120000 _argohub/applications/application-configuration-settings.md create mode 100644 _docs/deployments/gitops/application-configuration-settings.md diff --git a/_argohub/applications/application-configuration-settings.md b/_argohub/applications/application-configuration-settings.md new file mode 120000 index 000000000..8cbb47498 --- /dev/null +++ b/_argohub/applications/application-configuration-settings.md @@ -0,0 +1 @@ +../../_docs/deployments/gitops/application-configuration-settings.md \ No newline at end of file diff --git a/_data/argohub-nav.yml b/_data/argohub-nav.yml index 1c28ba709..2fe2d4fa0 100644 --- a/_data/argohub-nav.yml +++ b/_data/argohub-nav.yml @@ -193,9 +193,11 @@ - title: GitOps Apps dashboard url: "/gitops-apps-dashboard" - title: Application Groups for Argo CD applications - url: "/gitops-app-groups" + url: "/gitops-app-groups" - title: Creating Argo CD applications url: "/create-application" + - title: Application configuration settings + url: "/application-configuration-settings" - title: Monitoring Argo CD applications url: "/monitor-applications" - title: Managing Argo CD applications diff --git a/_data/nav.yml b/_data/nav.yml index b52ebe272..a1b938fab 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -377,6 +377,8 @@ url: "/gitops-app-groups" - title: Creating Argo CD applications url: "/create-application" + - title: Application configuration settings + url: "/application-configuration-settings" - title: Monitoring Argo CD applications url: "/monitor-applications" - title: Managing Argo CD applications diff --git a/_docs/deployments/gitops/application-configuration-settings.md b/_docs/deployments/gitops/application-configuration-settings.md new file mode 100644 index 000000000..02c83017b --- /dev/null +++ b/_docs/deployments/gitops/application-configuration-settings.md @@ -0,0 +1,160 @@ +--- +title: "Application configuration settings" +description: "Review descriptions of configuration settings for Argo CD applications in GitOps" +toc: true +--- + +## Application configuration settings +Configuration settings for applications define the application’s structure, sources, destination, and operational behavior. +For ease of use, settings are organized into distinct categories including: +* [Application definitions](#application-definitions): Basic metadata, such as the application name, GitOps Runtime, and the YAML manifest name. +* [General configuration settings](#application-general-configuration-settings): Product, Group, source, destination, and sync policies for the application. +* [Advanced configuration settings](#application-advanced-configuration-settings): Tool-specific options, project grouping, and propagation policies for resource and application deletion. + +For how-to instructions, see [Create applications]({{site.baseurl}}/docs/deployments/gitops/create-application/). + +## Application: Definitions +Application definitions include the application name, the GitOps Runtime, and the name of the YAML manifest. By default, the YAML manifest has the same name as that of the application. + +{% include + image.html + lightbox="true" + file="/images/applications/add-app-definitions.png" + url="/images/applications/add-app-definitions.png" + alt="Application definitions" + caption="Application definitions" + max-width="50%" + %} + + +## Application: General configuration settings + +General configuration settings define the product, group, to which the application belongs, source, destination, and sync policies for the application. + +{% include + image.html + lightbox="true" + file="/images/applications/add-app-general-settings.png" + url="/images/applications/add-app-general-settings.png" + alt="General configuration settings" + caption="General configuration settings" + max-width="70%" + %} + +### Products +Optional. The product to which to assign the application. Select an existing product, or create and add a new product. +Products empower promotions for applications and make for streamlined management and deployments. +See [Products]({{site.baseurl}}/docs/products/about-products/). + + +### Groups +Optional. The group or groups to which to add the application. Select an existing group or groups, or create a new application group by typing a name and pressing Enter. +Group applications based on criteria meaningful to your organization, such as environment, region, or any other relevant attribute. You can then view deployments for these applications in the same location in the Groups tab of the GitOps Apps dashboard. A new view for Argo CD applications, Groups allow you to collate multiple applications and view their timelines. +See [Application Groups]({{site.baseurl}}/docs/deployments/gitops/gitops-app-groups/). + + + + +### Source +The Git repository with the application resources. +{::nomarkdown}{:/} + + + +### Destination +The cluster and namespace to which to deploy the application. +{::nomarkdown}{:/} + + +### Sync Settings + + +#### Sync Policy +The synchronization policy to apply when there are differences between the desired state in Git and the actual state in the cluster.{::nomarkdown}{:/} + + + +#### Sync Options +Common to both manual and automatic sync policies.{% raw %}{::nomarkdown}{:/}{% endraw %} + + +#### Prune propagation policy +Defines how resources are pruned, applying Kubernetes cascading deletion prune policies. For more information, see [Kubernetes - Cascading deletion](https://kubernetes.io/docs/concepts/architecture/garbage-collection/#cascading-deletion){:target="\_blank"}.{::nomarkdown}
{:/} +All Prune propagation policies can be used with: + +**Replace**: When selected, Argo CD executes `kubectl replace` or `kubectl create`, instead of the default `kubectl apply` to enforce the changes in Git. This action will potentially recreate resources and should be used with care. See [Replace Resource Instead Of Applying Change](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/#replace-resource-instead-of-applying-changes){:target="\_blank"}. + +**Retry**: When selected, retries a failed sync operation, based on the retry settings configured: +* Maximum number of sync retries (**Limit**) +* Duration of each retry attempt in seconds, minutes, or hours (**Duration**) +* Maximum duration permitted for each retry (**Max Duration**) +* Factor by which to multiply the Duration in the event of a failed retry (**Factor**). A factor of 2 for example, attempts the second retry in 2 X 2 seconds, where 2 seconds is the Duration. + + + +## Application: Advanced configuration settings + +Advanced settings define the tool used to create the application, and related toll-specific settings. + +{% include + image.html + lightbox="true" + file="/images/applications/add-app-advanced-settings.png" + url="/images/applications/add-app-advanced-settings.png" + alt="Advanced configuration settings" + caption="Advanced configuration settings" + max-width="70%" + %} + + + +### ArgoCD Project +The project group to which the application belongs. A project is useful to enforce restrictions on permitted sources and targets for applications and roles. If not defined, the application is automatically assigned to the `default` project, which is created automatically by Argo CD and has no restrictions. +For more information, see Argo CD's documentation on [Projects](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#projects){:target="\_blank"}. + + + +### Propagation policy for application deletion +Defines how resources are pruned, applying Kubernetes cascading deletion prune policies when you delete the application. +For more information, see [Argo CD's app deletion](https://argo-cd.readthedocs.io/en/stable/user-guide/app_deletion/){:target="_blank"}. +* **Foreground** + The default prune propagation policy used by Argo CD. With this policy, Kubernetes changes the state of the owner resource to `deletion in progress`, until the controller deletes the dependent resources and finally the owner resource itself. +* **Background** + When selected, Kubernetes deletes the owner resource immediately, and then deletes the dependent resources in the background. +* **Non-cascading** + When selected, Kubernetes deletes only the application and not its resources. + + + +### Type of Application +The tool used to create the application's manifests. Codefresh supports defining application manifests as a directory, Helm charts, or Kustomize. If you are using other tools to define application manifests, use the Plugin type. For more information, see the Argo CD's documentation on [Tools](https://argo-cd.readthedocs.io/en/stable/user-guide/application_sources/){:target="_blank"}. + + +* **Directory**: A `directory` application, which is the default application type in Argo CD. + * **Directory recurse**: Optional. Select to include subdirectories. + * **Top-level arguments**: Optional. Select and define parameters. + * **External variables**: Optional. Select and define external variables. + +* **Helm**: Create the application as a Helm chart. + * **Values files**: One or more `values.yaml` files to store the parameters. + * **Values**: Optional. When defined, new values not in `values.yaml` files are added, and existing values are overridden. + +* **Kustomize**: Create a Kustomize application, with the following settings: + * **Version**: The version of Kustomize used to create the application. + * **Name Prefix** and **Name Suffix**: Optional. The prefix and suffix to be appended to the resources of the application. + +* **Plugin**: Use for any other tool. + * **Name**: The name of the Plugin used to create the application. + * **External Variables**: The variables to use in the application. + +For example applications, go to the [Argo CD example applications repo](https://github.com/argoproj/argocd-example-apps){:target="_blank"}. + + +## Related articles +[Monitoring Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/monitor-applications/) +[Managing Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/manage-application/) +[Promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) +[Environments dashboard]({{site.baseurl}}/docs/dashboards/gitops-environments/) +[Product Dashboard]({{site.baseurl}}/docs/dashboards/gitops-products/) +[Home dashboard]({{site.baseurl}}/docs/dashboards/home-dashboard/) +[DORA metrics]({{site.baseurl}}/docs/dashboards/dora-metrics/) \ No newline at end of file diff --git a/_docs/deployments/gitops/create-application.md b/_docs/deployments/gitops/create-application.md index 1d804012d..1c79e9d83 100644 --- a/_docs/deployments/gitops/create-application.md +++ b/_docs/deployments/gitops/create-application.md @@ -1,173 +1,29 @@ --- title: "Creating Argo CD applications" -description: "" +description: "Step-by-step instructions to create an Argo CD application in GitOps" group: deployments -sub_group: gitops toc: true --- +## GitOps & Argo CD applications +Create Argo CD applications that are fully GitOps-compliant from the GitOps Apps dashboard. +When you commit the changes, the application manifest is generated and stored in Git, ensuring a declarative and auditable deployment process. +For example Argo CD applications, see this [repo](https://github.com/oleksandr-codefresh/argocd-example-apps){:target="_blank"}. -## Argo CD applications in Codefresh -Create and manage fully GitOps-compliant Argo CD applications from the GitOps Apps dashboard. -For example Argo CD applications, see this [repo](https://github.com/oleksandr-codefresh/argocd-example-apps){:target="_blank"}. - -Configuration settings for applications define the application’s structure, sources, destination, and operational behavior. -For ease of use, settings are organized into distinct categories including: -* [Application definitions](#application-definitions): Basic metadata, such as the application name, GitOps Runtime, and the YAML manifest name. -* [General configuration settings](#application-general-configuration-settings): Product, Group, source, destination, and sync policies for the application. -* [Advanced configuration settings](#application-advanced-configuration-settings): Tool-specific options, project grouping, and propagation policies for resource and application deletion. - -For how-to instructions, see [Create applications](#create-an-argo-cd-application). - -## Application: Definitions -Application definitions include the application name, the GitOps Runtime, and the name of the YAML manifest. By default, the YAML manifest has the same name as that of the application. - -{% include - image.html - lightbox="true" - file="/images/applications/add-app-definitions.png" - url="/images/applications/add-app-definitions.png" - alt="Application definitions" - caption="Application definitions" - max-width="50%" - %} - - -## Application: General configuration settings - -General configuration settings define the product, group, to which the application belongs, source, destination, and sync policies for the application. - -{% include - image.html - lightbox="true" - file="/images/applications/add-app-general-settings.png" - url="/images/applications/add-app-general-settings.png" - alt="General configuration settings" - caption="General configuration settings" - max-width="70%" - %} - -### Products -Optional. The product to which to assign the application. Select an existing product, or create and add a new product. -Products empower promotions for applications and make for streamlined management and deployments. -See [Products]({{site.baseurl}}/docs/products/about-products/). - - -### Groups -Optional. The group or groups to which to add the application. Select an existing group or groups, or create a new application group by typing a name and pressing Enter. -Group applications based on criteria meaningful to your organization, such as environment, region, or any other relevant attribute. You can then view deployments for these applications in the same location in the Groups tab of the GitOps Apps dashboard. A new view for Argo CD applications, Groups allow you to collate multiple applications and view their timelines. -See [Application Groups]({{site.baseurl}}/docs/deployments/gitops/gitops-app-groups/). - - - - -### Source -The Git repository with the application resources. -{::nomarkdown}{:/} - - - -### Destination -The cluster and namespace to which to deploy the application. -{::nomarkdown}{:/} - - -### Sync Settings - - -#### Sync Policy -The synchronization policy to apply when there are differences between the desired state in Git and the actual state in the cluster.{::nomarkdown}{:/} - - - -#### Sync Options -Common to both manual and automatic sync policies.{% raw %}{::nomarkdown}{:/}{% endraw %} - - -#### Prune propagation policy -Defines how resources are pruned, applying Kubernetes cascading deletion prune policies. For more information, see [Kubernetes - Cascading deletion](https://kubernetes.io/docs/concepts/architecture/garbage-collection/#cascading-deletion)){:target="\_blank"}.{::nomarkdown}
{:/} -All Prune propagation policies can be used with: - -**Replace**: When selected, Argo CD executes `kubectl replace` or `kubectl create`, instead of the default `kubectl apply` to enforce the changes in Git. This action will potentially recreate resources and should be used with care. See [Replace Resource Instead Of Applying Change](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/#replace-resource-instead-of-applying-changes){:target="\_blank"}. - -**Retry**: When selected, retries a failed sync operation, based on the retry settings configured: -* Maximum number of sync retries (**Limit**) -* Duration of each retry attempt in seconds, minutes, or hours (**Duration**) -* Maximum duration permitted for each retry (**Max Duration**) -* Factor by which to multiply the Duration in the event of a failed retry (**Factor**). A factor of 2 for example, attempts the second retry in 2 X 2 seconds, where 2 seconds is the Duration. - - - -## Application: Advanced configuration settings - -Advanced settings define the tool used to create the application, and related toll-specific settings. - -{% include - image.html - lightbox="true" - file="/images/applications/add-app-advanced-settings.png" - url="/images/applications/add-app-advanced-settings.png" - alt="Advanced configuration settings" - caption="Advanced configuration settings" - max-width="70%" - %} - - - -### ArgoCD Project -The project group to which the application belongs. A project is useful to enforce restrictions on permitted sources and targets for applications and roles. If not defined, the application is automatically assigned to the `default` project, which is created automatically by Argo CD and has no restrictions. -For more information, see Argo CD's documentation on [Projects](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#projects){:target="\_blank"}. - - - -### Propagation policy for application deletion -Defines how resources are pruned, applying Kubernetes cascading deletion prune policies when you delete the application. -For more information, see [Argo CD's app deletion](https://argo-cd.readthedocs.io/en/stable/user-guide/app_deletion/){:target="_blank"}. -* **Foreground** - The default prune propagation policy used by Argo CD. With this policy, Kubernetes changes the state of the owner resource to `deletion in progress`, until the controller deletes the dependent resources and finally the owner resource itself. -* **Background** - When selected, Kubernetes deletes the owner resource immediately, and then deletes the dependent resources in the background. -* **Non-cascading** - When selected, Kubernetes deletes only the application and not its resources. - - - -### Type of Application -The tool used to create the application's manifests. Codefresh supports defining application manifests as a directory, Helm charts, or Kustomize. If you are using other tools to define application manifests, use the Plugin type. For more information, see the Argo CD's documentation on [Tools](https://argo-cd.readthedocs.io/en/stable/user-guide/application_sources/){:target="_blank"}. - - -* **Directory**: A `directory` application, which is the default application type in Argo CD. - * **Directory recurse**: Optional. Select to include subdirectories. - * **Top-level arguments**: Optional. Select and define parameters. - * **External variables**: Optional. Select and define external variables. - -* **Helm**: Create the application as a Helm chart. - * **Values files**: One or more `values.yaml` files to store the parameters. - * **Values**: Optional. When defined, new values not in `values.yaml` files are added, and existing values are overridden. - -* **Kustomize**: Create a Kustomize application, with the following settings: - * **Version**: The version of Kustomize used to create the application. - * **Name Prefix** and **Name Suffix**: Optional. The prefix and suffix to be appended to the resources of the application. - -* **Plugin**: Use for any other tool. - * **Name**: The name of the Plugin used to create the application. - * **External Variables**: The variables to use in the application. - -For example applications, go to the [Argo CD example applications repo](https://github.com/argoproj/argocd-example-apps){:target="_blank"}. - +After creating applications, monitor and track version in the Environments and Products dashboards, and promote them across environments. ## Create an Argo CD application Create a new application from the GitOps Apps dashboard. -Edit the manifest directly in YAML mode, or define the settings in the Form mode. Toggle between the modes as convenient. +Define settings in Form mode or edit the manifest directly in YAML mode, toggling between them as needed. ##### Before you begin -* Make sure you have a valid [Git Source]({{site.baseurl}}/docs/installation/gitops/git-sources/) +* Make sure you have a valid [Git Source]({{site.baseurl}}/docs/gitops-runtime/git-sources/) * Review: - [General configuration settings](#application-general-configuration-settings) - [Advanced configuration settings](#application-advanced-configuration-settings) + [General configuration settings]({{site.baseurl}}/docs/deployments/gitops/application-configuration-settings/#application-general-configuration-settings) + [Advanced configuration settings]({{site.baseurl}}/docs/deployments/gitops/application-configuration-settings#application-advanced-configuration-settings) ##### How to @@ -241,7 +97,40 @@ Edit the manifest directly in YAML mode, or define the settings in the Form mode Your application is first committed to Git, and then synced to the cluster which may take a few moments. - +## YAML version of application manifest +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: demo-trioapp-dev + finalizers: + - resources-finalizer.argocd.argoproj.io/foreground + annotations: + codefresh.io/product: demo-trioapp +spec: + project: default + destination: + name: in-cluster + namespace: demo-dev + source: + path: demo-applications/trioapp-dev + repoURL: https://github.com/codefresh-sandbox/codefresh-quickstart-demo.git + targetRevision: main + syncPolicy: + automated: + prune: true + selfHeal: true + allowEmpty: false + syncOptions: + - PrunePropagationPolicy=foreground + - Replace=false + - PruneLast=false + - Validate=true + - CreateNamespace=true + - ApplyOutOfSyncOnly=false + - ServerSideApply=true + - RespectIgnoreDifferences=false +``` ## Related articles [Monitoring Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/monitor-applications/) diff --git a/assets/js/src/argohub-redirect-mapping.json b/assets/js/src/argohub-redirect-mapping.json index e691c2c2e..64f654873 100644 --- a/assets/js/src/argohub-redirect-mapping.json +++ b/assets/js/src/argohub-redirect-mapping.json @@ -113,5 +113,6 @@ "/docs/gitops-quick-start/policy-multi-env-promotion/": "/argohub/gitops-quick-starts/policy-multi-env-promotion/", "/docs/gitops-quick-start/quick-start-gitops-environments/": "/argohub/gitops-quick-starts/quick-start-gitops-environments/", "/docs/gitops-quick-start/runtime/": "/argohub/gitops-quick-starts/runtime/", - "/docs/gitops-quick-start/verify-requirements/": "/argohub/gitops-quick-starts/verify-requirements/" + "/docs/gitops-quick-start/verify-requirements/": "/argohub/gitops-quick-starts/verify-requirements/", + "/docs/deployments/gitops/application-configuration-settings/": "/argohub/applications/application-configuration-settings/" } From f9f7b48557f73868124dc0ff5fec45bc373c82e8 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 12 Feb 2025 09:03:57 +0200 Subject: [PATCH 2/3] Update --- .../deployments/gitops/application-configuration-settings.md | 2 +- _docs/deployments/gitops/create-application.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_docs/deployments/gitops/application-configuration-settings.md b/_docs/deployments/gitops/application-configuration-settings.md index 02c83017b..87997eb35 100644 --- a/_docs/deployments/gitops/application-configuration-settings.md +++ b/_docs/deployments/gitops/application-configuration-settings.md @@ -7,7 +7,7 @@ toc: true ## Application configuration settings Configuration settings for applications define the application’s structure, sources, destination, and operational behavior. For ease of use, settings are organized into distinct categories including: -* [Application definitions](#application-definitions): Basic metadata, such as the application name, GitOps Runtime, and the YAML manifest name. +* [Application definitions](#application-definitions): Basic metadata, such as the application name, GitOps Runtime, and the name of the YAML manifest. * [General configuration settings](#application-general-configuration-settings): Product, Group, source, destination, and sync policies for the application. * [Advanced configuration settings](#application-advanced-configuration-settings): Tool-specific options, project grouping, and propagation policies for resource and application deletion. diff --git a/_docs/deployments/gitops/create-application.md b/_docs/deployments/gitops/create-application.md index 1c79e9d83..1c4fba3dc 100644 --- a/_docs/deployments/gitops/create-application.md +++ b/_docs/deployments/gitops/create-application.md @@ -11,13 +11,12 @@ When you commit the changes, the application manifest is generated and stored in For example Argo CD applications, see this [repo](https://github.com/oleksandr-codefresh/argocd-example-apps){:target="_blank"}. -After creating applications, monitor and track version in the Environments and Products dashboards, and promote them across environments. ## Create an Argo CD application Create a new application from the GitOps Apps dashboard. -Define settings in Form mode or edit the manifest directly in YAML mode, toggling between them as needed. +Define settings in Form mode, or edit the manifest directly in YAML mode, toggling between them as needed. ##### Before you begin * Make sure you have a valid [Git Source]({{site.baseurl}}/docs/gitops-runtime/git-sources/) @@ -137,5 +136,6 @@ spec: [Managing Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/manage-application/) [Environments dashboard]({{site.baseurl}}/docs/dashboards/gitops-environments/) [Product Dashboard]({{site.baseurl}}/docs/dashboards/gitops-products/) +[Trigger promotions for applications]({{site.baseurl}}/docs/promotions/trigger-promotions/) [Home dashboard]({{site.baseurl}}/docs/dashboards/home-dashboard/) [DORA metrics]({{site.baseurl}}/docs/dashboards/dora-metrics/) \ No newline at end of file From 314ebce6a1ea179a95b8db49e270bee761aa3e58 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 12 Feb 2025 09:22:13 +0200 Subject: [PATCH 3/3] Update apps-whats-changed-in-documentation.md --- _docs/deployments/gitops/apps-whats-changed-in-documentation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_docs/deployments/gitops/apps-whats-changed-in-documentation.md b/_docs/deployments/gitops/apps-whats-changed-in-documentation.md index 09589535c..1b6c8fafb 100644 --- a/_docs/deployments/gitops/apps-whats-changed-in-documentation.md +++ b/_docs/deployments/gitops/apps-whats-changed-in-documentation.md @@ -17,4 +17,6 @@ The table below outlines the updates to Applications documentation, including ar |--------------------------|----- |----------------------------------------------------| | Deployments > GitOps |[About applications in GitOps]({{site.baseurl}}/docs/deployments/gitops/about-apps/) | New overview topic summarizing capabilities for Argo CD applications in Codefresh GitOps. | | |[GitOps Apps dashboard]({{site.baseurl}}/docs/deployments/gitops/gitops-apps-dashboard/) | Split from **Monitoring applications** article to standalone article entitled **GitOps Apps dashboard** for visibility. | +| |[Create Argo CD applications]({{site.baseurl}}/docs/deployments/gitops/create-application/) | Focuses on how-to instructions on creating applications. | +| |[Application configuration settings]({{site.baseurl}}/docs/deployments/gitops/application-configuration-settings/) | Split from **Creating applications** article to a standalone reference article describing the settings you can configure for applications. | | |[Monitoring applications]({{site.baseurl}}/docs/deployments/gitops/monitor-applications/) | Focuses on options to monitor individual applications. |