About Instance and Event Data

This topic describes the application instance data fields that the Replicated vendor portal uses to generate events for the instance.

How the Vendor Portal Collects Instance Data

For application instances installed in online customer environments, Replicated KOTS periodically sends a small amount of instance data to the vendor portal, including properties such as the current version and status of the instance.

KOTS sends this instance data to the vendor portal when any of the following check-ins occur:

• The instance checks for updates. An update check can occur when a user clicks the Check for updates button in the Replicated admin console, or when the admin console runs an automatic update check. By default, the admin console runs automatic update checks every four hours. Users can modify or disable automatic update checks from the admin console. For more information, see Updating an Application in the Enterprise section.
• The status of an instance changes. For example, an instance can change from a Ready to Degraded status.
• (KOTS v1.92 and later only) The instance completes an update to a new application version.

The primary purpose of this instance data is to help the cloud-hosted update service to compile the list of new versions that are available to the given instance for upgrade. The vendor portal also uses this instance data to display insights about the active instances of your application.

For a full overview of what data might be included, see the Replicated Data Transmission Policy.

How the Vendor Portal Generates Events

When the vendor portal receives instance data from KOTS, it evaluates each data field to determine if there was a change in its value. For each field that changes in value, the vendor portal creates an event to record the change. For example, a change from ready to degraded in the appStatus data field generates an event in the vendor portal.

In addition to creating events for changes in data fields sent by KOTS, the vendor portal also generates events for changes in the value of a computed metric. For example, the vendor portal computes a numberVersionsBehind metric that tracks the number of versions behind the latest available version for the instance. When the instance checks for updates and the vendor portal identifies a new version that is available to the instance, then the vendor portal generates an event to indicate the change in the value of the numberVersionsBehind metric. The vendor portal updates the values of computed metrics each time KOTS sends instance data.

Each event that the vendor portal generates for application instances has the following fields:

• fieldName: The instance data field that generated the event. For example, appStatus.
• previousValue: The value of the data field before the vendor portal generated the event.
• newValue: The value of the data field after the vendor portal generated the event.

The vendor portal uses events to display insights for each active application instance in a Instance details dashboard. For more information about using the vendor portal Instance details page to monitor active instances of your application, see Viewing Instance Details.

Limitations

The vendor portal has the following limitations for reporting instance data and generating events:

• Status informers required: You must configure one or more status informers for your application in the Application custom resource to populate instance data about the application status or uptime. For more information about how to configure status informers, see Displaying Application Status.

• Air gap not supported: Instance data is available only for application instances installed in online environments. Data for instances installed in air gapped environments is not available.

• Active instances only: Instance data is available only for active application instances. An instance is considered inactive when its most recent check-in was more than two weeks ago. An instance can become inactive if it is decommissioned, stops checking for updates, or otherwise stops reporting.

  The vendor portal continues to display data for an inactive instance from its most-recently seen state. This means that data for an inactive instance might continue to show a Ready status after the instance becomes inactive. Replicated recommends that you use the timestamp in the Last Check-in field to understand if an instance might have become inactive, causing its data to be out-of-date.

• Instance data freshness: The rate at which data is updated in the vendor portal varies depends on how often the vendor portal receives instance data from KOTS. The vendor portal receives instance data when any of the following occur:

  • The instance checks for updates. An update check can occur when a user clicks the Check for updates button in the Replicated admin console, or when the admin console runs an automatic update check. By default, the admin console runs automatic update checks every four hours. Users can modify or disable automatic update checks from the admin console. For more information, see Updating an Application in the Enterprise section.
  • The status of an instance changes. For example, an instance can change from a Ready to Degraded status.
  • (KOTS v1.92 and later only) The instance completes an update to a new application version.

• Event timestamps: The timestamp of events displayed on the Instances details page is the timestamp when the Replicated Vendor API received the instance data from KOTS. The timestamp of events does not necessarily reflect the timestamp of when the event occurred.

• Caching for kURL cluster data: For clusters created with Replicated kURL (embedded clusters), KOTS stores the counts of total nodes and ready nodes in a cache for five minutes. If KOTS sends instance data to the vendor portal within the five minute window, then the reported data for total nodes and ready nodes reflects the data in the cache. This means that events displayed on the Instances details page for the total nodes and ready nodes can show values that differ from the current values of these fields.

Types of Events

This section describes each type of event that the vendor portal generates for active application instances. Events in the vendor portal are grouped into the following categories:

• Application Installation and Upgrade Events
• Cluster Status Events
• Infrastructure Status Events
• KOTS Status Events
• Upstream Update Events

The tables in this section include the following details about each event type:

• Field Name: The fieldName associated with the event.
• Description: A description of the data field.
• Type: The data type of the field. Possible values are string, number, and boolean.
• Label: The label for the event that displays in the Instance Activity stream in the vendor portal Instance Details page. For more information, see Instance Activity in Viewing Instance Details.

Application Installation and Upgrade Events

Field Name	Description	Type	Label
appStatus	A string that represents the status of the application. Possible values: Ready, Updating, Degraded, Unavailable, Missing. For more information about how KOTS determines appStatus, see Resource Statuses in Viewing Status Details.	string	App Status
channelId	The ID of the channel the application instance is assigned.	string	App Channel
versionLabel	The version label of the release that the instance is currently running. The versionLabel is the version that you assigned to the release when promoting it to a channel.	string	App Version

Cluster Status Events

Field Name	Description	Type	Label
isKurl	Indicates if the cluster was provisioned by kURL. Possible values: kURL: The cluster is provisioned by kURL. Existing: The cluster is not provisioned by kURL. See Creating a Kubernetes Installer.	boolean	Cluster Type
k8sVersion	The version of Kubernetes running in the cluster.
k8sDistribution	The Kubernetes distribution of the cluster. Possible values: EKS GKE K3S RKE2	string	Kubernetes Distribution
kurlNodeCountTotal	Total number of nodes in the cluster. Note: Applies only to clusters provisioned by kURL.	number	kURL Nodes Total
kurlNodeCountReady	Number of nodes in the cluster that are in a healthy state and ready to run Pods. Note: Applies only to clusters provisioned by kURL.	number	kURL Nodes Ready
kurlInstallerSpecID	The ID of the Kubernetes installer specification that kURL used to provision the cluster. An installer specification is a manifest file that has apiVersion: cluster.kurl.sh/v1beta1 and kind: Installer. A kurlInstallerSpecID event indicates that a new Installer specification was added. See Creating a Kubernetes Installer. Note: Applies only to clusters provisioned by kURL.	string	New kURL Installer

Infrastructure Status Events

Field Name	Description	Type	Label
cloudProvider	The cloud provider where the instance is running. cloudProvider is determined by the IP address that makes the request. Possible values: AWS GCP DigitalOcean	string	Cloud Provider
cloudProviderRegion	The cloud provider region where the instance is running. For example, us-central1-b

KOTS Status Events

Field Name	Description	Type	Label
kotsVersion	The version of KOTS that the instance is running. KOTS version is displayed as a Semantic Versioning compliant string.	string	KOTS Version

Upstream Update Events

Field Name	Description	Type	Label
numberVersionsBehind	The number of versions between the version that the instance is currently running and the latest version available on the channel. The numberVersionsBehind metric is computed by the vendor portal each time KOTS sends instance data.	number	Versions Behind