List all vclusters in the current Kubernetes context.

This function retrieves all vclusters managed by the vcluster platform in the current Kubernetes context. It sets up the Kubernetes client internally and returns the list of vclusters as serialized JSON on success, or an error object if the command failed.

Args: kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[Dict, List, str]: List of vclusters on success, or error object if failed.

Describe a specific vcluster in detail.

This function retrieves detailed information about a specific vcluster, including its status, resources, and configuration. The information is returned as serialized JSON on success, or an error object if the command failed.

Args: name: The name of the vcluster to describe. namespace: Optional namespace where the vcluster is located. If not provided, defaults to the vcluster name. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[Dict, str]: Detailed vcluster information on success, or error object if failed.

Check the control-plane certificates of a vcluster.

This function reports the current certificates and their expiry dates. Expired control-plane certificates typically surface as opaque connection failures, so this is worth checking when a vcluster is unreachable but otherwise appears healthy. The operation is read-only.

Args: name: The name of the vcluster to check. namespace: Optional namespace where the vcluster is located. If not provided, defaults to the vcluster name. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[Dict, List, str]: Certificate report on success, or error object if failed.

Export a vcluster kubeconfig to a file without switching contexts.

Use this when you need credentials to hand to another tool, for example kubectl --kubeconfig <path> or a Helm invocation. Unlike vcluster_call, it leaves the caller's current kube context untouched.

The kubeconfig is written to a private (0600) temporary file and the path is returned rather than the contents, because the file holds client credentials. The caller owns that file and should delete it after use.

Args: name: The name of the vcluster to export credentials for. namespace: Optional namespace where the vcluster is located. If not provided, defaults to the vcluster name. server: Optional API server address to record in the kubeconfig. Set this when the vcluster is reached through an ingress or load balancer rather than a local port forward. insecure: If True, the generated kubeconfig skips TLS verification. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[Dict[str, str], str]: A dict with kubeconfig_path, context and server on success, or error object if failed.

Pause a running vcluster.

This function pauses a running vcluster, which stops the virtual cluster without deleting it. This is useful for temporarily suspending workloads while preserving the cluster state.

Args: name: The name of the vcluster to pause. namespace: Optional namespace where the vcluster is located. If not provided, defaults to the vcluster name. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[CommandResult, str]: CommandResult on success, or error object if failed.

Resume a paused vcluster.

This function resumes a previously paused vcluster, restoring its operation and allowing workloads to run again.

Args: name: The name of the vcluster to resume. namespace: Optional namespace where the vcluster is located. If not provided, defaults to the vcluster name. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[CommandResult, str]: CommandResult on success, or error object if failed.

Delete a vcluster.

This action is irreversible - the cluster and all its resources will be permanently removed. By default the host namespace is preserved; the vcluster CLI still cleans up namespaces it created itself.

Args: name: The name of the vcluster to delete. namespace: Optional namespace where the vcluster is located. If not provided, defaults to the vcluster name. delete_namespace: If True, also delete the host namespace. DESTRUCTIVE - this removes every other workload in that namespace as well. Only set it when the namespace exists solely for this vcluster. keep_pvc: If True, retain the vcluster's persistent volume claim so the data survives the deletion. ignore_not_found: If True, succeed instead of erroring when the vcluster does not exist. Useful for idempotent cleanup. wait: If False, return immediately instead of waiting for the deletion to complete. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[CommandResult, str]: CommandResult on success, or error object if failed.

Create a new vcluster.

Creates a vcluster with the specified name. Configuration can come from values files, inline helm values, or both. The caller's kube context is never switched by this operation.

Args: name: The name for the new vcluster. values: Optional path to a values file, or a list of paths. Later files override earlier ones. upgrade: Optional flag to upgrade the cluster if it was created before. namespace: Optional namespace to create the vcluster in. If not provided, the vcluster CLI picks the default. set_values: Optional inline helm values, e.g. {"sync.toHost.ingresses.enabled": "true"}. Avoids writing a temporary values file for a single setting. chart_version: Optional vcluster chart version to pin, e.g. "0.36.0". chart_repo: Optional chart repository URL override. chart_name: Optional chart name override. expose: If True, create a load balancer service to expose the vcluster endpoint outside the host cluster. create_namespace: If False, do not create the namespace. Defaults to the CLI behaviour, which creates it when missing. kube_config_context_name: Optional override for the generated kube context name. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[CommandResult, str]: CommandResult on success, or error object if failed.

Execute a command inside a vcluster.

This function connects to a running vcluster and executes the given command within the virtual cluster context. It uses vcluster connect with the server-side flag to establish the connection and run the command.

Args: name: The name of the vcluster to connect to and execute the command in. command: The command string to execute inside the vcluster. Supports standard shell quoting (e.g. "kubectl get pods -n default"). namespace: Optional namespace where the vcluster is located. If not provided, defaults to vcluster-<name>. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[CommandResult, Dict[str, str], str]: CommandResult with exit code and output on success, or error object if failed.

Disconnect from a vcluster.

Returns: Union[CommandResult, str]: CommandResult on success, or error object if failed.

Get labels for a specific namespace.

This function retrieves all labels associated with a Kubernetes namespace. Labels are key-value pairs that can be used to organize and select resources.

Args: namespace: The name of the namespace to get labels from. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[Dict[str, str], str]: Dictionary of labels on success, or error object if failed.

Create or update a label on a namespace.

This function creates a new label or updates an existing label on a Kubernetes namespace. Labels are key-value pairs used for organizing and selecting resources.

Args: namespace: The name of the namespace to label. key: The label key to set. value: The label value to assign. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[bool, str]: True on success, or error object if failed.

Delete a label from a namespace.

This function removes a label from a Kubernetes namespace. If the label doesn't exist, the operation is considered successful.

Args: namespace: The name of the namespace to remove the label from. key: The label key to delete. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[bool, str]: True on success (or if label didn't exist), or error object if failed.

Get annotations for a specific namespace.

This function retrieves all annotations associated with a Kubernetes namespace. Annotations are similar to labels but are typically used for storing non-identifying metadata.

Args: namespace: The name of the namespace to get annotations from. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[Dict[str, str], str]: Dictionary of annotations on success, or error object if failed.

Create or update an annotation on a namespace.

This function creates a new annotation or updates an existing annotation on a Kubernetes namespace. Annotations are key-value pairs used for storing non-identifying metadata such as descriptions, links, or configuration data.

Args: namespace: The name of the namespace to annotate. key: The annotation key to set. value: The annotation value to assign. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[bool, str]: True on success, or error object if failed.

Delete an annotation from a namespace.

This function removes an annotation from a Kubernetes namespace. If the annotation doesn't exist, the operation is considered successful.

Args: namespace: The name of the namespace to remove the annotation from. key: The annotation key to delete. kubeconfig_path: Optional path to a kubeconfig file. If not provided, the default kubeconfig from the environment will be used.

Returns: Union[bool, str]: True on success (or if annotation didn't exist), or error object if failed.