Deploy applications

This guide covers declaring Argo CD Applications in your Platform configuration after a connector is enabled. Platform reconciles these declarations into ArgoCDApplication objects and syncs them to your Argo CD instance.

Prerequisites

• A connector is already configured and enabled on the target cluster. See Connect to Argo CD or Connect to Akuity.

Application templates

An ArgoCDApplicationTemplate is a reusable Argo CD ApplicationSpec. Create one when you want to deploy the same application definition across multiple tenant clusters without duplicating configuration.

Platform UI

1. Click Argo CD Templates in the left sidebar.

2. Click .

3. In the Basics section, enter a Display Name for the template. The ArgoCD Application Template ID is auto-generated from the display name and is the identifier you reference in your applications. Optionally add a Description.

4. In the ArgoCD Application Spec section, fill in the YAML editor with the Argo CD ApplicationSpec.

5. Click .

YAML

apiVersion: storage.loft.sh/v1
kind: ArgoCDApplicationTemplate
metadata:
  name: app-template
spec:
  template:
    spec:
      source:
        repoURL: "https://github.com/acme/app-charts"
        targetRevision: "main"
        path: "app"
      project: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Application naming

Every application has two name fields: name and displayName.

name is the Kubernetes resource name for the ArgoCDApplication object. It must be unique within the project namespace. Platform checks explicitly defined names against existing ArgoCDApplication resources in the same project namespace. A name already owned by another tenant cluster is rejected.

displayName is the label shown in the Platform UI. displayName defined in vcluster.yaml must be unique across all the applications defined in the vcluster.yaml.

Naming modes

• Set name explicitly: Platform uses it as the Kubernetes resource name. If displayName is not set, it defaults to the value of name.
• Set displayName only: Omit name and specify only displayName. Platform automatically generates a unique Kubernetes resource name.
• Set neither field: When defined in vcluster.yaml, Platform rejects the configuration with a validation error. When creating an application through the UI or Management API, Platform automatically generates a resource name if one is not provided.

Argo CD name uniqueness

Argo CD requires application names to be unique across all projects. Platform satisfies this by appending the project name when registering the application in Argo CD.

Deploy to a tenant cluster

Applications deployed to a tenant cluster are declared in the cluster's vcluster.yaml under deploy.argoCD.applications. Each entry can target:

• vcluster (default): the tenant cluster itself
• host: the control plane cluster the tenant cluster runs on (see Deploying to the control plane cluster)

Platform UI

New tenant cluster

1. Select your project from the projects dropdown at the top of the left navigation bar.

2. Navigate to Tenant Clusters and click .

3. Click Continue Without a Template, select the wanted type of tenant cluster then click .

   Optionally select a cluster template, then configure it. The template must have been created to allow ArgoCD Applications configuration.

4. Select the Argo CD Integration tab in the cluster creation form.

5. Click on the slider Enable Argo CD Integration

6. Select a Connector in the dropdown list of connectors or click Configure Argo CD Connectors to configure a connector.

7. Click .

8. In the Basics section, enter a Display Name for the application. The Argo CD Application ID is auto-generated and uniquely identifies the application in Argo CD.

9. Choose where to deploy:

   • Select Deploy to vCluster to deploy into the tenant cluster itself.
   • Select Deploy to control plane cluster to deploy into the control plane cluster the tenant cluster runs on. The control plane cluster must already have an Argo CD connector configured.

10. Select a Template or choose Inline application spec from the Argo CD Application Template dropdown.

11. If you choose a Template, fill the Template Parameters if needed.

    If you choose Inline application spec, fill the Argo CD Application Spec.

    You can make additional change directly in the YAML editor.

12. Click to add the ArgoCD Application to the tenant cluster.

13. Complete the remaining cluster configuration and click .

Existing tenant cluster

1. Select your project from the projects dropdown at the top of the left navigation bar.

2. Navigate to Tenant Clusters and open the tenant cluster where you want to deploy an application.

3. Select the ArgoCD Apps tab in the cluster detail view.

4. Click .

5. In the Basics section, enter a Display Name for the application. The Argo CD Application ID is auto-generated and uniquely identifies the application in Argo CD.

6. Choose where to deploy:

   • Select Deploy to vCluster to deploy into the tenant cluster itself.
   • Select Deploy to control plane cluster to deploy into the control plane cluster the tenant cluster runs on. The control plane cluster must already have an Argo CD connector configured.

7. Select a Template or choose Inline application spec from the Argo CD Application Template dropdown.

8. If you choose a Template, fill the Template Parameters if needed.

   If you choose Inline application spec, fill the Argo CD Application Spec.

   You can make additional change directly in the YAML editor.

9. Click to add the ArgoCD Application to the tenant cluster.

10. Click .

YAML

Add the deploy.argoCD.applications block to the tenant cluster's vcluster.yaml. Set target: vcluster to deploy into the tenant cluster (this is the default) or target: host to deploy into the control plane cluster it runs on.

Template reference

deploy:
  argoCD:
    applications:
      - name: myapp            # omit this to generate the name or ensure that the defined name is unique accross the project
        displayName: "My Application"
        target: vcluster       # or "host" to target the control plane cluster
        template:
          name: app-template   # references an ArgoCDApplicationTemplate

Inline spec

deploy:
  argoCD:
    applications:
      - name: grafana             # omit this to generate the name or ensure that the defined name is unique accross the project
        displayName: "Grafana"
        target: vcluster          # or "host" to target the control plane cluster
        inline:
          source:
            repoURL: "https://github.com/acme/charts"
            targetRevision: HEAD
            path: grafana
          project: default
          syncPolicy:
            automated:
              prune: true
              selfHeal: true
          destination:
            namespace: `default destination`

Deploying to the control plane cluster

Setting target: host deploys the application onto the control plane cluster rather than inside the tenant cluster. Use this for shared infrastructure — monitoring agents, logging collectors, or networking components — that belongs on the underlying cluster rather than inside a tenant cluster.

Understand the access boundary before using target: host

target: host allows configuration inside a tenant cluster to affect workloads on the control plane cluster. Before enabling this, consider:

• Who controls the tenant cluster configuration? If tenants can edit vcluster.yaml directly, they can deploy arbitrary workloads onto the control plane cluster. Restrict this to platform admins or use cluster templates to limit what values tenants can set.
• The control plane cluster must have a connector. If the control plane cluster does not have an Argo CD connector configured, applications with target: host will fail to deploy.
• Applications are deployed into a specific namespace. The destination.namespace in the argoCDApplication field determines where the application lands on the control plane cluster. Ensure that deploying in that namespace wouldn't cause any disruption on the host cluster.

This is a platform-admin-level capability. Do not expose it to end users without proper guardrails.

Prerequisite for target: host

The control plane cluster the tenant cluster runs on must already be registered with an Argo CD connector. Complete the connector setup for the control plane cluster first (see Connect to Argo CD or Connect to Akuity).

Deploy to a control plane cluster

Applications deployed directly onto a control plane cluster are created as ArgoCDApplication objects in the project namespace. This is the recommended pattern for shared infrastructure that should live on the underlying cluster rather than inside a tenant cluster.

Platform UI

1. Click Clusters in the left sidebar under the infrastructure section.

2. Click the name of the control plane cluster to open its detail page.

3. Select the ArgoCD Apps tab in the cluster header.

4. Click .

5. In the Basics section, enter a Display Name for the application. The Argo CD Application ID is auto-generated from the display name.

6. Select a Template or choose Inline application spec from the Argo CD Application Template dropdown.

7. If you choose a Template, fill the Template Parameters if needed.

   If you choose Inline application spec, fill the Argo CD Application Spec.

   You can make additional change directly in the YAML editor.

8. Click .

YAML

Create an ArgoCDApplication object in the project namespace. Use spec.destination.cluster to target the control plane cluster by name.

Template reference

apiVersion: storage.loft.sh/v1
kind: ArgoCDApplication
metadata:
  name: shared-infra
  namespace: p-my-project       # replace with your project namespace
spec:
  displayName: "Shared Infrastructure"
  destination:
    cluster:
      name: loft-cluster        # replace with your control plane cluster name
  templateRef:
    name: infra-template        # references an ArgoCDApplicationTemplate

Inline spec

apiVersion: storage.loft.sh/v1
kind: ArgoCDApplication
metadata:
  name: cluster-monitoring
  namespace: p-my-project       # replace with your project namespace
spec:
  displayName: "Cluster Monitoring"
  destination:
    cluster:
      name: loft-cluster        # replace with your control plane cluster name
  template:
    spec:
      source:
        repoURL: "https://github.com/acme/charts"
        targetRevision: HEAD
        path: monitoring
      project: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Disabling the integration

Disabling integrations.argoCD.enabled on a tenant cluster, or removing spec.argoCD from a control plane cluster, removes the cluster from Argo CD and deletes all ArgoCDApplication objects managed by Platform. Any applications deployed by the integration will be removed from Argo CD.