add helm cli tutorial

Author: paigecalvert

docs/vendor/tutorial-helm-cli.mdx

@@ -0,0 +1,396 @@
+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 topic provides a tutorial that demonstrates how to install a sample application using the Helm CLI.
+
+## Introduction
+
+This tutorial shows how to install a Helm chart distributed with Replicated using the Helm CLI.
+
+In this tutorial, you will:
+
+* Download the Helm chart for the sample application (SlackerNews)
+
+* Create a release for SlackerNews in the Replicated Platform
+
+* Get the Helm CLI installation instructions for SlackerNews from the Replicated Enterprise Portal 
+
+* 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).
+
+* Ensure that you have access to a cluster that meets the requirements for Embedded Cluster:
+
+   * **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 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.**
+
+   For more information, see [Set Up Development Environments for Testing](/vendor/environment-setup#dev).
+
+## Tutorial
+
+1. Create an application using the Replicated CLI:
+
+    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
+       ```
+
+   1. Set the `REPLICATED_APP` environment variable to 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 `app create` command.
+
+       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. 
+
+1. Get the sample SlackerNews Helm chart:
+
+   1. Run the following command to download version 1.0.0 of the sample SlackerNews Helm chart to a new `quick-start` directory: 
+
+      ```
+      curl -O --create-dirs --output-dir quick-start https://docs.replicated.com/slackernews-1.0.0.tar.gz
+      ```
+
+   1. Untar the chart:
+
+      ```
+      tar -xzf quick-start/slackernews-1.0.0.tar.gz -C quick-start/ && rm quick-start/slackernews-1.0.0.tar.gz
+      ```
+
+   1. Change to the `slackernews` chart directory:
+
+      ```bash
+      cd quick-start/chart/slackernews
+      ```
+
+   1. List the files in the `slackernews` directory to view the contents of the Helm chart:
+      ```bash
+      ls
+      ```
+      ```bash
+      Chart.lock  Chart.yaml  NOTES.txt   README.md   templates   values.yaml
+      ```
+
+   1. In the SlackerNews Helm chart `Chart.yaml`, add the Replicated SDK as a dependency:
+
+      <DependencyYaml/>
+
+      The Replicated SDK is a Helm chart that provides access to Replicated features and can be installed as a small service alongside your application. For more information, see [About the Replicated SDK](/vendor/replicated-sdk-overview).
+
+   adds preflight checks to the application:
+
+   1. In your local filesystem, go to the `quick-start/chart/slackernews` directory.
+
+   1. Create a `preflights.yaml` file in the `templates` directory for the chart:
+
+      ```
+      touch templates/preflights.yaml
+      ```
+
+   1. In the `preflights.yaml` file, add the following YAML to create a Kubernetes Secret with a simple preflight spec: 
+
+      ```yaml
+      apiVersion: v1
+      kind: Secret
+      metadata:
+        name: slackernews-preflight
+        labels:
+          troubleshoot.sh/kind: preflight
+      stringData:
+        preflight.yaml: |-
+          apiVersion: troubleshoot.sh/v1beta2
+          kind: Preflight
+          metadata:
+            name: slackernews-preflight
+          spec:
+            collectors:
+              - clusterInfo: {}
+              - clusterResources: {}
+              - http:
+                  collectorName: slack
+                  get:
+                    url: https://api.slack.com/methods/api.test
+                    timeout: 20s
+            analyzers:
+              # verify that slack is accessible
+              - textAnalyze:
+                  checkName: Slack Accessible
+                  fileName: slack.json
+                  regex: '"status": 200,'
+                  outcomes:
+                    - pass:
+                        when: "true"
+                        message: "Can access the Slack API"
+                    - fail:
+                        when: "false"
+                        message: "Cannot access the Slack API. Check that the server can reach the internet and check [status.slack.com](https://status.slack.com)."
+      ```
+      
+      The YAML above defines a preflight check that confirms that an HTTP request to the Slack API at `https://api.slack.com/methods/api.test` made from the cluster returns a successful response of `"status": 200,`.
+
+   1. In the `Chart.yaml` file, increment the version to 1.0.1:
+
+      ```yaml
+      # Chart.yaml
+      version: 1.0.1
+      ```   
+
+   1. Update dependencies and package the Helm chart to a `.tgz` chart archive:
+
+      ```bash
+      helm package --dependency-update .
+      ```
+      Where `--dependency-update` (or `-u`) is an option for the `helm package` command that updates chart dependencies before packaging. For more information, see [Helm Package](https://helm.sh/docs/helm/helm_package/) in the Helm documentation.
+
+      The output of this command is a file named `slackernews-1.0.0.tgz`.
+
+1. Add the chart to a new release with `replicated release create --yaml-dir . --promote Unstable`.
+
+1. Create a customer:
+
+    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. Click **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 **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**.
+
+1. Access the Enterprise Portal for the customer to get the Helm CLI installatio 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 are assigned 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, enter your work email address and click **Send invite**.
+
+         For your production application, this is where you would invite your customers to access the Enterprise Portal.
+
+    1. In your inbox, open the **Invitation to join the Replicated Enterprise Portal** email and click **Activate your account**.
+
+         ![invitation email](/images/enterprise-portal-invitation-email.png)
+
+         [View a larger version of this image](/images/enterprise-portal-invitation-email.png)
+
+    1. On the join page, click **Accept invite**.
+
+         ![join page](/images/enterprise-portal-join-team.png)
+
+        [View a larger version of this image](/images/enterprise-portal-join-team.png) 
+
+         The Enterprise Portal dashboard opens.
+
+    1. Go to the **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**.
+
+         The installation options that are displayed in the Enterprise Portal depend on the **Install types** options that you enabled for the customer. 
+
+         ![installation guide landing page](/images/enterprise-portal-installation-guide.png)
+
+        [View a larger version of this image](/images/enterprise-portal-installation-guide.png)
+
+    1. For instance name, enter a nickname for the instance.
+
+    1. For **Kubernetes Distribution**, select the distribution of your cluster where you will install SlackerNews.
+
+    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**.
+
+1. Access your cluster. 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. After the cluster is running, use the kubectl command provided to set your kubectl context to the cluster.
+
+1. Go back to the Enterprise Portal installation guide to get the installation commands:
+
+    1. For **Helm Online Install**, select the release version that you promoted (`0.0.1`).
+
+    1. Copy and run the first command to log in to the Replicated registry.
+
+    1. Copy and run the commands to install and run preflight checks.
+
+    1. Create a values file to set the domain for the SlackerNews application.
+
+       ```bash
+       touch my-values.yaml
+       ```
+    1. In the `my-values.yaml` file, copy and paste the following YAML:
+
+        <details>
+          <summary>View `my-values.yaml`</summary>
+          ```yaml
+          postgres:
+            # tells slackernews to use postgres as the
+            # backing database instead of sqlite
+            enabled: false
+            # deploys a postgresql workload to the cluster
+            deploy_postgres: false
+            # the password to use with deploy_postgres
+            password: ""
+            # if deploy_postgres is false, provide a URI
+            uri: ""
+            # use a value in an existing secret instead of
+            # .postgres.password OR .postgres.uri
+            existingSecretName: ""
+            # key in the secret that contains the password
+            existingSecretPasswordKey: ""
+            # key in the secret that contains the uri
+            existingSecretUriKey: ""
+            # service type if deploy_postgres is true
+            service:
+              type: ClusterIP
+              nodePort:
+                port:
+            sqlite:
+              enabled: true
+            ingress:
+              annotations: {}
+              enabled: false
+              ingressClassName: ""
+            nginx:
+              service:
+                type: ClusterIP
+                nodePort:
+                  port:
+            service:
+              tls:
+                enabled: false
+                existingSecretName: ""
+                existingSecretCertKey: ""
+                existingSecretKeyKey: ""
+                cert: ""
+                key: ""
+            slack:
+              clientId: ""
+              clientSecret: ""
+              userToken: ""
+              botToken: ""
+              existingSecretName: ""
+              existingSecretClientIdKey: ""
+              existingSecretClientSecretKey: ""
+              existingSecretUserTokenKey: ""
+              existingSecretBotTokenKey: ""
+            slackernews:
+              domain: ""
+              # set default admin users
+              adminUserEmails: ""
+              # display running version on admin dashboard
+              version: "$TAG"
+            replicated:
+              isEmbeddedCluster: false
+              image:
+                registry: registry.replicated.com
+                repository: library/replicated-sdk-image
+                tag: 1.8.0
+            images:
+              pullSecrets:
+                - name: slackernews-pull-secret
+              slackernews:
+                registry: us-docker.pkg.dev
+                repository: smart-proxy-839/slackernews/slackernews-web
+                tag: v1.0.36
+                pullPolicy: IfNotPresent
+              nginx:
+                registry: index.docker.io
+                repository: library/nginx
+                tag: 1.28.0
+                pullPolicy: IfNotPresent
+              postgres:
+                registry: index.docker.io
+                repository: library/postgres
+                tag: 16
+                pullPolicy: IfNotPresent
+          ```
+        </details>
+
+    1. In the `my-values.yaml` file, enter a hostname in the `slackernews.domain` field.  
+
+    1. Run the install command to install SlackerNews in your cluster using the Helm CLI.
+
+1. Run `kubectl get all -n slackernews` to see when services are running
+
+1. Run `kubectl port-forward --namespace slackernews svc/slackernews-nginx 8080:80` to port forward
+
+1. Open `localhost:8080` in a browser.