Troubleshooting

Like any complex system, Argo CD sometimes encounters problems. Fortunately, it also provides several tools that help you troubleshoot and resolve these issues.

The first step in troubleshooting is to check the status of your applications with the Argo CD UI or the argocd CLI. In the Argo CD UI, you can see the sync and health status of your applications at a glance. Clicking on an application lets you see more detailed information, including the status of individual resources.

With the argocd CLI, you can see information about, for example, the my-app application, including its sync and health status:

argocd app get my-app

If checking the application status doesn't reveal the issue, the next step is to check the Argo CD logs, which can provide more detailed information about what Argo CD is doing and any errors it's encountering. You can view the logs of the Argo CD components with the kubectl logs command. For example, to view the logs of the Argo CD API server, you can use the command

kubectl logs -n argocd deployment/argocd-server

This command displays the logs of the argocd-server deployment in the argocd namespace.

The argocd CLI includes several commands that can be useful for troubleshooting. For example, the

argocd app diff my-app

command shows the differences between the live state of your application and the desired state defined in your Git repository.

Further Automation

Argo CD provides several features that allow you to automate tasks, making it easier to manage your applications and streamline your workflows. These features include, among others, generating applications with ApplicationSet and automating tasks from continuous integration (CI) pipelines.

ApplicationSet is a feature of Argo CD that allows you to generate multiple Argo CD applications from a template and can be useful if you need to create similar applications for different environments, clusters, or other variations. To use ApplicationSet, you need to create an ApplicationSet resource in your Git repository. The ApplicationSet resource defines a template for the applications and a generator that produces the parameters for the template (Listing 12).

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-app-set
spec:
  generators:
  - list:
      items:
      - cluster: production
        url: https://production-cluster.kubernetes.default.svc
      - cluster: staging
        url: https://staging-cluster.kubernetes.default.svc
  template:
    metadata:
      name: 'my-app-{{cluster}}'
    spec:
      source:
        repoURL: https://github.com/my-org/my-repo.git
        targetRevision: HEAD
        path: /path/to/application/manifests
      destination:
        server: '{{url}}'
        namespace: default

The ApplicationSet resource uses a list generator to create two applications, one for a production cluster and one for a staging cluster. The template defines the common configuration for the applications, and the generator provides the parameters that vary between the applications.

Argo CD can also be integrated with CI pipelines to automate tasks such as deploying new versions of your applications, allowing you to implement a continuous delivery workflow in which changes to your applications are automatically deployed to your Kubernetes cluster.

To automate tasks from a CI pipeline, use the argocd CLI in your CI scripts. For example, to sync an application as part of your CI pipeline, use

argocd login argocd-server --username my-username --password my-password
argocd app sync my-app

Running these commands in your CI scripts lets you deploy new versions of your applications automatically whenever changes are pushed to your Git repository.

Useful Tips

When deleting an application in Argo CD, it's important to remember that, to prevent accidental data loss, Argo CD does not delete the Kubernetes resources associated with the application by default. If you want to delete the Kubernetes resources when deleting an application, you use the --cascade option:

argocd app delete my-app --cascade

Argo CD provides status badges that you can embed in your documentation or website that show the sync and health status of an application, allowing you a quick glimpse of the status of your applications. To use a status badge, use the URL format:

https://<argocd.example.com>/api/badge?name=<my-app>

Replace <argocd.example.com> with the URL of your Argo CD server and <my-app> with the name of your application.

Moreover, Argo CD allows you to add external URLs to your applications that point to documentation, dashboards, or any other relevant resources. Adding external URLs make it easier to access related resources directly from the Argo CD UI. To add an external URL, use the --info option:

argocd app set my-app --info "documentation=https://my-docs.example.com"

In this case, the option adds an external URL labeled documentation that points to https://my-docs.example.com .