diff --git a/docs/partials/replicated-sdk/_integration-mode-install.mdx b/docs/partials/replicated-sdk/_integration-mode-install.mdx new file mode 100644 index 0000000000..835dde768d --- /dev/null +++ b/docs/partials/replicated-sdk/_integration-mode-install.mdx @@ -0,0 +1,49 @@ +You can install the Replicated SDK in integration mode to develop locally against the SDK API without needing to add the SDK to your application, create a release in the Replicated Vendor Portal, or make changes in your environment. You can also use integration mode to test sending instance data to the Vendor Portal, including any custom metrics that you configure. + +To use integration mode, install the Replicated SDK as a standalone component using a valid Development license created in the Vendor Portal. After you install in integration mode, the SDK provides default mock data for requests to the SDK API `app` endpoints. Requests to the `license` endpoints use the real data from your Development license. + +To install the SDK in integration mode: + +1. Create a Development license that you can use to install the SDK in integration mode: + + 1. In the Vendor Portal, go to **Customers** and click **Create customer**. + + 1. Complete the following fields: + + 1. For **Customer name**, add a name for the customer. + + 1. For **Assigned channel**, assign the customer to the channel that you use for testing. For example, Unstable. + + 1. For **Customer type**, select **Development**. + + 1. For **Customer email**, add the email address that you want to use for the license. + + 1. For **Install types**, ensure that the **Existing Cluster (Helm CLI)** option is enabled. + + 1. (Optional) Add any license field values that you want to use for testing: + + 1. For **Expiration policy**, you can add an expiration date for the license. + + 1. For **Custom fields**, you can add values for any custom license fields in your application. For information about how to create custom license fields, see [Managing Customer License Fields](/vendor/licenses-adding-custom-fields). + + 1. Click **Save Changes**. + +1. On the **Manage customer** page for the customer you created, click **Helm install instructions**. + + Helm install instructions button on the manage customer page + + [View a larger version of this image](/images/helm-install-instructions-button.png) + +1. In the **Helm install instructions** dialog, copy and run the command to log in to the Replicated registry. + + Registry login command in the Helm install instructions dialog + + [View a larger version of this image](/images/helm-install-instructions-registry-login.png) + +1. From the same dialog, copy and run the command to install the SDK in integration mode: + + SDK integration mode install command in the Helm install instructions dialog + + [View a larger version of this image](/images/helm-install-instructions-sdk-integration.png) + +1. Make requests to the SDK API from your application. You can access the SDK API for testing by forwarding the API service to your local machine. For more information, see [Port Forwarding the SDK API Service](/vendor/replicated-sdk-development#port-forward). \ No newline at end of file diff --git a/docs/partials/replicated-sdk/_kots-version-req.mdx b/docs/partials/replicated-sdk/_kots-version-req.mdx index 14d2672334..b7ef54010e 100644 --- a/docs/partials/replicated-sdk/_kots-version-req.mdx +++ b/docs/partials/replicated-sdk/_kots-version-req.mdx @@ -1 +1 @@ -To install the SDK with KOTS, KOTS v1.104.0 or later and the SDK version 1.0.0-beta.12 or later are required. You can verify the version of KOTS installed with `kubectl kots version`. \ No newline at end of file +To install the SDK with a Replicated installer, KOTS v1.104.0 or later and the SDK version 1.0.0-beta.12 or later are required. You can verify the version of KOTS installed with `kubectl kots version`. For Replicated Embedded Cluster installations, you can see the version of KOTS that is installed by your version of Embedded Cluster in the [Embedded Cluster Release Notes](/release-notes/rn-embedded-cluster). \ No newline at end of file diff --git a/docs/reference/replicated-sdk-apis.md b/docs/reference/replicated-sdk-apis.md index 00a4d3f803..69369391b8 100644 --- a/docs/reference/replicated-sdk-apis.md +++ b/docs/reference/replicated-sdk-apis.md @@ -4,32 +4,9 @@ The Replicated SDK provides an API that you can use to embed Replicated function For example, if your application includes a UI where users manage their application instance, then you can use the `/api/v1/app/updates` endpoint to include messages in the UI that encourage users to upgrade when new versions are available. You could also revoke access to the application during runtime when a license expires using the `/api/v1/license/fields` endpoint. -For more information about how to get started with the Replicated SDK, see [About the Replicated SDK (Beta)](/vendor/replicated-sdk-overview). +For more information about how to get started with the Replicated SDK, see [About the Replicated SDK](/vendor/replicated-sdk-overview). -## Use Port Forwarding to Access the SDK API - -After the Replicated SDK is installed and initialized in a cluster, the Replicated SDK API is exposed at `replicated:3000`. You can access the SDK API for testing by forwarding port 3000 to your local machine. - -To use port forwarding to access the SDK API: - -1. Install the SDK in your cluster. See [Installing the Replicated SDK](/vendor/replicated-sdk-installing). - -1. Run the following command to port forward to the SDK API service: - - ```bash - kubectl port-forward service/replicated 3000 - ``` - ``` - Forwarding from 127.0.0.1:3000 -> 3000 - Forwarding from [::1]:3000 -> 3000 - ``` - -1. With the port forward running, test the SDK API endpoints as desired. For example: - - ```bash - curl localhost:3000/api/v1/license/fields/expires_at - curl localhost:3000/api/v1/license/fields/{field} - ``` +For information about how to develop against the Replicated SDK API with mock data, see [Developing Against the Replicated SDK](/vendor/replicated-sdk-developing). ## app diff --git a/docs/vendor/replicated-sdk-development.md b/docs/vendor/replicated-sdk-development.md deleted file mode 100644 index d4febb466f..0000000000 --- a/docs/vendor/replicated-sdk-development.md +++ /dev/null @@ -1,64 +0,0 @@ -# Developing Against the SDK API (Beta) - -This topic describes how to enable integration mode for the Replicated SDK to develop and test changes locally. For more information about the SDK API, see [Replicated SDK API (Beta)](/reference/replicated-sdk-apis). - -## About Integration Mode - -You can use the Replicated SDK in integration mode to develop locally against the SDK API without needing to make real changes in the Replicated Vendor Portal or in your environment. - -To use integration mode, install the Replicated SDK as a standalone component using a valid development license created in the Replicated Vendor Portal. After you install in integration mode, the SDK provides default mock data for requests to the SDK API `app` endpoints. Requests to the `license` endpoints use the real data from your development license. - -To use the Replicated SDK in integration mode, complete the following procedures: -1. [Create a Development License](#license) -1. [Install the SDK in integration mode](#install) - -## Create a Development License {#license} - -To use integration mode, you first need to create a development license that you can use to install the SDK. When you create the development license, you can add values to any license fields that you want to use in testing. - -For information about development licenses, see [License Types](licenses-about#license-types) in _About Licenses_. - -To create a development license: - -1. In the Vendor Portal, go to **Customers** and click **Create customer**. - -1. Complete the following fields: - - 1. For **Customer name**, add a name for the customer. - - 1. For **Assigned channel**, assign the customer to the channel that you use for testing. For example, Unstable. - - 1. For **Customer type**, select **Development**. - - 1. For **Customer email**, add the email address that you want to use for the license. - - ![create customer page in the Vendor Portal](/images/create-customer-development-mode.png) - [View a larger version of this image](/images/create-customer-development-mode.png) - -1. (Optional) Add any license field values that you want to use for testing: - - 1. For **Expiration policy**, you can add an expiration date for the license. - - 1. For **Custom fields**, you can add values for any custom license fields in your application. For information about how to create custom license fields, see [Managing Customer License Fields](/vendor/licenses-adding-custom-fields). - -1. Click **Save Changes**. - -## Install the SDK in Integration Mode {#install} - -To develop against the SDK locally in your development environment, install the SDK in integration mode as a standalone component in your cluster. - -To install the SDK in integration mode: - -1. On the **Manage customer** page for the customer you created, click **Helm install instructions**. - - ![Helm install instructions button on the manage customer page](/images/helm-install-instructions-button.png) - -1. In the **Helm install instructions** dialog, copy and run the command to log in to the Replicated registry. - - ![Registry login command in the Helm install instructions dialog](/images/helm-install-instructions-registry-login.png) - -1. From the same dialog, copy and run the command to install the SDK in integration mode: - - ![SDK integration mode install command in the Helm install instructions dialog](/images/helm-install-instructions-sdk-integration.png) - -1. Make requests to the SDK API from your application. Requests to the `license` endpoints use your actual development license data, while requests to the `app` endpoints use the default mock data. For more information about using the SDK API, see [Replicated SDK API (Beta)](/reference/replicated-sdk-apis). \ No newline at end of file diff --git a/docs/vendor/replicated-sdk-development.mdx b/docs/vendor/replicated-sdk-development.mdx new file mode 100644 index 0000000000..4ba7ca89a3 --- /dev/null +++ b/docs/vendor/replicated-sdk-development.mdx @@ -0,0 +1,38 @@ +import IntegrationMode from "../partials/replicated-sdk/_integration-mode-install.mdx" + +# Developing Against the SDK API (Beta) + +This topic describes how to develop against the SDK API to test changes locally. It includes information about installing the SDK in integration mode and port forwarding the SDK API service to your local machine. For more information about the SDK API, see [Replicated SDK API (Beta)](/reference/replicated-sdk-apis). + +## Install the SDK in Integration Mode + + + +## Port Forwarding the SDK API Service {#port-forward} + +After the Replicated SDK is installed and initialized in a cluster, the Replicated SDK API is exposed at `replicated:3000`. You can access the SDK API for testing by forwarding port 3000 to your local machine. + +To port forward the SDK API service to your local machine: + +1. Run the following command to port forward to the SDK API service: + + ```bash + kubectl port-forward service/replicated 3000 + ``` + ``` + Forwarding from 127.0.0.1:3000 -> 3000 + Forwarding from [::1]:3000 -> 3000 + ``` + +1. With the port forward running, test the SDK API endpoints as desired. For example: + + ```bash + curl localhost:3000/api/v1/license/fields/expires_at + curl localhost:3000/api/v1/license/fields/{field} + ``` + + For more information, see [Replicated SDK API (Beta)](/reference/replicated-sdk-apis). + + :::note + When the SDK is installed in integration mode, requests to the `license` endpoints use your actual development license data, while requests to the `app` endpoints use the default mock data. + ::: \ No newline at end of file diff --git a/docs/vendor/replicated-sdk-installing.mdx b/docs/vendor/replicated-sdk-installing.mdx index 64539995d9..44c90e89b8 100644 --- a/docs/vendor/replicated-sdk-installing.mdx +++ b/docs/vendor/replicated-sdk-installing.mdx @@ -1,12 +1,13 @@ import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" import KotsVerReq from "../partials/replicated-sdk/_kots-version-req.mdx" import RegistryLogout from "../partials/replicated-sdk/_registry-logout.mdx" +import IntegrationMode from "../partials/replicated-sdk/_integration-mode-install.mdx" # Installing the Replicated SDK (Beta) This topic describes the methods for distributing and installing the Replicated SDK. -It includes information about how to install the SDK alongside Helm chart- or standard manifest-based applications using the Helm CLI or Replicated KOTS. It also includes information about installing the SDK separately from an application as a standalone component in integration mode. +It includes information about how to install the SDK alongside Helm charts or Kubernetes manifest-based applications using the Helm CLI or a Replicated installer (Replicated KOTS, kURL, Embedded Cluster). It also includes information about installing the SDK as a standalone component in integration mode. For information about installing the SDK in air gap mode, see [Installing the SDK in Air Gap Environments](replicated-sdk-airgap). @@ -65,13 +66,13 @@ To install the SDK as a subchart: replicated 1/1 1 1 35s ``` -## Install the SDK Alongside a Standard Manifest-Based Application +## Install the SDK Alongside a Kubernetes Manifest-Based Application -For applications that use standard Kubernetes manifest files, the SDK Helm chart can be added to a release and then installed by KOTS alongside the application. +For applications that use Kubernetes manifest files instead of Helm charts, the SDK Helm chart can be added to a release and then installed by KOTS alongside the application. -To add the SDK Helm chart to a release for a standard manifest-based application: +To add the SDK Helm chart to a release for a Kubernetes manifest-based application: 1. Install the Helm CLI using Homebrew: @@ -99,7 +100,7 @@ To add the SDK Helm chart to a release for a standard manifest-based application [View a larger version of this image](/images/sdk-kots-release.png) -1. If one was not created automatically, add a Replicated HelmChart custom resource to the release. HelmChart custom resources have `apiVersion: kots.io/v1beta2` and `kind: HelmChart`. +1. If one was not created automatically, add a KOTS HelmChart custom resource to the release. HelmChart custom resources have `apiVersion: kots.io/v1beta2` and `kind: HelmChart`. **Example:** @@ -126,7 +127,7 @@ To add the SDK Helm chart to a release for a standard manifest-based application 1. Save and promote the release to an internal-only channel used for testing, such as the default Unstable channel. -1. Install the release using a Replicated installer (Emebdded Cluster, KOTS, kURL). For more information, see: +1. Install the release using a Replicated installer. For more information, see: * [Online Installation with Embedded Cluster](/enterprise/installing-embedded) * [Online Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster) * [Online Installation with kURL](/enterprise/installing-kurl) @@ -149,6 +150,4 @@ To add the SDK Helm chart to a release for a standard manifest-based application ## Install the SDK in Integration Mode -You can use the Replicated SDK in integration mode to develop locally against the SDK API without needing to add the SDK to your application, create a release in the Replicated Vendor Portal, or make changes in your environment. You can also use integration mode to test sending instance data to the Vendor Portal, including any custom metrics that you configure. - -To use integration mode, install the Replicated SDK as a standalone component using a valid development license. For more information, see [Developing Against the SDK API](/vendor/replicated-sdk-development). + diff --git a/sidebars.js b/sidebars.js index 4d3748cae1..b68cd8ad93 100644 --- a/sidebars.js +++ b/sidebars.js @@ -508,6 +508,7 @@ const sidebars = { 'vendor/replicated-sdk-overview', 'vendor/replicated-sdk-installing', 'vendor/replicated-sdk-airgap', + 'vendor/replicated-sdk-development', 'vendor/replicated-sdk-customizing', ], }, @@ -605,14 +606,7 @@ const sidebars = { // DEVELOPER TOOLS {type: 'html', value: '
Developer tools
', defaultStyle: true}, - { - type: 'category', - label: 'Replicated SDK API (Beta)', - items: [ - 'reference/replicated-sdk-apis', - 'vendor/replicated-sdk-development', - ], - }, + 'reference/replicated-sdk-apis', { type: 'category', label: 'Replicated CLI',