add setup and install

Signed-off-by: Anisur Rahman <[email protected]>
kubestash · Dec 28, 2023 · 4bb6c87 · 4bb6c87
1 parent ff8859d
commit 4bb6c87
Show file tree

Hide file tree

Showing 6 changed files with 324 additions and 0 deletions.
diff --git a/docs/setup/README.md b/docs/setup/README.md
@@ -0,0 +1,31 @@
+---
+title: Setup | KubeStash
+description: Setup guides for KubeStash by AppsCode
+menu:
+  docs_{{ .version }}:
+    identifier: setup-readme
+    name: Readme
+    parent: setup
+    weight: -1
+product_name: kubestash
+menu_name: docs_{{ .version }}
+section_menu_id: setup
+url: /docs/{{ .version }}/setup/
+aliases:
+  - /docs/{{ .version }}/setup/README/
+---
+
+# Setup
+
+The setup section contains instructions for installing the KubeStash and its various components in Kubernetes. This section has been divided into the following sub-sections:
+
+- **Install KubeStash:** Installation instructions for KubeStash and its various components.
+  - [Install KubeStash](): Installation instructions for KubeStash.
+  - [KubeStash kubectl Plugin](): Installation instructions for KubeStash `kubectl` plugin.
+  - [Troubleshooting](): Troubleshooting guide for various installation problems.
+- **Uninstall KubeStash:** Uninstallation instructions for KubeStash and its various components.
+  - [Uninstall KubeStash](): Uninstallation instructions for Stash Enterprise Edition.
+  - [KubeStash kubectl Plugin](): Uninstallation instructions for KubeStash `kubectl` plugin.
+- [Upgrading KubeStash](): Instruction for updating KubeStash license and upgrading between various KubeStash versions.
+
+
diff --git a/docs/setup/_index.md b/docs/setup/_index.md
@@ -0,0 +1,9 @@
+---
+title: Setup | KubeStash
+menu:
+  docs_{{ .version }}:
+    identifier: setup
+    name: Setup
+    weight: 30
+menu_name: docs_{{ .version }}
+---
diff --git a/docs/setup/install/_index.md b/docs/setup/install/_index.md
@@ -0,0 +1,11 @@
+---
+title: Installation Guide | KubeStash
+description: KubeStash Installation Guide
+menu:
+  docs_{{ .version }}:
+    identifier: installation-guide
+    name: Install
+    parent: setup
+    weight: 10
+menu_name: docs_{{ .version }}
+---
diff --git a/docs/setup/install/kubectl-plugin/index.md b/docs/setup/install/kubectl-plugin/index.md
@@ -0,0 +1,82 @@
+---
+title: Install KubeStash kubectl Plugin
+description: Installation guide for KubeStash kubectl Plugin
+menu:
+  docs_{{ .version }}:
+    identifier: install-kubestash
+    name: KubeStash kubectl Plugin
+    parent: installation-guide
+    weight: 30
+product_name: kubestash
+menu_name: docs_{{ .version }}
+section_menu_id: setup
+---
+
+# Install KubeStash kubectl Plugin
+
+KubeStash provides a `kubectl` plugin to interact with KubeStash resources.
+
+## Install using Krew
+
+KubeStash `kubectl` plugin can be installed using Krew. [Krew](https://krew.sigs.k8s.io/) is the plugin manager for kubectl command-line tool. To install follow the steps below:
+
+- Install `krew` following the steps [here](https://krew.sigs.k8s.io/docs/user-guide/setup/install/).
+
+- If you have already installed `krew`, please upgrade `krew` to version v0.4.0 or later so that you can use [custom plugin indexes](https://krew.sigs.k8s.io/docs/user-guide/custom-indexes/).
+
+```bash
+kubectl krew upgrade
+kubectl krew version
+```
+
+- Add [AppsCode's kubectl plugin index](https://github.com/appscode/krew-index). If you have already added the index, update the index.
+
+```bash
+kubectl krew index add appscode https://github.com/appscode/krew-index.git
+kubectl krew index list
+kubectl krew update
+```
+
+- Install Kubestash `kubectl` plugin following the commands below:
+
+```bash
+kubectl krew install appscode/kubestash
+kubectl kubestash version
+```
+
+- If KubeStash `kubectl` plugin is already installed, run the following command to upgrade the plugin:
+
+```bash
+kubectl krew upgrade
+kubectl kubestash version
+```
+
+## Install using pre-built binary
+
+You can download the pre-build binaries from [kubestash/cli](https://github.com/kubestash/cli/releases) releases and put it into one of your installation directory denoted by `$PATH` variable.
+
+Here is a simple Linux command to install the latest 64-bit Linux binary directly into your `/usr/local/bin` directory:
+
+```bash
+# Linux amd 64-bit
+curl -o kubectl-kubestash.tar.gz -fsSL https://github.com/kubestash/cli/releases/download/{{< param "info.cli" >}}/kubectl-kubestash-linux-amd64.tar.gz \
+  && tar zxvf kubectl-kubestash.tar.gz \
+  && chmod +x kubectl-kubestash-linux-amd64 \
+  && sudo mv kubectl-kubestash-linux-amd64 /usr/local/bin/kubectl-kubestash \
+  && rm kubectl-kubestash.tar.gz LICENSE.md
+
+# Mac OSX 64-bit
+curl -o kubectl-kubestash.tar.gz -fsSL https://github.com/kubestash/cli/releases/download/{{< param "info.cli" >}}/kubectl-kubestash-darwin-amd64.tar.gz \
+  && tar zxvf kubectl-kubestash.tar.gz \
+  && chmod +x kubectl-kubestash-darwin-amd64 \
+  && sudo mv kubectl-kubestash-darwin-amd64 /usr/local/bin/kubectl-kubestash \
+  && rm kubectl-kubestash.tar.gz LICENSE.md
+```
+
+If you prefer to install kubectl kubestash cli from source code, make sure that your go development environment has been setup properly. Then, just run:
+
+```bash
+go get github.com/kubestash/cli/...
+```
+
+> Please note that this will install kubestash cli from master branch which might include breaking and/or undocumented changes.
diff --git a/docs/setup/install/kubestash/images/enterprise_license_form.png b/docs/setup/install/kubestash/images/enterprise_license_form.png
diff --git a/docs/setup/install/kubestash/index.md b/docs/setup/install/kubestash/index.md
@@ -0,0 +1,191 @@
+---
+title: Install KubeStash
+description: Installation guide for KubeStash
+menu:
+  docs_{{ .version }}:
+    identifier: install-kubestash
+    name: KubeStash
+    parent: installation-guide
+    weight: 20
+product_name: kubestash
+menu_name: docs_{{ .version }}
+section_menu_id: setup
+---
+
+# Install KubeStash
+
+If you are willing to try KubeStash, you can grab a **30 days trial** license from [here](https://license-issuer.appscode.com/?p=kubestash).
+
+## Prerequisites
+
+- **Kubernetes version**: KubeStash is compatible with any Kubernetes cluster with version `1.16` or later.
+- **Extended API server**: Your cluster needs to support Kubernetes extended API server.
+- **Webhook support**: Your cluster must support Kubernetes validation and mutation webhooks.
+- **RBAC permissions**: KubeStash operator needs a few RBAC permissions on your cluster. You can find the list of the required RBAC permissions [here]().
+- **Installing on GKE cluster**: To install KubeStash on your GKE cluster, please check the requirements [here]().
+- **NFS volume**: If you are willing to use NFS volume as a backend, you need to customize the KubeStash installation like [here]().
+
+
+## Get a Trial License
+
+
+In this section, we are going to show you how you can get a **30 days trial** license for KubeStash. You can get a license for your Kubernetes cluster by going through the following steps:
+
+
+- At first, go to [AppsCode License Server](https://license-issuer.appscode.com/?p=stash-enterprise) and fill up the form. It will ask for your Name, Email, the product you want to install, and your cluster ID (UID of the `kube-system` namespace).
+- Provide your name and email address. **You must provide your work email address**.
+- Then, select `KubeStash License` in the product field.
+- Now, provide your cluster ID. You can get your cluster ID easily by running the following command:
+
+
+```bash
+kubectl get ns kube-system -o=jsonpath='{.metadata.uid}'
+```
+
+
+- Then, you have to agree with the terms and conditions. We recommend reading it before checking the box.
+- Now, you can submit the form. After you submit the form, the AppsCode License server will send an email to the provided email address with a link to your license file.
+- Navigate to the provided link and save the license into a file. Here, we save the license to a `license.txt` file.
+
+
+Here is a screenshot of the license form.
+
+
+<figure align="center">
+  <img alt="KubeStash Backend Overview" src="images/enterprise_license_form.png">
+  <figcaption align="center">Fig: KubeStash License Form</figcaption>
+</figure>
+
+
+You can create licenses for as many clusters as you want. You can upgrade your license any time without re-installing KubeStash by following the upgrading guide from [here](/docs/setup/upgrade/index.md#upgrading-license).
+
+
+## Get an Enterprise License
+
+If you are interested in purchasing Enterprise license, please contact us via [email protected] for further discussion. You can also set up a meeting via our [calendly link](https://calendly.com/appscode/intro).
+
+If you are willing to purchasing Enterprise license but need more time to test in your dev cluster, feel free to contact [email protected]. We will be happy to extend your trial period.
+
+## Install
+
+KubeStash operator can be installed as a Helm chart or simply as Kubernetes manifests.
+
+<ul class="nav nav-tabs" id="installerTab" role="tablist">
+  <li class="nav-item">
+    <a class="nav-link active" id="helm3-tab" data-toggle="tab" href="#helm3" role="tab" aria-controls="helm3" aria-selected="true">Helm 3 (Recommended)</a>
+  </li>
+  <li class="nav-item">
+    <a class="nav-link" id="script-tab" data-toggle="tab" href="#script" role="tab" aria-controls="script" aria-selected="false">YAML</a>
+  </li>
+</ul>
+<div class="tab-content" id="installerTabContent">
+  <div class="tab-pane fade show active" id="helm3" role="tabpanel" aria-labelledby="helm3-tab">
+
+## Using Helm 3
+
+KubeStash can be installed via [Helm](https://helm.sh/) using the [chart]() from [AppsCode Charts Repository](https://github.com/appscode/charts). To install the chart with the release name `kubestash`:
+
+```bash
+$ helm repo add appscode https://charts.appscode.com/stable/
+$ helm repo update
+$ helm search repo appscode/kubestash --version {{< param "info.version" >}}
+NAME                      	CHART VERSION	APP VERSION	DESCRIPTION                                       
+appscode/kubestash        	v2023.12.1   	v2023.12.1 	KubeStash by AppsCode - Backup your Kubernetes ...
+
+$ helm install kubestash appscode/kubestash     \
+  --version {{< param "info.version" >}}        \
+  --namespace kube-system                       \
+  --set-file global.license=/path/to/the/license.txt
+```
+
+To see the detailed configuration options, visit [here]().
+
+</div>
+<div class="tab-pane fade" id="script" role="tabpanel" aria-labelledby="script-tab">
+
+## Using YAML
+
+If you prefer to not use Helm, you can generate YAMLs from KubeStash chart and deploy using `kubectl`. Here we are going to show the prodecure using Helm 3.
+
+```bash
+$ helm repo add appscode https://charts.appscode.com/stable/
+$ helm repo update
+$ helm search repo appscode/kubestash --version {{< param "info.version" >}}
+NAME                      	CHART VERSION	APP VERSION	DESCRIPTION                                       
+appscode/kubestash        	v2023.12.1   	v2023.12.1 	KubeStash by AppsCode - Backup your Kubernetes ...
+
+$ helm template kubestash appscode/kubestash     \
+  --version {{< param "info.version" >}}         \
+  --namespace kube-system                        \
+  --set global.skipCleaner=true                  \
+  --set-file global.license=/path/to/the/license.txt | kubectl apply -f -
+```
+
+To see the detailed configuration options, visit [here]().
+
+</div>
+</div>
+
+## Verify installation
+
+To check if KubeStash operator pods have started, run the following command:
+
+```bash
+$ kubectl get pods --all-namespaces -l app.kubernetes.io/name=kubestash-operator --watch
+NAMESPACE     NAME                                           READY   STATUS    RESTARTS   AGE
+kube-system   kubestash-kubestash-operator-fcd8bf7c6-psjs6   2/2     Running   0          5m49s
+```
+
+Once the operator pod is running, you can cancel the above command by typing `Ctrl+C`.
+
+Now, to confirm CRD groups have been registered by the operator, run the following command:
+```bash
+$ kubectl get crd -l app.kubernetes.io/name=kubestash
+NAME                                      CREATED AT
+addons.addons.kubestash.com               2023-12-07T06:27:41Z
+backupbatches.core.kubestash.com          2023-12-07T06:27:41Z
+backupblueprints.core.kubestash.com       2023-12-07T06:27:41Z
+backupconfigurations.core.kubestash.com   2023-12-07T06:40:37Z
+backupsessions.core.kubestash.com         2023-12-07T06:40:37Z
+backupstorages.storage.kubestash.com      2023-12-07T06:40:37Z
+functions.addons.kubestash.com            2023-12-07T06:27:41Z
+hooktemplates.core.kubestash.com          2023-12-07T06:27:42Z
+repositories.storage.kubestash.com        2023-12-07T06:40:37Z
+restoresessions.core.kubestash.com        2023-12-07T06:27:42Z
+retentionpolicies.storage.kubestash.com   2023-12-07T06:27:42Z
+snapshots.storage.kubestash.com           2023-12-07T06:40:37Z
+```
+
+### Verify Addons
+
+KubeStash automatically installs the necessary Addons for workload, pvc backup & restore. Verify that the Addons have been installed using the following command.
+
+```bash
+$ kubectl get addons.addons.kubestash.com
+NAME             AGE
+kubedump-addon   7m1s
+pvc-addon        7m1s
+workload-addon   7m1
+```
+
+As you can see from the above output that KubeStash has created `Addon` objects.
+
+### Verify Functions
+
+KubeStash also automatically installs the necessary functions for the corresponding installed addons. Verify that the functions have been installed using the following command.
+
+```bash
+$ kubectl get functions.addons.kubestash.com 
+NAME                     AGE
+kubedump-backup          7m25s
+pvc-backup               7m25s
+pvc-restore              7m25s
+volumesnapshot-backup    7m25s
+volumesnapshot-restore   7m25s
+workload-backup          7m25s
+workload-restore         7m25s
+```
+
+As you can see from the above output that KubeStash has created `Functions` objects.
+
+Now, you are ready to [take your first backup]() using KubeStash.