Skip to content

Move info about port forwarding the SDK API service #2900

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 16, 2024
Merged

Move info about port forwarding the SDK API service #2900

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1706f8d
Move info about port forwarding the SDK API service
paigecalvert Dec 12, 2024
0b8e0d5
make integration mode procedure into partial
paigecalvert Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/partials/replicated-sdk/_integration-mode-install.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Copy link
Contributor Author

@paigecalvert paigecalvert Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

made these steps a partial so they could be included in both the Developing Against the SDK API and the Installing the SDK topics. Both seemed reasonable places to look for this info


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).
2 changes: 1 addition & 1 deletion docs/partials/replicated-sdk/_kots-version-req.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
27 changes: 2 additions & 25 deletions docs/reference/replicated-sdk-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
64 changes: 0 additions & 64 deletions docs/vendor/replicated-sdk-development.md
View file
Open in desktop

This file was deleted.

38 changes: 38 additions & 0 deletions docs/vendor/replicated-sdk-development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}
Copy link
Contributor Author

@paigecalvert paigecalvert Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved the port forwarding procedure to its own section of "Developing Against the SDK API".

Originally, I had this as just the last two steps in the integration mode procedure, but then I wasn't sure if maybe people would want to know how to do this outside of integration mode & also if it might be helpful to have a direct anchor link to the port forwarding steps that we could send to people


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.
:::
17 changes: 8 additions & 9 deletions docs/vendor/replicated-sdk-installing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor Author

@paigecalvert paigecalvert Dec 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ Updating some dated language. Removing "standard" manifest in favor or k8s manifest. Also, the "Replicated installer" thing is the current way to talk about kots, kurl, ec


For information about installing the SDK in air gap mode, see [Installing the SDK in Air Gap Environments](replicated-sdk-airgap).

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:**

Expand All @@ -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)
Expand All @@ -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/>
Copy link
Contributor Author

@paigecalvert paigecalvert Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ put the partial here so that people could see the steps rather than having to click away

10 changes: 2 additions & 8 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -508,6 +508,7 @@ const sidebars = {
'vendor/replicated-sdk-overview',
'vendor/replicated-sdk-installing',
'vendor/replicated-sdk-airgap',
'vendor/replicated-sdk-development',
Copy link
Contributor Author

@paigecalvert paigecalvert Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved this up to main SDK section

'vendor/replicated-sdk-customizing',
],
},
Expand Down Expand Up @@ -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',
Expand Down