Skip to main content

Telemetry

In this section, you will find a description of the vCluster telemetry - why we are collecting telemetry, what data points are we gathering, where we are sending the data, and how to opt-out.

Why do we collect telemetry​

Because vCluster is a freely available open source project, we as maintainers have a very limited idea of how the project is being used, and very limited possibilities to gather this information from the users. Without reliable information, it is difficult to make decisions about the prioritization of features, test automation or bug fixes. Deprecation of the flags and features turns into guesswork, and removal becomes nearly impossible. To get to the next step in maturing the project, and ensure long-term maintainability, we will be making decisions about feature deprecation, prioritizing test coverage, etc., and we want these decisions to be data-driven.

What are we collecting and how​

First of all, we want to emphasize that we are not interested in collecting data about individuals that are using vCluster, we are collecting data about how it is being used. This entails information about the configuration of vCluster, and the environment where it is deployed (e.g. Kubernetes version, CPU architecture, etc.).

Each vCluster is deployed with a "syncer" component that contains all controllers that make a virtual cluster function. This component will be collecting the data and uploading it to our backend at regular intervals (once every 1-5 minutes). We provide a documented example of the telemetry payload that would be uploaded, and of course, the source code responsible for this is fully available in our repo. The telemetry backend is hosted at this address - "https://admin.loft.sh/analytics/v1/vcluster/". The ingestion service is written and maintained by the vCluster maintainers. The data is saved into a relational database with strict access control.

Telemetry payload example​

Below you can find an example of the payload that vCluster syncer component would send to our telemetry backend. Some fields are self-explanatory, and some are explained below the example.

{
  "instanceProperties":{
    "uid":"7629e852-34d9-4fa6-8fc7-4c0423b5c44b",
    "instanceCreator":"vclusterctl",
    "instanceCreatorUID":"2c98c17cb7b02912d68eed65398d136ea4ff42e77d14f48a4d383420f8eada44",
    "arch":"amd64",
    "os":"linux",
    "syncerVersion":"v0.15.0",
    "syncerFlags":"{setFlags:{\"node-selector\":true},controllers:[\"hoststorageclasses\"]}",
    "vclusterServiceType":"NodePort",
    "virtualKubernetesVersion":{
      "major":"1",
      "minor":"26",
      "gitVersion":"v1.26.0+k3s1"
    },
    "hostKubernetesVersion":{
      "major":"1",
      "minor":"25",
      "gitVersion":"v1.25.3"
    }
  },
  "events":[
    {
      "type":"SyncerStarted",
      "time":1681418584841756
    },
    {
      "type":"LeadershipStarted",
      "time":1681418585169754
    },
    {
      "type":"ResourceSync",
      "time":1681418812947320,
      "success":true,
      "group":"core",
      "version":"v1",
      "kind":"ConfigMap"
    },
    {
      "type":"ResourceSync",
      "time":1681418812968426,
      "success":true,
      "processingTime":21,
      "group":"core",
      "version":"v1",
      "kind":"Pod"
    }
  ],
  "token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjRnektQWDRLLTdNZXlYWVFRVjdKM1BVUnhHRTdOVW1UazIyeGphcVRmdlUifQ.eyJpc3MiOiJ2Y2x1c3Rlci10ZWxlbWV0cnkifQ.WEh-8EfCpB1mW24s-jLW1vkcgLzTo6UArxgL03A650BnHv5aUY-C-BcR_sdOoMJIGZifdTImYwWIZYBPD232odlOiVijKGH3CMRPH9gblzUeRkBO1Qdl_qq7pIjEIWiQ4y6-H02u3nFtXBWmdq77rF32pxtzonvknFPKCvdoICP773wiJk_Tvofno0GnMxWLuojqahZdTjo15ww4kB5BnZZoT7UrhyPRFYD6fAL1YJq8WLi0GSKN2hoeC5EpcvLzmCfV3qUd_3PmHTIvvUJdTvjDfTUjI7aQfn1XsPz_GfRCsv18LNmTd2PqYbOaIZP7GeJ5l63pNp0IDKNgjtnjdl6bPgtoV21cZjZ4iVd2ODjUiTBUtFTT8QxXPA6_fuX1ZCpnAEppfELopkrFKD0F9RQFZW8BVWiaKLiULy3AgfaOUYOTlt0-j52JXW7gbNXhdIgWvt5r99a7DUAd8yo76SJBxMA3WQfSs43SeppM_iegVAa13ZUSKsiyNWUZ84SXtT1nlma93JZPchtdNKpgQIWiKC9MrNf3DiibBLHln3DE21XMVzn7CEuFiNLy4zl088Kg3Ue3KJiJBvWWFBN1kf-5xq1BN9lfVzwbaRW_mF2zcKz5sXe8J5wbiFzWOuCTWu24XPUUVj4aW_SkTeag80iMqFtrSAt63diQ6s9gm9g"
}
  • instanceProperties.uid - is a unique identifier of a particular instance. It is used to deduplicate data sent over time. The .metadata.uid value of the vCluster PVC or Service resource is used as value.
  • instanceProperties.instanceCreatorUID - is a machine identifier attached by the vCluster CLI to an instance during creation. We use machineid library to get the identifier, and then hash it for privacy.
  • instanceProperties.syncerFlags - contains a JSON payload that can have two fields: setFlags - list of the non-default syncer flags that were set, but the values are not collected, we only set true as value for each key; controllers - list of the resource sync controllers that have been enabled in addition to the default one.
  • events - an array of events for which we want to track duration and outcome (success/failure). We are sending just the GVK of the resource, but never any content.
  • token - this is a token generated in memory from a static key that is part of the vCluster binary. It is used to validate that the payload is being received from a real vCluster binary.

The cli may also send telemetry data to our backend, the cli telemetry data is as below:

{
  "data": [
    {
      "event": {
        "machine_id": "randomID",
        "platform_instance_id": "randomID",
        "platform_user_id": "randomID",
        "properties": "{\"command\":[\"vcluster\",\"completion\",\"bash\"],\"version\":\"0.18.1\"}",
        "timestamp": 17071593829,
        "type": "vcluster_cli"
      },
      "user": {
        "machine_id": "randomID",
        "platform_instance_id": "randomID",
        "platform_user_id": "randomID",
        "properties": "{\"os_arch\":\"arm64\",\"os_name\":\"darwin\",\"timezone\":\"GMT\"}",
        "timestamp": 17071593829
      }
    }
  ]
}

Telemetry opt-out process​

Below, you can find the instructions for disabling the telemetry based on the tool that you use to install or upgrade your vCluster instances.

Execute the following command to permanently opt out of telemetry on a given machine:

vcluster telemetry disable

Your decision will be saved in $HOME/.vcluster/config.json. All subsequently created or upgraded vCluster instances managed by the vCluster CLI will have the telemetry disabled.

To re-enable telemetry, you can execute the following command:

vcluster telemetry enable