From 221f6c1b1fb77b0b452193d337377d0d9f284310 Mon Sep 17 00:00:00 2001 From: Dexter Yan Date: Tue, 28 Jan 2025 16:00:57 +1300 Subject: [PATCH 01/11] feat(sdk): add values schema --- docs/vendor/replicated-sdk-values-schema.md | 23 +++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/vendor/replicated-sdk-values-schema.md diff --git a/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md new file mode 100644 index 0000000000..d8e9ee5c12 --- /dev/null +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -0,0 +1,23 @@ + +import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx" +import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" + +# Helm global.replicated Values Schema + +This document describes the global.replicated values schema injected by the Replicated registry when using the Helm CLI installation method. It includes information on the structure and purpose of fields to help developers integrate seamlessly with the Replicated SDK. + +## Overview + +The `global.replicated` values schema is a set of values that are injected by the Replicated registry when using the Helm CLI installation method. These values are used by the Replicated SDK to provide information about the replicated application and the environment in which it is running. These values are critical for licensing, release management, and enabling key features of the Replicated Vendor Portal. + +For additional information about the Replicated SDK, see [Replicated SDK Overview](/vendor/replicated-sdk-overview). + +## Values Schema Structure + +The `global.replicated` values schema is a set of values that are injected by the Replicated registry when using the Helm CLI installation method. The schema is a JSON object that contains the following fields: + +| Field | Type | Description | +| --- | --- | --- | +| `imagePullSecrets` | Array | An array of Kubernetes image pull secrets that are used to pull images from private registries. | +| `appName` | String | The name of the application, as specified in the Replicated Vendor Portal. | +| `channelID` | String | The unique ID of the release channel. | From 31b89104677fd8c401e0e6399e16586213b7b022 Mon Sep 17 00:00:00 2001 From: Dexter Yan Date: Tue, 28 Jan 2025 16:13:01 +1300 Subject: [PATCH 02/11] feat(sdk): update values schema --- docs/vendor/replicated-sdk-values-schema.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md index d8e9ee5c12..64b5aa5f25 100644 --- a/docs/vendor/replicated-sdk-values-schema.md +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -21,3 +21,11 @@ The `global.replicated` values schema is a set of values that are injected by th | `imagePullSecrets` | Array | An array of Kubernetes image pull secrets that are used to pull images from private registries. | | `appName` | String | The name of the application, as specified in the Replicated Vendor Portal. | | `channelID` | String | The unique ID of the release channel. | +| `channelName` | String | The name of the release channel (e.g., “Stable”, “Beta”). | +| `channelSequence` | Integer | The sequence number of the channel, sed to track updates in channel. | +| `releaseSequence` | Integer | The sequence number of the release associated with this deployment. | +| `releaseCreatedAt` | String | The timestamp when the release was created. | +| `releaseNotes` | String | Release notes for the current release, as provided in the Vendor Portal. | +| `versionLabel` | String | The version label for the release, often displayed in UI dashboards. | +| `parentChartURL` | String | The URL of the parent Helm chart if the application is nested in a chart hierarchy. | +| `statusInformers` | map | Configuration for custom status informers. Used for application health and status insights. | From 13118b27365b44a1bb84dc42aa3a9b37e9f1b8f9 Mon Sep 17 00:00:00 2001 From: Dexter Yan Date: Wed, 29 Jan 2025 16:26:21 +1300 Subject: [PATCH 03/11] feat(sdk): update values schema --- docs/vendor/replicated-sdk-values-schema.md | 42 ++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md index 64b5aa5f25..5b2899251e 100644 --- a/docs/vendor/replicated-sdk-values-schema.md +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -18,7 +18,13 @@ The `global.replicated` values schema is a set of values that are injected by th | Field | Type | Description | | --- | --- | --- | -| `imagePullSecrets` | Array | An array of Kubernetes image pull secrets that are used to pull images from private registries. | +| `global.imageRegistry` | String | The URL of the image registry where the replicated-sdk images are stored. | +| `image.registry` | String | The URL of the image registry where the replicated-sdk images are stored. | +| `image.repository` | String | The name of the replicated/replicated-sdk image repository. | +| `image.tag` | String | The tag of the replicated/replicated-sdk image. | +| `image.pullPolicy` | String | The Kubernetes image pull policy for the replicated/replicated-sdk image. | +| `license` | String | The license ID of customer. | +| `licenseFields` | string | The license fields of the customer. | | `appName` | String | The name of the application, as specified in the Replicated Vendor Portal. | | `channelID` | String | The unique ID of the release channel. | | `channelName` | String | The name of the release channel (e.g., “Stable”, “Beta”). | @@ -29,3 +35,37 @@ The `global.replicated` values schema is a set of values that are injected by th | `versionLabel` | String | The version label for the release, often displayed in UI dashboards. | | `parentChartURL` | String | The URL of the parent Helm chart if the application is nested in a chart hierarchy. | | `statusInformers` | map | Configuration for custom status informers. Used for application health and status insights. | +| `replicatedAppEndpoint` | String | If it is not using the default Replicated App endpoint https://replicated.app, this field specifies the endpoint to use. | +| `serviceAccountName` | String | The name of the Kubernetes service account used by the Replicated SDK. | +| `clusterRole` | String | The name of the Kubernetes cluster role used by the Replicated SDK. | +| `imagePullSecrets` | Array | An array of Kubernetes image pull secrets that are used to pull images from private registries. | +| `nameOverride` | String | Overrides the name of the chart. | +| `namespaceOverride` | String | Overrides the namespace of the chart. | +| `containerSecurityContext.enabled` | Boolean | Enables the security context for the container. | +| `containerSecurityContext.runAsNonRoot`| Boolean | Runs the container as a non-root user. | +| `containerSecurityContext.readOnlyRootFilesystem` | Boolean | Mounts the container’s root filesystem as read-only. | +| `containerSecurityContext.allowPrivilegeEscalation` | Boolean | Allows privilege escalation for the container. | +| `containerSecurityContext.capabilities.drop` | Array | Define which capabilities for dropping. | +| `podSecurityContext.enabled` | Boolean | Enables the security context for the pod. | +| `podSecurityContext.runAsUser` | Integer | The user ID for the pod. | +| `podSecurityContext.runAsGroup` | Integer | The group ID for the pod. | +| `podSecurityContext.fsGroup` | Integer | The group ID for the pod’s filesystem. | +| `podSecurityContext.supplementalGroups` | Array | The supplemental groups for the pod. | +| `podSecurityContext.seccompProfile.type` | String | The type of seccomp profile. | +| `service.type` | String | The replicated-sdk service type. | +| `service.port` | Integer | The port for the replicated-sdk service. | +| `privateCAConfigmap` | String | The name of the ConfigMap that contains the private CA certificate. | +| `privateCASecret` | String | The name of the Secret that contains the private CA certificate. | +| `extraEnv` | Array | Additional environment variables to inject into the container. | +| `integration.licenseID` | String | The license ID of the customer. | +| `integration.enabled` | Boolean | Enables the integration. | +| `integration.mockData` | string | The mock data for the integration. | +| `isAirgap` | Boolean | Indicates whether the replicated is installed in airgap environment. | +| `replicatedID` | String | The unique ID of the replicated-sdk instance cluster ID. | +| `appID` | String | The unique ID of the replicated app slug. | +| `tolerations` | Array | The tolerations for the pod. | +| `affinity` | Object | The affinity for the pod. | + + +## Using Replicated Registry Values +With the Replicated proxy registry, each customer’s license information is injected into the application’s environment and grant proxy access to images in an external private registry. From c1c55eef33ef176ffd9a986908dd021f094769ce Mon Sep 17 00:00:00 2001 From: Dexter Yan Date: Wed, 29 Jan 2025 17:26:27 +1300 Subject: [PATCH 04/11] feat(sdk): update values schema --- docs/vendor/replicated-sdk-values-schema.md | 32 +++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md index 5b2899251e..d97e4a83e0 100644 --- a/docs/vendor/replicated-sdk-values-schema.md +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -69,3 +69,35 @@ The `global.replicated` values schema is a set of values that are injected by th ## Using Replicated Registry Values With the Replicated proxy registry, each customer’s license information is injected into the application’s environment and grant proxy access to images in an external private registry. +To use the Replicated registry values, you must first configure the Replicated proxy registry in your Kubernetes cluster. For more information, see [Replicated Proxy Registry](/vendor/replicated-proxy-registry). + +Here is an example of how to use the `global.replicated` values schema in your application: + +```yaml +dockerconfigjson: '{{ .Values.global.replicated.dockerconfigjson }}' +images: + myapp: + # Add image URL in the values file + apiImageRepository: proxy.replicated.com/proxy/my-app/quay.io/my-org/api + apiImageTag: v1.0.1 +``` +In your deployment manifest, you can reference the `global.replicated` values schema to access the license information and other values injected by the Replicated registry. +```yaml +# /templates/deployment.yaml + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + template: + spec: + containers: + - name: api + # Access the apiImageRepository field from the values file + image: "{{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}" + {{ if .Values.global.replicated.dockerconfigjson }} + imagePullSecrets: + - name: replicated-pull-secret + {{ end }} +``` From cda1da2a102a4cc542bc24d5d5357212a1388865 Mon Sep 17 00:00:00 2001 From: Dexter Yan Date: Mon, 3 Feb 2025 16:31:05 +1300 Subject: [PATCH 05/11] update --- docs/vendor/helm-image-registry.mdx | 1 + docs/vendor/replicated-sdk-values-schema.md | 76 ++++++++++++--------- 2 files changed, 43 insertions(+), 34 deletions(-) diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index 866dea5ac7..81980775e0 100644 --- 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/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md index d97e4a83e0..4edf902e0b 100644 --- a/docs/vendor/replicated-sdk-values-schema.md +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -1,7 +1,3 @@ - -import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx" -import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" - # Helm global.replicated Values Schema This document describes the global.replicated values schema injected by the Replicated registry when using the Helm CLI installation method. It includes information on the structure and purpose of fields to help developers integrate seamlessly with the Replicated SDK. @@ -23,7 +19,7 @@ The `global.replicated` values schema is a set of values that are injected by th | `image.repository` | String | The name of the replicated/replicated-sdk image repository. | | `image.tag` | String | The tag of the replicated/replicated-sdk image. | | `image.pullPolicy` | String | The Kubernetes image pull policy for the replicated/replicated-sdk image. | -| `license` | String | The license ID of customer. | +| `license` | String | The yaml representation of the customer license. | | `licenseFields` | string | The license fields of the customer. | | `appName` | String | The name of the application, as specified in the Replicated Vendor Portal. | | `channelID` | String | The unique ID of the release channel. | @@ -66,38 +62,50 @@ The `global.replicated` values schema is a set of values that are injected by th | `tolerations` | Array | The tolerations for the pod. | | `affinity` | Object | The affinity for the pod. | +## license Values Schema -## Using Replicated Registry Values -With the Replicated proxy registry, each customer’s license information is injected into the application’s environment and grant proxy access to images in an external private registry. -To use the Replicated registry values, you must first configure the Replicated proxy registry in your Kubernetes cluster. For more information, see [Replicated Proxy Registry](/vendor/replicated-proxy-registry). - -Here is an example of how to use the `global.replicated` values schema in your application: +The `license` field in the `global.replicated` values schema is a string that contains the YAML representation of the customer license. The license schema is a yaml object that contains the following fields: ```yaml -dockerconfigjson: '{{ .Values.global.replicated.dockerconfigjson }}' -images: - myapp: - # Add image URL in the values file - apiImageRepository: proxy.replicated.com/proxy/my-app/quay.io/my-org/api - apiImageTag: v1.0.1 -``` -In your deployment manifest, you can reference the `global.replicated` values schema to access the license information and other values injected by the Replicated registry. -```yaml -# /templates/deployment.yaml - -apiVersion: apps/v1 -kind: Deployment +apiVersion: kots.io/v1beta1 +kind: License metadata: - name: example + name: name of the license spec: - template: - spec: - containers: - - name: api - # Access the apiImageRepository field from the values file - image: "{{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}" - {{ if .Values.global.replicated.dockerconfigjson }} - imagePullSecrets: - - name: replicated-pull-secret - {{ end }} + appSlug: The unique application slug that the customer is associated with. This value never changes. + channelID: The ID of the channel where the customer is assigned. + channelName: The name of the channel where the customer is assigned. + channels: + - channelID: The ID of the channel where the customer is assigned. + channelName: The name of the channel where the customer is assigned. + channelSlug: The unique channel slug. + endpoint: The default Replicated App endpoint https://replicated.app + replicatedProxyDomain: The domain of Replicated Proxy Registry. + customerEmail: The customer email address. + customerName: The name of the customer. + endpoint: This is the endpoint that the KOTS Admin Console uses to synchronize the licenses and download updates. + entitlements: + expires_at: + description: License Expiration + signature: {} + title: Expiration + value: "" + valueType: String + isAirgapSupported: If a license supports air gap installations with the Replicated installers (KOTS, kURL, Embedded Cluster), then this field is set to true. + isDisasterRecoverySupported: If a license supports the Embedded Cluster disaster recovery feature, this field is set to true. + isEmbeddedClusterDownloadEnabled: If a license supports installation with Replicated Embedded Cluster, this field is set to true or missing. + isKotsInstallEnabled: If a license supports installation with Replicated KOTS, this field is set to true. + isSnapshotSupported: If a license supports the snapshots backup and restore feature, this field is set to true. + isSupportBundleUploadSupported: If a license supports uploading a support bundle in the Admin Console, this field is set to true. + licenseID: Unique ID for the installed license. This value never changes. + licenseSequence: This value represents the license sequence that the client currently has. + licenseType: A string value that describes the type of the license + replicatedProxyDomain: proxy.replicated.com + signature: The base64-encoded license signature. This value will change when the license is updated. + parentChartURL: The URL of the parent Helm chart if the application is nested in a chart hierarchy. + releaseCreatedAt: The timestamp when the release was created. + releaseNotes: Release notes for the current release, as provided in the Vendor Portal. + releaseSequence: The sequence number of the release associated with this deployment. + replicatedAppEndpoint: https://replicated.app + versionLabel: Unstable-1457889-dirty ``` From 4626b4f028b0edcb51d2d04184636458967f3b02 Mon Sep 17 00:00:00 2001 From: Dexter Yan Date: Mon, 3 Feb 2025 17:25:43 +1300 Subject: [PATCH 06/11] update --- docs/vendor/replicated-sdk-values-schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md index 4edf902e0b..55d02983a6 100644 --- a/docs/vendor/replicated-sdk-values-schema.md +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -107,5 +107,5 @@ spec: releaseNotes: Release notes for the current release, as provided in the Vendor Portal. releaseSequence: The sequence number of the release associated with this deployment. replicatedAppEndpoint: https://replicated.app - versionLabel: Unstable-1457889-dirty + versionLabel: The version label for the release ``` From f4ca076f0bb06313fc03be91c6d4c85986f5bbca Mon Sep 17 00:00:00 2001 From: ada mancini Date: Mon, 3 Feb 2025 13:11:58 -0500 Subject: [PATCH 07/11] update SDK values --- docs/vendor/replicated-sdk-values-schema.md | 91 ++++++++------------- 1 file changed, 34 insertions(+), 57 deletions(-) diff --git a/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md index 55d02983a6..e7287a1bf6 100644 --- a/docs/vendor/replicated-sdk-values-schema.md +++ b/docs/vendor/replicated-sdk-values-schema.md @@ -1,70 +1,53 @@ # Helm global.replicated Values Schema -This document describes the global.replicated values schema injected by the Replicated registry when using the Helm CLI installation method. It includes information on the structure and purpose of fields to help developers integrate seamlessly with the Replicated SDK. +This document describes the values injected by the Replicated registry when using the Helm CLI installation method. It describes the structure and purpose of fields to help developers integrate seamlessly with the Replicated SDK. ## Overview -The `global.replicated` values schema is a set of values that are injected by the Replicated registry when using the Helm CLI installation method. These values are used by the Replicated SDK to provide information about the replicated application and the environment in which it is running. These values are critical for licensing, release management, and enabling key features of the Replicated Vendor Portal. +When a user installs a Helm application using the Helm CLI, the Replicated registry injects a set of customer-specific values into the `replicated` and `global.replicated` keys. For additional information about the Replicated SDK, see [Replicated SDK Overview](/vendor/replicated-sdk-overview). ## Values Schema Structure -The `global.replicated` values schema is a set of values that are injected by the Replicated registry when using the Helm CLI installation method. The schema is a JSON object that contains the following fields: +The `replicated` schema contains the following fields: | Field | Type | Description | | --- | --- | --- | -| `global.imageRegistry` | String | The URL of the image registry where the replicated-sdk images are stored. | -| `image.registry` | String | The URL of the image registry where the replicated-sdk images are stored. | -| `image.repository` | String | The name of the replicated/replicated-sdk image repository. | -| `image.tag` | String | The tag of the replicated/replicated-sdk image. | -| `image.pullPolicy` | String | The Kubernetes image pull policy for the replicated/replicated-sdk image. | -| `license` | String | The yaml representation of the customer license. | -| `licenseFields` | string | The license fields of the customer. | -| `appName` | String | The name of the application, as specified in the Replicated Vendor Portal. | -| `channelID` | String | The unique ID of the release channel. | -| `channelName` | String | The name of the release channel (e.g., “Stable”, “Beta”). | -| `channelSequence` | Integer | The sequence number of the channel, sed to track updates in channel. | -| `releaseSequence` | Integer | The sequence number of the release associated with this deployment. | -| `releaseCreatedAt` | String | The timestamp when the release was created. | -| `releaseNotes` | String | Release notes for the current release, as provided in the Vendor Portal. | -| `versionLabel` | String | The version label for the release, often displayed in UI dashboards. | -| `parentChartURL` | String | The URL of the parent Helm chart if the application is nested in a chart hierarchy. | -| `statusInformers` | map | Configuration for custom status informers. Used for application health and status insights. | -| `replicatedAppEndpoint` | String | If it is not using the default Replicated App endpoint https://replicated.app, this field specifies the endpoint to use. | -| `serviceAccountName` | String | The name of the Kubernetes service account used by the Replicated SDK. | -| `clusterRole` | String | The name of the Kubernetes cluster role used by the Replicated SDK. | -| `imagePullSecrets` | Array | An array of Kubernetes image pull secrets that are used to pull images from private registries. | -| `nameOverride` | String | Overrides the name of the chart. | -| `namespaceOverride` | String | Overrides the namespace of the chart. | -| `containerSecurityContext.enabled` | Boolean | Enables the security context for the container. | -| `containerSecurityContext.runAsNonRoot`| Boolean | Runs the container as a non-root user. | -| `containerSecurityContext.readOnlyRootFilesystem` | Boolean | Mounts the container’s root filesystem as read-only. | -| `containerSecurityContext.allowPrivilegeEscalation` | Boolean | Allows privilege escalation for the container. | -| `containerSecurityContext.capabilities.drop` | Array | Define which capabilities for dropping. | -| `podSecurityContext.enabled` | Boolean | Enables the security context for the pod. | -| `podSecurityContext.runAsUser` | Integer | The user ID for the pod. | -| `podSecurityContext.runAsGroup` | Integer | The group ID for the pod. | -| `podSecurityContext.fsGroup` | Integer | The group ID for the pod’s filesystem. | -| `podSecurityContext.supplementalGroups` | Array | The supplemental groups for the pod. | -| `podSecurityContext.seccompProfile.type` | String | The type of seccomp profile. | -| `service.type` | String | The replicated-sdk service type. | -| `service.port` | Integer | The port for the replicated-sdk service. | -| `privateCAConfigmap` | String | The name of the ConfigMap that contains the private CA certificate. | -| `privateCASecret` | String | The name of the Secret that contains the private CA certificate. | -| `extraEnv` | Array | Additional environment variables to inject into the container. | -| `integration.licenseID` | String | The license ID of the customer. | -| `integration.enabled` | Boolean | Enables the integration. | -| `integration.mockData` | string | The mock data for the integration. | -| `isAirgap` | Boolean | Indicates whether the replicated is installed in airgap environment. | -| `replicatedID` | String | The unique ID of the replicated-sdk instance cluster ID. | -| `appID` | String | The unique ID of the replicated app slug. | -| `tolerations` | Array | The tolerations for the pod. | -| `affinity` | Object | The affinity for the pod. | +| `enabled` | Boolean | Whether the Replicated SDK is enabled | +| `appName` | String | The name of the application | +| `channelID` | String | The unique ID of the release channel | +| `channelName` | String | The name of the release channel (e.g., "Stable", "Beta") | +| `channelSequence` | Integer | The sequence number of the channel | +| `integration.enabled` | Boolean | Whether integration features are enabled | +| `license` | String | The YAML representation of the customer license | +| `parentChartURL` | String | The URL of the parent Helm chart | +| `releaseCreatedAt` | String | The timestamp when the release was created | +| `releaseNotes` | String | Release notes for the current release | +| `releaseSequence` | Integer | The sequence number of the release | +| `replicatedAppEndpoint` | String | The Replicated app endpoint URL | +| `versionLabel` | String | The version label for the release | + +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.expires_at.description` | String | Description of the license expiration | +| `licenseFields.expires_at.signature` | Object | Signature data for the expiration field | +| `licenseFields.expires_at.title` | String | Title of the expiration field | +| `licenseFields.expires_at.value` | String | Value of the expiration field | +| `licenseFields.expires_at.valueType` | String | Type of the expiration value | +| `licenseFields.expires_at.signature.v1` | String | Signature data for the license | +| `licenseID` | String | The unique identifier for the license | +| `licenseType` | String | The type of license (e.g., "dev", "prod") | ## license Values Schema -The `license` field in the `global.replicated` values schema is a string that contains the YAML representation of the customer license. The license schema is a yaml object that contains the following fields: +The `license` field in the `global.replicated` values schema is a string that contains the YAML representation of the customer license: ```yaml apiVersion: kots.io/v1beta1 @@ -102,10 +85,4 @@ spec: licenseType: A string value that describes the type of the license replicatedProxyDomain: proxy.replicated.com signature: The base64-encoded license signature. This value will change when the license is updated. - parentChartURL: The URL of the parent Helm chart if the application is nested in a chart hierarchy. - releaseCreatedAt: The timestamp when the release was created. - releaseNotes: Release notes for the current release, as provided in the Vendor Portal. - releaseSequence: The sequence number of the release associated with this deployment. - replicatedAppEndpoint: https://replicated.app - versionLabel: The version label for the release ``` From 6b6466f479166aec30e4fd768aa693efa0d51544 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 11:44:57 -0700 Subject: [PATCH 08/11] docs edits --- docs/partials/helm/_helm-diagram-overview.mdx | 5 -- docs/partials/replicated-sdk/_sdk-values.mdx | 7 ++ docs/vendor/helm-install-overview.mdx | 44 ++-------- docs/vendor/helm-install-values-schema.mdx | 61 +++++++++++++ docs/vendor/licenses-using-builtin-fields.mdx | 41 +++++++++ ...verview.md => replicated-sdk-overview.mdx} | 7 +- docs/vendor/replicated-sdk-slsa-validating.md | 4 - docs/vendor/replicated-sdk-values-schema.md | 88 ------------------- sidebars.js | 1 + 9 files changed, 124 insertions(+), 134 deletions(-) delete mode 100644 docs/partials/helm/_helm-diagram-overview.mdx create mode 100644 docs/partials/replicated-sdk/_sdk-values.mdx create mode 100644 docs/vendor/helm-install-values-schema.mdx rename docs/vendor/{replicated-sdk-overview.md => replicated-sdk-overview.mdx} (93%) delete mode 100644 docs/vendor/replicated-sdk-values-schema.md diff --git a/docs/partials/helm/_helm-diagram-overview.mdx b/docs/partials/helm/_helm-diagram-overview.mdx deleted file mode 100644 index bcca3ff9b7..0000000000 --- a/docs/partials/helm/_helm-diagram-overview.mdx +++ /dev/null @@ -1,5 +0,0 @@ -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 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. \ No newline at end of file diff --git a/docs/partials/replicated-sdk/_sdk-values.mdx b/docs/partials/replicated-sdk/_sdk-values.mdx new file mode 100644 index 0000000000..88e4e73899 --- /dev/null +++ b/docs/partials/replicated-sdk/_sdk-values.mdx @@ -0,0 +1,7 @@ +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. + +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). \ No newline at end of file diff --git a/docs/vendor/helm-install-overview.mdx b/docs/vendor/helm-install-overview.mdx index 254176fa45..9535cebbf0 100644 --- 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: diagram of a helm chart in a custom environment [View a larger version of this image](/images/helm-install-diagram.png) - +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 new file mode 100644 index 0000000000..9b1f39c380 --- /dev/null +++ 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. + +## Overview + +When a user installs an 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 + + \ No newline at end of file diff --git a/docs/vendor/licenses-using-builtin-fields.mdx b/docs/vendor/licenses-using-builtin-fields.mdx index 110ba424b4..ace848c3e1 100644 --- 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.md b/docs/vendor/replicated-sdk-overview.mdx similarity index 93% rename from docs/vendor/replicated-sdk-overview.md rename to docs/vendor/replicated-sdk-overview.mdx index 79b17409a6..feaa67f448 100644 --- a/docs/vendor/replicated-sdk-overview.md +++ 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 + + \ No newline at end of file diff --git a/docs/vendor/replicated-sdk-slsa-validating.md b/docs/vendor/replicated-sdk-slsa-validating.md index 6dbfc1f3fe..0dd2ffd5f7 100644 --- 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/docs/vendor/replicated-sdk-values-schema.md b/docs/vendor/replicated-sdk-values-schema.md deleted file mode 100644 index e7287a1bf6..0000000000 --- a/docs/vendor/replicated-sdk-values-schema.md +++ /dev/null @@ -1,88 +0,0 @@ -# Helm global.replicated Values Schema - -This document describes the values injected by the Replicated registry when using the Helm CLI installation method. It describes the structure and purpose of fields to help developers integrate seamlessly with the Replicated SDK. - -## Overview - -When a user installs a Helm application using the Helm CLI, the Replicated registry injects a set of customer-specific values into the `replicated` and `global.replicated` keys. - -For additional information about the Replicated SDK, see [Replicated SDK Overview](/vendor/replicated-sdk-overview). - -## Values Schema Structure - -The `replicated` schema contains the following fields: - -| Field | Type | Description | -| --- | --- | --- | -| `enabled` | Boolean | Whether the Replicated SDK is enabled | -| `appName` | String | The name of the application | -| `channelID` | String | The unique ID of the release channel | -| `channelName` | String | The name of the release channel (e.g., "Stable", "Beta") | -| `channelSequence` | Integer | The sequence number of the channel | -| `integration.enabled` | Boolean | Whether integration features are enabled | -| `license` | String | The YAML representation of the customer license | -| `parentChartURL` | String | The URL of the parent Helm chart | -| `releaseCreatedAt` | String | The timestamp when the release was created | -| `releaseNotes` | String | Release notes for the current release | -| `releaseSequence` | Integer | The sequence number of the release | -| `replicatedAppEndpoint` | String | The Replicated app endpoint URL | -| `versionLabel` | String | The version label for the release | - -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.expires_at.description` | String | Description of the license expiration | -| `licenseFields.expires_at.signature` | Object | Signature data for the expiration field | -| `licenseFields.expires_at.title` | String | Title of the expiration field | -| `licenseFields.expires_at.value` | String | Value of the expiration field | -| `licenseFields.expires_at.valueType` | String | Type of the expiration value | -| `licenseFields.expires_at.signature.v1` | String | Signature data for the license | -| `licenseID` | String | The unique identifier for the license | -| `licenseType` | String | The type of license (e.g., "dev", "prod") | - -## license Values Schema - -The `license` field in the `global.replicated` values schema is a string that contains the YAML representation of the customer license: - -```yaml -apiVersion: kots.io/v1beta1 -kind: License -metadata: - name: name of the license -spec: - appSlug: The unique application slug that the customer is associated with. This value never changes. - channelID: The ID of the channel where the customer is assigned. - channelName: The name of the channel where the customer is assigned. - channels: - - channelID: The ID of the channel where the customer is assigned. - channelName: The name of the channel where the customer is assigned. - channelSlug: The unique channel slug. - endpoint: The default Replicated App endpoint https://replicated.app - replicatedProxyDomain: The domain of Replicated Proxy Registry. - customerEmail: The customer email address. - customerName: The name of the customer. - endpoint: This is the endpoint that the KOTS Admin Console uses to synchronize the licenses and download updates. - entitlements: - expires_at: - description: License Expiration - signature: {} - title: Expiration - value: "" - valueType: String - isAirgapSupported: If a license supports air gap installations with the Replicated installers (KOTS, kURL, Embedded Cluster), then this field is set to true. - isDisasterRecoverySupported: If a license supports the Embedded Cluster disaster recovery feature, this field is set to true. - isEmbeddedClusterDownloadEnabled: If a license supports installation with Replicated Embedded Cluster, this field is set to true or missing. - isKotsInstallEnabled: If a license supports installation with Replicated KOTS, this field is set to true. - isSnapshotSupported: If a license supports the snapshots backup and restore feature, this field is set to true. - isSupportBundleUploadSupported: If a license supports uploading a support bundle in the Admin Console, this field is set to true. - licenseID: Unique ID for the installed license. This value never changes. - licenseSequence: This value represents the license sequence that the client currently has. - licenseType: A string value that describes the type of the license - replicatedProxyDomain: proxy.replicated.com - signature: The base64-encoded license signature. This value will change when the license is updated. -``` diff --git a/sidebars.js b/sidebars.js index a2aef0a25b..52057e1575 100644 --- a/sidebars.js +++ b/sidebars.js @@ -501,6 +501,7 @@ const sidebars = { 'vendor/install-with-helm', 'vendor/helm-install-airgap', 'vendor/using-third-party-registry-proxy', + 'vendor/helm-install-values-schema', ], }, { From 55cb64f45527b5a91be8a116ea6e80ccb698ca6d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 11:51:15 -0700 Subject: [PATCH 09/11] minor copyedits --- docs/vendor/helm-install-values-schema.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/vendor/helm-install-values-schema.mdx b/docs/vendor/helm-install-values-schema.mdx index 9b1f39c380..030e7ea0cf 100644 --- a/docs/vendor/helm-install-values-schema.mdx +++ b/docs/vendor/helm-install-values-schema.mdx @@ -2,11 +2,11 @@ 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. +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 an 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. +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: From b511ab0a6ca1f60c8c0ccc54daf0850ca257add5 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 11:59:39 -0700 Subject: [PATCH 10/11] add example of replicated sdk values --- docs/partials/replicated-sdk/_sdk-values.mdx | 22 ++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/partials/replicated-sdk/_sdk-values.mdx b/docs/partials/replicated-sdk/_sdk-values.mdx index 88e4e73899..5d82e5b578 100644 --- a/docs/partials/replicated-sdk/_sdk-values.mdx +++ b/docs/partials/replicated-sdk/_sdk-values.mdx @@ -1,5 +1,27 @@ 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-authoritative + 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. From 0f3492c4325c75e78d44f1f062ca74ae5d92efe4 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 12:00:17 -0700 Subject: [PATCH 11/11] edit example --- docs/partials/replicated-sdk/_sdk-values.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/partials/replicated-sdk/_sdk-values.mdx b/docs/partials/replicated-sdk/_sdk-values.mdx index 5d82e5b578..f319bfc264 100644 --- a/docs/partials/replicated-sdk/_sdk-values.mdx +++ b/docs/partials/replicated-sdk/_sdk-values.mdx @@ -14,7 +14,7 @@ replicated: integration: enabled: true license: {} - parentChartURL: oci://registry.replicated.com/gitea/beta/gitea-authoritative + parentChartURL: oci://registry.replicated.com/gitea/beta/gitea releaseCreatedAt: "2024-11-25T20:38:22Z" releaseNotes: 'CLI release' releaseSequence: 88