> ## 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.

# Applications

> Deploy and manage GitOps applications with ArgoCD

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

<CardGroup cols={2}>
  <Card title="Application" icon="rocket">
    A deployment unit connecting Git source to Kubernetes destination with sync policies.
  </Card>

  <Card title="Sync Status" icon="arrows-rotate">
    Whether the live state matches the desired state in Git (Synced, OutOfSync, Unknown).
  </Card>

  <Card title="Health Status" icon="heart-pulse">
    The operational health of deployed resources (Healthy, Progressing, Degraded, etc.).
  </Card>

  <Card title="Resource Tree" icon="sitemap">
    Visual representation of all Kubernetes resources managed by the application.
  </Card>
</CardGroup>

## Required Permissions

| Action                     | Permission                        |
| -------------------------- | --------------------------------- |
| View applications          | `iam:project:cicd:argocd:read`    |
| Create applications        | `iam:project:cicd:argocd:write`   |
| Edit applications          | `iam:project:cicd:argocd:write`   |
| Sync/Rollback applications | `iam:project:cicd:argocd:execute` |
| View logs                  | `iam:project:cicd:argocd:logs`    |
| Delete applications        | `iam:project:cicd:argocd:delete`  |

## Application Statuses

### Sync Status

| Status        | Description                             |
| ------------- | --------------------------------------- |
| **Synced**    | Live state matches desired state in Git |
| **OutOfSync** | Live state differs from desired state   |
| **Unknown**   | Sync status cannot be determined        |

### Health Status

| Status          | Description                               |
| --------------- | ----------------------------------------- |
| **Healthy**     | All resources are healthy and running     |
| **Progressing** | Resources are being created or updated    |
| **Degraded**    | One or more resources have issues         |
| **Suspended**   | Application is suspended (scaled to zero) |
| **Missing**     | Required resources are not found          |
| **Unknown**     | Health cannot be determined               |

### Operation Phase

| Phase           | Description                   |
| --------------- | ----------------------------- |
| **Running**     | Sync operation is in progress |
| **Succeeded**   | Sync completed successfully   |
| **Failed**      | Sync operation failed         |
| **Error**       | Error occurred during sync    |
| **Terminating** | Sync is being cancelled       |

## How to Create an Application

<Steps>
  <Step title="Select ArgoCD Instance">
    Choose the ArgoCD instance from the dropdown in the toolbar.
  </Step>

  <Step title="Click Add Application">
    Click the **Add Application** button in the header.
  </Step>

  <Step title="Enter Application Name">
    Provide a unique name (lowercase alphanumeric with dashes only).
  </Step>

  <Step title="Select Project">
    Choose the ArgoCD project for this application.
  </Step>

  <Step title="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
  </Step>

  <Step title="Configure Destination">
    * Select target cluster
    * Enter target namespace
  </Step>

  <Step title="Configure Sync Options">
    * **Create Namespace**: Auto-create namespace if it doesn't exist
    * **Server-Side Apply**: Use server-side apply for resources
  </Step>

  <Step title="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
  </Step>

  <Step title="Create">
    Click **Create Application** to deploy.
  </Step>
</Steps>

## Application Name Rules

| Rule           | Requirement                                         |
| -------------- | --------------------------------------------------- |
| **Characters** | Lowercase letters (a-z), numbers (0-9), hyphens (-) |
| **Start/End**  | Must start and end with alphanumeric character      |
| **Uppercase**  | Not allowed                                         |
| **Spaces**     | Not allowed                                         |

**Valid examples**: `my-app`, `frontend-v2`, `api-service`

**Invalid examples**: `My-App`, `my_app`, `-app`, `app-`

## Required Fields

| Field                     | Required | Description                           |
| ------------------------- | -------- | ------------------------------------- |
| **Application Name**      | Yes      | Unique identifier for the application |
| **Project**               | Yes      | ArgoCD project for access control     |
| **Repository URL**        | Yes      | Source Git repository                 |
| **Path**                  | Yes      | Path to manifests within repository   |
| **Destination Cluster**   | Yes      | Target Kubernetes cluster             |
| **Destination Namespace** | Yes      | Target namespace for deployment       |

## Sync Options

| Option                | Default | Description                                             |
| --------------------- | ------- | ------------------------------------------------------- |
| **Create Namespace**  | Off     | Automatically create namespace if missing               |
| **Server-Side Apply** | Off     | Use server-side apply (recommended for large resources) |
| **Automated Sync**    | Off     | Auto-sync on Git changes                                |
| **Prune Resources**   | Off     | Delete resources not in Git (requires Automated Sync)   |
| **Self Heal**         | Off     | Auto-revert manual changes (requires Automated Sync)    |
| **Retry Policy**      | Off     | Retry failed syncs with backoff                         |

## How to Sync an Application

<Steps>
  <Step title="Find the Application">
    Locate the application in the list or open its detail page.
  </Step>

  <Step title="Click Sync">
    Click the **Sync** button on the application card or detail page header.
  </Step>

  <Step title="Monitor Progress">
    Watch the sync status change to "Running" and then "Synced" on completion.
  </Step>
</Steps>

<Info>
  Sync compares the desired state in Git with the live state in Kubernetes and applies necessary changes.
</Info>

## How to View Application Logs

<Steps>
  <Step title="Open Application Detail">
    Click on an application to open its detail page with the resource tree.
  </Step>

  <Step title="Select a Pod">
    Click on a Pod resource in the resource tree.
  </Step>

  <Step title="Click View Logs">
    Click the **Logs** action in the resource context menu.
  </Step>

  <Step title="View Logs">
    Logs appear in the bottom panel. Select container if the pod has multiple containers.
  </Step>
</Steps>

<Tip>
  Logs stream in real-time. Use the search and filter options to find specific log entries.
</Tip>

## How to Execute Commands in a Pod

<Steps>
  <Step title="Open Application Detail">
    Navigate to the application detail page.
  </Step>

  <Step title="Select a Pod">
    Click on a Pod resource in the resource tree.
  </Step>

  <Step title="Click Exec">
    Click the **Exec** action in the resource context menu.
  </Step>

  <Step title="Use Terminal">
    A terminal opens in the bottom panel connected to the pod's container.
  </Step>
</Steps>

<Warning>
  Terminal exec requires appropriate RBAC permissions on the target cluster. Use with caution in production environments.
</Warning>

## How to Scale a Workload

<Steps>
  <Step title="Open Application Detail">
    Navigate to the application detail page.
  </Step>

  <Step title="Select Workload">
    Click on a Deployment, StatefulSet, or ReplicaSet in the resource tree.
  </Step>

  <Step title="Click Scale">
    Click the **Scale** action in the resource context menu.
  </Step>

  <Step title="Set Desired Replicas">
    Use the controls to set the desired replica count (0-100).
  </Step>

  <Step title="Apply">
    Click **Scale** to apply the change.
  </Step>
</Steps>

<Warning>
  Scaling to 0 replicas stops all pods for the workload. The application will become unavailable.
</Warning>

## How to Restart a Workload

<Steps>
  <Step title="Open Application Detail">
    Navigate to the application detail page.
  </Step>

  <Step title="Select Workload">
    Click on a Deployment, StatefulSet, or DaemonSet in the resource tree.
  </Step>

  <Step title="Click Restart">
    Click the **Restart** action in the resource context menu.
  </Step>

  <Step title="Confirm">
    Confirm the restart. Pods will be restarted in a rolling manner.
  </Step>
</Steps>

<Info>
  Restart performs a rolling restart, keeping the application available during the process.
</Info>

## How to Rollback an Application

<Steps>
  <Step title="Open Application">
    Find and open the application you want to rollback.
  </Step>

  <Step title="Click Rollback">
    Click the **Rollback** button or select from the actions menu.
  </Step>

  <Step title="Select Deployment">
    Choose a previous deployment from the history list.
  </Step>

  <Step title="Review Details">
    Review the revision details including commit SHA and deployment date.
  </Step>

  <Step title="Confirm Rollback">
    Click **Rollback** to redeploy the selected revision.
  </Step>
</Steps>

<Warning>
  Rolling back redeploys the application to a previous revision. Any changes made after that deployment will be lost.
</Warning>

## 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

<Tip>
  Refresh is useful when you've made changes outside ArgoCD and want to see the current state.
</Tip>

## How to Delete an Application

<Steps>
  <Step title="Find the Application">
    Locate the application to delete.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon or select **Delete** from the actions menu.
  </Step>

  <Step title="Choose Deletion Mode">
    * **Foreground**: Delete resources before removing application
    * **Background**: Remove application, delete resources in background
    * **Non-cascading**: Remove application only, leave resources running
  </Step>

  <Step title="Confirm">
    Type the application name to confirm deletion.
  </Step>
</Steps>

<Warning>
  Foreground and background deletion will remove all Kubernetes resources managed by this application. Use non-cascading to preserve resources.
</Warning>

## Resource Tree Actions

The resource tree provides actions based on resource type:

| Resource Type   | Available Actions                                      |
| --------------- | ------------------------------------------------------ |
| **Pod**         | View Logs, Exec (Terminal), View Events, View Manifest |
| **Deployment**  | Scale, Restart, View Events, View Manifest             |
| **StatefulSet** | Scale, Restart, View Events, View Manifest             |
| **ReplicaSet**  | Scale, View Events, View Manifest                      |
| **DaemonSet**   | Restart, View Events, View Manifest                    |
| **Service**     | View Events, View Manifest                             |
| **ConfigMap**   | View Events, View Manifest                             |
| **Secret**      | View 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

<AccordionGroup>
  <Accordion title="Application shows OutOfSync" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Application health is Degraded" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Sync operation failed" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot view logs" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot exec into pod" icon="circle-question">
    * Verify you have execute permission
    * Ensure pod is running
    * Check that container allows exec
    * Verify network connectivity to cluster
  </Accordion>

  <Accordion title="Scale operation not available" icon="circle-question">
    * Scale is only available for Deployments, StatefulSets, and ReplicaSets
    * Verify you have write permission
    * Check that the resource exists and is healthy
  </Accordion>

  <Accordion title="Rollback shows no history" icon="circle-question">
    * Application must have been synced at least once
    * History is limited to recent deployments
    * First deployment has no previous state to rollback to
  </Accordion>

  <Accordion title="Application not updating in real-time" icon="circle-question">
    * WebSocket connection may be interrupted
    * Try refreshing the page
    * Check browser console for connection errors
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between Sync and Refresh?">
    **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.
  </Accordion>

  <Accordion title="Can I sync specific resources instead of the whole application?">
    Currently, sync operates on the entire application. For partial syncs, use the ArgoCD CLI with resource selectors.
  </Accordion>

  <Accordion title="What does Self Heal do?">
    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.
  </Accordion>

  <Accordion title="What's the difference between Prune and Self Heal?">
    **Prune** deletes resources that no longer exist in Git. **Self Heal** reverts changes to resources that still exist but were modified manually.
  </Accordion>

  <Accordion title="How do I deploy to multiple namespaces?">
    Create separate applications for each namespace. Each application can only target one namespace.
  </Accordion>

  <Accordion title="Can I use Helm charts with ArgoCD?">
    Yes. Point the application source path to a directory containing a Helm chart. ArgoCD will render the chart and apply the manifests.
  </Accordion>

  <Accordion title="What happens if I delete a running pod?">
    If the pod belongs to a Deployment or ReplicaSet, Kubernetes will automatically create a replacement pod. The application health may temporarily show Progressing.
  </Accordion>

  <Accordion title="How do I see what changed between syncs?">
    Click on the application to view the manifest drift panel. This shows differences between the desired state (Git) and live state (cluster).
  </Accordion>

  <Accordion title="Can multiple users edit the same application?">
    Yes, but be careful of conflicts. Changes are applied in order received. Use Git as the source of truth to avoid conflicts.
  </Accordion>

  <Accordion title="What's the retry policy for?">
    Retry policy automatically retries failed sync operations with exponential backoff. Useful for transient failures like network issues or temporary resource conflicts.
  </Accordion>
</AccordionGroup>

## 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