End-to-end GitOps with ArgoCD

This guide walks through the full lifecycle of managing platform resources with ArgoCD, covering platform installation, cluster connections, project creation, and virtual cluster deployment. Each section references the detailed documentation for that step and provides the ArgoCD-specific configuration needed.

info

While this guide uses ArgoCD as the example, the same principles apply to other GitOps tools like Flux. Each section links to detailed documentation that includes tabs for alternative tooling.

Prerequisites

Before you begin, ensure you have:

• A Kubernetes cluster with administrative access
• ArgoCD installed and configured on the cluster
• helm v3.10 or later
• kubectl configured with admin access to the target cluster

1. Install the platform

Deploy the platform as an ArgoCD Application. This uses the platform Helm chart with your desired configuration values.

Create an ArgoCD Application that points to the platform Helm chart:

Modify the following with your specific values to generate a copyable command:

PLATFORM_VERSION

ADMIN_PASSWORD

PLATFORM_HOST

platform-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: vcluster-platform
namespace: argocd
spec:
destination:
  namespace: vcluster-platform
  server: "https://kubernetes.default.svc"
source:
  repoURL: "https://charts.loft.sh"
  targetRevision: 4.6.0
  chart: vcluster-platform
  helm:
    parameters:
      - name: admin.create
        value: "true"
      - name: admin.username
        value: admin
      - name: admin.password
        value: "your-secure-password"
      - name: ingress.enabled
        value: "true"
      - name: ingress.host
        value: "vcluster-platform.example.com"
      - name: config.loftHost
        value: "https://vcluster-platform.example.com"
project: default
syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true

Apply this to your cluster or commit it to a Git repository that ArgoCD monitors.

kubectl apply -f platform-application.yaml

ArgoCD and Helm releases

ArgoCD does not deploy the Helm release secret. Platform configuration updates must be managed through your Git repository, not the platform UI.

For the full set of Helm configuration options and alternative installation methods, see the platform installation with ArgoCD guide.

2. Connect a host cluster

After the platform is running, connect host clusters where virtual clusters will be deployed. In a GitOps workflow, you can manage connected clusters as Kubernetes resources alongside your platform installation.

Each connected cluster requires two resources: a Cluster object and a Secret containing the cluster credentials.

Modify the following with your specific values to generate a copyable command:

CLUSTER_NAME

cluster.yaml

apiVersion: management.loft.sh/v1
kind: Cluster
metadata:
name: my-host-cluster
annotations:
  argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
spec:
displayName: "my-host-cluster"
owner:
  user: admin
config:
  secretName: "loft-cluster-config-my-host-cluster"
  secretNamespace: "vcluster-platform"
access:
  - subresources:
      - "*"
    users:
      - admin
    verbs:
      - "*"

Modify the following with your specific values to generate a copyable command:

CLUSTER_NAME

CLUSTER_API_SERVER

CA_DATA

CLUSTER_TOKEN

cluster-secret.yaml

apiVersion: v1
kind: Secret
metadata:
name: "loft-cluster-config-my-host-cluster"
namespace: vcluster-platform
type: Opaque
stringData:
config: |
  apiVersion: v1
  kind: Config
  clusters:
    - name: my-host-cluster
      cluster:
        server: https://1.2.3.4:6443
        certificate-authority-data: YOUR-CA-DATA
  contexts:
    - name: my-host-cluster
      context:
        cluster: my-host-cluster
        user: my-host-cluster-user
  current-context: my-host-cluster
  users:
    - name: my-host-cluster-user
      user:
        token: YOUR-TOKEN

Cluster secrets

The Secret contains authentication data for the remote cluster. Handle this appropriately in your GitOps pipeline. Consider using sealed secrets or an external secrets operator.

The SkipDryRunOnMissingResource=true annotation is required because the Cluster CRD is installed by the platform itself. Without it, ArgoCD cannot sync the resource on initial deployment.

You also need to install the platform agent on each connected cluster. If you manage agents through GitOps, set the DISABLE_AGENT=true environment variable in your platform deployment and create a separate ArgoCD Application for the agent:

Modify the following with your specific values to generate a copyable command:

CLUSTER_NAME

CLUSTER_API_SERVER

PLATFORM_VERSION

agent-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: platform-agent-my-host-cluster
namespace: argocd
spec:
destination:
  namespace: vcluster-platform
  server: "https://1.2.3.4:6443"
source:
  repoURL: "https://charts.loft.sh"
  targetRevision: 4.6.0
  chart: vcluster-platform
  helm:
    parameters:
      - name: agentOnly
        value: "true"
project: default
syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true

For interactive setup methods using the UI or CLI, see the connect a cluster guide.

3. Create a project

Projects organize virtual clusters and control access, templates, and quotas. In a GitOps workflow, define projects as Project custom resources.

Modify the following with your specific values to generate a copyable command:

PROJECT_NAME

TEAM_NAME

project.yaml

apiVersion: management.loft.sh/v1
kind: Project
metadata:
name: team-alpha
annotations:
  argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
spec:
displayName: team-alpha
owner:
  user: admin
allowedClusters:
  - name: "*"
allowedTemplates:
  - kind: VirtualClusterTemplate
    group: storage.loft.sh
    name: "*"
members:
  - kind: Team
    group: storage.loft.sh
    name: dev-team
    clusterRole: loft-management-project-admin

Enable ArgoCD integration on the project

To sync virtual clusters into ArgoCD as deployment targets, enable the ArgoCD integration on the project. This is configured through the project spec and allows virtual clusters to appear as available clusters in the ArgoCD UI.

See the ArgoCD integration guide for UI-based setup and configuration of SSO integration and App Project mapping.

management.loft.sh vs storage.loft.sh

Define resources using the management.loft.sh API group. The storage.loft.sh group is used internally by platform controllers and appears in some spec fields as references to existing resources.

For interactive project creation using the UI, see the create a project guide.

4. Deploy virtual clusters

With the platform, cluster, and project in place, deploy virtual clusters through ArgoCD. There are two approaches depending on how you want to manage the virtual cluster lifecycle.

Option A: Deploy with VirtualClusterInstance

Create a VirtualClusterInstance resource that the platform manages. This gives you full platform features like sleep mode, auto-delete, and template enforcement.

Modify the following with your specific values to generate a copyable command:

VCLUSTER_NAME

PROJECT_NAME

CLUSTER_NAME

VCLUSTER_VERSION

virtualclusterinstance.yaml

apiVersion: storage.loft.sh/v1
kind: VirtualClusterInstance
metadata:
name: dev-vcluster
namespace: loft-p-team-alpha
annotations:
  argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
spec:
clusterRef:
  cluster: my-host-cluster
external: false
owner:
  user: admin
template:
  helmRelease:
    chart:
      version: 0.31.0
    values: |
      controlPlane:
        backingStore:
          etcd:
            deploy:
              enabled: true

tip

The namespace follows the pattern loft-p-<project-name>. The platform uses this convention to associate virtual clusters with projects.

Option B: Deploy with Helm chart directly

Deploy the vCluster Helm chart through an ArgoCD Application. This approach gives you direct control over the Helm release but does not provide platform lifecycle features unless you register the virtual cluster afterward.

Modify the following with your specific values to generate a copyable command:

VCLUSTER_NAME

VCLUSTER_VERSION

NAMESPACE

vcluster-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: dev-vcluster
namespace: argocd
spec:
project: default
source:
  chart: vcluster
  repoURL: https://charts.loft.sh
  targetRevision: 0.31.0
  helm:
    releaseName: dev-vcluster
    valueFiles:
      - vcluster.yaml
destination:
  server: https://kubernetes.default.svc
  namespace: team-alpha

For the full list of deployment options including CLI, Terraform, and Flux, see the deploy vCluster guide.

Manage GitOps drift

Platform controllers may modify certain fields on resources after creation, causing drift in ArgoCD. Configure ignoreDifferences in your ArgoCD Applications to handle this:

spec:
  ignoreDifferences:
    # Ignore status for all Platform CRDs
    - group: management.loft.sh
      kind: "*"
      jsonPointers:
        - /status
    # Ignore controller-managed fields
    - group: management.loft.sh
      kind: "*"
      managedFieldsManagers:
        - loft
  syncPolicy:
    syncOptions:
      - RespectIgnoreDifferences=true

For a complete breakdown of drift-causing fields by resource type and tool-specific configuration, see the GitOps drift management section.

Repository structure

A typical Git repository for this workflow looks like:

platform-gitops/
  applications/
    platform.yaml              # ArgoCD Application for vCluster Platform
    agent-cluster-1.yaml       # ArgoCD Application for agent on cluster-1
  resources/
    clusters/
      cluster-1.yaml           # Cluster + Secret resources
    projects/
      team-alpha.yaml           # Project resource
    virtual-clusters/
      dev-vcluster.yaml         # VirtualClusterInstance

Next steps

• Configure platform settings for authentication, audit logging, and more
• Set up templates to standardize virtual cluster configurations
• Configure project quotas to control resource usage
• Enable sleep mode to reduce costs on idle virtual clusters