About the Replicated SDK (Beta)

This topic provides an introduction to using the Replicated SDK with your application.

Overview

The Replicated SDK is a Helm chart that can be installed as a small service alongside your application. The SDK can be installed alongside applications packaged as Helm charts or Kubernetes manifests. The SDK can be installed using the Helm CLI or KOTS.

For information about how to distribute and install the SDK with your application, see Installing the Replicated SDK.

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, including granular details about the status of different application resources. For more information, see About Instance and 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.
  • Check customer license entitlements at runtime. See Querying Entitlements with the Replicated SDK API and Verifying License Field Signatures with the 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 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 in Replicated SDK API (Beta).
  • Programatically name or tag instances from the instance itself. See Programatically Set Tags.

For more information about the Replicated SDK API, see Replicated SDK API (Beta). For information about developing against the SDK API locally, see Developing Against the SDK API (Beta).

Limitations

The Replicated SDK has the following limitations:

• Some popular enterprise continuous delivery tools, such as ArgoCD and Pulumi, deploy Helm charts by running helm template then kubectl apply on the generated manifests, rather than running helm install or helm upgrade. The following limitations apply to applications installed by running helm template then kubectl apply:

  • The /api/v1/app/history SDK API endpoint always returns an empty array because there is no Helm history in the cluster. See GET /app/history in Replicated SDK API (Beta).

  • The SDK does not automatically generate status informers to report status data for installed instances of the application. To get instance status data, you must enable custom status informers by overriding the replicated.statusInformers Helm value. See Enable Application Status Insights in Enabling and Understanding Application Status.

• When installing a KOTS application that includes the SDK, license field titles with special YAML characters like question marks (?) can lead to errors during application release downloads. To avoid this issue, use only alphanumeric characters in license field titles when including the SDK in a KOTS application.

SDK Resiliency

At startup and when serving requests, the SDK retrieves and caches the latest information from the upstream Replicated APIs, including customer license information.

If the upstream APIs are not available at startup, the SDK does not accept connections or serve requests until it is able to communicate with the upstream APIs. If communication fails, the SDK retries every 10 seconds and the SDK pod is at 0/1 ready.

When serving requests, if the upstream APIs become unavailable, the SDK serves from the memory cache and sets the X-Replicated-Served-From-Cache header to true. Additionally, rapid sucessive requests to same SDK endpoint with the same request properties will be rate-limited returning the last cached payload and status code without reaching out to the upstream APIs. A X-Replicated-Rate-Limited header will set to true.