diff --git a/docs/_index.md b/docs/_index.md index e10e72a..88c8976 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -1,6 +1,6 @@ --- -title: Docs | Stash -description: Stash Docs +title: Docs | KubeStash +description: KubeStash Docs menu: docs_{{ .version }}: identifier: welcome diff --git a/docs/setup/README.md b/docs/setup/README.md index f8812cc..c3ab8dc 100644 --- a/docs/setup/README.md +++ b/docs/setup/README.md @@ -1,6 +1,6 @@ --- -title: Setup | Stash -description: Setup guides for Stash by AppsCode +title: Setup | KubeStash +description: Setup guides for KubeStash by AppsCode menu: docs_{{ .version }}: identifier: setup-readme @@ -17,20 +17,15 @@ aliases: # Setup -
- Install Stash -
-
+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: -The setup section contains instructions for installing the Stash 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. -- **Install Stash:** Installation instructions for Stash and its various components. - - [Stash operator](/docs/setup/install/stash/index.md): Installation instructions for Stash operator. - - [Stash kubectl Plugin](/docs/setup/install/kubectl-plugin/index.md): Installation instructions for Stash `kubectl` plugin. - - [Troubleshooting](/docs/setup/install/troubleshooting/index.md): Troubleshooting guide for various installation problems. - -- **Uninstall Stash:** Uninstallation instructions for Stash and its various components. - - [Stash operator](/docs/setup/uninstall/stash/index.md): Uninstallation instructions for Stash operator. - - [Stash kubectl Plugin](/docs/setup/uninstall/kubectl-plugin/index.md): Uninstallation instructions for Stash `kubectl` plugin. - -- [Upgrading Stash](/docs/setup/upgrade/index.md): Instruction for updating Stash license and upgrading between various Stash versions. + \ No newline at end of file diff --git a/docs/setup/_index.md b/docs/setup/_index.md index 68d0a93..f1c8515 100644 --- a/docs/setup/_index.md +++ b/docs/setup/_index.md @@ -1,5 +1,5 @@ --- -title: Setup | Stash +title: Setup | KubeStash menu: docs_{{ .version }}: identifier: setup diff --git a/docs/setup/install/_index.md b/docs/setup/install/_index.md index 7247d85..9e9a3db 100644 --- a/docs/setup/install/_index.md +++ b/docs/setup/install/_index.md @@ -1,6 +1,6 @@ --- -title: Installation Guide | Stash -description: Stash Installation Guide +title: Installation Guide | KubeStash +description: KubeStash Installation Guide menu: docs_{{ .version }}: identifier: installation-guide diff --git a/docs/setup/install/kubectl-plugin/index.md b/docs/setup/install/kubectl-plugin/index.md index 0f50f61..1a7f4cb 100644 --- a/docs/setup/install/kubectl-plugin/index.md +++ b/docs/setup/install/kubectl-plugin/index.md @@ -1,10 +1,10 @@ --- -title: Install Stash kubectl Plugin -description: Installation guide for Stash kubectl Plugin +title: Install KubeStash kubectl Plugin +description: Installation guide for KubeStash kubectl Plugin menu: docs_{{ .version }}: - identifier: install-stash-kubectl-plugin - name: Stash kubectl Plugin + identifier: install-kubestash + name: KubeStash kubectl Plugin parent: installation-guide weight: 30 product_name: kubestash @@ -12,13 +12,13 @@ menu_name: docs_{{ .version }} section_menu_id: setup --- -# Install Stash kubectl Plugin +# Install KubeStash kubectl Plugin -Stash provides a `kubectl` plugin to interact with Stash resources. +KubeStash provides a `kubectl` plugin to interact with KubeStash resources. ## Install using Krew -Stash `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: +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/). @@ -37,46 +37,46 @@ kubectl krew index list kubectl krew update ``` -- Install Stash `kubectl` plugin following the commands below: +- Install Kubestash `kubectl` plugin following the commands below: ```bash -kubectl krew install appscode/stash -kubectl stash version +kubectl krew install appscode/kubestash +kubectl kubestash version ``` -- If Stash `kubectl` plugin is already installed, run the following command to upgrade the plugin: +- If KubeStash `kubectl` plugin is already installed, run the following command to upgrade the plugin: ```bash kubectl krew upgrade -kubectl stash version +kubectl kubestash version ``` ## Install using pre-built binary -You can download the pre-build binaries from [stashed/cli](https://github.com/kubestash/cli/releases) releases and put it into one of your installation directory denoted by `$PATH` variable. +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-stash.tar.gz -fsSL https://github.com/kubestash/cli/releases/download/{{< param "info.cli" >}}/kubectl-stash-linux-amd64.tar.gz \ - && tar zxvf kubectl-stash.tar.gz \ - && chmod +x kubectl-stash-linux-amd64 \ - && sudo mv kubectl-stash-linux-amd64 /usr/local/bin/kubectl-stash \ - && rm kubectl-stash.tar.gz LICENSE.md +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-stash.tar.gz -fsSL https://github.com/kubestash/cli/releases/download/{{< param "info.cli" >}}/kubectl-stash-darwin-amd64.tar.gz \ - && tar zxvf kubectl-stash.tar.gz \ - && chmod +x kubectl-stash-darwin-amd64 \ - && sudo mv kubectl-stash-darwin-amd64 /usr/local/bin/kubectl-stash \ - && rm kubectl-stash.tar.gz LICENSE.md +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 Stash cli from source code, make sure that your go development environment has been setup properly. Then, just run: +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 Stash cli from master branch which might include breaking and/or undocumented changes. +> 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/stash/images/enterprise_license_form.png b/docs/setup/install/kubestash/images/enterprise_license_form.png similarity index 100% rename from docs/setup/install/stash/images/enterprise_license_form.png rename to 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 new file mode 100644 index 0000000..8b07821 --- /dev/null +++ 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. + + +
+ KubeStash Backend Overview +
Fig: KubeStash License Form
+
+ + +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 sales@appscode.com 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 sales@appscode.com. We will be happy to extend your trial period. + +## Install + +KubeStash operator can be installed as a Helm chart or simply as Kubernetes manifests. + + +
+
+ +## 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](). + +
+
+ +## 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](). + +
+
+ +## 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. diff --git a/docs/setup/install/stash/index.md b/docs/setup/install/stash/index.md deleted file mode 100644 index f899f95..0000000 --- a/docs/setup/install/stash/index.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Install Stash -description: Installation guide for Stash -menu: - docs_{{ .version }}: - identifier: install-stash-enterprise - name: Stash - parent: installation-guide - weight: 20 -product_name: kubestash -menu_name: docs_{{ .version }} -section_menu_id: setup ---- - -# Install Stash - -## Get a Free License - -Download a FREE license from [AppsCode License Server](https://appscode.com/issue-license?p=stash). - -> KubeStash licensing process has been designed to work with CI/CD workflow. You can automatically obtain a license from your CI/CD pipeline by following the guide from [here](https://github.com/appscode/offline-license-server#offline-license-server). - -## Install - -Stash operator can be installed as a Helm chart or simply as Kubernetes manifests. - - -
-
- -## Using Helm 3 - -Stash can be installed via [Helm](https://helm.sh/) using the [chart](https://github.com/kubestash/installer/tree/{{< param "info.installer" >}}/charts/stash) from [AppsCode Charts Repository](https://github.com/appscode/charts). To install the chart with the release name `stash`: - -```bash -$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ - --version {{< param "info.version" >}} \ - --namespace kubestash --create-namespace \ - --set-file global.license=/path/to/the/license.txt \ - --wait --burst-limit=10000 --debug -``` - -To see the detailed configuration options, visit [here](https://github.com/kubestash/installer/tree/{{< param "info.installer" >}}/charts/kubestash). - -
-
- -## Using YAML - -If you prefer to not use Helm, you can generate YAMLs from Stash chart and deploy using `kubectl`. Here we are going to show the prodecure using Helm 3. - -```bash -$ helm template kubestash oci://ghcr.io/appscode-charts/kubestash \ - --version {{< param "info.version" >}} \ - --namespace kubestash --create-namespace \ - --set global.skipCleaner=true \ - --set-file global.license=/path/to/the/license.txt | kubectl apply -f - -``` - -To see the detailed configuration options, visit [here](https://github.com/kubestash/installer/tree/{{< param "info.installer" >}}/charts/kubestash). - -
-
- -## Verify installation - -To check if Stash operator pods have started, run the following command: - -```bash -❯ kubectl get pods --all-namespaces -l app.kubernetes.io/name=stash-enterprise --watch -NAMESPACE NAME READY STATUS RESTARTS AGE -kube-system stash-stash-enterprise-678bcb6db4-267vk 2/2 Running 0 3m -``` - -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=stash - -NAME CREATED AT -backupbatches.stash.appscode.com 2020-08-24T08:20:54Z -backupblueprints.stash.appscode.com 2020-08-24T08:20:55Z -backupconfigurations.stash.appscode.com 2020-08-24T08:20:54Z -backupsessions.stash.appscode.com 2020-08-24T08:20:55Z -functions.stash.appscode.com 2020-08-24T08:20:55Z -recoveries.stash.appscode.com 2020-08-24T08:20:54Z -repositories.stash.appscode.com 2020-08-24T08:20:54Z -restics.stash.appscode.com 2020-08-24T08:20:54Z -restorebatches.stash.appscode.com 2020-08-24T08:20:55Z -restoresessions.stash.appscode.com 2020-08-24T08:20:55Z -tasks.stash.appscode.com 2020-08-24T08:20:55Z -``` - -### Verify Catalogs - -Stash automatically installs the necessary Addon catalogs for database backup. Verify that the Addon catalogs have been installed using the following command. - -```bash -❯ kubectl get tasks.stash.appscode.com -NAME AGE -elasticsearch-backup-5.6.4 5m8s -elasticsearch-backup-6.2.4 5m8s -elasticsearch-backup-6.3.0 5m8s -elasticsearch-backup-6.4.0 5m8s -elasticsearch-backup-6.5.3 5m8s -elasticsearch-backup-6.8.0 5m8s -elasticsearch-backup-7.2.0 5m8s -elasticsearch-backup-7.3.2 5m8s -elasticsearch-restore-5.6.4 5m8s -elasticsearch-restore-6.2.4 5m8s -elasticsearch-restore-6.3.0 5m8s -elasticsearch-restore-6.4.0 5m8s -elasticsearch-restore-6.5.3 5m8s -elasticsearch-restore-6.8.0 5m8s -elasticsearch-restore-7.2.0 5m8s -elasticsearch-restore-7.3.2 5m8s -mariadb-backup-10.5.8 5m8s -mariadb-restore-10.5.8 5m8s -mongodb-backup-3.4.17 5m8s -mongodb-backup-3.4.22 5m8s -mongodb-backup-3.6.13 5m8s -mongodb-backup-4.0.11 5m8s -mongodb-backup-4.0.3 5m8s -mongodb-backup-4.1.13 5m8s -mongodb-backup-4.1.4 5m8s -mongodb-backup-4.1.7 5m8s -mongodb-backup-4.2.3 5m8s -mongodb-restore-3.4.17 5m8s -mongodb-restore-3.4.22 5m8s -mongodb-restore-3.6.13 5m8s -mongodb-restore-4.0.11 5m8s -mongodb-restore-4.0.3 5m8s -mongodb-restore-4.1.13 5m8s -mongodb-restore-4.1.4 5m8s -mongodb-restore-4.1.7 5m8s -mongodb-restore-4.2.3 5m8s -mysql-backup-5.7.25 5m8s -mysql-backup-8.0.14 5m8s -mysql-backup-8.0.21 5m8s -mysql-backup-8.0.3 5m8s -mysql-restore-5.7.25 5m8s -mysql-restore-8.0.14 5m8s -mysql-restore-8.0.21 5m8s -mysql-restore-8.0.3 5m8s -perconaxtradb-backup-5.7 5m8s -perconaxtradb-restore-5.7 5m8s -postgres-backup-10.14 5m8s -postgres-backup-11.9 5m8s -postgres-backup-12.4 5m8s -postgres-backup-13.1 5m8s -postgres-backup-9.6.19 5m8s -postgres-restore-10.14 5m8s -postgres-restore-11.9 5m8s -postgres-restore-12.4 5m8s -postgres-restore-13.1 5m8s -postgres-restore-9.6.19 5m8s -pvc-backup 5m2s -pvc-restore 5m2s -``` - -As you can see from the above output that Stash has created `Task` objects for each supported databases. - -Now, you are ready to [take your first backup](/docs/guides/README.md) using Stash. - -## Purchase Stash License - -If you are interested in purchasing Stash license, please contact us via sales@appscode.com for further discussion. You can also set up a meeting via our [calendly link](https://calendly.com/appscode/intro). - -If you are willing to purchase Stash license but need more time to test in your dev cluster, feel free to contact sales@appscode.com. We will be happy to extend your trial period. diff --git a/docs/setup/install/troubleshooting/index.md b/docs/setup/install/troubleshooting/index.md index de28af7..bab930d 100644 --- a/docs/setup/install/troubleshooting/index.md +++ b/docs/setup/install/troubleshooting/index.md @@ -1,9 +1,9 @@ --- -title: Troubleshooting Stash Installation -description: Troubleshooting guide for Stash installation +title: Troubleshooting KubeStash Installation +description: Troubleshooting guide for KubeStash installation menu: docs_{{ .version }}: - identifier: install-stash-troubleshoot + identifier: install-kubestash name: Troubleshooting parent: installation-guide weight: 40 @@ -12,9 +12,13 @@ menu_name: docs_{{ .version }} section_menu_id: setup --- + +# Troubleshooting Kubestash +This doc is about kubestash installation troubleshooting. + ## Installing in GKE Cluster -If you are installing Stash on a GKE cluster, you will need cluster admin permissions to install Stash operator. Run the following command to grant admin permision to the cluster. +If you are installing KubeStash on a GKE cluster and if you need cluster admin permissions to install KubeStash operator. Run the following command to grant admin permission to the cluster. ```bash $ kubectl create clusterrolebinding "cluster-admin-$(whoami)" \ @@ -26,7 +30,7 @@ In addition, if your GKE cluster is a [private cluster](https://cloud.google.com ## Configuring Network Volume Accessor -For network volume such as NFS, Stash needs to deploy a helper deployment in the same namespace as the Repository that uses the NFS as backend to provide Snapshot listing facility. We call this helper deployment network volume accessor. You can configure its resources, user id, privileged permission etc. Run the following command to enable network volume accessor, +For network volume such as NFS, KubeStash needs to deploy a helper deployment in the same namespace as the Repository that uses the NFS as backend to provide Snapshot listing facility. We call this helper deployment network volume accessor. You can configure its resources, user id, privileged permission etc. Run the following command to enable network volume accessor,