Merge pull request #2370 from replicatedhq/clarify-sdk-for-granular-a…

…pp-status

Add note about Replicated SDK requirement for granular resource status details

docs/partials/replicated-sdk/_overview.mdx

@@ -4,9 +4,10 @@ For information about how to distribute and install the SDK with your applicatio
 
 Replicated recommends that the SDK is distributed with all applications because it provides access to key Replicated functionality, such as:
 
-* Automatic access to insights and operational telemetry for instances running in customer environments. For more information, see [About Instance and Event Data](/vendor/instance-insights-event-data).
+* Automatic access to insights and operational telemetry for instances running in customer environments, including granular details about the status of different application resources. For more information, see [About Instance and Event Data](/vendor/instance-insights-event-data).
 * An in-cluster API that you can use to embed Replicated features into your application, including:
   * Collect custom metrics on instances running in online or air gap environments. See [Configuring Custom Metrics](/vendor/custom-metrics).
   * Check customer license entitlements at runtime. See [Querying Entitlements with the Replicated SDK API](/vendor/licenses-reference-sdk) and [Verifying License Field Signatures with the Replicated SDK API](/vendor/licenses-verify-fields-sdk-api). 
+  * Provide update checks to alert customers when new versions of your application are available for upgrade. See [Support Update Checks in Your Application](/reference/replicated-sdk-apis#support-update-checks-in-your-application) in _Replicated SDK API_.
   * Provide update checks to alert customers when new versions of your application are available for upgrade. See [Support Update Checks in Your Application](/reference/replicated-sdk-apis#support-update-checks-in-your-application) in _Replicated SDK API (Beta)_.
-  * Programatically name or tag instances from the instance itself. See [Programatically Set Tags](/reference/replicated-sdk-apis#post-appinstance-tags). 
+  * Programatically name or tag instances from the instance itself. See [Programatically Set Tags](/reference/replicated-sdk-apis#post-appinstance-tags). 

docs/vendor/insights-app-status.md

@@ -27,9 +27,9 @@ To enable status informers for your application, do one of the following, depend
 
 ### Helm Installations 
 
-To get instance status data for applications installed with Helm, include the Replicated SDK as a dependency of your application. For information about how to distribute the SDK with your application, see [About the Replicated SDK](replicated-sdk-overview).
+To get instance status data for applications installed with Helm, the Replicated SDK must be installed alongside the application. For information about how to distribute and install the SDK with your application, see [Installing the Replicated SDK](/vendor/replicated-sdk-installing).
 
-After you include the SDK as a dependency, the requirements for enabling status informers vary depending on how your Helm chart-based application is installed:
+After you include the SDK as a dependency, the requirements for enabling status informers vary depending on how your application is installed:
 
 * For applications installed by running `helm install` or `helm upgrade`, the Replicated SDK automatically detects and reports the status of the resources that are part of the Helm release. No additional configuration is required to get instance status data.
 
@@ -50,15 +50,27 @@ After you include the SDK as a dependency, the requirements for enabling status
 
 ### KOTS Installations
 
-For applications installed with Replicated KOTS, configure one or more status informers in the Replicated Application custom resource. For more information, see [Add Status Informers](admin-console-display-app-status#add-status-informers) in _Adding Resource Status Informers_.
+For applications installed with Replicated KOTS, configure one or more status informers in the KOTS Application custom resource. For more information, see [Adding Resource Status Informers](admin-console-display-app-status).
 
-When Helm chart-based applications that include the Replicated SDK are deployed by KOTS, the SDK inherits the KOTS status informers configured in the Application custom resource. In this case, the SDK does _not_ automatically report the status of the resources that are part of the Helm release. This prevents discrepancies in the instance data in the vendor platform.
+When Helm-based applications that include the Replicated SDK and are deployed by KOTS, the SDK inherits the status informers configured in the KOTS Application custom resource. In this case, the SDK does _not_ automatically report the status of the resources that are part of the Helm release. This prevents discrepancies in the instance data in the vendor platform.
+
+## View Resource Status Insights {#resource-status}
+
+For applications that include the Replicated SDK, the vendor portal also displays granular resource status insights in addition to the aggregate application status. For example, you can hover over the **App status** field on the **Instance details** page to view the statuses of the indiviudal resources deployed by the application, as shown below:
+
+<img src="/images/resource-status-hover-current-state.png" alt="resource status pop up" width="400px"/>
+
+[View a larger version of this image](/images/resource-status-hover-current-state.png)
+
+Viewing these resource status details is helpful for understanding which resources are contributing to the aggregate application status. For example, when an application has an Unavailable status, that means that one or more resources are Unavailable. By viewing the resource status insights on the **Instance details** page, you can quickly understand which resource or resources are Unavailable for the purpose of troubleshooting.
+
+Granular resource status details are automatically available when the Replicated SDK is installed alongside the application. For information about how to distribute and install the SDK with your application, see [Installing the Replicated SDK](/vendor/replicated-sdk-installing).
 
 ## Understanding Application Status
 
 This section provides information about how Replicated interprets and aggregates the status of Kubernetes resources for your application to report an application status.
 
-### Resource Statuses
+### About Resource Statuses {#resource-statuses}
 
 Possible resource statuses are Ready, Updating, Degraded, Unavailable, and Missing.
 

docs/vendor/instance-insights-details.md

@@ -39,9 +39,9 @@ As shown in the image above, the **Instance details** page includes the followin
 
 The **Current State** section displays the following event data about the status and version of the instance:
 
-* **App status**: The status of the application. Possible statuses are Ready, Updating, Degraded, Unavailable, and Missing. Hover over the **App status** field to view the statuses of the indiviudal resources deployed by the application. For more information about enabling the **App status** field, see [Enabling and Understanding Application Status](insights-app-status).
+* **App status**: The status of the application. Possible statuses are Ready, Updating, Degraded, Unavailable, and Missing. For more information about enabling application status insights and how to interpret the different statuses, see [Enabling and Understanding Application Status](insights-app-status).
 
-    The following image shows an example of the granular resource status view that is displayed on hover:
+    Additionally, for applications that include the [Replicated SDK](/vendor/replicated-sdk-overview), you can hover over the **App status** field to view the statuses of the indiviudal resources deployed by the application, as shown in the example below:
 
     <img src="/images/resource-status-hover-current-state.png" alt="resource status pop up" width="400px"/>
 
@@ -232,8 +232,8 @@ The following tables describe the events that can be displayed in the **Instance
   <tr>
     <td>App Status</td>
     <td>
-      <p>A string that represents the status of the application. Possible values: Ready, Updating, Degraded, Unavailable, Missing. Hover to view the statuses of the indiviudal resources deployed by the application.</p>
-      <p>Additional configuration is required to get app status data. See <a href="insights-app-status">Enabling and Understanding Application Status</a>.</p>
+      <p>A string that represents the status of the application. Possible values: Ready, Updating, Degraded, Unavailable, Missing. For applications that include the <a href="/vendor/replicated-sdk-overview">Replicated SDK</a>, hover over the application status to view the statuses of the indiviudal resources deployed by the application.</p>
+      <p>For more information, see <a href="insights-app-status">Enabling and Understanding Application Status</a>.</p>
     </td>
   </tr>
 </table>

docs/vendor/instance-insights-event-data.mdx

@@ -78,12 +78,14 @@ The vendor portal uses events to display insights for each active instance in a
 
 ## Requirements
 
-The following requirements apply to collecting telemetry for online instances:
+The following requirements apply to collecting instance telemetry:
 
 * Replicated KOTS or the Replicated SDK must be installed in the cluster where the application instance is running. 
 
 * For KOTS installations and for Helm CLI installations that use `helm template` then `kubectl apply`, additional configuration is required to get application status data. For more information, see [Enabling and Understanding Application Status](/vendor/insights-app-status).
 
+* To view resource status details for an instance on the **Instance details** page, the Replicated SDK must be installed in the cluster alongside the application. For more information, see [View Resource Status Insights](insights-app-status#resource-status) in _Enabling and Understanding Application Status_.
+
 * There are additional requirements for collecting telemetry from air gap instances. For more information, see [Collecting Telemetry for Air Gap Instances](/vendor/telemetry-air-gap).
 
 ## Limitations