Skip to main content

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:

For more information about the Replicated SDK API, see Replicated SDK API.

Limitation​

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

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​

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 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.

For the complete list of Replicated SDK Helm values, see the values.yaml file for the SDK Helm chart in GitHub.

note

The Replicated SDK replicated values are different from the global.replicated values that are injected by the Replicated registry during 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.

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.

# 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
  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.

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

# 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...