Virtual Cluster Instance
A virtual cluster is a fully functional Kubernetes cluster that runs inside the namespace of another Kubernetes cluster (host cluster). Virtual clusters are very useful if you are hitting the limits of namespaces and do not want to make special exceptions to the multi-tenancy configuration of the underlying cluster, e.g. a user needs their own CRD or user needs pods from 2 namespaces to communicate with each other but your standard NetworkPolicy does not allow this, then a virtual cluster may be perfect for this user.
Example Virtual Cluster
An example Virtual Cluster:
apiVersion: management.loft.sh/v1
kind: VirtualClusterInstance
metadata:
creationTimestamp: null
name: my-virtual-cluster
namespace: loft-p-my-project
spec:
clusterRef: {}
displayName: my-display-name
owner:
user: my-user
parameters: 'my-parameter: my-value'
templateRef:
name: my-virtual-cluster-template
status: {}
Virtual Cluster Reference
kind required string
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
kind required string apiVersion required string
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
apiVersion required string metadata required object
metadata required object spec required object
spec required object status required object
status required object Retrieve: Virtual Clusters
You can either use curl or kubectl to retrieve Virtual Clusters.
- kubectl
- curl
Retrieve a list of Virtual Clusters
Run the following command to list all Virtual Clusters in project my-project:
kubectl get virtualclusterinstances.management.loft.sh -n loft-p-my-project -o yaml
Retrieve a single Virtual Cluster by name
Run the following kubectl command to get Virtual Cluster my-virtual-cluster in project my-project:
kubectl get virtualclusterinstances.management.loft.sh my-virtual-cluster -n loft-p-my-project -o yaml
Retrieve a list of Virtual Clusters
Run the following curl command to list all Virtual Clusters in project my-project:
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/namespaces/loft-p-my-project/virtualclusterinstances" \
-X GET --insecure \
-H "Authorization: Bearer $ACCESS_KEY"
Get a single Virtual Cluster by name
Run the following curl command to get Virtual Cluster my-virtual-cluster in project my-project:
# Exchange my-virtual-cluster in the url below with the name of the Virtual Cluster
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/namespaces/loft-p-my-project/virtualclusterinstances/my-virtual-cluster" \
-X GET --insecure \
-H "Authorization: Bearer $ACCESS_KEY"
Create: Virtual Cluster
You can either use curl or kubectl to create a new Virtual Cluster.
Make sure to set the project in the metadata.namespace field you want to create the Virtual Cluster in. If your project has the id my-project, the corresponding namespace would be loft-p-my-project.
- kubectl
- curl
Create a file object.yaml with the following contents:
apiVersion: management.loft.sh/v1
kind: VirtualClusterInstance
metadata:
creationTimestamp: null
name: my-virtual-cluster
namespace: loft-p-my-project
spec:
clusterRef: {}
displayName: my-display-name
owner:
user: my-user
parameters: 'my-parameter: my-value'
templateRef:
name: my-virtual-cluster-template
status: {}
Then create the Virtual Cluster my-virtual-cluster in project my-project with:
kubectl create -f object.yaml -n loft-p-my-project
Create a file object.yaml with the following contents:
apiVersion: management.loft.sh/v1
kind: VirtualClusterInstance
metadata:
creationTimestamp: null
name: my-virtual-cluster
namespace: loft-p-my-project
spec:
clusterRef: {}
displayName: my-display-name
owner:
user: my-user
parameters: 'my-parameter: my-value'
templateRef:
name: my-virtual-cluster-template
status: {}
Run the following curl command to create a new Virtual Cluster my-virtual-cluster in project my-project:
curl -s -X POST --insecure \
"https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/namespaces/loft-p-my-project/virtualclusterinstances" \
--data-binary "$(cat object.yaml)" \
-H "Content-Type: application/yaml" \
-H "Authorization: Bearer $ACCESS_KEY"
Update: Virtual Cluster
You can either use curl or kubectl to update Virtual Clusters.
- kubectl
- curl
Update Virtual Cluster
Run the following command to update Virtual Cluster my-virtual-cluster in project my-project:
kubectl edit virtualclusterinstances.management.loft.sh my-virtual-cluster -n loft-p-my-project
Then edit the object and upon save, kubectl will update the resource.
Patch Virtual Cluster
Patching a resource is useful if you want to generically exchange only a small portion of the object instead of retrieving the whole object first and then modifying it. To learn more about patches in Kubernetes, please take a look at the official docs.
Run the following kubectl command to add a new annotation my-annotation: my-value to the Virtual Cluster my-virtual-cluster in project my-project via a patch:
kubectl patch virtualclusterinstances.management.loft.sh my-virtual-cluster -n loft-p-my-project \
--type json \
-p '[{"op": "add", "path": "/metadata/annotations/my-annotation", "value": "my-value"}]'
Update Virtual Cluster
First retrieve the current object into a file object.yaml. This could look like:
apiVersion: management.loft.sh/v1
kind: VirtualClusterInstance
metadata:
creationTimestamp: "2023-04-03T00:00:00Z"
generation: 12
name: my-virtual-cluster
namespace: loft-p-my-project
resourceVersion: "66325905"
uid: af5f9f0f-8ab9-4b4b-a595-a95a5921f3c2
spec:
clusterRef: {}
displayName: my-display-name
owner:
user: my-user
parameters: 'my-parameter: my-value'
templateRef:
name: my-virtual-cluster-template
status: {}
Run the following curl command to update a single Virtual Cluster my-virtual-cluster in project my-project:
# Replace the my-virtual-cluster in the url below with the name of the Virtual Cluster you want to update
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/namespaces/loft-p-my-project/virtualclusterinstances/my-virtual-cluster" \
-X PUT --insecure \
-H "Content-Type: application/yaml" \
-H "Authorization: Bearer $ACCESS_KEY" \
--data-binary "$(cat object.yaml)"
Patch Virtual Cluster
Patching a resource is useful if you want to generically exchange only a small portion of the object instead of retrieving the whole object first and then modifying it. To learn more about patches in Kubernetes, please take a look at the official docs.
Run the following curl command to add a new annotation my-annotation: my-value to the Virtual Cluster my-virtual-cluster in project my-project via a patch:
# Replace the my-virtual-cluster in the url below with the name of the Virtual Cluster you want to update
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/namespaces/loft-p-my-project/virtualclusterinstances/my-virtual-cluster" \
-X PATCH --insecure \
-H "Content-Type: application/json-patch+json" \
-H "Authorization: Bearer $ACCESS_KEY" \
--data '[{"op": "add", "path": "/metadata/annotations/my-annotation", "value": "my-value"}]'
Delete: Virtual Cluster
You can either use curl or kubectl to delete Virtual Clusters.
- kubectl
- curl
Run the following command to delete Virtual Cluster my-virtual-cluster in project my-project:
kubectl delete virtualclusterinstances.management.loft.sh my-virtual-cluster -n loft-p-my-project
Run the following curl command to delete Virtual Cluster my-virtual-cluster in project my-project:
# Replace the my-virtual-cluster in the url below with the name of the Virtual Cluster you want to delete
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/namespaces/loft-p-my-project/virtualclusterinstances/my-virtual-cluster" \
-X DELETE --insecure \
-H "Authorization: Bearer $ACCESS_KEY"
