Skip to content

Installation

This page covers bootstrapping the platform itself. Once it is installed and healthy, vending a stack is the copy-edit-review-commit path in Getting started.

Review every manifest and replace platform.example.org, the region, repository URLs, secret paths, profiles, and the function package reference before treating either path below as production. See Configuration for the full list of what to change.

Direct installation

Suitable for a disposable or evaluation cluster.

1. Prepare the repository

Fork or copy the repository, choose an API group under a domain you control, and replace platform.example.org everywhere. Change the repository URLs and function package path to your fork. Keep enabled/ empty until the controllers, provider, secret store, and organization ProviderConfig are healthy.

2. Install Crossplane

helm upgrade --install crossplane crossplane \
  --repo https://charts.crossplane.io/stable \
  --version 2.3.4 \
  --namespace crossplane-system \
  --create-namespace \
  --values deploy/crossplane/values.yaml

Wait for the Crossplane and RBAC manager deployments to become Available.

3. Install External Secrets Operator

helm upgrade --install external-secrets external-secrets \
  --repo https://charts.external-secrets.io \
  --version 2.6.0 \
  --namespace external-secrets \
  --create-namespace \
  --values deploy/external-secrets/values.yaml

Configure workload identity before applying the SecretStore. Confirm the organization credential exists at the configured remote path first — see Secrets.

4. Install the platform and environment configuration

kubectl create namespace grafana-vending
kubectl apply -k platform
kubectl apply -k deploy/aws

platform/ installs the Grafana provider (with signature verification), the vending composition function (also signature-verified), the ManagedResourceActivationPolicy, the XRDs and Compositions, and the extra composition RBAC needed for ESO's PushSecret and ExternalSecret resources. deploy/aws installs the SecretStore, the organization ExternalSecret, and the organization ProviderConfig.

Wait for the provider and function to become healthy:

kubectl wait provider.pkg.crossplane.io/provider-grafana \
  --for=condition=HealthyPackageRevision \
  --timeout=10m

kubectl wait function.pkg.crossplane.io/function-grafana-vending \
  --for=condition=HealthyPackageRevision \
  --timeout=10m

kubectl get providerconfig.grafana.m.crossplane.io \
  -n grafana-vending grafana-cloud-org

The optional profile secrets are intentionally excluded from deploy/aws/kustomization.yaml. Apply deploy/aws/optional-profile-secrets.yaml only after the corresponding remote secrets and profile definitions are ready — it contains OAuth inputs for the example generic_oauth and azuread profiles plus the incident relay input. The example SAML profile uses public IdP metadata and needs no committed key material.

5. Enable one request

See Getting started for the full copy-edit-review-commit path. For a quick evaluation:

cp -R examples/catalog/minimal enabled/my-stack
kubectl apply -k enabled/my-stack

6. Observe reconciliation

kubectl get grafanacloudstackrequests -n grafana-vending
kubectl describe grafanacloudstackrequest -n grafana-vending REPLACE_WITH_SLUG
kubectl get managed -n grafana-vending
kubectl get pushsecrets,externalsecrets -n grafana-vending
kubectl get providerconfigs.grafana.m.crossplane.io -n grafana-vending

Argo CD installation

deploy/argocd contains four building blocks:

  1. crossplane.yaml installs Crossplane 2.3.4 with the reference values.
  2. external-secrets.yaml installs the version-gated ESO release.
  3. platform.yaml installs platform/ plus the environment-specific AWS SecretStore and ProviderConfig.
  4. requests-applicationset.yaml creates one Argo CD Application per directory under enabled/.

The examples assume an Argo CD AppProject named platform and a repository Argo CD can read. While a fork is private, configure repository access through Argo CD's credential mechanism rather than placing credentials in an Application. A consumer of this public repository should pin targetRevision to an audited commit SHA, not main, and update the pin only after rendering and testing the new revision.

Apply the relevant settings from deploy/argocd/argocd-values.yaml to your Argo CD install:

  • application.resourceTrackingMethod: annotation — prevents Crossplane-generated children from inheriting Argo CD ownership by label. This is not optional: without it, Argo CD's default label-based tracking claims resources Crossplane also considers its own.
  • The resource.customizations health Lua scripts teach Argo CD to understand Crossplane package, managed-resource, and composite conditions, and to treat the platform.example.org/* custom resources as Progressing until their composed resources report Ready.
  • ProviderConfigUsage is excluded from resource.customizations because it is an internal Crossplane bookkeeping object.

The Application sync waves order controllers before platform APIs and requests. SkipDryRunOnMissingResource=true is needed while CRDs are still appearing. ServerSideApply=true avoids client-side annotation-size limits on large CRDs.

GitOps ownership and pruning

Argo CD selfHeal repairs changes to request objects and platform manifests. Crossplane repairs changes to external Grafana resources according to its management policies. These are different reconciliation loops — see Architecture.

Argo CD pruning a GrafanaCloudStackRequest deletes the composite Kubernetes object and its composed managed-resource objects. The managed resources omit the Delete management policy, the Stack enables delete protection, rotating tokens set deleteOnDestroy: false, and PushSecret uses deletionPolicy: None. External Grafana and secret-manager objects are therefore orphaned rather than destroyed. This is intentional: a destructive decommission must be a separately reviewed operation. See the decommission runbook in the project README.

Next steps

  • Getting started — vend your first stack.
  • Secrets — the organization credential and per-stack token flow in detail.
  • Architecture — the ownership boundaries between Argo CD, Crossplane, and ESO.