Skip to content

Commit d421c30

Browse files
guowenatkguowenatk
authored
fix (platform): add registration of host clusters (#1340)
1 parent 428a098 commit d421c30

File tree

7 files changed

+274
-95
lines changed

7 files changed

+274
-95
lines changed

‎platform/_partials/cluster/connect-cli.mdx‎

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,42 @@
1+
import Flow, { Step } from '@site/src/components/Flow'
12
import NavStep from '@site/src/components/NavStep'
3+
import Button from '@site/src/components/Button'
4+
import Label from '@site/src/components/Label'
5+
import Input from '@site/src/components/Input'
6+
import Expander from '@site/src/components/Expander'
27

3-
When connecting a cluster from the vCluster CLI, you will need to provide a name for the cluster. This name will be used for the Cluster resource that gets created in Kubernetes. Optionally, you can use the `display-name` flag to specify a name for this cluster, when it gets displayed under the <NavStep>Clusters</NavStep> view in vCluster Platform.
8+
<Flow id="cluster-connect-cli">
9+
<Step>
10+
When connecting a cluster from the vCluster CLI, you will need to provide a name for the cluster. This name will be used for the Cluster resource that gets created in Kubernetes. Optionally, you can use the `display-name` flag to specify a name for this cluster, when it gets displayed under the <NavStep>Clusters</NavStep> view in vCluster Platform.
411

5-
```bash
6-
vcluster platform add cluster cluster-name --display-name [display-name]
7-
```
12+
```bash
13+
vcluster platform add cluster cluster-name --display-name [display-name]
14+
```
815

9-
The above command will automatically install the vCluster Platform Agent in the cluster that is one's current context. If you want to connect a cluster that is not your current context, you can use the `--context` flag to specify the context of the cluster you want to connect.
16+
The above command automatically installs the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) in the cluster that corresponds to your current Kubernetes context. The host cluster where the vCluster Platform itself is deployed is automatically connected to the platform during installation. Therefore, this command should be executed in a different host cluster from the one where the vCluster Platform is running.
1017

11-
```bash
12-
vcluster platform add cluster cluster-name --display-name [display-name] --context [context]
13-
```
18+
By default, the `vcluster-platform` namespace is created automatically if it does not already exist on the cluster. The vCluster Platform Agent resources are deployed into this namespace. You can override this behavior by explicitly specifying a different namespace using the `--namespace` flag. If you want to connect a cluster that is not associated with your current Kubernetes context, use the `--context` flag to specify the context of the target cluster.
19+
:::info
20+
For more information about available CLI flags, refer to the [CLI documentation](/docs/vcluster/cli/vcluster_platform_add_cluster).
21+
:::
22+
23+
```bash
24+
vcluster platform add cluster cluster-name --display-name [display-name] --context [context]
25+
```
26+
</Step>
27+
<Step>
28+
You can verify that the cluster is connected to the platform by running:
29+
```bash
30+
vcluster platform list clusters
31+
```
32+
33+
and the expected output is:
34+
```bash
35+
CLUSTER | AGE
36+
--------------------+--------
37+
cluster-name | 7s
38+
host-cluster | 10m4s
39+
```
40+
The `host-cluster` is the cluster name where the vCluster Platform is deployed.
41+
</Step>
42+
</Flow>

‎platform/_partials/cluster/connect-helm.mdx‎

Lines changed: 100 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,101 @@
1+
import Flow, { Step } from '@site/src/components/Flow'
12
import NavStep from '@site/src/components/NavStep'
2-
3-
4-
If you prefer to use Helm, you need to make sure that you have a valid Access Key.
5-
6-
You can either reuse the CLI Access Key or create a new one by following the
7-
[Access Key guide](../../administer/users-permissions/access-keys.mdx#create-an-access-key).
8-
9-
10-
- Reusing the CLI Access Key
11-
12-
```bash
13-
export ACCESS_KEY=$(vcluster platform access-key | jq -r .status.token)
14-
```
15-
16-
- Create new Access Key by following the [Access
17-
Key](/platform/administer/users-permissions/access-keys#create-an-access-key) guide.
18-
19-
```bash
20-
export ACCESS_KEY="[Newly Created Access Key]"
21-
```
22-
23-
After that, you need to provide a name for the cluster.
24-
25-
```bash
26-
export CLUSTER_NAME="cluster-name"
27-
```
28-
29-
Next, you must create the Cluster custom resource within the platform using the following code:
30-
31-
```bash
32-
cat <<EOF | kubectl apply -f -
33-
apiVersion: management.loft.sh/v1
34-
kind: Cluster
35-
metadata:
36-
name: $CLUSTER_NAME
37-
spec:
38-
displayName: $CLUSTER_NAME
39-
networkPeer: true
40-
managementNamespace: vcluster-platform
41-
EOF
42-
```
43-
44-
Then, you need to set the Platform Host using the following code:
45-
46-
```bash
47-
export PLATFORM_HOST="YOUR_LOFT_HOST"
48-
```
49-
50-
To get the Platform version, you should run the following command:
51-
52-
```bash
53-
export PLATFORM_VERSION=$(curl -s "https://$PLATFORM_HOST/version" | jq -r '.version | .[0:]')
54-
```
55-
56-
To get the Cluster Connect token, you should run the following command:
57-
58-
```bash
59-
export CLUSTER_ACCESS_KEY=$(curl -s "https://$PLATFORM_HOST/kubernetes/management/apis/management.loft.sh/v1/clusters/$CLUSTER_NAME/accesskey" -H "Authorization: bearer $ACCESS_KEY")
60-
```
61-
62-
Finally, you can connect the cluster using the following command:
63-
64-
```bash
65-
helm upgrade loft vcluster-platform --install \
66-
--repo https://charts.loft.sh/ \
67-
--version $PLATFORM_VERSION \
68-
--namespace vcluster-platform \
69-
--create-namespace \
70-
--set agentOnly=true \
71-
--set url=https://$PLATFORM_HOST \
72-
--set token=$(echo $CLUSTER_ACCESS_KEY | jq -r .accessKey) \
73-
--set additionalCA=$(echo $CLUSTER_ACCESS_KEY | jq -r .caCert) \
74-
--set insecure=$(echo $CLUSTER_ACCESS_KEY | jq -r .insecure)
75-
```
76-
:::warning
77-
vCluster Platform exclusively supports the default `secret` backend for storing Helm releases. Alternative `HELM_DRIVER` configurations (such as `configmap` or `sql`) are not supported.
78-
:::
79-
80-
This command automatically installs the Platform Agent in the cluster that is your current context.
81-
However, if you want to connect a cluster that is not your current context, you can append the `--kube-context` flag to specify the context of the cluster you want to connect.
82-
3+
import Button from '@site/src/components/Button'
4+
import Label from '@site/src/components/Label'
5+
import Input from '@site/src/components/Input'
6+
import Expander from '@site/src/components/Expander'
7+
8+
<Flow id="cluster-connect-helm">
9+
<Step>
10+
If you prefer to use Helm, you need to make sure that you have a valid Access Key.
11+
12+
You can either reuse the CLI Access Key or create a new one by following the
13+
[Access Key guide](../../administer/users-permissions/access-keys.mdx#create-an-access-key).
14+
15+
16+
- Reusing the CLI Access Key
17+
18+
```bash
19+
export ACCESS_KEY=$(vcluster platform access-key | jq -r .status.token)
20+
```
21+
22+
- Create new Access Key by following the [Access
23+
Key](/platform/administer/users-permissions/access-keys#create-an-access-key) guide.
24+
25+
```bash
26+
export ACCESS_KEY="[Newly Created Access Key]"
27+
```
28+
</Step>
29+
<Step>
30+
After that, you need to provide a name for the cluster.
31+
32+
```bash
33+
export CLUSTER_NAME="cluster-name"
34+
```
35+
</Step>
36+
<Step>
37+
Next, you must create the `Cluster` custom resource within the platform using the following code:
38+
39+
```bash
40+
cat <<EOF | kubectl apply -f -
41+
apiVersion: management.loft.sh/v1
42+
kind: Cluster
43+
metadata:
44+
name: $CLUSTER_NAME
45+
spec:
46+
displayName: $CLUSTER_NAME
47+
networkPeer: true
48+
managementNamespace: vcluster-platform
49+
EOF
50+
```
51+
</Step>
52+
<Step>
53+
Then, you need to set the Platform Host using the following code:
54+
55+
```bash
56+
export PLATFORM_HOST="YOUR_PLATFORM_HOST"
57+
```
58+
</Step>
59+
<Step>
60+
To get the Platform version, you should run the following command:
61+
62+
```bash
63+
export PLATFORM_VERSION=$(curl -s "https://$PLATFORM_HOST/version" | jq -r '.version | .[0:]')
64+
```
65+
</Step>
66+
<Step>
67+
To get the Cluster Connect token, you should run the following command:
68+
69+
```bash
70+
export CLUSTER_ACCESS_KEY=$(curl -s "https://$PLATFORM_HOST/kubernetes/management/apis/management.loft.sh/v1/clusters/$CLUSTER_NAME/accesskey" -H "Authorization: bearer $ACCESS_KEY")
71+
```
72+
</Step>
73+
<Step>
74+
Finally, you can connect the cluster using the following command:
75+
76+
```bash
77+
helm upgrade loft vcluster-platform --install \
78+
--repo https://charts.loft.sh/ \
79+
--version $PLATFORM_VERSION \
80+
--namespace vcluster-platform \
81+
--create-namespace \
82+
--set agentOnly=true \
83+
--set url=https://$PLATFORM_HOST \
84+
--set token=$(echo $CLUSTER_ACCESS_KEY | jq -r .accessKey) \
85+
--set additionalCA=$(echo $CLUSTER_ACCESS_KEY | jq -r .caCert) \
86+
--set insecure=$(echo $CLUSTER_ACCESS_KEY | jq -r .insecure)
87+
```
88+
89+
This command automatically installs the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) in the cluster that is your current context.
90+
However, if you want to connect a cluster that is not your current context, you can append the `--kube-context` flag to specify the context of the cluster you want to connect.
91+
92+
You can also retrieve pre-configured agent values from your platform by appending the `--values` flag with the platform endpoint `--values "https://$HOST/clusters/agent-values/$CLUSTER_NAME?token=$TOKEN"`.
93+
- `$HOST` — your vCluster Platform domain
94+
- `$CLUSTER_NAME` — the name you're assigning to the cluster being connected (e.g., `cluster-name`)
95+
- `$TOKEN` — the authentication token to access your vCluster Platform
96+
The endpoint returns an intelligently merged content of
97+
- Platform-level defaults configured in the `agentValues` field of your vCluster Platform Helm values
98+
- Cluster-specific overrides from the `loft.sh/agent-values` annotation (when present)
99+
100+
</Step>
101+
</Flow>

‎platform/_partials/cluster/upgrade-cli.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import Flow, { Step } from '@site/src/components/Flow'
2+
import NavStep from '@site/src/components/NavStep'
3+
import Button from '@site/src/components/Button'
4+
import Label from '@site/src/components/Label'
5+
import Input from '@site/src/components/Input'
6+
import Expander from '@site/src/components/Expander'
7+
8+
9+
<Flow id="upgrade-cluster-cli">
10+
<Step>
11+
You can verify that the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) is installed in the cluster by running:
12+
13+
```bash
14+
vcluster platform list clusters
15+
```
16+
17+
The expected output would be:
18+
19+
```bash
20+
CLUSTER | AGE
21+
--------------------+--------
22+
cluster-name | 7s
23+
```
24+
25+
In this example, the host cluster where the platform agent is installed is named `cluster-name`.
26+
</Step>
27+
<Step>
28+
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:
29+
30+
```
31+
vcluster platform add cluster cluster-name \
32+
--helm-chart-version v4.5 \
33+
--helm-values my-helm-values \
34+
--context cluster-name-context
35+
```
36+
37+
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.
38+
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.
39+
You can find more details about the available flags for the `vcluster platform add cluster` command in the [CLI documentation](/docs/vcluster/cli/vcluster_platform_add_cluster).
40+
</Step>
41+
</Flow>

‎platform/_partials/cluster/upgrade-helm.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import Flow, { Step } from '@site/src/components/Flow'
2+
import NavStep from '@site/src/components/NavStep'
3+
import Button from '@site/src/components/Button'
4+
import Label from '@site/src/components/Label'
5+
import Input from '@site/src/components/Input'
6+
import Expander from '@site/src/components/Expander'
7+
8+
<Flow id="upgrade-cluster-helm">
9+
<Step>
10+
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.
11+
</Step>
12+
<Step>
13+
To retrieve the access key for a connected cluster, run:
14+
15+
```bash
16+
vcluster platform get cluster-access-key cluster-name
17+
```
18+
19+
The expected output is:
20+
21+
```bash
22+
14:43:35 info vCluster platform host: https://loftg2fei.loft.host
23+
14:43:35 info Access Key: xxxxxxxx
24+
```
25+
In this example, `cluster-name` refers to the host cluster containing the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) to be upgraded.
26+
27+
<!-- vale off -->
28+
Here, `https://loftg2fei.loft.host` represents the `url`, and `xxxxxxxx` is the `token`.
29+
<!-- vale on -->
30+
</Step>
31+
<Step>
32+
Next, use the following Helm command to upgrade the platform agent by providing the retrieved `url` and `token`:
33+
34+
```yaml
35+
helm upgrade loft vcluster-platform \
36+
--repo https://charts.loft.sh \
37+
--install \
38+
--create-namespace \
39+
--namespace vcluster-platform \
40+
--set agentOnly=true \
41+
--set url=https://loftg2fei.loft.host \
42+
--set token=xxxxxxxx
43+
```
44+
Ensure that the namespace specified with `--namespace` exists. This is the namespace where the platform agent is installed.
45+
If you deploy the platform agent’s resources into a different namespace, make sure to set `--namespace` accordingly.
46+
47+
You can also retrieve pre-configured agent values from your platform by appending the `--values` flag with platform endpoint
48+
`--values "https://$HOST/clusters/agent-values/$CLUSTER_NAME?token=$TOKEN"`.
49+
- `$HOST` — your platform domain.
50+
- `$CLUSTER_NAME` — the name of the cluster you are connecting.
51+
- `$TOKEN` — the authentication token.
52+
In this example, `$HOST=loftg2fei.loft.host`, `$CLUSTER_NAME=cluster-name` and `$TOKEN=xxxxxxxx`.
53+
The endpoint returns a YAML file with agent values that are configured in the `agentValues` field of your vCluster
54+
Platform Helm values, merged with any cluster-specific overrides from the `loft.sh/agent-values` annotation (when present).
55+
56+
If the platform agent is not yet installed, you can include the `--install` and `--create-namespace` flags. The combination
57+
of `--create-namespace` and `--namespace vcluster-platform` will create the `vcluster-platform` namespace in the host cluster
58+
if it does not already exist. All platform agent resources will then be deployed and run within that namespace.
59+
</Step>
60+
</Flow>

‎platform/administer/clusters/advanced/cluster-upgrades.mdx‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ sidebar_label: Agent Upgrades
66
import Tabs from '@theme/Tabs';
77
import TabItem from '@theme/TabItem'
88

9-
import PartialClusterConnectUI from '../../../_partials/cluster/connect-ui.mdx'
10-
import PartialClusterConnectCLI from '../../../_partials/cluster/connect-cli.mdx'
9+
import ConnectPlatform from '../../../_fragments/cli-steps/connect-platform.mdx';
10+
import PartialClusterUpgradeCLI from '../../../_partials/cluster/upgrade-cli.mdx'
11+
import PartialClusterUpgradeHelm from '../../../_partials/cluster/upgrade-helm.mdx'
1112

1213
import BeforeSvg from '@site/static/media/agent/before-agent-upgrade.excalidraw.svg';
1314
import DuringSvg1 from '@site/static/media/agent/during-agent-upgrade-1.excalidraw.svg';
@@ -49,7 +50,33 @@ Once the agent upgrade is complete, the platform will remove the proxy-only agen
4950
<AfterSvg width="100%" />
5051

5152
## Self-managed agents
53+
If the platform does not manage your agents, you can still manually upgrade them.
5254

53-
If the platform does not manage your agents, manually upgrade them by repeating the installation steps using the CLI or Helm command.
54-
Instructions on how to do can be found [here](../connect-cluster.mdx).
55+
<Tabs
56+
defaultValue="cli"
57+
values={[
58+
{label: 'CLI', value: 'cli'},
59+
{label: 'Helm', value: 'helm'},
60+
]}>
61+
<TabItem value="cli">
62+
<PartialClusterUpgradeCLI />
5563

64+
65+
:::info platform login
66+
<ConnectPlatform />
67+
68+
If your kubectl context is not set to the cluster with running platform, it's
69+
possible to login to the platform using the CLI and access key.
70+
If you haven't already, you need to [create access key](/docs/platform/api/authentication#create-an-access-key) to be able to login to the platform.
71+
72+
```bash title="Login to the platform using access key"
73+
vcluster platform login [platform-url] --access-key [access-key]
74+
```
75+
76+
:::
77+
78+
</TabItem>
79+
<TabItem value="helm">
80+
<PartialClusterUpgradeHelm />
81+
</TabItem>
82+
</Tabs>

0 commit comments

Comments
 (0)