Merge pull request #3524 from replicatedhq/helm-cli-tutorial

add helm cli tutorial

Author: paigecalvert

docs/vendor/tutorial-helm-cli.mdx

@@ -0,0 +1,313 @@
+import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx"
+import HelmPackage from "../partials/helm/_helm-package.mdx"
+import Requirements from "../partials/embedded-cluster/_requirements.mdx"
+
+# Install SlackerNews with the Helm CLI
+
+This tutorial demonstrates how to install an application distributed with Replicated using the Helm CLI.
+
+## Introduction
+
+In this tutorial, you will:
+
+* Download the sample Helm chart (SlackerNews)
+
+* Create a release for SlackerNews in the Replicated Platform
+
+* Get the Helm CLI installation instructions for SlackerNews from the [Replicated Enterprise Portal](/vendor/enterprise-portal-about) 
+
+* Install SlackerNews using the Helm CLI in a Kubernetes cluster
+
+## Set Up Your Environment
+
+Before you begin, do the following to set up your environment:
+
+* Install the Helm CLI, which is the tool for interacting with Helm and managing Helm charts. See [Install Helm](/vendor/environment-setup#install-helm) in _Set Up Your Environment_.
+
+* Ensure that you have access to a Kubernetes cluster where you can test the installation using the Helm CLI:
+
+   * **Option 1: Use Compatibility Matrix.** To use Replicated Compatibility Matrix to create a cluster for this tutorial, first request Compatibility Matrix credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about Compatibility Matrix credits, see [Billing and Credits](/vendor/testing-about#billing-and-credits).
+
+          :::note
+          If you are new to the Replicated platform, you might be eligible for $100 in free Compatibility Matrix credits. To request your free credits, reach out to our sales team at https://www.replicated.com/contact and note in the comments that you are completing a Replicated tutorial.
+          :::
+
+      After you complete the prerequisites described above, continue to the [Tutorial](#tutorial). You will create the cluster with Compatibility Matrix as part of the tutorial.
+
+   * **Option 2: Bring your own Cluster.** You can use any cloud provider or tool that you prefer to create a cluster, such as Google Kubernetes Engine (GKE) or minikube.
+
+   For more information, see [Set Up Development Environments for Testing](/vendor/environment-setup#dev).
+
+## Tutorial
+
+### Create an Application
+
+Create a SlackerNews application in the Replicated Platform:
+
+1. On your local machine, install the Replicated CLI:
+
+    * MacOS
+
+      ```bash
+      brew install replicatedhq/replicated/cli
+      ```
+    * Linux / Windows Subsystem for Linux (WSL)
+
+      ```bash
+      version=$(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
+         | grep -m1 -Po '"tag_name":\s*"v\K[^"]+')
+      curl -Ls \
+         "https://github.com/replicatedhq/replicated/releases/download/v${version}/replicated_${version}_linux_amd64.tar.gz" \
+         -o replicated.tar.gz
+      tar xf replicated.tar.gz replicated && rm replicated.tar.gz
+      mv replicated /usr/local/bin/replicated
+      ``` 
+   For more information and additional installation options, see [Install the Replicated CLI](/reference/replicated-cli-installing).
+
+1. Authorize the Replicated CLI:
+
+   ```bash
+   replicated login
+   ```
+   In the browser window that opens, follow the prompt to log in to your Vendor Portal account and authorize the CLI.
+
+1. Create an application named SlackerNews:
+
+   ```bash
+   replicated app create "SlackerNews"
+   ```
+   :::note
+   If you already have an application named SlackerNews in your Vendor Portal team, you can add a qualifier to the name. For example, "SlackerNews Tutorial" or "SlackerNews YOUR_NAME".
+   :::
+
+1. Set the `REPLICATED_APP` environment variable to the slug of the application that you created:
+
+   ```bash
+   export REPLICATED_APP=APP_SLUG
+   ```
+   Where `APP_SLUG` is the unique application slug provided in the output of the `replicated app create` or `replicated app ls` commands.
+
+   Setting the `REPLICATED_APP` environment variable allows you to interact with the application using the Replicated CLI without needing to use the `--app` flag with every command.
+
+### Get the Chart Archive and Create a Release
+
+Download the chart archive for SlackerNews version 1.0.1, then add the archive to a new release in the Replicated Platform:
+
+1. Run the following command to download the SlackerNews Helm chart archive to a new `tutorial-helm-install` directory: 
+
+    ```bash
+    curl -O --create-dirs --output-dir tutorial-helm-install https://docs.replicated.com/slackernews-1.0.1.tgz
+    ```
+
+1. Add the chart archive to a new release:
+
+   ```bash
+   replicated release create --yaml-dir tutorial-helm-install --promote Unstable
+   ```
+   **Example output:**
+   ```
+   • Reading manifests from . ✓
+   • Creating Release ✓
+    • SEQUENCE: 1
+   • Promoting ✓
+    • Channel 32q8tKLfRFbHYPGJ1Q2E2vcDQ9j successfully set to release 1
+   ```
+
+### Customize the Enterprise Portal
+
+Customize the look and feel of the Enterprise Portal for the SlackerNews application:
+
+1. Log in to the [Vendor Portal](https://vendor.replicated.com).
+
+1. Under the application drop down, select the SlackerNews application that you created.
+
+    <img alt="App drop down" src="/images/quick-start-app-dropdown-slackernews.png" width="250px"/>
+
+    [View a larger version of this image](/images/quick-start-app-dropdown-slackernews.png)
+
+1. In the left navigation panel, click **Enterprise Portal**.
+
+1. On the **Enterprise Portal > Settings** tab, for **Title** enter `SlackerNews Enterprise Portal`.
+
+1. Scroll down to the **Colors** section.
+
+1. For **Primary**, enter `#fd9431`. For **Secondary**, enter `#297372`. Click **Save**.
+
+    ![Enterprise Portal color settings](/images/enterprise-portal-settings-colors.png)
+
+    [View a larger version of this image](/images/enterprise-portal-settings-colors.png)
+
+1. Go to the **Knowledge base** tab. For **Helm Post-Install Instructions**, enter the following markdown:
+
+     ```mdx
+     Congratulations! For more information about getting started with SlackerNews, see the docs at [https://docs.slackernews.io/](https://docs.slackernews.io/).
+     ```
+
+     ![Enterprise Portal install instructions settings](/images/enterprise-portal-settings-post-install.png)
+
+     [View a larger version of this image](/images/enterprise-portal-settings-post-install.png)
+
+1. Click **Save Changes**.    
+
+### Create a Customer
+
+Create a test customer:
+
+1. In the Vendor Portal, go to **Customers > Create customer**.
+
+     The **Create a new customer** page opens:
+
+     ![Customer a new customer page in the Vendor Portal](/images/create-customer.png)
+
+     [View a larger version of this image](/images/create-customer.png)
+
+1. For **Customer name**, enter a name for the customer. For example, `Example Customer`.
+
+1. For **Customer email**, enter an email address. This email address is only used as a username for authenticating with the Replicated registry and is never contacted. A customer email address is required for Helm CLI installations.
+
+1. For **Assigned Channel**, select **Unstable**. This allows the customer to install releases promoted to the Unstable channel.
+
+1. For **Customer type**, select **Development**.
+
+1. For **Install types**, enable **Existing Cluster (Helm CLI)**.
+
+1. Click **Save Changes**.
+
+### Access the Customer's Enterprise Portal
+
+Log in to the Enterprise Portal for the customer to get the Helm CLI installation instructions:
+
+1. On the customer's page, go to the **Enterprise Portal Access** tab.
+
+1. Enable the **Enable Enterprise Portal for this customer** toggle.
+
+    ![enterprise portal toggle enabled](/images/customer-enterprise-portal-access-toggle.png)
+
+    [View a larger version of this image](/images/customer-enterprise-portal-access-toggle.png)
+
+    :::note
+    The Enterprise Portal is beta. By default, customers have access to the Replicated Download Portal. For more information, see [Comparison to the Download Portal](/vendor/enterprise-portal-about#comparison-to-the-download-portal) in _About the Enterprise Portal_.
+    :::
+
+1. In the **Invite users** dialog that opens automatically, click **Cancel** to close the dialog.
+
+   For your production application, this is where you could send initations to customers so they can access the Enterprise Portal.
+
+1. Click **Login to portal** to generate a one-time login and open the Enterprise Portal for the customer.
+
+   ![Login to portal button](/images/enterprise-portal-one-time-login.png)
+
+   [View a larger version of this image](/images/enterprise-portal-one-time-login.png)
+
+   The Enterprise Portal dashboard opens.   
+
+1. Go to the Enterprise Portal **Install** tab. 
+
+    ![install tab](/images/enterprise-portal-install-tab.png)
+
+    [View a larger version of this image](/images/enterprise-portal-install-tab.png)
+
+1. On the **Installation Guide** page, if multiple installation options are displayed, select **Helm**.
+
+    :::note
+    The installation options that are displayed in the Enterprise Portal depend on the **Install types** enabled for the customer. 
+    :::
+
+1. For **Instance Name**, enter a nickname for the instance.
+
+1. For **Kubernetes Distribution**, select the distribution of the cluster where you will install SlackerNews. If you are going to use Compatibility Matrix to create the cluster, select **Vanilla Kubernetes**.
+
+1. For **Cluster Network Availability**, select **Outbound requests allowed**.
+
+1. For **Registry Access**, select **My workstation can access the internet, the registry AND the cluster**.
+
+1. Click **Next**.
+
+### Install    
+
+Install SlackerNews in a cluster:
+
+1. If you brought your own cluster, set kubectl context to the cluster where you want to install. If you are using Compatibility Matrix, do the following:
+
+   1. Create a kind cluster with version 1.34.0 of Kubernetes:
+
+      ```bash
+      replicated cluster create --distribution kind --instance-type r1.small --disk 50 --version 1.34.0
+      ```
+
+   1. Watch for the cluster to have a `running` status:
+
+      ```bash
+      replicated cluster ls --watch
+      ```    
+
+   1. After the cluster status is `running`, run the following command to set your kubectl context to the cluster:
+
+      ```bash
+      replicated cluster shell CLUSTER_ID
+      ```
+      Where `CLUSTER_ID` is the ID of the cluster provided in the output of `replicated cluster ls`.
+
+      :::note
+      You can also copy the shell command for the cluster from the **Compatibility Matrix** page in the Vendor Portal.
+      :::
+
+1. Go back to the install wizard in the Enterprise Portal.
+
+    ![Helm online install wizard](/images/enterprise-portal-helm-online-install-slackernews.png)
+
+    [View a larger version of this image](/images/enterprise-portal-helm-online-install-slackernews.png)
+
+1. On the **Helm Online Install**, for **Select a version**, ensure that the version you promoted (`1.0.1`) is selected.
+
+1. For **Export credential and log in**, run the command to log in to the Replicated registry.
+
+1. Run the next command to install the preflight plugin.
+
+1. Run preflight checks against the cluster.
+
+1. Skip the **Create values override file** step. This is not necessary for the purpose of this tutorial because you do not need to pass a local values file to the chart.
+
+1. Copy the install command provided and make the following changes:
+   * Remove the `--values my-values.yaml` flag.
+   * Add `--namespace slackernews --create-namespace` to install the application in the slackernews namespace.
+
+   **Example:**
+
+   ```bash
+   helm install slackernews oci://registry.replicated.com/slackernews/unstable/slackernews --version 1.0.1 --namespace slackernews --create-namespace 
+   ```
+
+1. Watch the SlackerNews deployment: 
+
+    ```bash
+    kubectl get all --namespace slackernews --watch
+    ```
+
+1. When the installation is complete and the `slackernews-nginx` service is running, run the following command to port forward the service to local port 8080:
+
+   ```bash
+   kubectl port-forward --namespace slackernews svc/slackernews-nginx 8080:8080
+   ``` 
+
+1. In a browser, go to `localhost:8080`. The SlackerNews application landing page opens.
+
+    ![SlackerNews landing page page](/images/slackernews-landing-page.png)
+
+    [View a larger version of this image](/images/slackernews-landing-page.png)
+
+1. Go back to the **Helm Online Install** wizard in the Enterprise Portal and click **Continue**. On the **Installation Complete** page, you can see the post-installation message that you set.
+
+    ![Installation Complete page](/images/enterprise-portal-post-installation.png)
+
+    [View a larger version of this image](/images/enterprise-portal-post-installation.png)
+
+1. Return to the Vendor Portal, select the SlackerNews application, and go to **Customers**. Under the name of the customer, confirm that you can see an active instance.
+
+1. (Optional) Under Instance ID, click on the ID to view additional insights including the versions of Kubernetes and the Replicated SDK running in the cluster where you installed the application.
+
+## Summary
+
+Congratulations! You created a release using a Helm chart, then followed the Helm CLI installation steps provided in the Enterprise Portal to install the release in a cluster.
+
+For more information about Helm CLI installations for applications distributed with Replicated, see [About Helm Installations with Replciated](/vendor/helm-install-overview).

sidebars.js

@@ -53,6 +53,7 @@ const sidebars = {
       label: 'Tutorials',
       items: [
         'vendor/tutorial-embedded-cluster-automation',
+        'vendor/tutorial-helm-cli',
       ],
     },
     {