diff --git a/docs/vendor/tutorial-helm-cli.mdx b/docs/vendor/tutorial-helm-cli.mdx new file mode 100644 index 0000000000..bfcdd76041 --- /dev/null +++ b/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. + + App drop down + + [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). \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 9e674da263..090d9427fd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -53,6 +53,7 @@ const sidebars = { label: 'Tutorials', items: [ 'vendor/tutorial-embedded-cluster-automation', + 'vendor/tutorial-helm-cli', ], }, { diff --git a/static/images/enterprise-portal-helm-online-install-slackernews.png b/static/images/enterprise-portal-helm-online-install-slackernews.png new file mode 100644 index 0000000000..60fdc4ac39 Binary files /dev/null and b/static/images/enterprise-portal-helm-online-install-slackernews.png differ diff --git a/static/images/enterprise-portal-install-tab.png b/static/images/enterprise-portal-install-tab.png new file mode 100644 index 0000000000..b90c0912bf Binary files /dev/null and b/static/images/enterprise-portal-install-tab.png differ diff --git a/static/images/enterprise-portal-invite-user-dialog.png b/static/images/enterprise-portal-invite-user-dialog.png index 22b98f9487..931b03adbb 100644 Binary files a/static/images/enterprise-portal-invite-user-dialog.png and b/static/images/enterprise-portal-invite-user-dialog.png differ diff --git a/static/images/enterprise-portal-one-time-login.png b/static/images/enterprise-portal-one-time-login.png new file mode 100644 index 0000000000..90be2d945e Binary files /dev/null and b/static/images/enterprise-portal-one-time-login.png differ diff --git a/static/images/enterprise-portal-post-installation.png b/static/images/enterprise-portal-post-installation.png new file mode 100644 index 0000000000..1a17238672 Binary files /dev/null and b/static/images/enterprise-portal-post-installation.png differ diff --git a/static/images/enterprise-portal-settings-colors.png b/static/images/enterprise-portal-settings-colors.png new file mode 100644 index 0000000000..f2959133cc Binary files /dev/null and b/static/images/enterprise-portal-settings-colors.png differ diff --git a/static/images/enterprise-portal-settings-post-install.png b/static/images/enterprise-portal-settings-post-install.png new file mode 100644 index 0000000000..a0ed0e97bf Binary files /dev/null and b/static/images/enterprise-portal-settings-post-install.png differ