vCluster Platform Demo Repository

This repository template is configured to automatically integrate with fully managed and fully automated vCluster Platform Demo Generator, and provides a GitOps approach for managing vCluster Platform (vcluster-gitops directory) and selectable demo-use-cases-as-code for self-service vCluster Platform demo environments (vcluster-use-cases directory).

Although originally designed and optimized for a hierarchical vCluster Platform with the fully managed [vCluster Platform Demo Generator] -leveraging vCluster inception- the vCluster Platform Demo Repository may also be used for standalone vCluster Platform demo environments where the host cluster, along with the vCluster Platform and Argo CD installations (bootstrap applications), are self-managed. See the instructions for self managed vCluster Platform installs.

vCluster Platform Integration Examples

• vCluster Platform GitOps: Mainly used to create and update vCluster Platform custom resources to pre-configure the vCluster Platform Demo environment. The resources are deployed to the vCluster Platform Demo vCluster via Argo CD and Flux.
• Argo CD: Argo CD is used for vCluster Platform Demo GitOps and to install additional template selectable demo use cases as code using the App of Apps pattern. Argo CD is also used to showcase vCluster Platform integrations like ephmeral virtual cluster for GitHub Pull Requests.
• vNode: Using vNode with vCluster and vCluster Platform
• Crossplane: Crossplane highlights custom resource syncing and is used to create ephemeral GitHub resources that are automatically cleaned up when a VCP demo environment vCluster is deleted.
• External Secrets Operator showcases vCluster integration with ESO.
• vCluster Central Admission Control with Kyverno
• Flux: Showcases vCluster integration with Flux.
• MySQL Operator example that showcases using the vCluster Platform database connector to provide backing stores for Platform managed vCluster instances.
• Postgres Operator showcases custom resource syncing.
• vCluster Virtual Scheduler with Volcano Scheduler and KubeRay
• vCluster Rancher integration showcases using the vCluster Rancher Operator with vCluster Platform managed vCluster instances

GitHub Actions Automations

There are a number of GitHub Actions workflows included as part of this template repository. Some are used to automate the configuration and modification of the contents of the repository, while others are used to demonstrate the features and capabilities of vCluster Platform and vCluster.

Automation Workflows

replace-text

This GitHub Actions workflow replaces template values in YAML files based on the current repository name, default values and/or user-defined inputs. It’s designed to help scaffold new vCluster Platform demo repositories created from this template repository.

What It Does

• Triggers on:

  • A push to the main branch that modifies helm-chart/Chart.yaml that is pushed to the repository by a vCluster Platform Demo Generator Crossplane integration
  • A manual run via the "Run workflow" button in the GitHub UI

• Replaces placeholders in all *.yaml files using the flcdrg/replace-multiple-action GitHub Action:

  • {REPLACE_REPO_NAME} → current GitHub repo name
  • {REPLACE_ORG_NAME} → GitHub org that owns the repo
  • {REPLACE_VCLUSTER_NAME} → user-supplied name or repo name with -app removed
  • {REPLACE_BASE_DOMAIN} → user-supplied base domain (defaults to us.demo.dev)

• Commits changes automatically using git-auto-commit-action

• Deletes any associated container image (e.g., GitHub Container Registry package) for the repo under the org, using a GitHub PAT

• Disables itself after running, so it’s only used once per repo initialization

Auto-Update vCluster Templates + K8s Versions

This GitHub Actions workflow runs the update_templates.sh script and creates a pull request if there are any changes.

Integration Details

Argo CD Integrations

vCluster Platform includes an Argo CD integration that will automatically add a vCluster instance, created with a virtual cluster template, to Argo CD as a target cluster of an Argo CD Application destination.

Example management.loft.sh/v1 VirtualClusterTemplate manifest (with unrelated configuration execluded - full version here) that enables the automatic syncing of the vCluster instance created with the template to Argo CD:

kind: VirtualClusterTemplate
apiVersion: management.loft.sh/v1
metadata:
  name: preview-template
spec:
  displayName: vCluster.Pro Preview Template
  template:
    metadata:
      labels:
        loft.sh/import-argocd: 'true'
...

The virtual cluster template integration requires the vCluster Platform Project, where the vCluster instance is created from said template, to have the Argo CD integration for Projects enabled.

Example management.loft.sh/v1 Project manifest (with unrelated configuration execluded - full version here) that enables the syncing of vCluster instances to Argo CD:

kind: Project
apiVersion: management.loft.sh/v1
metadata:
  name: api-framework
spec:
  displayName: API Framework
...
  argoCD:
    enabled: true
    cluster: loft-cluster
    namespace: argocd
    project:
      enabled: true

Important

The Argo CD instance must be in a vCluster Platform connected cluster or in a vCluster instance that is managed by vCluster Platform. More info is available here.

Example: ApplicationSet Cluster Generator

>[!IMPORTANT] >The vCluster Platform Argo CD integration, as described above, must be enabled on the vCluster Platform project the vCluster instance is created in, for the vCluster instance to be automatically added to Argo CD as an available `Application` `destination` cluster.

In addition to automatically adding/syncing vCluster instances to Argo CD, the vCluster Platform integration also syncs instanceTemplate labels of a virtual cluster template to the Argo CD cluster Secret generated by the integration discussed above. This integration allows the use of the labels as selectors with the Argo CD Cluster Generator for ApplciationSets.

Example management.loft.sh/v1 VirtualClusterTemplate manifest (with unrelated configuration execluded - full version here) that enables the automatic syncing of vCluster instances created with this template to Argo CD and adds the spec.versions.template.metadata.labels to the generate Argo CD Cluster Secret:

apiVersion: management.loft.sh/v1
kind: VirtualClusterTemplate
metadata:
  name: vcluster-pro-template
  labels:
    app.kubernetes.io/instance: loft-configuration
spec:
  displayName: Virtual Cluster Pro Template
...
  template:
...
  versions:
    - template:
        metadata:
          labels:
            loft.sh/import-argocd: 'true'
        instanceTemplate:
          metadata:
            labels:
              env: '{{ .Values.env }}'
              team: '{{ .Values.loft.project }}'
        pro:
          enabled: true
...
      parameters:
      ...
        - variable: env
          label: Deployment Environment
          description: Environment for deployments for this vCluster used as cluster label for Argo CD ApplicationSet Cluster Generator
          options:
            - dev
            - qa
            - prod
          defaultValue: dev
      version: 1.0.0
    - template:
        metadata: {}
        instanceTemplate:
          metadata: {}
      version: 0.0.0
...

In this example the value for the instanceTemplate.metadata.labels.env label is populated with the selected env parameter value, but the value also be hardcoded so that every vCluster instance created from this template had the same env label value. The team label is populated with the project vCluster Platform Parameter values as documented here.

The generated Argo CD Cluster Secret for a vCluster instance created in the api-framework project and using the above template:

apiVersion: v1
kind: Secret
metadata:
  name: loft-api-framework-vcluster-api-framework-dev
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
    env: dev
    loft.sh/vcluster-instance-name: api-framework-dev
    loft.sh/vcluster-instance-namespace: loft-p-api-framework
    team: api-framework
  annotations:
    co-managed-by: loft.sh
    managed-by: argocd.argoproj.io
data:
  config: >-
    ...
  name: bG9mdC1hcGktZnJhbWV3b3JrLXZjbHVzdGVyLWFwaS1mcmFtZXdvcmstZGV2
  server: >-
    ...
type: Opaque

With all of that in place, you would then be able to create an Argo CD ApplicationSet that used the Cluster Generator as below (replacing necessary values with those for your Git repository):

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: REPO_NAME-env-config
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: "dev"
    - clusters:
        selector:
          matchLabels:
            env: "qa"
    - clusters:
        selector:
          matchLabels:
            env: "prod"
  template:
    metadata:
      # {{name}} is the name of the kubernetes cluster as selected by the spec above
      name: REPO_NAME-{{name}}
    spec:
      destination:
        # {{server}} is the url of the 
        server: '{{server}}'
        # {{metadata.labels.env}} is the value of the env label that is being used to select kubernetes clusters 
        # and used as sub-folder in the target git repository
        namespace: hello-world-app-{{metadata.labels.env}}
      info:
        - name: GitHub Repo
          value: https://github.com/loft-demos/REPO_NAME/
      project: default
      source:
        path: k8s-manifests/{{metadata.labels.env}}/
        repoURL: https://github.com/loft-demos/REPO_NAME.git
        targetRevision: main
      syncPolicy:
        automated:
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

[!NOTE] The use of the env label as part of the spec.template.spec.source.path allowing vCluster instances with different env values to target different subdirectories in the GitHub repository for the Argo CD generated Application.

The resulting Argo CD Application for the hello-app-a1 repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello-app-a1-config
  namespace: argocd
spec:
  destination:
    namespace: hello-world-app
    server: >-
      https://a1.us.demo.dev/kubernetes/project/api-framework/virtualcluster/api-framework-dev
  info:
    - name: GitHub Repo
      value: https://github.com/loft-demos/hello-app-a1/
  project: default
  source:
    path: k8s-manifests/dev/
    repoURL: https://github.com/loft-demos/hello-app-a1.git
    targetRevision: main
  syncPolicy:
    automated:
      selfHeal: true
    syncOptions:
      - CreateNamespace=true