Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt

Use this file to discover all available pages before exploring further.

ArgoCD Applications are the core deployment units in GitOps. Each application connects a Git repository source to a Kubernetes destination, enabling automated and declarative deployments.

​
Key Concepts

Application

A deployment unit connecting Git source to Kubernetes destination with sync policies.

Sync Status

Whether the live state matches the desired state in Git (Synced, OutOfSync, Unknown).

Health Status

The operational health of deployed resources (Healthy, Progressing, Degraded, etc.).

Resource Tree

Visual representation of all Kubernetes resources managed by the application.

​
Required Permissions

ActionPermission
View applicationsiam:project:cicd:argocd:read
Create applicationsiam:project:cicd:argocd:write
Edit applicationsiam:project:cicd:argocd:write
Sync/Rollback applicationsiam:project:cicd:argocd:execute
View logsiam:project:cicd:argocd:logs
Delete applicationsiam:project:cicd:argocd:delete

​
Application Statuses

​
Sync Status

StatusDescription
SyncedLive state matches desired state in Git
OutOfSyncLive state differs from desired state
UnknownSync status cannot be determined

​
Health Status

StatusDescription
HealthyAll resources are healthy and running
ProgressingResources are being created or updated
DegradedOne or more resources have issues
SuspendedApplication is suspended (scaled to zero)
MissingRequired resources are not found
UnknownHealth cannot be determined

​
Operation Phase

PhaseDescription
RunningSync operation is in progress
SucceededSync completed successfully
FailedSync operation failed
ErrorError occurred during sync
TerminatingSync is being cancelled

​
How to Create an Application

1

Select ArgoCD Instance

Choose the ArgoCD instance from the dropdown in the toolbar.
2

Click Add Application

Click the Add Application button in the header.
3

Enter Application Name

Provide a unique name (lowercase alphanumeric with dashes only).
4

Select Project

Choose the ArgoCD project for this application.
5

Configure Source

  • Select a repository from connected repositories
  • Choose revision type (Branch or Tag)
  • Enter target revision (e.g., HEAD, main, v1.0.0)
  • Select the path containing Kubernetes manifests or Helm chart
6

Configure Destination

  • Select target cluster
  • Enter target namespace
7

Configure Sync Options

  • Create Namespace: Auto-create namespace if it doesn’t exist
  • Server-Side Apply: Use server-side apply for resources
8

Configure Sync Policy

  • Automated Sync: Auto-sync when Git changes
  • Prune Resources: Delete resources removed from Git
  • Self Heal: Auto-sync when live state drifts
  • Retry Policy: Configure retry on sync failures
9

Create

Click Create Application to deploy.

​
Application Name Rules

RuleRequirement
CharactersLowercase letters (a-z), numbers (0-9), hyphens (-)
Start/EndMust start and end with alphanumeric character
UppercaseNot allowed
SpacesNot allowed
Valid examples: my-app, frontend-v2, api-service Invalid examples: My-App, my_app, -app, app-

​
Required Fields

FieldRequiredDescription
Application NameYesUnique identifier for the application
ProjectYesArgoCD project for access control
Repository URLYesSource Git repository
PathYesPath to manifests within repository
Destination ClusterYesTarget Kubernetes cluster
Destination NamespaceYesTarget namespace for deployment

​
Sync Options

OptionDefaultDescription
Create NamespaceOffAutomatically create namespace if missing
Server-Side ApplyOffUse server-side apply (recommended for large resources)
Automated SyncOffAuto-sync on Git changes
Prune ResourcesOffDelete resources not in Git (requires Automated Sync)
Self HealOffAuto-revert manual changes (requires Automated Sync)
Retry PolicyOffRetry failed syncs with backoff

​
How to Sync an Application

1

Find the Application

Locate the application in the list or open its detail page.
2

Click Sync

Click the Sync button on the application card or detail page header.
3

Monitor Progress

Watch the sync status change to “Running” and then “Synced” on completion.
Sync compares the desired state in Git with the live state in Kubernetes and applies necessary changes.

​
How to View Application Logs

1

Open Application Detail

Click on an application to open its detail page with the resource tree.
2

Select a Pod

Click on a Pod resource in the resource tree.
3

Click View Logs

Click the Logs action in the resource context menu.
4

View Logs

Logs appear in the bottom panel. Select container if the pod has multiple containers.
Logs stream in real-time. Use the search and filter options to find specific log entries.

​
How to Execute Commands in a Pod

1

Open Application Detail

Navigate to the application detail page.
2

Select a Pod

Click on a Pod resource in the resource tree.
3

Click Exec

Click the Exec action in the resource context menu.
4

Use Terminal

A terminal opens in the bottom panel connected to the pod’s container.
Terminal exec requires appropriate RBAC permissions on the target cluster. Use with caution in production environments.

​
How to Scale a Workload

1

Open Application Detail

Navigate to the application detail page.
2

Select Workload

Click on a Deployment, StatefulSet, or ReplicaSet in the resource tree.
3

Click Scale

Click the Scale action in the resource context menu.
4

Set Desired Replicas

Use the controls to set the desired replica count (0-100).
5

Apply

Click Scale to apply the change.
Scaling to 0 replicas stops all pods for the workload. The application will become unavailable.

​
How to Restart a Workload

1

Open Application Detail

Navigate to the application detail page.
2

Select Workload

Click on a Deployment, StatefulSet, or DaemonSet in the resource tree.
3

Click Restart

Click the Restart action in the resource context menu.
4

Confirm

Confirm the restart. Pods will be restarted in a rolling manner.
Restart performs a rolling restart, keeping the application available during the process.

​
How to Rollback an Application

1

Open Application

Find and open the application you want to rollback.
2

Click Rollback

Click the Rollback button or select from the actions menu.
3

Select Deployment

Choose a previous deployment from the history list.
4

Review Details

Review the revision details including commit SHA and deployment date.
5

Confirm Rollback

Click Rollback to redeploy the selected revision.
Rolling back redeploys the application to a previous revision. Any changes made after that deployment will be lost.

​
How to Refresh an Application

Click the Refresh button to:
  • Fetch the latest state from the cluster
  • Update health and sync status
  • Refresh the resource tree
Refresh is useful when you’ve made changes outside ArgoCD and want to see the current state.

​
How to Delete an Application

1

Find the Application

Locate the application to delete.
2

Click Delete

Click the delete (trash) icon or select Delete from the actions menu.
3

Choose Deletion Mode

  • Foreground: Delete resources before removing application
  • Background: Remove application, delete resources in background
  • Non-cascading: Remove application only, leave resources running
4

Confirm

Type the application name to confirm deletion.
Foreground and background deletion will remove all Kubernetes resources managed by this application. Use non-cascading to preserve resources.

​
Resource Tree Actions

The resource tree provides actions based on resource type:
Resource TypeAvailable Actions
PodView Logs, Exec (Terminal), View Events, View Manifest
DeploymentScale, Restart, View Events, View Manifest
StatefulSetScale, Restart, View Events, View Manifest
ReplicaSetScale, View Events, View Manifest
DaemonSetRestart, View Events, View Manifest
ServiceView Events, View Manifest
ConfigMapView Events, View Manifest
SecretView Events, View Manifest

​
Favorites

Mark frequently accessed applications as favorites for quick access:
  1. Click the star icon on any application card
  2. Use the Favorites filter to show only favorited applications
  3. Favorites are stored per user

​
Troubleshooting

  • Verify Git repository is accessible
  • Check if manifests have changed in Git
  • Review sync status details for specific differences
  • Click Sync to apply changes from Git
  • Check resource tree for unhealthy resources
  • View pod logs for error messages
  • Review events for failing resources
  • Verify resource requests/limits are appropriate
  • Check if dependent services are available
  • Review sync result details in the application
  • Check for invalid manifest syntax
  • Verify RBAC permissions on target cluster
  • Ensure destination namespace exists or enable “Create Namespace”
  • Check for conflicting resources
  • Verify you have logs permission
  • Ensure pod is running (not pending or terminated)
  • Check cluster connectivity
  • Select the correct container if pod has multiple containers
  • Verify you have execute permission
  • Ensure pod is running
  • Check that container allows exec
  • Verify network connectivity to cluster
  • Scale is only available for Deployments, StatefulSets, and ReplicaSets
  • Verify you have write permission
  • Check that the resource exists and is healthy
  • Application must have been synced at least once
  • History is limited to recent deployments
  • First deployment has no previous state to rollback to
  • WebSocket connection may be interrupted
  • Try refreshing the page
  • Check browser console for connection errors

​
FAQ

Refresh fetches the latest state from the cluster without making changes. Sync applies the desired state from Git to the cluster, making actual changes to resources.
Currently, sync operates on the entire application. For partial syncs, use the ArgoCD CLI with resource selectors.
Self Heal automatically reverts manual changes made to resources. If someone modifies a resource directly in Kubernetes, ArgoCD will detect the drift and sync it back to the Git state.
Prune deletes resources that no longer exist in Git. Self Heal reverts changes to resources that still exist but were modified manually.
Create separate applications for each namespace. Each application can only target one namespace.
Yes. Point the application source path to a directory containing a Helm chart. ArgoCD will render the chart and apply the manifests.
If the pod belongs to a Deployment or ReplicaSet, Kubernetes will automatically create a replacement pod. The application health may temporarily show Progressing.
Click on the application to view the manifest drift panel. This shows differences between the desired state (Git) and live state (cluster).
Yes, but be careful of conflicts. Changes are applied in order received. Use Git as the source of truth to avoid conflicts.
Retry policy automatically retries failed sync operations with exponential backoff. Useful for transient failures like network issues or temporary resource conflicts.

​
Best Practices

​
Application Design

  • One application per microservice or logical unit
  • Use descriptive names that include service and environment
  • Group related applications in the same ArgoCD project
  • Keep manifest paths organized within repositories

​
Sync Configuration

  • Enable Automated Sync for development environments
  • Use manual sync for production to maintain control
  • Enable Prune carefully - test in non-production first
  • Configure Self Heal for critical applications that should not drift

​
Source Management

  • Use specific branches or tags for production
  • Use HEAD or branch names for development
  • Keep paths short and meaningful
  • Document which applications use which repository paths

​
Resource Management

  • Set appropriate resource requests and limits
  • Use readiness and liveness probes
  • Configure pod disruption budgets for high availability
  • Monitor resource utilization regularly

​
Security

  • Use separate ArgoCD projects for different environments
  • Restrict which clusters and namespaces projects can access
  • Avoid storing secrets in Git - use external secret management
  • Audit application changes regularly

​
Monitoring

  • Set up alerts for application health changes
  • Monitor sync failures and investigate promptly
  • Track deployment frequency and success rates
  • Review application logs regularly

​
Rollback Strategy

  • Test rollback procedures before incidents
  • Keep deployment history available
  • Document which versions are known-good
  • Consider blue-green or canary deployments for critical services