Agent Upgrades

Platform-managed agents

Platform-managed agents automatically receive upgrades controlled by the control plane. These automatic upgrades also handle more significant agent changes and migrations. All agents connect using an egress-only connection to the platform.

Upgrade process

When the platform initiates an upgrade on an egress-only agent, it will first deploy a proxy-only agent. As the name suggests, this proxy-only agent solely aims to proxy the communication between the platform and the connected cluster's Kubernetes API server.

The platform deploys the proxy-only agent by creating a deployment in the connected cluster's agent's namespace. It additionally reuses the agent's service account and associated RBAC permissions. Once the proxy-only agent is healthy, the platform upgrades the agent deployment. In case of a failure during the upgrade, the platform can still connect via the proxy-only agent and perform a rollback to a previous agent version.

When the platform starts the agent upgrade, the agent will be unavailable for a brief period until it restarts and reconnects. This proxy-only agent maintains a connection to the connected cluster's Kubernetes apiserver during that upgrade period and serves as a backup connection.

The proxy-only agent exists for the entire duration of the upgrade process, and the platform uses it to communicate with the connected cluster's Kubernetes API server. By doing so, the platform ensures that the connected cluster remains operational and can continue to receive updates and perform operations.

Once the agent upgrade is complete, the platform will remove the proxy-only agent and the associated resources from the connected cluster.

Self-managed agents

If the platform does not manage your agents, you can still manually upgrade them.

CLI

1. You can verify that the vCluster Platform Agent is installed in the cluster by running:

   vcluster platform list clusters

   The expected output would be:

           CLUSTER      |  AGE
   --------------------+--------
       cluster-name      |  7s

   In this example, the host cluster where the platform agent is installed is named cluster-name.

2. By providing the Helm chart version and values configuration, you can install or upgrade the existing platform agent deployment for the cluster-name cluster using:

   vcluster platform add cluster cluster-name \
       --helm-chart-version v4.5 \
       --helm-values my-helm-values \
       --context cluster-name-context

   Choose the appropriate version in --helm-chart-version and Helm chart configuration in --helm-values. Replace --context with the Kubernetes context of your target cluster. If you are already operating within that cluster’s context, you can omit the --context flag — the command will automatically install or upgrade the platform agent in the current cluster. You can find more details about the available flags for the vcluster platform add cluster command in the CLI documentation.

platform login

Connect to the Platform: to use any vcluster platform command, you need to be connected to the platform. See authentication documentation for more details.

When you started the platform, you would have automatically connected to the platform when you ran vcluster platform start.

If you aren't sure if you are connected and already have a running platform, then you can login. Before running this command, be sure that your kubecontext is set to the cluster running the platform.

Login to the platform.

vcluster platform login

If your kubectl context is not set to the cluster with running platform, it's possible to login to the platform using the CLI and access key. If you haven't already, you need to create access key to be able to login to the platform.

Login to the platform using access key

vcluster platform login [platform-url] --access-key [access-key]

Helm

1. If you prefer to use Helm, ensure that you have a valid access key. You can only obtain an access key after the cluster has been connected to the Platform.

2. To retrieve the access key for a connected cluster, run:

   vcluster platform get cluster-access-key cluster-name

   The expected output is:

   14:43:35 info vCluster platform host: https://loftg2fei.loft.host
   14:43:35 info Access Key: xxxxxxxx

   In this example, cluster-name refers to the host cluster containing the vCluster Platform Agent to be upgraded.

   Here, https://loftg2fei.loft.host represents the url, and xxxxxxxx is the token.

3. Next, use the following Helm command to upgrade the platform agent by providing the retrieved url and token:

   helm upgrade loft vcluster-platform \
       --repo https://charts.loft.sh \
       --install \
       --create-namespace \
       --namespace vcluster-platform \
       --set agentOnly=true \
       --set url=https://loftg2fei.loft.host \
       --set token=xxxxxxxx

   Ensure that the namespace specified with --namespace exists. This is the namespace where the platform agent is installed. If you deploy the platform agent’s resources into a different namespace, make sure to set --namespace accordingly.

   You can also retrieve pre-configured agent values from your platform by appending the --values flag with platform endpoint --values "https://$HOST/clusters/agent-values/$CLUSTER_NAME?token=$TOKEN".

   • $HOST — your platform domain.
   • $CLUSTER_NAME — the name of the cluster you are connecting.
   • $TOKEN — the authentication token. In this example, $HOST=loftg2fei.loft.host, $CLUSTER_NAME=cluster-name and $TOKEN=xxxxxxxx. The endpoint returns a YAML file with agent values that are configured in the agentValues field of your vCluster Platform Helm values, merged with any cluster-specific overrides from the loft.sh/agent-values annotation (when present).

   If the platform agent is not yet installed, you can include the --install and --create-namespace flags. The combination of --create-namespace and --namespace vcluster-platform will create the vcluster-platform namespace in the host cluster if it does not already exist. All platform agent resources will then be deployed and run within that namespace.