# About the Replicated SDK

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. You can distribute the Replicated SDK with your application by including it as a dependency of your parent Helm chart.

The Replicated SDK provides access to insights and operational telemetry for instances running in customer environments. You can use the Replicated SDK's in-cluster API to integrate key Replicated functionality with your application. For example:

* Collect custom metrics on instances running in online or air gap environments. See [Configure Custom Metrics](/vendor/custom-metrics).
* Check customer license entitlements. See [Query Entitlements with the Replicated SDK API](/vendor/licenses-reference-sdk) and [Verify 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_.
* Programmatically name or tag instances from the instance itself. See [Programatically Set Tags](/reference/replicated-sdk-apis#post-appinstance-tags).

For more information about the Replicated SDK API, see [Replicated SDK API](/reference/replicated-sdk-apis).
 
## 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 successive 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`.

## Replicated SDK Helm values

:::note
The Replicated SDK `replicated` values are different from the `global.replicated` values that are injected by the Replicated registry as part of Helm CLI installations. The `global.replicated` values are injected regardless of if the Replicated SDK is distributed alongside the application as dependency. For more information about the `global.replicated` values, see [Helm global.replicated Values Schema](/vendor/helm-install-values-schema).
:::

When a user installs a Helm chart that includes the Replicated SDK as a dependency, the SDK injects a set of `replicated` values in the parent chart's values file. These values include:
* Details about the given application release from the Vendor Portal, such as the version label, channel release sequence, and the release images.
* Details about the customer license, including the complete YAML representation of the customer license. For more information, see [Replicated SDK `replicated.license` Value](#replicated-sdk-replicatedlicense-value) on this page.
* Details about the SDK deployment, such as the Replicated SDK image location and properties, container resource requirements that control CPU and memory allocation, and the pod and container security context.
* Customizable settings for the SDK, such as RBAC settings, custom labels and annotations applied to the SDK Helm chart, and high availability (HA) deployment settings. For more information about how to customize the Replicated SDK, see [Customize the Replicated SDK](/vendor/replicated-sdk-customizing).

For the complete list of Replicated SDK Helm values, see the [`values.yaml`](https://github.com/replicatedhq/replicated-sdk/blob/main/chart/values.yaml) file for the SDK Helm chart in GitHub.

### Example

The following is an example of Replicated SDK `replicated` values for an application named NGINX that was installed in a cluster with Helm. These values are injected in the `values.yaml` file for the parent Helm chart of the NGINX application.

```yaml
# nginx parent Helm chart values.yaml file

replicated:
  affinity: null
  appID: ""
  appName: NGINX
  automountServiceAccountToken: false
  channelID: 38FsA8b1C8LP6Ifzql89MGXYGwx
  channelName: Unstable
  channelSequence: 5
  clusterRole: ""
  commonAnnotations: {}
  commonLabels: {}
  isAirgap: false
  # ... several additional values ommitted for brevity
  readOnlyMode: false
  reportAllImages: false
  resources:
    limits:
      cpu: 500m
      memory: 500Mi
    requests:
      cpu: 100m
      memory: 100Mi
  restartPolicy: Always
  schedulerName: ""
  service:
    port: 3000
    type: ClusterIP
  serviceAccountName: ""
  statusInformers: null
  terminationGracePeriodSeconds: 30
  tlsCertSecretName: ""
  tolerations: []
  topologySpreadConstraints: []
  versionLabel: 0.0.2
```

### Replicated SDK `replicated.license` value

The Replicated SDK includes a `replicated.license` value that contains a YAML representation of the customer license. For more information about the built-in fields included in all Replicated licenses, see [Built-In License Fields](/vendor/licenses-using-builtin-fields).

The following shows an example of the `replicated.license` value for a customer named Nitflex:

```yaml
# nginx parent Helm chart values.yaml file

replicated:
  # YAML representation of the customer's license
  license: |
    apiVersion: kots.io/v1beta1
    kind: License
    metadata:
        name: nitflex
    spec:
      appSlug: nginx-shark
      channelID: 38FsA8b1C8LP6Ifzql89MGXYGwx
      channelName: Unstable
      channels:
        - channelID: 38FsA8b1C8LP6Ifzql89MGXYGwx
          channelName: Unstable
          channelSlug: unstable
          endpoint: https://replicated.app
          isDefault: true
          isSemverRequired: true
          replicatedProxyDomain: proxy.replicated.com
      customerEmail: paige@replicated.com
      customerName: Nitflex
      endpoint: https://replicated.app
      entitlements:
        activeUsers:
          signature:
            v1: eyJsaWNlbnNlRGF0Y...
          title: Active Users
          value: 25
          valueType: Integer
        expires_at:
          description: License Expiration
          signature:
            v1: eyJsaWNlbnNlRGF0Y...
          title: Expiration
          value: ""
          valueType: String
      isAirgapSupported: true
      isEmbeddedClusterDownloadEnabled: true
      isSemverRequired: true
      isSupportBundleUploadSupported: true
      licenseID: 38FtQgjZqjRFAxUnVJXGrlGi2X7
      licenseSequence: 4
      licenseType: dev
      replicatedProxyDomain: proxy.replicated.com
      signature: eyJsaWNlbnNlRGF0Y...
```