Move info about port forwarding the SDK API service (#2900)

paigecalvert · web-flow · commit 9a8e65917f03 · 2024-12-16T11:41:14.000-05:00
* Move info about port forwarding the SDK API service

* make integration mode procedure into partial
diff --git a/docs/partials/replicated-sdk/_integration-mode-install.mdx 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**.
+
+   <img alt="Helm install instructions button on the manage customer page" src="/images/helm-install-instructions-button.png" width="700px"/>
+
+   [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.
+
+   <img alt="Registry login command in the Helm install instructions dialog" src="/images/helm-install-instructions-registry-login.png" width="600px"/>
+
+   [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:
+
+   <img alt="SDK integration mode install command in the Helm install instructions dialog" src="/images/helm-install-instructions-sdk-integration.png" width="600px"/>
+
+   [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).
diff --git 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`.
+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).
diff --git 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
diff --git a/docs/vendor/replicated-sdk-development.mdx 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
+
+<IntegrationMode/>
+
+## 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.
+   :::
diff --git 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.
 
 <KotsVerReq/>
 
-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).
+<IntegrationMode/>
diff --git 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: '<h5>Developer tools</h5>', 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',

Original file line number	Diff line number	Diff line change
`@@ -1 +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`.
	`1`	+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).