Sync a namespaced custom resource from the control plane cluster

Supported Configurations

Running the control plane as a container with:

• Shared Nodes

This guide walks through syncing a namespaced custom resource from the control plane cluster to a tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster, using an example CRD. For the config reference, see Custom resources from the control plane cluster.

Set up cluster contexts

Setting up the control plane and tenant cluster contexts makes it easier to switch between them.

set up kubectl contexts

export HOST_CTX="your-host-context"
export VCLUSTER_CTX="vcluster-ctx"

Then, create a namespace in your control plane clusterControl plane clusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The control plane cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both.Related: Tenant cluster, Control plane cluster, Tenant cluster. This example uses foobar2:

create namespace

kubectl --context="${HOST_CTX}" create namespace foobar2

tip

You can find your contexts by running kubectl config get-contexts

Create a CustomResourceDefinition in the control plane cluster

Save the following CustomResourceDefinition:

example-crd.yaml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: examples.demo.loft.sh
spec:
  group: demo.loft.sh
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                image:
                  type: string
                replicas:
                  type: integer
      additionalPrinterColumns:
      - name: Image
        type: string
        description: The image of an example
        jsonPath: .spec.image
      - name: Replicas
        type: integer
        description: The number of replicas in example
        jsonPath: .spec.replicas
  scope: Namespaced
  names:
    plural: examples
    singular: example
    kind: Example

Save this file locally and apply it to the control plane cluster:

Create Example CRD in the host

kubectl --context="${HOST_CTX}" create -f example-crd.yaml

Enable from-host syncing for your custom resource

Enable from-host syncing for Example custom resources in your tenant cluster configuration:

Enable from host syncing for CustomResource

sync:
  fromHost:
    customResources:
      examples.demo.loft.sh:
        enabled: true
        scope: Namespaced
        mappings:
          byName:
            "foobar2/*": "default/*"

This configuration:

• Enables from-host syncing of examples.demo.loft.sh from the foobar2 namespace you created earlier.
• Automatically configures RBAC permissions for vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs.Related: Tenant cluster, Control plane cluster, so it can get, watch, and list Example resources in the foobar2 namespace.
• Syncs all Examples from the foobar2 namespace to the default namespace in the tenant cluster.

create tenant cluster

Create or update a tenant cluster following the vCluster quick start guide.

Sync a namespaced custom resource to the tenant cluster

1. First, create an example resource in the control plane cluster.

   Copy this file and save it locally as example-cr.yaml:

   apiVersion: demo.loft.sh/v1
   kind: Example
   metadata:
     name: my-example
     namespace: foobar2
   spec:
     image: "my-image:latest"
     replicas: 2

   Then create the example in the control plane cluster:

   Create example in the host

   kubectl --context="${HOST_CTX}" create -f example-cr.yaml

Ensure the custom resource synced to the tenant cluster

The custom resource should now be accessible in the tenant cluster. If you edit a field on the tenant object, it stays until the control plane cluster changes that same field, which then overwrites it.

2. Check the custom resource in the tenant cluster:

   Get synced CustomResource

   kubectl --context="${VCLUSTER_CTX}" get examples.demo.loft.sh --namespace default

   You should see similar output:

   examples in vCluster

   NAME         IMAGE             REPLICAS
   my-example   my-image:latest   2

Edit the custom resource in the control plane cluster

3. Now edit the example in the control plane cluster and see that the change syncs to the tenant cluster. To set replicas to 4, run:

   Patch Example CR

   kubectl --context="${HOST_CTX}" patch examples.demo.loft.sh my-example --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": 4}]'  --namespace foobar2

Verify the tenant cluster copy updated

4. Tenant Cluster Check the number of replicas:

   Check example

   kubectl --context="${VCLUSTER_CTX}" get --namespace default examples.demo.loft.sh

   You should see the number of replicas updated from the control plane cluster object:

   Example updated in vCluster

   NAME         IMAGE             REPLICAS
   my-example   my-image:latest   4