Merge pull request #3009 from replicatedhq/dx/sc-118600/add-replicated-values-schema

paigecalvert · web-flow · commit 664d30f76962 · 2025-02-14T12:50:50.000-07:00
feat(sdk): add Replicated Helm Install values schema
diff --git a/docs/partials/helm/_helm-diagram-overview.mdx b/docs/partials/helm/_helm-diagram-overview.mdx
diff --git a/docs/partials/replicated-sdk/_sdk-values.mdx b/docs/partials/replicated-sdk/_sdk-values.mdx
@@ -0,0 +1,29 @@
+When a user installs a Helm chart that includes the Replicated SDK as a dependency, a set of default SDK values are included in the `replicated` key of the parent chart's values file.
+
+For example:
+
+```yaml
+# values.yaml 
+
+replicated:
+  enabled: true
+  appName: gitea
+  channelID: 2jKkegBMseH5w...
+  channelName: Beta
+  channelSequence: 33
+  integration:
+    enabled: true
+  license: {}
+  parentChartURL: oci://registry.replicated.com/gitea/beta/gitea
+  releaseCreatedAt: "2024-11-25T20:38:22Z"
+  releaseNotes: 'CLI release'
+  releaseSequence: 88
+  replicatedAppEndpoint: https://replicated.app
+  versionLabel: Beta-1234
+```
+
+These `replicated` values can be referenced by the application or set during installation as needed. For example, if users need to add labels or annotations to everything that runs in their cluster, then they can pass the labels or annotations to the relevant value in the SDK subchart.
+
+For the default Replicated SDK Helm chart values file, see [values.yaml.tmpl](https://github.com/replicatedhq/replicated-sdk/blob/main/chart/values.yaml.tmpl) in the [replicated-sdk](https://github.com/replicatedhq/replicated-sdk) repository in GitHub.
+
+The SDK Helm values also include a `replicated.license` field, which is a string that contains the YAML representation of the customer license. For more information about the built-in fields in customer licenses, see [Built-In License Fields](licenses-using-builtin-fields).
diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx
@@ -50,6 +50,7 @@ To enable the proxy registry:
    ```yaml
    # values.yaml
    ...
+   dockerconfigjson: '{{ .Values.global.replicated.dockerconfigjson }}'
    images:
      myapp:
        # Add image URL in the values file
diff --git a/docs/vendor/helm-install-overview.mdx b/docs/vendor/helm-install-overview.mdx
@@ -1,4 +1,3 @@
-import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx"
 import Helm from "../partials/helm/_helm-definition.mdx"
 
 # About Helm Installations with Replicated
@@ -13,48 +12,23 @@ Replicated strongly recommends that all applications are packaged using Helm bec
 
 Existing releases in the Replicated Platform that already support installation with Replicated KOTS and Replicated Embedded Cluster (and that include one or more Helm charts) can also be installed with the Helm CLI; it is not necessary to create and manage separate releases or channels for each installation method.
 
+For information about how to install with Helm, see:
+* [Installing with Helm](/vendor/install-with-helm)
+* [Installing and Updating with Helm in Air Gap Environments (Alpha)](helm-install-airgap)
+
 The following diagram shows how Helm charts distributed with Replicated are installed with Helm in online (internet-connected) customer environments:
 
 <img src="/images/helm-install-diagram.png" alt="diagram of a helm chart in a custom environment" width="700px"/> 
 
 [View a larger version of this image](/images/helm-install-diagram.png)
 
-<HelmDiagramOverview/>
+As shown in the diagram above, when a release containing one or more Helm charts is promoted to a channel, the Replicated Vendor Portal automatically extracts any Helm charts included in the release. These charts are pushed as OCI objects to the Replicated registry. The Replicated registry is a private OCI registry hosted by Replicated at `registry.replicated.com`. For information about security for the Replicated registry, see [Replicated Registry Security](packaging-private-registry-security).
 
-For information about how to install with Helm, see:
-* [Installing with Helm](/vendor/install-with-helm)
-* [Installing and Updating with Helm in Air Gap Environments (Alpha)](helm-install-airgap)
+For example, if your application in the Vendor Portal is named My App and you promote a release containing a Helm chart with `name: my-chart` to a channel with the slug `beta`, then the Vendor Portal pushes the chart to the following location: `oci://registry.replicated.com/my-app/beta/my-chart`.
+
+Customers can install your Helm chart by first logging in to the Replicated registry with their unique license ID. This step ensures that any customer who installs your chart from the registry has a valid, unexpired license. After the customer logs in to the Replicated registry, they can run `helm install` to install the chart from the registry.
 
-## About the `global.replicated` Helm Values
-
-When a customer installs your Helm chart from the Replicated registry, the Replicated registry injects values into the `global.replicated` field of the Helm chart values file.
-
-The following is an example of a Helm values file containing the `global.replicated` field injected by the Replicated registry:
-
-```yaml
-# Helm values.yaml
-global:
-  replicated:
-    channelName: Stable
-    customerEmail: username@example.com
-    customerName: Example Customer
-    dockerconfigjson: eyJhdXRocyI6eyJd1dIRk5NbEZFVGsxd2JGUmFhWGxYWm5scloyNVRSV1pPT2pKT2NGaHhUVEpSUkU1...
-    licenseFields:
-      expires_at:
-        description: License Expiration
-        name: expires_at
-        signature:
-          v1: iZBpESXx7fpdtnbMKingYHiJH42rP8fPs0x8izy1mODckGBwVoA... 
-        title: Expiration
-        value: "2023-05-30T00:00:00Z"
-        valueType: String
-    licenseID: YiIXRTjiB7R...
-    licenseType: dev
-```
-
-The values in the `global.replicated` field provide information about the following:
-* Details about the fields in the customer's license, such as the field name, description, signature, value, and any custom license fields that you define. You can use this license information to check license entitlments before the application is installed. For more information, see [Checking Entitlements in Helm Charts Before Deployment](/vendor/licenses-reference-helm).
-* A base64 encoded Docker configuration file. To proxy images from an external private registry with the Replicated proxy registry, you can use the `global.replicated.dockerconfigjson` field to create an image pull secret for the proxy registry. For more information, see [Proxying Images for Helm Installations](/vendor/helm-image-registry). 
+During installation, the Replicated registry injects values into the `global.replicated` key of the parent Helm chart's values file. For more information about the values schema, see [Helm global.replicated Values Schema](helm-install-values-schema).
 
 ## Limitations
 
diff --git a/docs/vendor/helm-install-values-schema.mdx b/docs/vendor/helm-install-values-schema.mdx
@@ -0,0 +1,61 @@
+import SdkValues from "../partials/replicated-sdk/_sdk-values.mdx"
+
+# Helm global.replicated Values Schema
+
+This topic describes the `global.replicated` values that are injected in the values file of an application's parent Helm chart during Helm installations with Replicated.
+
+## Overview
+
+When a user installs a Helm application with the Helm CLI, the Replicated registry injects a set of customer-specific values into the `global.replicated` key of the parent Helm chart's values file.
+
+The values in the `global.replicated` field include the following:
+
+* The fields in the customer's license, such as the field names, descriptions, signatures, values, and any custom license fields that you define. Vendors can use this license information to check entitlements before the application is installed. For more information, see [Checking Entitlements in Helm Charts Before Deployment](/vendor/licenses-reference-helm).
+
+* A base64 encoded Docker configuration file. To proxy images from an external private registry with the Replicated proxy registry, you can use the `global.replicated.dockerconfigjson` field to create an image pull secret for the proxy registry. For more information, see [Proxying Images for Helm Installations](/vendor/helm-image-registry).
+
+The following is an example of a Helm values file containing the `global.replicated` values:
+
+```yaml
+# Helm values.yaml
+global:
+  replicated:
+    channelName: Stable
+    customerEmail: username@example.com
+    customerName: Example Customer
+    dockerconfigjson: eyJhdXRocyI6eyJd1dIRk5NbEZFVGsxd2JGUmFhWGxYWm5scloyNVRSV1pPT2pKT2NGaHhUVEpSUkU1...
+    licenseFields:
+      expires_at:
+        description: License Expiration
+        name: expires_at
+        signature:
+          v1: iZBpESXx7fpdtnbMKingYHiJH42rP8fPs0x8izy1mODckGBwVoA... 
+        title: Expiration
+        value: "2023-05-30T00:00:00Z"
+        valueType: String
+    licenseID: YiIXRTjiB7R...
+    licenseType: dev
+```
+
+## `global.replicated` Values Schema
+
+The `global.replicated` values schema contains the following fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `channelName` | String | The name of the release channel |
+| `customerEmail` | String | The email address of the customer |
+| `customerName` | String | The name of the customer |
+| `dockerconfigjson` | String | Base64 encoded docker config json for pulling images |
+| `licenseFields`| | A list containing each license field in the customer's license. Each element under `licenseFields` has the following properties: `description`, `signature`, `title`, `value`, `valueType`. `expires_at` is the default `licenseField` that all licenses include. Other elements under `licenseField` include the custom license fields added by vendors in the Vendor Portal. For more information, see [Managing Customer License Fields](/vendor/licenses-adding-custom-fields). |
+| `licenseFields.[FIELD_NAME].description` | String | Description of the license field |
+| `licenseFields.[FIELD_NAME].signature.v1` | Object | Signature of the license field |
+| `licenseFields.[FIELD_NAME].title` | String | Title of the license field |
+| `licenseFields.[FIELD_NAME].value` | String | Value of the license field |
+| `licenseFields.[FIELD_NAME].valueType` | String | Type of the license field value |
+| `licenseID` | String | The unique identifier for the license |
+| `licenseType` | String | The type of license, such as "dev" or "prod". For more information, see [Customer Types](/vendor/licenses-about#customer-types) in _About Customers and Licensing_. |
+
+## Replicated SDK Helm Values
+
+<SdkValues/>
diff --git a/docs/vendor/licenses-using-builtin-fields.mdx b/docs/vendor/licenses-using-builtin-fields.mdx
@@ -10,6 +10,47 @@ The license associated with each customer record in the Replicated Vendor Portal
 
 When a customer installs an application distributed with Replicated, the values for each built-in and custom field in their license can be accessed using the [Replicated SDK](/vendor/replicated-sdk-overview) in-cluster API [license](/reference/replicated-sdk-apis#license) endpoints. Applications installed with a Replicated installer (KOTS, kURL, Embedded Cluster) can also access license fields using the Replicated KOTS [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) template function.
 
+The following shows an example of a customer license:
+
+```yaml
+apiVersion: kots.io/v1beta1
+kind: License
+metadata:
+  name: customertest
+spec:
+  appSlug: gitea
+  channelID: 2iy68JBTkvUqamgD...
+  channelName: Beta
+  channels:
+  - channelID: 2iy68JBTkvUqamgD...
+    channelName: Beta
+    channelSlug: beta
+    endpoint: https://replicated.app
+    isDefault: true
+    isSemverRequired: true
+    replicatedProxyDomain: proxy.replicated.com
+  customerEmail: example@replicated.com
+  customerName: Customer Test
+  endpoint: https://replicated.app
+  entitlements:
+    expires_at:
+      description: License Expiration
+      signature: {}
+      title: Expiration
+      value: ""
+      valueType: String
+  isAirgapSupported: true
+  isEmbeddedClusterDownloadEnabled: true
+  isKotsInstallEnabled: true
+  isSemverRequired: true
+  isSupportBundleUploadSupported: true
+  licenseID: 2sY6ZC2J9sO2...
+  licenseSequence: 4
+  licenseType: prod
+  replicatedProxyDomain: proxy.replicated.com
+  signature: eyJsaWNlbnNlRGF...
+```
+
 ## License Field Names
 
 This section lists the built-in fields that are included in customer licenses for applications distributed with Replicated.
diff --git a/docs/vendor/replicated-sdk-overview.mdx b/docs/vendor/replicated-sdk-overview.mdx
@@ -1,6 +1,5 @@
 import SDKOverview from "../partials/replicated-sdk/_overview.mdx"
-import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx"
-import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx"
+import SdkValues from "../partials/replicated-sdk/_sdk-values.mdx"
 
 # About the Replicated SDK
 
@@ -29,3 +28,7 @@ At startup and when serving requests, the SDK retrieves and caches the latest in
 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
+
+<SdkValues/>
diff --git a/docs/vendor/replicated-sdk-slsa-validating.md b/docs/vendor/replicated-sdk-slsa-validating.md
@@ -1,7 +1,3 @@
-import SDKOverview from "../partials/replicated-sdk/_overview.mdx"
-import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx"
-import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx"
-
 # SLSA Provenance Validation Process for the Replicated SDK
 
 This topic describes the process to perform provenance validation on the Replicated SDK.
diff --git a/sidebars.js b/sidebars.js
@@ -506,6 +506,7 @@ const sidebars = {
     label: 'Helm Installations with Replicated',
     items: [
       'vendor/helm-install-overview',
+      'vendor/helm-install-values-schema',
       'vendor/install-with-helm',
       'vendor/helm-install-airgap',
       'vendor/using-third-party-registry-proxy',
