Deploy Fleet Observability with Argo CD

When the Argo CD integration is enabled, vCluster Platform ships a set of default ArgoCDApplicationTemplate resources for Fleet Observability. You reference these templates from ArgoCDApplication resources to deploy the metrics backend, Grafana, and edge collectors through GitOps, instead of installing and wiring them up by hand.

The templates are an alternative to the manual setup in Install the observability gateway and Configure edge collectors. The observability gateway itself is still deployed from an observability connector Secret, as described on the install page.

Prerequisites

The bundled templates are installed only when the Argo CD integration is enabled and your license includes Fleet Observability. You also need an Argo CD connector registered on the target cluster. See Connect to Argo CD.

Bundled templates

Platform installs the following cluster-scoped ArgoCDApplicationTemplate resources. The Platform UI lists them by display name. In an ArgoCDApplication, you reference them by their resource name through spec.templateRef.name.

Template (Platform UI)	templateRef.name	Deploys	Default namespace
Fleet Observability: Prometheus	fleet-observability-prometheus	Prometheus configured as an OTLP metrics backend	vcluster-platform
Fleet Observability: Grafana	fleet-observability-grafana	Grafana with the fleet, cluster, and GPU dashboards pre-provisioned	vcluster-platform
Fleet Observability: Cluster Collector	cluster-collector	OpenTelemetry Collectors	observability

The integration also ships templates for cert-manager and GPU monitoring, which are outside the scope of this guide.

Because the templates are cluster-scoped, you don't copy them into each project. You reference them by name and pass per-deployment values through spec.parameters. For the general template and application model, see Deploy applications.

How the pieces fit together

The full setup assembles four pieces in order:

1. fleet-observability-prometheus deploys the metrics backend on the control plane cluster.
2. The observability connector Secret deploys the Write Gateway and Query Proxy and points them at that backend.
3. cluster-collector deploys collectors that push OTLP metrics to the Write Gateway.
4. fleet-observability-grafana deploys Grafana with datasources that read through the Query Proxy.

Deploy to the control plane cluster

The metrics backend and Grafana run on the control plane cluster, alongside the gateway. Deploy them once, before creating the connector.

Deploy the metrics backend

Deploy an ArgoCDApplication that references fleet-observability-prometheus. This deploys Prometheus as a pure OTLP receiver, sized for fleet metrics, into the Platform namespace on your control plane cluster.

Platform UI

Create the ArgoCDApplication object in your project namespace:

fleet-metrics-backend.yaml

apiVersion: management.loft.sh/v1
kind: ArgoCDApplication
metadata:
  name: fleet-metrics-backend
  namespace: p-my-project          # replace with your project namespace
spec:
  displayName: "Fleet metrics backend"
  destination:
    cluster:
      name: loft-cluster           # replace with your control plane cluster name
  templateRef:
    name: fleet-observability-prometheus
  parameters:
    destinationNamespace: vcluster-platform
    prometheusStorageSize: 20Gi
    project: default

YAML

1. Click Control Plane Clusters in the left sidebar under the infrastructure section, then click the name of the control plane cluster to open its detail page.

2. Select the ArgoCD Apps tab and click .

3. In the Basics section, enter a Display Name such as Fleet metrics backend.

4. From the Argo CD Application Template dropdown, select the Fleet Observability: Prometheus template.

5. Fill the Template Parameters. Keep destinationNamespace as vcluster-platform, and adjust the storage size or chart version if needed.

6. Click .

Parameter	Default	Description
destinationNamespace	vcluster-platform	Namespace for the Prometheus backend.
project	default	Argo CD project that owns the application.
repoURL	Prometheus community Helm repo	Helm repository for the Prometheus chart.
version	29.14.0	Prometheus Helm chart version.
prometheusStorageSize	20Gi	Persistent volume size for Prometheus storage.
metricsBackendTLSSecret	(empty)	Existing mTLS Secret for the backend. When empty, Platform self-signs a Secret named metrics-backend-mtls.

The observability connector you create on the install page must use these endpoints when the template is deployed in its default namespace:

stringData:
  metricsBackendOtlpEndpoint: https://prom-prometheus-server.vcluster-platform.svc.cluster.local/api/v1/otlp
  metricsBackendPromQLEndpoint: https://prom-prometheus-server.vcluster-platform.svc.cluster.local
  metricsBackendCertSecretName: metrics-backend-mtls

The /api/v1/otlp path is required for OTLP ingestion. If you change destinationNamespace, replace vcluster-platform in both endpoints. If you supply metricsBackendTLSSecret, use that Secret name instead of metrics-backend-mtls.

Deploy Grafana

Grafana is optional. Deploy it when you want the pre-provisioned fleet dashboards and Platform-authenticated access. Reference fleet-observability-grafana.

Platform UI

Create the ArgoCDApplication object in your project namespace:

fleet-grafana.yaml

apiVersion: management.loft.sh/v1
kind: ArgoCDApplication
metadata:
  name: fleet-grafana
  namespace: p-my-project          # replace with your project namespace
spec:
  displayName: "Fleet Grafana"
  destination:
    cluster:
      name: loft-cluster           # replace with your control plane cluster name
  templateRef:
    name: fleet-observability-grafana
  parameters:
    destinationNamespace: vcluster-platform
    platformHost: platform.example.com
    project: default

YAML

1. Click Control Plane Clusters in the left sidebar under the infrastructure section, then click the name of the control plane cluster to open its detail page.

2. Select the ArgoCD Apps tab and click .

3. In the Basics section, enter a Display Name such as Fleet Grafana.

4. From the Argo CD Application Template dropdown, select the Fleet Observability: Grafana template.

5. Fill the Template Parameters. Set platformHost to your Platform host.

6. Click .

Parameter	Default	Description
destinationNamespace	vcluster-platform	Namespace for Grafana.
project	default	Argo CD project that owns the application.
platformHost	Platform host	Platform host used to authenticate Grafana users.
grafanaAdminGroup	(empty)	Group mapped to the Grafana admin role.
grafanaCertSecret	(empty)	TLS Secret for Grafana serving. When empty, Platform self-signs a Secret named grafana-server-tls.

Configure the fleet observability connector so Platform can proxy and embed the bundled Grafana dashboards. These values match the template defaults:

stringData:
  grafanaUrl: https://grafana.vcluster-platform.svc.cluster.local
  grafanaCertSecretName: grafana-server-tls
  fleetObservabilityDashboardUid: vcluster-fleet-observability

If you change destinationNamespace, update grafanaUrl. If you supply grafanaCertSecret, use that Secret name instead of grafana-server-tls.

Deploy collectors to each cluster

Collectors run on the clusters to observe. Deploy one to each cluster once the gateway is running and a metrics-writer key is in place.

The cluster-collector template deploys OpenTelemetry Collectors that push OTLP metrics to the Write Gateway. Deploy it to each tenant cluster you want to collect from.

vCluster Standalone tenant clusters

The out-of-the-box collector path relies on the Argo CD integration, which vCluster Standalone tenant clusters can't use. There is no bundled collector for them. Deploy a collector manually instead, as described in Configure edge collectors.

Each collector authenticates to the gateway with a metrics-writer bearer token. Create a Secret named otel-otlp-auth in the collector namespace before you deploy, or pass the token through the bearerToken parameter.

otel-otlp-auth.yaml

apiVersion: v1
kind: Secret
metadata:
  name: otel-otlp-auth
  namespace: observability
type: Opaque
stringData:
  authorization: "Bearer REPLACE_WITH_METRICS_WRITER_KEY"

Create the writer key first, as described in Create a writer key for a tenant cluster or Create a writer key for a control plane cluster, then deploy the collectors:

Platform UI

Create the ArgoCDApplication object in your project namespace:

fleet-edge-collectors.yaml

apiVersion: management.loft.sh/v1
kind: ArgoCDApplication
metadata:
  name: fleet-edge-collectors
  namespace: p-my-project          # replace with your project namespace
spec:
  displayName: "Fleet edge collectors"
  destination:
    virtualCluster:
      name: my-vcluster            # replace with your tenant cluster name
      target: vCluster             # deploy into the tenant cluster
  templateRef:
    name: cluster-collector
  parameters:
    destinationNamespace: observability
    otlpEndpoint: https://gateway-fleet-observability.vcluster-platform.svc.cluster.local:4318
    project: default

YAML

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 you want to collect from.

3. Select the ArgoCD Apps tab and click .

4. In the Basics section, enter a Display Name such as Fleet edge collectors.

5. Select Deploy to vCluster to deploy into the tenant cluster itself.

6. From the Argo CD Application Template dropdown, select the Fleet Observability: Cluster Collector template.

7. Fill the Template Parameters. Set destinationNamespace to observability and otlpEndpoint to the Write Gateway endpoint. Use the in-cluster Service endpoint for collectors in the Platform cluster, or the gateway LoadBalancer address for collectors in a tenant cluster elsewhere.

8. Click to add the Argo CD Application to the tenant cluster.

Parameter	Default	Description
destinationNamespace	observability	Namespace for the collectors.
project	default	Argo CD project that owns the application.
otlpEndpoint	Fleet Write Gateway Service	OTLP HTTP endpoint the collectors push to. Use the in-cluster Service endpoint (:4318) for collectors in the Platform cluster, or the gateway LoadBalancer address (https://<loadbalancer-address>:4318) for collectors elsewhere. See Expose the gateway with a LoadBalancer.
bearerToken	(empty)	metrics-writer bearer token. When empty, the collectors read the otel-otlp-auth Secret.
otlpCaData	(empty)	PEM CA data used to verify the gateway serving certificate.
otlpInsecureSkipVerify	false	Skip gateway TLS verification. Use only for test gateways.

The collectors stamp the request scope from the destination, so target a tenant cluster for tenant-scoped writes or a control plane cluster for cluster-scoped writes. Set destination.cluster instead of destination.virtualCluster to target a control plane cluster. Don't set vcluster_platform_* labels in collector configuration; the Write Gateway owns that namespace. See Configure edge collectors for the scope headers and label rules.

Verify

Once the applications sync, verify the backend and collectors with the checks in Install the observability gateway and Configure edge collectors.